Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

72.6 KB
Raw Blame
import {
    NotebookBlockNode,
    NotebookCodeBlockNode,
    NotebookCodeRefMark,
    NotebookComponentBlockNode,
    NotebookComponentProps,
    NotebookDocument,
    NotebookInlineMark,
    NotebookInlineNode,
    NotebookListBlockNode,
    NotebookParseError,
    NotebookTableAlignment,
    NotebookTableBlockNode,
    NotebookTableCell,
    NotebookPropValue,
    NotebookTextBlockNode,
} from './types'
import {
    createStableNodeId,
    ensureUniqueNodeIds,
    getNodeFingerprint,
    hashString,
    isNotebookPropValue,
    normalizeInlineMarks,
    normalizeInlineNodes,
    seedNodeFingerprint,
} from './utils'

type BlockParseResult = {
    node: NotebookBlockNode | null
    nextLineIndex: number
    error?: NotebookParseError
}

type PropParseResult = {
    props: NotebookComponentProps
    errors: string[]
}

type ComponentScanResult = {
    raw: string
    nextLineIndex: number
    foundTerminator: boolean
}

type ComponentScanState = {
    quote: string | null
    expressionDepth: number
    escapeNext: boolean
    awaitingPropValue: boolean
    openingTagClosed: boolean
}

const COMPONENT_START_REGEX = /^<[A-Z][A-Za-z0-9]*(\s|>|\/)/
const ESCAPED_COMPONENT_START_REGEX = /^\\<[A-Z][A-Za-z0-9]*(\s|>|\/)/
const MAX_COMPONENT_BLOCK_LINES = 1_000
const MAX_COMPONENT_BLOCK_CHARACTERS = 256 * 1024
const ORDERED_LIST_REGEX = /^\s*\d+[.)](?:\s+|$)/
const BULLET_LIST_REGEX = /^\s*[-*+•](?:\s+|$)/
const LIST_ITEM_REGEX = /^(\s*)(\d+[.)]|[-*+•])(?:\s+(.*))?$/
const TASK_LIST_ITEM_REGEX = /^\[([ xX])\](?:\s+(.*))?$/
const HEADING_REGEX = /^(#{1,6})\s+(.*)$/
const IMAGE_BLOCK_REGEX = /^!\[((?:\\.|[^\]\\])*)\]\(((?:\\.|[^)\\])*)\)$/
const DIVIDER_BLOCK_REGEX = /^(?:-{3,}|\*{3,}|_{3,})$/
export const DIVIDER_COMPONENT_TAG = 'Divider'
export const COMMENT_COMPONENT_TAG = 'Comment'

/**
 * The `Comment` tag has two flavors: an authorial note (`text` prop, stored as a markdown
 * `<!-- … -->` comment) and a Google Docs-style discussion thread anchored to a `<ref>`
 * highlight (`ref` + `replies` props, stored as a real `<Comment … />` tag).
 */
export function isDiscussionCommentProps(props: NotebookComponentProps): boolean {
    return typeof props.ref === 'string' || Array.isArray(props.replies)
}
const TABLE_SEPARATOR_CELL_REGEX = /^:?-{3,}:?$/
const EMPTY_PARAGRAPH_MARKDOWN = ' '
/** One blank line separates two blocks of the same card; a second one starts a new card
 * (`startsGroup` in `types.ts`). Programmatic writers append blocks with this separator so each
 * one lands as its own node. */
export const NOTEBOOK_BLOCK_SEPARATOR = '\n\n\n'
const NOTEBOOK_BLOCK_JOINER = '\n\n'
/**
 * A block id the document stores, rather than one derived from the block's content on every
 * parse. Only these are written back as an anchor, so a document that never carried one
 * serializes byte for byte as it was read.
 */
export const STORED_NODE_ID_PREFIX = 'phb-'
/**
 * A stored block id, written on its own line above the block it names.
 *
 * A comment is the only place a paragraph can carry an id: the document is markdown, and prose
 * has no attribute to hold one. It renders nowhere, so a reader never sees it.
 *
 * The prefix is part of the pattern, so this matches exactly what the serializer writes back.
 * A wider pattern would eat an authorial `<!--ph:note-->` as an anchor and drop it on the next
 * save, because the serializer writes no anchor for an id it did not store.
 */
const NODE_ANCHOR_REGEX = /^<!--ph:(phb-[A-Za-z0-9._-]{1,124})-->$/

export function isStoredNodeId(id: string | undefined): boolean {
    return !!id && id.startsWith(STORED_NODE_ID_PREFIX)
}

export function serializeNodeAnchor(id: string): string {
    return `<!--ph:${id}-->\n`
}
// Every character the serializer may backslash-escape; the inline parser turns `\X` back into
// the literal character for exactly this set, so the two must stay in sync.
const INLINE_ESCAPABLE_CHARS = new Set([
    '\\',
    '`',
    '*',
    '_',
    '~',
    '[',
    ']',
    '(',
    ')',
    '<',
    '>',
    '#',
    '+',
    '-',
    '.',
    '|',
    '!',
    '•',
])
type InlineEmphasisToken = {
    token: string
    markType: 'bold' | 'italic' | 'strike'
    // Underscore emphasis must not trigger inside words (snake_case), per CommonMark
    requiresWordBoundary: boolean
}
const INLINE_EMPHASIS_TOKENS: InlineEmphasisToken[] = [
    { token: '**', markType: 'bold', requiresWordBoundary: false },
    { token: '__', markType: 'bold', requiresWordBoundary: true },
    { token: '~~', markType: 'strike', requiresWordBoundary: false },
    { token: '*', markType: 'italic', requiresWordBoundary: false },
    { token: '_', markType: 'italic', requiresWordBoundary: true },
]
// Inline tags are lowercase (HTML-style) so they can never collide with block components,
// whose tag names are required to start with an uppercase letter.
const INLINE_TAG_NAMES = ['ref', 'mention'] as const
type InlineTagName = (typeof INLINE_TAG_NAMES)[number]
const INLINE_TAG_OPEN_REGEX = /^<(ref|mention)\s+id=(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)')\s*>/
let generatedNodeIdCounter = 0
const serializedNodeCache = new WeakMap<NotebookBlockNode, string>()

export function parseMarkdownNotebook(markdown: string | null | undefined): NotebookDocument {
    const lines = (markdown ?? '').replace(/\r\n?/g, '\n').split('\n')
    const nodes: NotebookBlockNode[] = []
    const errors: NotebookParseError[] = []
    const occurrences = new Map<string, number>()
    let pendingAnchorId: string | null = null
    const pushParsedNode = (node: NotebookBlockNode): void => {
        const anchorId = pendingAnchorId
        pendingAnchorId = null
        // A tag's own `nodeId` prop wins over an anchor above it, matching the backend walk in
        // products/notebooks/backend/util.py. Taking the anchor here would address one cell by
        // two different ids, one per layer.
        const carriesOwnId = node.type === 'component' && typeof node.props.nodeId === 'string' && !!node.props.nodeId
        if (anchorId !== null && !carriesOwnId) {
            node.id = anchorId
            nodes.push(node)
            return
        }
        const fingerprint = getNodeFingerprint(node)
        const occurrence = occurrences.get(fingerprint) ?? 0
        occurrences.set(fingerprint, occurrence + 1)
        node.id = createStableNodeId(fingerprint, occurrence)
        nodes.push(node)
    }

    let lineIndex = 0
    let blankLinesBeforeBlock = 0
    while (lineIndex < lines.length) {
        const line = lines[lineIndex]

        if (isEmptyParagraphPlaceholderLine(line)) {
            pushParsedNode({
                id: '',
                type: 'paragraph',
                children: [],
                startsGroup: nodes.length > 0 && blankLinesBeforeBlock > 1 ? true : undefined,
            })
            blankLinesBeforeBlock = 0
            lineIndex += 1
            continue
        }

        if (!line.trim()) {
            // An anchor names only the block on the line below it. Text removed from under an
            // anchor leaves the anchor behind, and carried over a blank line it would hand the id
            // to the next block, so an edit by that id would reach a block its caller never read.
            pendingAnchorId = null
            blankLinesBeforeBlock += 1
            lineIndex += 1
            continue
        }

        // Read before the block scan, so `parseCommentBlock` never takes an anchor for an
        // authorial note. The blank-line count is left alone: the anchor sits inside the
        // separator that decides the card boundary, and must not close it.
        const anchorMatch = NODE_ANCHOR_REGEX.exec(line.trim())
        if (anchorMatch) {
            pendingAnchorId = anchorMatch[1]!
            lineIndex += 1
            continue
        }

        const result = parseBlock(lines, lineIndex)
        if (result.error) {
            errors.push(result.error)
        }
        if (result.node) {
            if (nodes.length > 0 && blankLinesBeforeBlock > 1) {
                result.node.startsGroup = true
            }
            pushParsedNode(result.node)
        }
        blankLinesBeforeBlock = 0
        lineIndex = Math.max(result.nextLineIndex, lineIndex + 1)
    }

    return { type: 'doc', nodes: ensureUniqueNodeIds(nodes), errors }
}

