: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
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 `})`
}
// 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, '&')
.replace(/\u00a0/g, ' ')
.replace(/</g, '<')
.replace(/>/g, '>')
}
function escapeAttribute(text: string): string {
return text
.replace(/&/g, '&')
.replace(/\u00a0/g, ' ')
.replace(/"/g, '"')
}
function decodeHtmlEntities(text: string): string {
return text
.replace(/"/g, '"')
.replace(/'/g, "'")
.replace(/'/g, "'")
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/&/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
}