export function serializeMarkdownNotebook(document: NotebookDocument): string {
    if (document.nodes.length === 1 && isEmptyNotebookTitleNode(document.nodes[0])) {
        return ''
    }

    const shouldPreserveEmptyParagraphs = document.nodes.length > 1
    const serialized = document.nodes
        .map((node, index) => {
            const body = serializeDocumentNode(node, shouldPreserveEmptyParagraphs)
            // A derived id is rebuilt from the block on the next parse, so writing it back would
            // rewrite every document the editor opens and break `serialize(parse(md)) === md`.
            const block = isStoredNodeId(node.id) ? `${serializeNodeAnchor(node.id)}${body}` : body
            if (index === 0) {
                return block
            }
            return `${node.startsGroup ? NOTEBOOK_BLOCK_SEPARATOR : NOTEBOOK_BLOCK_JOINER}${block}`
        })
        .join('')
    const lastNode = document.nodes[document.nodes.length - 1]
    const previousNode = document.nodes[document.nodes.length - 2]
    const shouldPreserveTrailingEmptyParagraph =
        shouldPreserveEmptyParagraphs && isEmptyParagraphNode(lastNode) && previousNode?.type !== 'component'

    return shouldPreserveTrailingEmptyParagraph ? serialized : serialized.trimEnd()
}

function isEmptyNotebookTitleNode(node: NotebookBlockNode | undefined): boolean {
    return !!node && node.type === 'heading' && node.level === 1 && serializeInlineNodes(node.children) === ''
}

export function serializeNode(node: NotebookBlockNode): string {
    const cachedValue = serializedNodeCache.get(node)
    if (cachedValue !== undefined) {
        return cachedValue
    }

    const serialized = serializeNodeUncached(node)
    serializedNodeCache.set(node, serialized)
    return serialized
}

function serializeNodeUncached(node: NotebookBlockNode): string {
    if (node.type === 'heading') {
        const [firstLine, ...followingLines] = serializeInlineNodes(node.children).split('\n')
        const linePrefix = node.blockquote ? '> ' : ''
        return [
            `${linePrefix}${'#'.repeat(node.level ?? 1)} ${firstLine}`,
            ...followingLines.map((followingLine) => `${linePrefix}${escapeMarkdownLineStart(followingLine)}`),
        ].join('\n')
    }
    if (node.type === 'paragraph') {
        return escapeMarkdownBlockLines(serializeInlineNodes(node.children))
    }
    if (node.type === 'blockquote') {
        return serializeInlineNodes(node.children)
            .split('\n')
            .map((line) => `> ${escapeMarkdownLineStart(line)}`)
            .join('\n')
    }
    if (node.type === 'list') {
        const orderedCounters: (number | undefined)[] = []
        const linePrefix = node.blockquote ? '> ' : ''
        return node.items
            .map((item) => {
                const depth = Math.max(0, item.depth)
                const ordered = item.ordered ?? node.ordered
                orderedCounters.length = depth + 1
                const start = item.start ?? (depth === 0 ? node.start : undefined) ?? 1
                const marker = ordered
                    ? `${orderedCounters[depth] === undefined ? start : orderedCounters[depth] + 1}.`
                    : '-'
                if (ordered) {
                    orderedCounters[depth] = orderedCounters[depth] === undefined ? start : orderedCounters[depth] + 1
                } else {
                    orderedCounters[depth] = undefined
                }
                const checkbox = !ordered && item.checked !== undefined ? (item.checked ? '[x] ' : '[ ] ') : ''
                return `${linePrefix}${'  '.repeat(depth)}${marker} ${checkbox}${serializeInlineNodes(
                    trimTrailingHardBreaks(item.children)
                )}`
            })
            .join('\n')
    }
    if (node.type === 'table') {
        const columnCount = getTableColumnCount(node)
        const headerCells = normalizeTableCells(node.headers, columnCount).map(serializeTableCell)
        const separatorCells = Array.from({ length: columnCount }, (_, index) =>
            serializeTableSeparatorCell(node.alignments?.[index])
        )
        const bodyRows = node.rows.map((row) => serializeTableRow(normalizeTableCells(row, columnCount)))

        return [serializeRawTableRow(headerCells), serializeRawTableRow(separatorCells), ...bodyRows].join('\n')
    }
    if (node.type === 'code') {
        // The fence must be longer than any backtick run in the content, so the content can't close it
        const fence = getCodeBlockFence(node.text)
        return `${fence}${serializeCodeBlockInfo(node)}\n${node.text}\n${fence}`
    }
    if (node.type === 'component' && node.errors?.length && node.raw) {
        // Props that failed to parse exist only in `raw` — re-emitting from `props` would
        // silently drop the malformed source on the next save
        return node.raw
    }
    if (node.type === 'component' && node.tagName === COMMENT_COMPONENT_TAG && !isDiscussionCommentProps(node.props)) {
        return serializeCommentNode(node)
    }
    if (node.type === 'component' && node.tagName === DIVIDER_COMPONENT_TAG) {
        return '---'
    }
    if (node.type === 'component' && node.tagName === 'Image') {
        return serializeImageNode(node)
    }
    if (node.type === 'component') {
        const multilineSource = getUnchangedMultilineComponentSource(node)
        if (multilineSource) {
            return multilineSource
        }
        return `<${node.tagName}${serializeComponentProps(node.props)} />`
    }
    return ''
}

function serializeDocumentNode(node: NotebookBlockNode, preserveEmptyParagraph: boolean): string {
    if (preserveEmptyParagraph && isEmptyParagraphNode(node)) {
        return EMPTY_PARAGRAPH_MARKDOWN
    }
    return serializeNode(node)
}

function isEmptyParagraphPlaceholderLine(line: string): boolean {
    return line === EMPTY_PARAGRAPH_MARKDOWN
}

function isEmptyParagraphNode(node: NotebookBlockNode | undefined): boolean {
    return !!node && node.type === 'paragraph' && node.children.length === 0
}

export function parseInlineMarkdown(markdown: string, marks: NotebookInlineMark[] = []): NotebookInlineNode[] {
    const nodes: NotebookInlineNode[] = []
    let index = 0

    const pushText = (text: string): void => {
        if (text) {
            nodes.push({ type: 'text', text, marks: marks.length ? [...marks] : undefined })
        }
    }

    while (index < markdown.length) {
        const character = markdown[index]

        if (character === '\n') {
            nodes.push({ type: 'hardBreak' })
            index += 1
            continue
        }

        if (character === '\\') {
            const nextCharacter = markdown[index + 1]
            if (nextCharacter !== undefined && INLINE_ESCAPABLE_CHARS.has(nextCharacter)) {
                pushText(nextCharacter)
                index += 2
                continue
            }
            pushText('\\')
            index += 1
            continue
        }

        const emphasis = matchEmphasisToken(markdown, index)
        if (emphasis) {
            const contentStart = index + emphasis.token.length
            const end = findEmphasisCloser(markdown, emphasis.token, contentStart, emphasis.requiresWordBoundary)
            if (end !== -1) {
                nodes.push(
                    ...parseInlineMarkdown(markdown.slice(contentStart, end), [...marks, { type: emphasis.markType }])
                )
                index = end + emphasis.token.length
                continue
            }
        }

        if (markdown.startsWith('<u>', index)) {
            const end = findTokenOutsideCodeSpans(markdown, '</u>', index + 3)
            if (end !== -1) {
                nodes.push(...parseInlineMarkdown(markdown.slice(index + 3, end), [...marks, { type: 'underline' }]))
                index = end + 4
                continue
            }
        }

        if (character === '<') {
            const inlineTag = parseInlineTag(markdown, index)
            if (inlineTag) {
                nodes.push(
                    ...parseInlineMarkdown(inlineTag.content, [...marks, { type: inlineTag.tagName, id: inlineTag.id }])
                )
                index = inlineTag.nextIndex
                continue
            }
        }

        if (character === '`') {
            const end = findUnescapedToken(markdown, '`', index + 1)
            if (end !== -1) {
                pushTextWithMarks(nodes, unescapeCodeSpanText(markdown.slice(index + 1, end)), [
                    ...marks,
                    { type: 'code' },
                ])
                index = end + 1
                continue
            }
        }

        if (character === '[') {
            const link = parseInlineLink(markdown, index)
            if (link) {
                nodes.push(
                    ...parseInlineMarkdown(
                        link.label,
                        link.href ? [...marks, { type: 'link', href: link.href }] : marks
                    )
                )
                index = link.nextIndex
                continue
            }
        }

        const nextSpecial = findNextInlineToken(markdown, index + 1)
        pushText(markdown.slice(index, nextSpecial))
        index = nextSpecial
    }

    return normalizeInlineNodes(nodes)
}

function matchEmphasisToken(markdown: string, index: number): InlineEmphasisToken | null {
    for (const emphasis of INLINE_EMPHASIS_TOKENS) {
        if (!markdown.startsWith(emphasis.token, index)) {
            continue
        }
        // A single `*`/`_` immediately followed by the same character is a doubled delimiter
        // whose closer was not found — treat it as literal rather than nesting into it.
        if (emphasis.token.length === 1 && markdown[index + 1] === emphasis.token) {
            continue
        }
        const contentStart = markdown[index + emphasis.token.length]
        if (contentStart === undefined || /\s/.test(contentStart)) {
            continue
        }
        if (emphasis.requiresWordBoundary && isAsciiAlphaNumeric(markdown[index - 1])) {
            continue
        }
        return emphasis
    }
    return null
}

function findEmphasisCloser(markdown: string, token: string, fromIndex: number, requiresWordBoundary: boolean): number {
    let searchIndex = fromIndex
    while (searchIndex < markdown.length) {
        const position = findTokenOutsideCodeSpans(markdown, token, searchIndex)
        if (position === -1) {
            return -1
        }

        const previousCharacter = markdown[position - 1]
        const followingCharacter = markdown[position + token.length]
        if (
            position > fromIndex &&
            previousCharacter !== undefined &&
            !/\s/.test(previousCharacter) &&
            (!requiresWordBoundary || !isAsciiAlphaNumeric(followingCharacter))
        ) {
            return position
        }
        searchIndex = position + 1
    }
    return -1
}

// Code spans bind tighter than other inline constructs — a token inside `...` doesn't count.
// Consumes complete code spans before the candidate and re-searches after them.
function findTokenOutsideCodeSpans(markdown: string, token: string, fromIndex: number): number {
    let searchIndex = fromIndex
    while (searchIndex < markdown.length) {
        const position = findUnescapedToken(markdown, token, searchIndex)
        if (position === -1) {
            return -1
        }

        const codeStart = findUnescapedToken(markdown, '`', searchIndex)
        if (codeStart !== -1 && codeStart < position) {
            const codeEnd = findUnescapedToken(markdown, '`', codeStart + 1)
            if (codeEnd !== -1) {
                searchIndex = codeEnd + 1
                continue
            }
        }

        return position
    }
    return -1
}

function findUnescapedToken(markdown: string, token: string, fromIndex: number): number {
    let position = markdown.indexOf(token, fromIndex)
    while (position !== -1) {
        let backslashCount = 0
        while (markdown[position - backslashCount - 1] === '\\') {
            backslashCount += 1
        }
        if (backslashCount % 2 === 0) {
            return position
        }
        position = markdown.indexOf(token, position + 1)
    }
    return -1
}

function parseInlineLink(
    markdown: string,
    index: number
): { label: string; href: string | null; nextIndex: number } | null {
    const labelEnd = findTokenOutsideCodeSpans(markdown, '](', index + 1)
    if (labelEnd === -1) {
        return null
    }

    const label = markdown.slice(index + 1, labelEnd)

    // CommonMark's pointy-bracket form, `[label](<href>)`. Slack writes links this way, so it
    // arrives with every link someone copies out of a Slack message.
    if (markdown[labelEnd + 2] === '<') {
        const hrefEnd = markdown.indexOf('>', labelEnd + 3)
        if (hrefEnd !== -1 && markdown[hrefEnd + 1] === ')') {
            return {
                label,
                href: sanitizeNotebookLinkHref(markdown.slice(labelEnd + 3, hrefEnd)),
                nextIndex: hrefEnd + 2,
            }
        }
    }

    // Hrefs may contain backslash-escaped characters and balanced parentheses (Wikipedia-style URLs)
    let cursor = labelEnd + 2
    let parenDepth = 0
    let rawHref = ''
    while (cursor < markdown.length) {
        const character = markdown[cursor]
        if (
            character === '\\' &&
            markdown[cursor + 1] !== undefined &&
            INLINE_ESCAPABLE_CHARS.has(markdown[cursor + 1])
        ) {
            rawHref += markdown[cursor + 1]
            cursor += 2
            continue
        }
        if (character === ')') {
            if (parenDepth === 0) {
                return {
                    label,
                    href: sanitizeNotebookLinkHref(rawHref),
                    nextIndex: cursor + 1,
                }
            }
            parenDepth -= 1
        }
        if (character === '(') {
            parenDepth += 1
        }
        rawHref += character
        cursor += 1
    }
    return null
}

/**
 * Parses an inline tag (`<ref id="x">…</ref>`, `<mention id="5">…</mention>`) at `index`.
 * A tag without a well-formed opener or matching closer is not a tag — the text stays
 * literal, so nothing a user types can ever be swallowed.
 */
function parseInlineTag(
    markdown: string,
    index: number
): { tagName: InlineTagName; id: string; content: string; nextIndex: number } | null {
    const openMatch = markdown.slice(index).match(INLINE_TAG_OPEN_REGEX)
    if (!openMatch) {
        return null
    }

    const tagName = openMatch[1] as InlineTagName
    const id = (openMatch[2] ?? openMatch[3] ?? '').replace(/\\(.)/g, '$1')
    const contentStart = index + openMatch[0].length
    const closeToken = `</${tagName}>`
    const end = findTokenOutsideCodeSpans(markdown, closeToken, contentStart)
    if (end === -1 || !id) {
        return null
    }

    return {
        tagName,
        id,
        content: markdown.slice(contentStart, end),
        nextIndex: end + closeToken.length,
    }
}

function isAsciiAlphaNumeric(character: string | undefined): boolean {
    return !!character && /[A-Za-z0-9]/.test(character)
}

export function serializeInlineNodes(nodes: NotebookInlineNode[]): string {
    return nodes.map(serializeInlineNode).join('')
}

export function htmlElementToInlineNodes(element: HTMLElement): NotebookInlineNode[] {
    return normalizeInlineNodes(htmlChildNodesToInlineNodes(element, []))
}

export function inlineNodesToHtml(nodes: NotebookInlineNode[]): string {
    return nodes.map(inlineNodeToHtml).join('')
}

export function sanitizeNotebookLinkHref(href: string): string | null {
    const trimmedHref = href.trim()
    if (!/^https?:\/\/\S+$/i.test(trimmedHref)) {
        return null
    }

    try {
        const url = new URL(trimmedHref)
        return url.protocol === 'http:' || url.protocol === 'https:' ? trimmedHref : null
    } catch {
        return null
    }
}

function parseBlock(lines: string[], lineIndex: number): BlockParseResult {
    const line = lines[lineIndex]
    const trimmed = line.trim()

    if (trimmed.startsWith('```')) {
        return parseCodeBlock(lines, lineIndex)
    }

    if (IMAGE_BLOCK_REGEX.test(trimmed)) {
        return parseImageBlock(lines, lineIndex)
    }

    if (DIVIDER_BLOCK_REGEX.test(trimmed)) {
        return {
            node: { id: '', type: 'component', tagName: DIVIDER_COMPONENT_TAG, props: {} },
            nextLineIndex: lineIndex + 1,
        }
    }

    if (trimmed.startsWith('<!--')) {
        const commentEndLineIndex = getCommentBlockEndLine(lines, lineIndex)
        if (commentEndLineIndex !== null) {
            return parseCommentBlock(lines, lineIndex, commentEndLineIndex)
        }
    }

    if (COMPONENT_START_REGEX.test(trimmed)) {
        const parsedComponent = parseComponentBlock(lines, lineIndex)
        const parsedNode = parsedComponent.node
        if (parsedNode?.type === 'component' && !parsedNode.errors?.length) {
            return parsedComponent
        }
        return parseRecoveredMultilineComponentBlock(lines, lineIndex) ?? parsedComponent
    }

    if (ESCAPED_COMPONENT_START_REGEX.test(trimmed)) {
        const recoveredComponent = parseRecoveredMultilineComponentBlock(lines, lineIndex)
        if (recoveredComponent) {
            return recoveredComponent
        }
    }

    const headingMatch = line.match(HEADING_REGEX)
    if (headingMatch) {
        return {
            node: {
                id: '',
                type: 'heading',
                level: headingMatch[1].length as NotebookTextBlockNode['level'],
                children: parseInlineMarkdown(headingMatch[2]),
            },
            nextLineIndex: lineIndex + 1,
        }
    }

    if (isTableStart(lines, lineIndex)) {
        return parseTableBlock(lines, lineIndex)
    }

    if (ORDERED_LIST_REGEX.test(line) || BULLET_LIST_REGEX.test(line)) {
        return parseListBlock(lines, lineIndex)
    }

    if (trimmed.startsWith('>')) {
        if (isListLine(stripBlockquoteMarker(line))) {
            return parseBlockquotedListBlock(lines, lineIndex)
        }
        if (COMPONENT_START_REGEX.test(stripAllBlockquoteMarkers(line))) {
            return parseBlockquotedComponentBlock(lines, lineIndex)
        }

        // The heading marker needs its trailing space (`> ## `), which stripBlockquoteMarker trims.
        const quotedHeadingMatch = line.replace(/^\s*>\s?/, '').match(HEADING_REGEX)
        if (quotedHeadingMatch) {
            return {
                node: {
                    id: '',
                    type: 'heading',
                    level: quotedHeadingMatch[1].length as NotebookTextBlockNode['level'],
                    blockquote: true,
                    children: parseInlineMarkdown(quotedHeadingMatch[2]),
                },
                nextLineIndex: lineIndex + 1,
            }
        }

        const quoteLines: string[] = []
        let nextLineIndex = lineIndex
        while (
            nextLineIndex < lines.length &&
            lines[nextLineIndex].trim().startsWith('>') &&
            !isListLine(stripBlockquoteMarker(lines[nextLineIndex])) &&
            !HEADING_REGEX.test(lines[nextLineIndex].replace(/^\s*>\s?/, '')) &&
            !COMPONENT_START_REGEX.test(stripAllBlockquoteMarkers(lines[nextLineIndex]))
        ) {
            quoteLines.push(stripBlockquoteMarker(lines[nextLineIndex]))
            nextLineIndex += 1
        }
        return {
            node: {
                id: '',
                type: 'blockquote',
                children: parseInlineMarkdown(quoteLines.join('\n')),
            },
            nextLineIndex,
        }
    }

    return parseParagraphBlock(lines, lineIndex)
}

function parseRecoveredMultilineComponentBlock(lines: string[], lineIndex: number): BlockParseResult | null {
    const recoveredComponent = parseComponentBlock(lines, lineIndex, true)
    const recoveredNode = recoveredComponent.node
    return recoveredNode?.type === 'component' &&
        recoveredComponent.nextLineIndex > lineIndex + 1 &&
        !recoveredNode.errors?.length
        ? recoveredComponent
        : null
}

function parseParagraphBlock(lines: string[], lineIndex: number): BlockParseResult {
    const paragraphLines: string[] = []
    let nextLineIndex = lineIndex

    while (nextLineIndex < lines.length) {
        const line = lines[nextLineIndex]
        const trimmed = line.trim()
        if (
            !trimmed ||
            trimmed.startsWith('```') ||
            IMAGE_BLOCK_REGEX.test(trimmed) ||
            DIVIDER_BLOCK_REGEX.test(trimmed) ||
            (trimmed.startsWith('<!--') && getCommentBlockEndLine(lines, nextLineIndex) !== null) ||
            COMPONENT_START_REGEX.test(trimmed) ||
            HEADING_REGEX.test(line) ||
            isTableStart(lines, nextLineIndex) ||
            ORDERED_LIST_REGEX.test(line) ||
            BULLET_LIST_REGEX.test(line) ||
            trimmed.startsWith('>')
        ) {
            break
        }
        paragraphLines.push(line)
        nextLineIndex += 1
    }

    return {
        node: {
            id: '',
            type: 'paragraph',
            children: parseInlineMarkdown(paragraphLines.join('\n')),
        },
        nextLineIndex,
    }
}

function isListLine(line: string): boolean {
    return ORDERED_LIST_REGEX.test(line) || BULLET_LIST_REGEX.test(line)
}

function stripBlockquoteMarker(line: string): string {
    return line.trim().replace(/^>\s?/, '')
}

function stripAllBlockquoteMarkers(line: string): string {
    let stripped = stripBlockquoteMarker(line)
    while (stripped.trim().startsWith('>')) {
        stripped = stripBlockquoteMarker(stripped)
    }
    return stripped
}

// Component tags have no blockquote representation in this model, so a quoted tag line (as
// produced by older legacy-notebook conversions, e.g. `> <Query … />`) is parsed as the
// component itself, broken out of the quote. Treating it as quote text would degrade the tag
// to escaped literal text on the next save, permanently destroying the node.
function parseBlockquotedComponentBlock(lines: string[], lineIndex: number): BlockParseResult {
    const strippedLines: string[] = []
    let end = lineIndex
    while (end < lines.length && lines[end].trim().startsWith('>')) {
        strippedLines.push(stripAllBlockquoteMarkers(lines[end]))
        end += 1
    }

    const result = parseComponentBlock(strippedLines, 0)
    return {
        ...result,
        nextLineIndex: lineIndex + result.nextLineIndex,
        error: result.error ? { ...result.error, line: lineIndex + result.error.line } : undefined,
    }
}

function parseBlockquotedListBlock(lines: string[], lineIndex: number): BlockParseResult {
    const listLines: string[] = []
    let nextLineIndex = lineIndex
    while (nextLineIndex < lines.length) {
        const line = lines[nextLineIndex]
        if (!line.trim().startsWith('>') || !isListLine(stripBlockquoteMarker(line))) {
            break
        }
        listLines.push(stripBlockquoteMarker(line))
        nextLineIndex += 1
    }

    const result = parseListBlock(listLines, 0)
    return {
        node: { ...result.node, blockquote: true } as NotebookListBlockNode,
        nextLineIndex: lineIndex + result.nextLineIndex,
    }
}

function parseListBlock(lines: string[], lineIndex: number): BlockParseResult {
    const ordered = ORDERED_LIST_REGEX.test(lines[lineIndex])
    const items: NotebookListBlockNode['items'] = []
    let nextLineIndex = lineIndex

    while (nextLineIndex < lines.length) {
        const line = lines[nextLineIndex]
        const listItem = parseListItemLine(line, nextLineIndex - lineIndex)
        if (!listItem) {
            break
        }
        items.push(listItem)
        nextLineIndex += 1
    }

    // External markdown indents nested items by 2-4 spaces (or marker width); clamp each item
    // to at most one level deeper than the previous so 4-space nesting doesn't double the depth
    let previousDepth = -1
    for (const item of items) {
        item.depth = Math.min(item.depth, previousDepth + 1)
        previousDepth = item.depth
    }

    return {
        node: {
            id: '',
            type: 'list',
            ordered,
            start: ordered ? items.find((item) => item.depth === 0 && item.ordered)?.start : undefined,
            items,
        },
        nextLineIndex,
    }
}

function parseListItemLine(line: string, listItemIndex: number): NotebookListBlockNode['items'][number] | null {
    const match = line.match(LIST_ITEM_REGEX)
    if (!match) {
        return null
    }

    const orderedMatch = match[2].match(/^(\d+)[.)]$/)
    // GFM task markers only apply to bullet items — `1. [x]` stays literal text
    const taskMatch = orderedMatch ? null : (match[3] ?? '').match(TASK_LIST_ITEM_REGEX)

    return {
        id: createStableNodeId(`list-item:${String(listItemIndex)}:${line}`, 0),
        children: parseInlineMarkdown(taskMatch ? (taskMatch[2] ?? '') : (match[3] ?? '')),
        depth: getListItemDepth(match[1]),
        ordered: orderedMatch !== null,
        start: orderedMatch ? Number(orderedMatch[1]) : undefined,
        checked: taskMatch ? taskMatch[1].toLowerCase() === 'x' : undefined,
    }
}

function getListItemDepth(indentation: string): number {
    const columns = [...indentation].reduce((total, character) => total + (character === '\t' ? 4 : 1), 0)
    return Math.floor(columns / 2)
}

function isTableStart(lines: string[], lineIndex: number): boolean {
    // Require a leading pipe so prose that merely contains a `|` can't become a table header
    if (!(lines[lineIndex] ?? '').trim().startsWith('|')) {
        return false
    }

    const headerCells = splitMarkdownTableRow(lines[lineIndex] ?? '')
    const separatorCells = splitMarkdownTableRow(lines[lineIndex + 1] ?? '')

    return headerCells.length >= 1 && separatorCells.length >= 1 && separatorCells.every(isTableSeparatorCell)
}

function parseTableBlock(lines: string[], lineIndex: number): BlockParseResult {
    const headers = splitMarkdownTableRow(lines[lineIndex]).map(parseTableCell)
    const alignments = splitMarkdownTableRow(lines[lineIndex + 1]).map(parseTableAlignment)
    const rows: NotebookTableBlockNode['rows'] = []
    let nextLineIndex = lineIndex + 2

    while (nextLineIndex < lines.length) {
        // Rows must start with a pipe — a following paragraph containing a `|` is not a row
        if (!lines[nextLineIndex].trim().startsWith('|')) {
            break
        }
        const cells = splitMarkdownTableRow(lines[nextLineIndex])
        if (cells.length < 1) {
            break
        }
        rows.push(cells.map(parseTableCell))
        nextLineIndex += 1
    }

    return {
        node: {
            id: '',
            type: 'table',
            headers,
            rows,
            alignments,
        },
        nextLineIndex,
    }
}

function splitMarkdownTableRow(line: string): string[] {
    if (!line.includes('|')) {
        return []
    }

    const cells: string[] = []
    let cell = ''
    let source = line.trim()
    if (source.startsWith('|')) {
        source = source.slice(1)
    }
    if (source.endsWith('|')) {
        source = source.slice(0, -1)
    }

    for (let index = 0; index < source.length; index++) {
        const character = source[index]
        if (character === '\\' && source[index + 1] === '|') {
            cell += '|'
            index += 1
            continue
        }
        if (character === '|') {
            cells.push(cell.trim())
            cell = ''
            continue
        }
        cell += character
    }
    cells.push(cell.trim())

    return cells
}

function isTableSeparatorCell(cell: string): boolean {
    return TABLE_SEPARATOR_CELL_REGEX.test(cell.trim())
}

function parseTableAlignment(cell: string): NotebookTableAlignment | undefined {
    const trimmedCell = cell.trim()
    const alignsLeft = trimmedCell.startsWith(':')
    const alignsRight = trimmedCell.endsWith(':')
    if (alignsLeft && alignsRight) {
        return 'center'
    }
    if (alignsLeft) {
        return 'left'
    }
    if (alignsRight) {
        return 'right'
    }
    return undefined
}

function parseTableCell(cell: string): NotebookTableCell {
    return { children: parseInlineMarkdown(cell) }
}

function getTableColumnCount(node: NotebookTableBlockNode): number {
    return Math.max(1, node.headers.length, node.alignments?.length ?? 0, ...node.rows.map((row) => row.length))
}

function normalizeTableCells(cells: NotebookTableCell[], columnCount: number): NotebookTableCell[] {
    return Array.from({ length: columnCount }, (_, index) => cells[index] ?? { children: [] })
}

function serializeTableRow(cells: NotebookTableCell[]): string {
    return serializeRawTableRow(cells.map(serializeTableCell))
}

function serializeRawTableRow(cells: string[]): string {
    return `| ${cells.join(' | ')} |`
}

function serializeTableCell(cell: NotebookTableCell): string {
    // Pipes in plain text are already escaped by escapeInlineMarkdownText; this pass only
    // covers pipes inside code spans (skipping `\X` pairs so they aren't double-escaped)
    return serializeInlineNodes(trimTrailingHardBreaks(cell.children))
        .replace(/\\[\s\S]|\|/g, (match) => (match === '|' ? '\\|' : match))
        .replace(/\n/g, ' ')
}

function serializeTableSeparatorCell(alignment: NotebookTableAlignment | undefined): string {
    if (alignment === 'left') {
        return ':---'
    }
    if (alignment === 'center') {
        return ':---:'
    }
    if (alignment === 'right') {
        return '---:'
    }
    return '---'
}

/** A comment anchor in a fence info string: `ref=<id>:<start>-<end>`. */
const CODE_BLOCK_REF_TOKEN_REGEX = /^ref=([A-Za-z0-9_-]+):(\d+)-(\d+)$/

function serializeCodeBlockInfo(node: NotebookCodeBlockNode): string {
    const refTokens = (node.refs ?? [])
        .filter((ref) => ref.start >= 0 && ref.start < node.text.length && ref.end > ref.start)
        .map((ref) => `ref=${ref.id}:${ref.start}-${Math.min(ref.end, node.text.length)}`)
    return [node.language ?? '', ...refTokens].filter(Boolean).join(' ')
}

function parseCodeBlockInfo(info: string): { language?: string; refs: NotebookCodeRefMark[] } {
    if (!info) {
        return { language: undefined, refs: [] }
    }

    const refs: NotebookCodeRefMark[] = []
    const languageTokens: string[] = []
    for (const token of info.split(/\s+/)) {
        const refMatch = token.match(CODE_BLOCK_REF_TOKEN_REGEX)
        if (refMatch) {
            refs.push({ id: refMatch[1], start: Number(refMatch[2]), end: Number(refMatch[3]) })
            continue
        }
        languageTokens.push(token)
    }

    return { language: languageTokens.join(' ') || undefined, refs }
}

function parseCodeBlock(lines: string[], lineIndex: number): BlockParseResult {
    const startLine = lines[lineIndex].trim()
    const fenceLength = startLine.match(/^`+/)?.[0].length ?? 3
    // Only a bare fence at least as long as the opener closes the block, so shorter
    // fences (or fences with info strings) inside the code stay part of the content
    const closingFenceRegex = new RegExp(`^\`{${fenceLength},}$`)
    const { language, refs } = parseCodeBlockInfo(startLine.slice(fenceLength).trim())
    const codeLines: string[] = []
    let nextLineIndex = lineIndex + 1

    while (nextLineIndex < lines.length && !closingFenceRegex.test(lines[nextLineIndex].trim())) {
        codeLines.push(lines[nextLineIndex])
        nextLineIndex += 1
    }

    const text = codeLines.join('\n')
    const validRefs = refs
        .map((ref) => ({ ...ref, end: Math.min(ref.end, text.length) }))
        .filter((ref) => ref.start >= 0 && ref.start < text.length && ref.end > ref.start)

    return {
        node: {
            id: '',
            type: 'code',
            language,
            text,
            ...(validRefs.length ? { refs: validRefs } : {}),
        },
        nextLineIndex: nextLineIndex < lines.length ? nextLineIndex + 1 : nextLineIndex,
        error:
            nextLineIndex >= lines.length
                ? {
                      message: 'Unclosed code block',
                      raw: lines.slice(lineIndex).join('\n'),
                      line: lineIndex + 1,
                  }
                : undefined,
    }
}

/**
 * A comment block is `<!--` … `-->` where the closing marker ends its line; when `-->`
 * has trailing content (or never appears) the text stays a paragraph so nothing is
 * ever swallowed. Comments may span lines, including blank ones.
 */
function getCommentBlockEndLine(lines: string[], lineIndex: number): number | null {
    for (let index = lineIndex; index < lines.length; index++) {
        const trimmed = lines[index].trim()
        const markerIndex = trimmed.indexOf('-->', index === lineIndex ? 4 : 0)
        if (markerIndex !== -1) {
            return markerIndex === trimmed.length - 3 ? index : null
        }
    }
    return null
}

function parseCommentBlock(lines: string[], lineIndex: number, endLineIndex: number): BlockParseResult {
    const raw = lines
        .slice(lineIndex, endLineIndex + 1)
        .join('\n')
        .trim()
    const text = raw.slice(4, raw.length - 3).trim()

    return {
        node: { id: '', type: 'component', tagName: COMMENT_COMPONENT_TAG, props: { text } },
        nextLineIndex: endLineIndex + 1,
    }
}

function serializeCommentNode(node: NotebookComponentBlockNode): string {
    const text = typeof node.props.text === 'string' ? node.props.text : ''
    // `-->` inside the text would close the comment early, so it is broken apart
    const safeText = text.replace(/-->/g, '-- >').trim()
    return `<!-- ${safeText} -->`
}

function parseImageBlock(lines: string[], lineIndex: number): BlockParseResult {
    const match = lines[lineIndex].trim().match(IMAGE_BLOCK_REGEX)

    return {
        node: {
            id: '',
            type: 'component',
            tagName: 'Image',
            props: {
                alt: unescapeMarkdownImageValue(match?.[1] ?? ''),
                src: unescapeMarkdownImageValue(match?.[2] ?? ''),
            },
        },
        nextLineIndex: lineIndex + 1,
    }
}

function parseComponentBlock(
    lines: string[],
    lineIndex: number,
    recoverEscapedSource: boolean = false
): BlockParseResult {
    const firstLine = getComponentSourceLine(lines[lineIndex], recoverEscapedSource).trim()
    const tagName = firstLine.match(/^<([A-Z][A-Za-z0-9]*)/)?.[1]

    if (!tagName) {
        const raw = firstLine
        return {
            node: makeComponentFallbackParagraph(raw),
            nextLineIndex: lineIndex + 1,
            error: { message: 'Unclosed component tag', raw, line: lineIndex + 1 },
        }
    }

    const scan = scanComponentBlock(lines, lineIndex, tagName, recoverEscapedSource)
    if (!scan.foundTerminator) {
        const singleLineComponent = parseComponentTag(firstLine)
        if (singleLineComponent.node) {
            return {
                node: singleLineComponent.node,
                nextLineIndex: lineIndex + 1,
            }
        }

        return {
            node: makeComponentFallbackParagraph(scan.raw),
            nextLineIndex: scan.nextLineIndex,
            error: { message: 'Unclosed component tag', raw: scan.raw, line: lineIndex + 1 },
        }
    }

    const parsed = parseComponentTag(scan.raw)
    return {
        // A malformed tag degrades to a paragraph holding the raw source — source text must
        // never be dropped from the node tree, or the next save destroys it
        node: parsed.node ?? makeComponentFallbackParagraph(scan.raw),
        nextLineIndex: scan.nextLineIndex,
        error: parsed.error ? { ...parsed.error, line: lineIndex + 1 } : undefined,
    }
}

function scanComponentBlock(
    lines: string[],
    lineIndex: number,
    tagName: string,
    recoverEscapedSource: boolean
): ComponentScanResult {
    const rawLines: string[] = []
    const state: ComponentScanState = {
        quote: null,
        expressionDepth: 0,
        escapeNext: false,
        awaitingPropValue: false,
        openingTagClosed: false,
    }
    let characterCount = 0
    let nextLineIndex = lineIndex
    let fallbackRawLineCount: number | null = null
    let fallbackNextLineIndex: number | null = null
    const lineLimit = Math.min(lines.length, lineIndex + MAX_COMPONENT_BLOCK_LINES)

    while (nextLineIndex < lineLimit) {
        const line = getComponentSourceLine(lines[nextLineIndex], recoverEscapedSource)
        if (nextLineIndex > lineIndex && !line.trim() && fallbackNextLineIndex === null) {
            fallbackRawLineCount = rawLines.length
            fallbackNextLineIndex = nextLineIndex
        }
        if (isComponentBlankLineBoundary(line, nextLineIndex, lineIndex, state)) {
            break
        }

        const separatorLength = rawLines.length ? 1 : 0
        if (isComponentCharacterLimitReached(rawLines, characterCount, separatorLength, line)) {
            break
        }
        characterCount += separatorLength + line.length
        rawLines.push(line)

        let characterIndex = 0
        while (characterIndex < line.length) {
            const character = line[characterIndex]

            if (state.openingTagClosed) {
                if (isComponentClosingTag(line, characterIndex, tagName)) {
                    return {
                        raw: rawLines.join('\n').trim(),
                        nextLineIndex: nextLineIndex + 1,
                        foundTerminator: true,
                    }
                }
                characterIndex += 1
                continue
            }

            if (isComponentSelfClosingTag(line, characterIndex, state)) {
                return {
                    raw: rawLines.join('\n').trim(),
                    nextLineIndex: nextLineIndex + 1,
                    foundTerminator: true,
                }
            }
            advanceComponentScan(state, character)
            characterIndex += 1
        }

        // Joined source contains a newline here. It consumes a pending escape without closing
        // the quoted value, matching the prop parser's treatment of backslash-newline.
        consumeComponentScanLineBreak(state)
        nextLineIndex += 1
    }

    const fallbackRawLines = fallbackRawLineCount === null ? rawLines : rawLines.slice(0, fallbackRawLineCount)
    return {
        raw: fallbackRawLines.join('\n').trim(),
        nextLineIndex: fallbackNextLineIndex ?? nextLineIndex,
        foundTerminator: false,
    }
}

function getComponentSourceLine(line: string, recoverEscapedSource: boolean): string {
    if (!recoverEscapedSource) {
        return line
    }

    let source = ''
    let index = 0
    while (index < line.length) {
        const character = line[index]
        const nextCharacter = line[index + 1]
        if (character === '\\' && nextCharacter !== undefined && INLINE_ESCAPABLE_CHARS.has(nextCharacter)) {
            source += nextCharacter
            index += 2
        } else {
            source += character
            index += 1
        }
    }
    return source
}

function isComponentBlankLineBoundary(
    line: string,
    nextLineIndex: number,
    lineIndex: number,
    state: ComponentScanState
): boolean {
    return nextLineIndex > lineIndex && !line.trim() && state.quote === null && state.expressionDepth === 0
}

function isComponentCharacterLimitReached(
    rawLines: string[],
    characterCount: number,
    separatorLength: number,
    line: string
): boolean {
    return rawLines.length > 0 && characterCount + separatorLength + line.length > MAX_COMPONENT_BLOCK_CHARACTERS
}

function isComponentClosingTag(line: string, characterIndex: number, tagName: string): boolean {
    const closingTag = `</${tagName}>`
    return line.startsWith(closingTag, characterIndex) && !line.slice(characterIndex + closingTag.length).trim()
}

function isComponentSelfClosingTag(line: string, characterIndex: number, state: ComponentScanState): boolean {
    return (
        state.quote === null &&
        state.expressionDepth === 0 &&
        line.startsWith('/>', characterIndex) &&
        !line.slice(characterIndex + 2).trim()
    )
}

function advanceComponentScan(state: ComponentScanState, character: string): void {
    if (state.quote !== null) {
        advanceComponentQuote(state, character)
        return
    }

    if (state.expressionDepth > 0) {
        advanceComponentExpression(state, character)
        return
    }

    if (state.awaitingPropValue) {
        if (/\s/.test(character)) {
            return
        }
        state.awaitingPropValue = false
        if (character === '"' || character === "'") {
            state.quote = character
            return
        }
        if (character === '{') {
            state.expressionDepth = 1
            return
        }
    }

    if (character === '=') {
        state.awaitingPropValue = true
    } else if (character === '>') {
        state.openingTagClosed = true
    }
}

function advanceComponentQuote(state: ComponentScanState, character: string): void {
    if (state.escapeNext) {
        state.escapeNext = false
    } else if (character === '\\') {
        state.escapeNext = true
    } else if (character === state.quote) {
        state.quote = null
    }
}

function advanceComponentExpression(state: ComponentScanState, character: string): void {
    if (character === '"' || character === "'") {
        state.quote = character
    } else if (character === '{') {
        state.expressionDepth += 1
    } else if (character === '}') {
        state.expressionDepth -= 1
    }
}

function consumeComponentScanLineBreak(state: ComponentScanState): void {
    if (state.quote !== null && state.escapeNext) {
        state.escapeNext = false
    }
}

function makeComponentFallbackParagraph(raw: string): NotebookTextBlockNode {
    const children: NotebookInlineNode[] = []
    raw.split('\n').forEach((line, index) => {
        if (index > 0) {
            children.push({ type: 'hardBreak' })
        }
        if (line) {
            children.push({ type: 'text', text: line })
        }
    })

    return {
        id: '',
        type: 'paragraph',
        children: normalizeInlineNodes(children),
    }
}

// Parsing a component tag JSON-decodes its props and fingerprinting re-encodes them, so for a
// cell that stores a result envelope both costs track the stored result, not the code. Every
// document parse re-reads every tag, so an unchanged tag (identical raw source) reuses the
// previously parsed node and its fingerprint. Prop objects are shared between the copies; that
// is safe because parsed props are never mutated in place (edits build new props objects).
// Evicted oldest-first under a total size budget, since one tag can carry large cached results.
const COMPONENT_TAG_CACHE_MAX_ENTRIES = 512
const COMPONENT_TAG_CACHE_MAX_TOTAL_CHARS = 16_000_000
const componentTagCache = new Map<string, { node: NotebookComponentBlockNode; fingerprint: string }>()
let componentTagCacheTotalChars = 0

function parseComponentTag(raw: string): { node: NotebookComponentBlockNode | null; error?: NotebookParseError } {
    const cached = componentTagCache.get(raw)
    if (cached) {
        componentTagCache.delete(raw)
        componentTagCache.set(raw, cached)
        // A shallow copy per use: the parse assigns each occurrence its own id, and the cached
        // template must not see that (or any later startsGroup flag).
        const node = { ...cached.node }
        seedNodeFingerprint(node, cached.fingerprint)
        return { node }
    }

    const match = raw.match(/^<([A-Z][A-Za-z0-9]*)([\s\S]*?)(?:\/>|>[\s\S]*<\/\1>)$/)
    if (!match) {
        return {
            node: null,
            error: {
                message: 'Invalid notebook component tag',
                raw,
                line: 0,
            },
        }
    }

    const propParseResult = parseComponentProps(match[2] ?? '')
    const node: NotebookComponentBlockNode = {
        id: '',
        type: 'component',
        tagName: match[1],
        props: propParseResult.props,
        raw,
        errors: propParseResult.errors.length ? propParseResult.errors : undefined,
    }
    componentTagCache.set(raw, { node: { ...node }, fingerprint: getNodeFingerprint(node) })
    componentTagCacheTotalChars += raw.length
    while (
        componentTagCache.size > COMPONENT_TAG_CACHE_MAX_ENTRIES ||
        componentTagCacheTotalChars > COMPONENT_TAG_CACHE_MAX_TOTAL_CHARS
    ) {
        const oldestRaw = componentTagCache.keys().next().value
        if (oldestRaw === undefined) {
            break
        }
        componentTagCache.delete(oldestRaw)
        componentTagCacheTotalChars -= oldestRaw.length
    }
    return { node }
}

function parseComponentProps(source: string): PropParseResult {
    const props: NotebookComponentProps = {}
    const errors: string[] = []
    let index = 0

    while (index < source.length) {
        while (/\s/.test(source[index] ?? '')) {
            index += 1
        }
        if (index >= source.length) {
            break
        }

        const nameMatch = source.slice(index).match(/^([A-Za-z_][A-Za-z0-9_-]*)/)
        if (!nameMatch) {
            errors.push(`Could not parse props near: ${source.slice(index, index + 24)}`)
            break
        }

        const name = nameMatch[1]
        index += name.length
        while (/\s/.test(source[index] ?? '')) {
            index += 1
        }

        if (source[index] !== '=') {
            props[name] = true
            continue
        }

        index += 1
        while (/\s/.test(source[index] ?? '')) {
            index += 1
        }

        const parsedValue = readPropValue(source, index)
        index = parsedValue.nextIndex

        if (parsedValue.error) {
            errors.push(parsedValue.error)
            continue
        }

        if (isNotebookPropValue(parsedValue.value)) {
            props[name] = parsedValue.value
        } else {
            errors.push(`Unsupported value for prop "${name}"`)
        }
    }

    return { props, errors }
}

function readPropValue(source: string, index: number): { value: unknown; nextIndex: number; error?: string } {
    const firstChar = source[index]

    if (firstChar === '"' || firstChar === "'") {
        const quote = firstChar
        let nextIndex = index + 1
        let value = ''
        while (nextIndex < source.length) {
            const char = source[nextIndex]
            if (char === '\\' && nextIndex + 1 < source.length) {
                value += source[nextIndex + 1]
                nextIndex += 2
                continue
            }
            if (char === quote) {
                if (quote === '"') {
                    try {
                        const parsedValue = JSON.parse(source.slice(index, nextIndex + 1))
                        if (typeof parsedValue === 'string') {
                            return { value: decodeHtmlEntities(parsedValue), nextIndex: nextIndex + 1 }
                        }
                    } catch {
                        // Fall through to the permissive parser for legacy hand-written values.
                    }
                }
                return { value: decodeHtmlEntities(value), nextIndex: nextIndex + 1 }
            }
            value += char
            nextIndex += 1
        }
        return { value: null, nextIndex, error: 'Unclosed quoted prop value' }
    }

    if (firstChar === '{') {
        const balanced = readBalancedExpression(source, index)
        if (!balanced) {
            return { value: null, nextIndex: source.length, error: 'Unclosed expression prop value' }
        }
        return {
            value: parseExpressionValue(balanced.value),
            nextIndex: balanced.nextIndex,
        }
    }

    const rawMatch = source.slice(index).match(/^([^\s/>]+)/)
    const raw = rawMatch?.[1] ?? ''
    return {
        value: parseExpressionValue(raw),
        nextIndex: index + raw.length,
    }
}

function readBalancedExpression(source: string, index: number): { value: string; nextIndex: number } | null {
    let depth = 0
    let nextIndex = index
    let quote: string | null = null

    while (nextIndex < source.length) {
        const char = source[nextIndex]
        const previousChar = source[nextIndex - 1]

        if (quote) {
            if (char === quote && previousChar !== '\\') {
                quote = null
            }
            nextIndex += 1
            continue
        }

        if (char === '"' || char === "'") {
            quote = char
            nextIndex += 1
            continue
        }

        if (char === '{') {
            depth += 1
        }
        if (char === '}') {
            depth -= 1
            if (depth === 0) {
                return {
                    value: source.slice(index, nextIndex + 1),
                    nextIndex: nextIndex + 1,
                }
            }
        }
        nextIndex += 1
    }

    return null
}

function parseExpressionValue(raw: string): unknown {
    const trimmed = raw.trim()
    const unwrapped = trimmed.startsWith('{') && trimmed.endsWith('}') ? trimmed.slice(1, -1).trim() : trimmed

    if (unwrapped === 'true') {
        return true
    }
    if (unwrapped === 'false') {
        return false
    }
    if (unwrapped === 'null') {
        return null
    }
    if (/^-?\d+(\.\d+)?$/.test(unwrapped)) {
        return Number(unwrapped)
    }

    try {
        return JSON.parse(unwrapped)
    } catch {
        return trimmed
    }
}

function serializeComponentProps(props: NotebookComponentProps): string {
    const serialized = getOrderedComponentPropEntries(getSerializableComponentProps(props))
        .filter(([, value]) => value !== undefined)
        .map(([key, value]) => (value === true ? ` ${key}` : ` ${key}=${serializePropValue(value)}`))
        .join('')
    return serialized
}

function getUnchangedMultilineComponentSource(node: NotebookComponentBlockNode): string | null {
    if (!node.raw?.includes('\n')) {
        return null
    }

    const parsed = parseComponentTag(node.raw)
    if (!parsed.node || parsed.node.errors?.length) {
        return null
    }

    return getNodeFingerprint(parsed.node) === getNodeFingerprint(node) ? node.raw : null
}

function getSerializableComponentProps(props: NotebookComponentProps): NotebookComponentProps {
    const nextProps = Object.entries(props).reduce<NotebookComponentProps>((accumulator, [key, value]) => {
        if (
            (key !== 'view' || typeof value !== 'boolean') &&
            key !== 'edit' &&
            key !== 'hideFilters' &&
            key !== 'hideResults' &&
            key !== 'showFilters' &&
            key !== 'showResults'
        ) {
            accumulator[key] = value
        }
        return accumulator
    }, {})
    const legacyViewPanelVisible = typeof props.view === 'boolean' ? props.view : undefined
    const showFilters = props.showFilters === true
    const showResults =
        typeof props.showResults === 'boolean'
            ? props.showResults
            : props.hideResults === true
              ? false
              : (legacyViewPanelVisible ?? true)

    if (showFilters) {
        nextProps.showFilters = true
    }
    if (!showResults) {
        nextProps.hideResults = true
    }

    return nextProps
}

function getOrderedComponentPropEntries(props: NotebookComponentProps): [string, NotebookPropValue][] {
    const entries = Object.entries(props)
    const orderedKeys = ['showFilters', 'hideResults']
    return [
        ...orderedKeys.flatMap((key): [string, NotebookPropValue][] =>
            Object.prototype.hasOwnProperty.call(props, key) ? [[key, props[key]]] : []
        ),
        ...entries.filter(([key]) => !orderedKeys.includes(key)),
    ]
}

// The whole tag re-serializes when any prop changes, so a big unchanged value (the result
// envelope of a cell whose code is being typed into) would re-encode on every keystroke.
// Keyed by object identity, which is safe because prop values are never mutated in place.
const serializedPropObjectCache = new WeakMap<object, string>()

function serializePropValue(value: NotebookPropValue): string {
    if (typeof value === 'string') {
        return JSON.stringify(value)
    }
    if (typeof value === 'number' || typeof value === 'boolean' || value === null) {
        return `{${String(value)}}`
    }
    const cachedValue = serializedPropObjectCache.get(value)
    if (cachedValue !== undefined) {
        return cachedValue
    }
    const serialized = `{${JSON.stringify(value)}}`
    serializedPropObjectCache.set(value, serialized)
    return serialized
}

function serializeImageNode(node: NotebookComponentBlockNode): string {
    const src = typeof node.props.src === 'string' ? node.props.src : ''
    const alt = typeof node.props.alt === 'string' ? node.props.alt : ''

    return `![${escapeMarkdownImageAlt(alt)}](${escapeMarkdownImageSrc(src)})`
}

// Browsers keep a trailing placeholder <br> in edited lines; it is presentational, so it must not
// become a line break in single-line markdown contexts.
function trimTrailingHardBreaks(nodes: NotebookInlineNode[]): NotebookInlineNode[] {
    let end = nodes.length
    while (end > 0 && nodes[end - 1].type === 'hardBreak') {
        end -= 1
    }
    return end === nodes.length ? nodes : nodes.slice(0, end)
}

function serializeInlineNode(node: NotebookInlineNode): string {
    if (node.type === 'hardBreak') {
        return '\n'
    }

    const marks = normalizeInlineMarks(node.marks ?? [])
    const isCodeText = marks.some((mark) => mark.type === 'code')
    const escapedText = isCodeText ? escapeCodeSpanText(node.text) : escapeInlineMarkdownText(node.text)

    return marks.reduce((text, mark) => wrapInlineText(text, mark, marks), escapedText)
}

function wrapInlineText(text: string, mark: NotebookInlineMark, marks: NotebookInlineMark[]): string {
    // `***text***` is ambiguous to parse — bold+italic is emitted as `**_text_**` in one step
    // (outer `**` has no word-boundary rules; the inner `_` is safely flanked by `*`)
    const hasBoldAndItalic =
        marks.some((otherMark) => otherMark.type === 'bold') && marks.some((otherMark) => otherMark.type === 'italic')
    if (mark.type === 'bold') {
        return hasBoldAndItalic
            ? wrapInlineEmphasis(wrapInlineEmphasis(text, '_'), '**')
            : wrapInlineEmphasis(text, '**')
    }
    if (mark.type === 'italic') {
        return hasBoldAndItalic ? text : wrapInlineEmphasis(text, '*')
    }
    if (mark.type === 'underline') {
        return `<u>${text}</u>`
    }
    if (mark.type === 'strike') {
        return wrapInlineEmphasis(text, '~~')
    }
    if (mark.type === 'code') {
        return `\`${text}\``
    }
    if (mark.type === 'ref' || mark.type === 'mention') {
        return mark.id ? `<${mark.type} id=${JSON.stringify(mark.id)}>${text}</${mark.type}>` : text
    }
    const href = sanitizeNotebookLinkHref(mark.href)
    return href ? `[${text}](${escapeMarkdownLinkHref(href)})` : text
}

// Emphasis delimiters are not recognized next to whitespace, so boundary whitespace is
// hoisted outside the delimiters (`*core* ` instead of `* core *`)
function wrapInlineEmphasis(text: string, delimiter: string): string {
    const leading = text.match(/^\s*/)?.[0] ?? ''
    const trailing = text.length > leading.length ? (text.match(/\s*$/)?.[0] ?? '') : ''
    const core = text.slice(leading.length, text.length - trailing.length)
    if (!core) {
        return text
    }
    return `${leading}${delimiter}${core}${delimiter}${trailing}`
}

function pushTextWithMarks(nodes: NotebookInlineNode[], text: string, marks: NotebookInlineMark[]): void {
    if (text) {
        nodes.push({ type: 'text', text, marks: marks.length ? marks : undefined })
    }
}

function findNextInlineToken(markdown: string, startIndex: number): number {
    const indexes = ['\\', '**', '*', '__', '_', '<u>', '<ref', '<mention', '~~', '`', '[', '\n']
        .map((token) => markdown.indexOf(token, startIndex))
        .filter((index) => index !== -1)
    return indexes.length ? Math.min(...indexes) : markdown.length
}

function htmlChildNodesToInlineNodes(parent: HTMLElement, marks: NotebookInlineMark[]): NotebookInlineNode[] {
    const children: NotebookInlineNode[] = []

    parent.childNodes.forEach((child) => {
        if (isBlockBreakElement(child) && children.length && children[children.length - 1]?.type !== 'hardBreak') {
            children.push({ type: 'hardBreak' })
        }

        children.push(...htmlNodeToInlineNodes(child, marks))
    })

    return children
}

function htmlNodeToInlineNodes(node: ChildNode, marks: NotebookInlineMark[]): NotebookInlineNode[] {
    if (node.nodeType === Node.TEXT_NODE) {
        return node.textContent
            ? [{ type: 'text', text: node.textContent, marks: marks.length ? marks : undefined }]
            : []
    }

    if (!(node instanceof HTMLElement)) {
        return []
    }

    const tagName = node.tagName.toLowerCase()
    if (tagName === 'br') {
        return [{ type: 'hardBreak' }]
    }

    const nextMarks = [...marks]
    if (tagName === 'strong' || tagName === 'b') {
        nextMarks.push({ type: 'bold' })
    }
    if (tagName === 'em' || tagName === 'i') {
        nextMarks.push({ type: 'italic' })
    }
    if (tagName === 'u') {
        nextMarks.push({ type: 'underline' })
    }
    if (tagName === 's' || tagName === 'del' || tagName === 'strike') {
        nextMarks.push({ type: 'strike' })
    }
    if (tagName === 'code') {
        nextMarks.push({ type: 'code' })
    }
    if (tagName === 'a') {
        const href = sanitizeNotebookLinkHref(node.getAttribute('href') ?? '')
        if (href) {
            nextMarks.push({ type: 'link', href })
        }
    }
    if (tagName === 'span') {
        const refId = node.getAttribute('data-notebook-ref')
        if (refId) {
            nextMarks.push({ type: 'ref', id: refId })
        }
        const mentionId = node.getAttribute('data-notebook-mention')
        if (mentionId) {
            nextMarks.push({ type: 'mention', id: mentionId })
        }
    }

    const children = htmlChildNodesToInlineNodes(node, nextMarks)

    if (isBlockBreakElement(node)) {
        children.push({ type: 'hardBreak' })
    }

    return children
}

function isBlockBreakElement(node: ChildNode): node is HTMLElement {
    if (!(node instanceof HTMLElement)) {
        return false
    }

    const tagName = node.tagName.toLowerCase()
    return tagName === 'div' || tagName === 'p'
}

function inlineNodeToHtml(node: NotebookInlineNode): string {
    if (node.type === 'hardBreak') {
        return '<br>'
    }

    return normalizeInlineMarks(node.marks ?? []).reduce(
        (html, mark) => wrapHtmlText(html, mark),
        escapeHtml(node.text)
    )
}

function wrapHtmlText(html: string, mark: NotebookInlineMark): string {
    if (mark.type === 'bold') {
        return `<strong>${html}</strong>`
    }
    if (mark.type === 'italic') {
        return `<em>${html}</em>`
    }
    if (mark.type === 'underline') {
        return `<u>${html}</u>`
    }
    if (mark.type === 'strike') {
        return `<s>${html}</s>`
    }
    if (mark.type === 'code') {
        return `<code>${html}</code>`
    }
    if (mark.type === 'ref') {
        return `<span class="MarkdownNotebook__ref" data-notebook-ref="${escapeAttribute(mark.id)}">${html}</span>`
    }
    if (mark.type === 'mention') {
        return `<span class="MarkdownNotebook__mention" data-notebook-mention="${escapeAttribute(mark.id)}">${html}</span>`
    }
    const href = sanitizeNotebookLinkHref(mark.href)
    return href ? `<a href="${escapeAttribute(href)}">${html}</a>` : html
}

// Escapes every character sequence the inline parser would interpret, so that
// parse(serialize(doc)) preserves literal user text exactly. Mirrored by the `\` branch
// in parseInlineMarkdown via INLINE_ESCAPABLE_CHARS.
export function escapeInlineMarkdownText(text: string): string {
    return text
        .replace(/[\\`*[\]|]/g, (match) => `\\${match}`)
        .replace(/~~+/g, (run) => '\\~'.repeat(run.length))
        .replace(/_/g, (_match, offset: number, source: string) =>
            // Intraword underscores (snake_case) are never emphasis, keep them readable
            isAsciiAlphaNumeric(source[offset - 1]) && isAsciiAlphaNumeric(source[offset + 1]) ? '_' : '\\_'
        )
        .replace(/<(?=\/?(?:u>|ref[\s>]|mention[\s>]))/g, '\\<')
}

export function escapeCodeSpanText(text: string): string {
    return text.replace(/[\\`]/g, (match) => `\\${match}`)
}

function unescapeCodeSpanText(text: string): string {
    return text.replace(/\\([\\`])/g, '$1')
}

function escapeMarkdownLinkHref(href: string): string {
    return href.replace(/[\\()]/g, (match) => `\\${match}`)
}

export function escapeMarkdownBlockLines(serialized: string): string {
    return serialized.split('\n').map(escapeMarkdownLineStart).join('\n')
}

// Prevents a serialized text line from being re-parsed as a different block type
// (heading, list, blockquote, divider, component). Inline-level characters (backtick,
// `*`, `[`, `|`) are already escaped by escapeInlineMarkdownText.
export function escapeMarkdownLineStart(line: string): string {
    const leadingWhitespace = line.match(/^\s*/)?.[0] ?? ''
    const content = line.slice(leadingWhitespace.length)

    const orderedListMatch = content.match(/^(\d+)([.)])(\s|$)/)
    if (orderedListMatch) {
        return `${leadingWhitespace}${orderedListMatch[1]}\\${content.slice(orderedListMatch[1].length)}`
    }

    if (/^(#{1,6}\s|>|[-+•](\s|$)|-{3,}\s*$)/.test(content) || COMPONENT_TAG_LINE_START.test(content)) {
        return `${leadingWhitespace}\\${content}`
    }

    return line
}

const COMPONENT_TAG_LINE_START = /^(<[A-Z]|<!--)/
const COMPONENT_TAG_OPENER = /^\\?(<[A-Z][A-Za-z0-9]*|<!--)/
// The notebooks backend reads a cell after Python's `str.strip()`, which also removes `\x1c` to `\x1f`
// and `\x85`. The editor lifts a quoted tag out of its blockquote, so `>` markers count as a prefix too.
const COMPONENT_TAG_LINE_PREFIX = /^[\s\x1c-\x1f\x85>]*/

// A backslash is not enough: both parsers recover a `\<Tag` that spans lines, because the prose
// serializer writes multiline components that way. Inline code cannot be recovered into a tag.
function escapeComponentTagLineStart(line: string): string {
    const prefix = line.match(COMPONENT_TAG_LINE_PREFIX)?.[0] ?? ''
    const content = line.slice(prefix.length)
    const match = content.match(COMPONENT_TAG_OPENER)
    return match ? `${prefix}\`${match[1]}\`${content.slice(match[0].length)}` : line
}

// For markdown the author meant to render: only a line that would parse as a component tag or a
// comment is neutralized, so headings and lists stay live. Lines inside code fences are neutralized
// too, because the editor and the notebooks backend disagree on where a fence ends, and a fence can
// span the blocks a caller joins. The cost is a stray pair of backticks in a code sample.
// The notebooks backend reads `\r` as a line break, so it is one here too.
export function escapeComponentTagLines(markdown: string): string {
    return markdown.replace(/\r\n?/g, '\n').split('\n').map(escapeComponentTagLineStart).join('\n')
}

function getCodeBlockFence(text: string): string {
    const longestRun = Math.max(0, ...Array.from(text.matchAll(/`+/g), (match) => match[0].length))
    return '`'.repeat(Math.max(3, longestRun + 1))
}

function escapeMarkdownImageAlt(text: string): string {
    return text.replace(/\\/g, '\\\\').replace(/\]/g, '\\]')
}

function escapeMarkdownImageSrc(text: string): string {
    return text.replace(/\\/g, '\\\\').replace(/\)/g, '\\)')
}

function unescapeMarkdownImageValue(text: string): string {
    return text.replace(/\\([\\\])])/g, '$1')
}

// Both escapes mirror the browser's HTML fragment serialization exactly: the editor compares
// generated HTML against live `innerHTML` to decide whether the DOM needs syncing, and any byte
// difference forces a rewrite that destroys the caret mid-typing.
function escapeHtml(text: string): string {
    return text
        .replace(/&/g, '&amp;')
        .replace(/\u00a0/g, '&nbsp;')
        .replace(/</g, '&lt;')
        .replace(/>/g, '&gt;')
}

function escapeAttribute(text: string): string {
    return text
        .replace(/&/g, '&amp;')
        .replace(/\u00a0/g, '&nbsp;')
        .replace(/"/g, '&quot;')
}

function decodeHtmlEntities(text: string): string {
    return text
        .replace(/&quot;/g, '"')
        .replace(/&#39;/g, "'")
        .replace(/&apos;/g, "'")
        .replace(/&lt;/g, '<')
        .replace(/&gt;/g, '>')
        .replace(/&amp;/g, '&')
}

export function makeEmptyParagraph(idSeed: string = 'empty'): NotebookTextBlockNode {
    const node: NotebookTextBlockNode = {
        id: '',
        type: 'paragraph',
        children: [],
    }
    node.id = makeGeneratedMarkdownId(idSeed)
    return node
}

export function makeListItemId(idSeed: string = 'list-item'): string {
    return makeGeneratedMarkdownId(idSeed)
}

function makeGeneratedMarkdownId(idSeed: string): string {
    const id = createStableNodeId(
        `${idSeed}:${hashString(`${String(Date.now())}:${String(generatedNodeIdCounter)}`)}`,
        0
    )
    generatedNodeIdCounter += 1
    return id
}