Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

62.8 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// Markdown → the bento/spaces block model: how an existing pile of notes
// becomes a space. Nobody adopts a notes app they cannot get their notes into.
//
// PURE, and deliberately DOM-FREE, so the whole of it runs in node under
// `scripts/test-spaces-model.ts`. The cases that decide whether an Obsidian
// vault survives the trip — wikilinks across hundreds of files, frontmatter,
// nested lists, a folder tree — are cheap to assert there and miserable to
// click through in a browser.
//
// IT DOES NOT SANITIZE. Raw inline html is reduced to an allowlisted skeleton
// here so this module needs no parser; `sanitizeInline` — the app's real
// policy, with a real one — runs over every block in the importer afterwards.
// One security gate, in the place that already has the tests for it.

// `.ts` extensions ON PURPOSE: this module is imported directly by
// `scripts/test-spaces-model.ts`, which node resolves without a bundler.
import { type Block, type Page, uid, writeTable, linkCard, linkCardHtml } from './model.ts'
import { esc, externalHref } from './sanitize.ts'
import { takeDefinitions, mergeNotes, renameRefs } from './footnotes.ts'
import { parseEmbedLine, linkEmbeds } from './embed.ts'
import { keepClasses, PALETTE } from './marks.ts'
import { readDesignFrontMatter } from './designs.ts'

/** A tab indents four columns. Nothing here depends on the exact number; it
 *  only has to be the same everywhere so nesting is consistent. */
const TAB = '    '

/** Inline tags a raw html span may keep — sanitize.ts's ALLOWED, carrying no
 *  attributes except a palette `class` on span/mark (see cleanRawTag).
 *  Restated rather than imported because that module's set is a DOM-side
 *  control and this one is a parser convenience; if they ever diverge, the
 *  sanitizer still wins, because it runs last. */
const INLINE_OK = new Set(['b', 'i', 'u', 's', 'em', 'strong', 'code', 'br', 'span', 'mark', 'sub', 'sup'])

/**
 * The href a wikilink carries between parsing and resolution.
 *
 * `#w/` never reaches a saved document: `resolveWikilinks` rewrites every one
 * before the blocks are committed, and `sanitizeInline` would strip any that
 * somehow survived — its allowlist is `https?:`, `mailto:` and `#p/`. So the
 * worst a bug in resolution can do is lose a link; it can never write one that
 * points somewhere unexpected.
 */
const WIKI_SCHEME = '#w/'

// ---- inline ----------------------------------------------------------------

/** One raw html tag, reduced to what the model allows, or null to drop it. */
function cleanRawTag(tag: string): string | null {
  const m = /^<(\/?)([a-zA-Z][a-zA-Z0-9]*)([^>]*?)\/?>$/.exec(tag)
  if (!m) return null
  const close = m[1] === '/'
  const name = m[2].toLowerCase()
  if (name === 'a') {
    if (close) return '</a>'
    const h = /href\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i.exec(m[3])
    const url = (h?.[1] ?? h?.[2] ?? h?.[3] ?? '').trim()
    return /^(https?:|mailto:)/i.test(url) ? `<a href="${esc(url)}">` : null
  }
  if (!INLINE_OK.has(name)) return null
  // A PALETTE CLASS SURVIVES ON SPAN AND MARK. Colour has no markdown syntax
  // at all, so the exporter writes it as raw inline html — and an importer that
  // threw the class away would make "export, edit the .md, import" a
  // colour-stripping round trip, which is the failure mode the export was
  // written to avoid in the first place.
  if (!close && (name === 'span' || name === 'mark')) {
    const c = /class\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i.exec(m[3])
    const kept = keepClasses(c ? (c[1] ?? c[2] ?? c[3] ?? '') : '')
    if (kept) return `<${name} class="${esc(kept)}">`
  }
  return close ? `</${name}>` : `<${name}>`
}

/**
 * Inline markdown → inline html.
 *
 * Everything this emits as MARKUP is parked in a placeholder first, so the
 * final pass can escape the whole remaining string in one go: text the author
 * typed can never turn into a tag, and a tag we generated can never be
 * double-escaped. Placeholders are `\u0000<n>\u0000` — digits, so they survive
 * escaping untouched, and the input's own NULs are dropped up front.
 */
export function inlineHtml(src: string): string {
  const held: string[] = []
  const hold = (html: string): string => `\u0000${held.push(html) - 1}\u0000`
  let s = src.replace(/\u0000/g, '')

  // code spans first: their content is literal, so nothing below may see it
  s = s.replace(/(`+)([^`]|[^`][\s\S]*?[^`])\1(?!`)/g, (_m, _t, code: string) =>
    hold(`<code>${esc(code.replace(/^ (.*) $/, '$1'))}</code>`))

  // backslash escapes — held as text so the marker cannot re-trigger below
  s = s.replace(/\\([\\`*_{}[\]()#+\-.!~>|=])/g, (_m, ch: string) => hold(esc(ch)))

  // <https://…> before the raw-tag sweep, which would otherwise eat it
  // DISPLAY TEXT IS NOT ESCAPED HERE.
  //
  // Everything a hold() placeholder protects is final markup and must carry its
  // own escaping. Everything OUTSIDE a placeholder is ordinary text, and the
  // single esc(s) at the end of this function escapes all of it exactly once.
  // Escaping display text here too ran it through twice: `[Q&A](…)` was written
  // into the file as `Q&amp;amp;A`, and the reader saw the entity. Bold, italic
  // and code were never affected — their text stays outside any placeholder —
  // which is why a spot-check of "inline formatting survived" passed.
  s = s.replace(/<((?:https?|mailto):[^>\s]+)>/gi, (_m, url: string) =>
    hold(`<a href="${esc(url)}">`) + url + hold('</a>'))

  // Raw inline html. A `</a>` is only kept when an `<a>` was kept: dropping a
  // link whose href we refuse (javascript:, obsidian:) must not leave its
  // closing tag behind for the sanitizer to trip over.
  let openA = 0
  s = s.replace(/<\/?[a-zA-Z][^<>]*>/g, (tag) => {
    const ok = cleanRawTag(tag)
    if (!ok) return ''
    if (ok === '</a>' && openA === 0) return ''
    if (ok.startsWith('<a ')) openA++
    else if (ok === '</a>') openA--
    return hold(ok)
  })

  // ![[embed]] and [[wikilink|alias]] before ordinary links.
  //
  // AN INLINE EMBED IS A LINK, and that is now a statement about grammar
  // rather than about the model: `embed` is a real block type (embed.ts), and
  // parseNote below turns a `![[Note]]` that is a whole LINE into one. A block
  // cannot live inside a sentence, so an `![[Note]]` with words either side of
  // it stays what it can be here — a link to the note.
  s = s.replace(/!?\[\[([^\]]+)\]\]/g, (_m, inner: string) => {
    const [target, alias] = splitOnce(inner, '|')
    return hold(`<a href="${WIKI_SCHEME}${encodeURIComponent(target.trim())}">`) +
      (alias ?? target).trim() + hold('</a>')
  })

  // an inline image cannot be a block, and the model has no inline <img>: keep
  // the alt text, and keep the address as a link when there is one to follow
  s = s.replace(/!\[([^\]]*)\]\(\s*<?([^\s)>]*)>?(?:\s+"[^"]*")?\s*\)/g,
    (_m, alt: string, url: string) => /^(https?:|data:)/i.test(url)
      ? hold(`<a href="${esc(url)}">`) + (alt || url) + hold('</a>')
      : (alt || url))

  // A link whose address the model cannot keep (relative paths, `obsidian://`,
  // `file:`) is left as the markdown the author wrote, address and all. The
  // sanitizer would strip such an href anyway, and text that still says where
  // it pointed beats a link that silently lost its destination.
  s = s.replace(/\[([^\]]*)\]\(\s*<?([^\s)>]*)>?(?:\s+"[^"]*")?\s*\)/g,
    (m: string, text: string, url: string) =>
      /^(https?:|mailto:)/i.test(url)
        ? hold(`<a href="${esc(url)}">`) + text + hold('</a>')
        : m)

  // A PANDOC SPAN carrying a palette colour — `[words]{color=red}` for the
  // ink, `[words]{bg=yellow}` for the band behind them, or both. This app's
  // own exporter writes colour as raw `<span class="sp-fg-red">`, which GitHub
  // and Obsidian show as clean text (the brace form would show as literal
  // braces there); this is the other spelling, for Markdown written with
  // Pandoc in mind. THE PALETTE ONLY: a name outside it (`coral`,
  // `red;background:url(…)`) or any key but these two leaves the whole span
  // as the text it was, so nothing here can mint a class the sanitizer's
  // pattern would then accept.
  s = s.replace(/\[([^[\]\n]+)\]\{([^{}\n]*)\}/g, (m: string, x: string, list: string) => {
    const a = parseAttrs(`{${list}}`)
    if (!a || a.id !== undefined || a.classes.length || !a.kv.size) return m
    const named = (k: string): string | undefined => {
      const v = a.kv.get(k)
      return v !== undefined && (PALETTE as readonly string[]).includes(v) ? v : undefined
    }
    for (const k of a.kv.keys()) if ((k !== 'color' && k !== 'bg') || !named(k)) return m
    const fg = named('color'), bg = named('bg')
    const open = (bg ? `<mark class="sp-bg-${bg}">` : '') + (fg ? `<span class="sp-fg-${fg}">` : '')
    const close = (fg ? '</span>' : '') + (bg ? '</mark>' : '')
    return hold(open) + x + hold(close)
  })

  s = s.replace(/~~([\s\S]+?)~~/g, (_m, x: string) => hold('<s>') + x + hold('</s>'))
  s = s.replace(/==([\s\S]+?)==/g, (_m, x: string) => hold('<mark>') + x + hold('</mark>'))
  // `***x***` — bold AND italic, which is how the exporter spells the pair
  // (marks.ts: strong outside em). Left to the two rules below it read as
  // `**` + `*x` + `**` and then an `*` with no partner, and came back as the
  // mis-nested `<strong><em>x</strong></em>`.
  s = s.replace(/\*\*\*(?=\S)([^*]+?)\*\*\*/g, (_m, x: string) => hold('<strong><em>') + x + hold('</em></strong>'))
  s = s.replace(/\*\*(?=\S)([\s\S]+?)\*\*/g, (_m, x: string) => hold('<strong>') + x + hold('</strong>'))
  s = s.replace(/(^|[^\w\\])__(?=\S)([\s\S]+?)__(?!\w)/g,
    (_m, pre: string, x: string) => pre + hold('<strong>') + x + hold('</strong>'))
  s = s.replace(/(^|[^*\w])\*(?=\S)([^*]+?)\*/g,
    (_m, pre: string, x: string) => pre + hold('<em>') + x + hold('</em>'))
  // `_` only outside a word, or snake_case_identifiers become italics
  s = s.replace(/(^|[^\w\\])_(?=\S)([^_]+?)_(?!\w)/g,
    (_m, pre: string, x: string) => pre + hold('<em>') + x + hold('</em>'))

  return esc(s).replace(/\u0000(\d+)\u0000/g, (_m, n: string) => held[Number(n)])
}

/** Inline markdown → plain text, for titles (a page title is text, not html). */
export function plainText(src: string): string {
  return src
    .replace(/!?\[\[([^\]|]+)(?:\|([^\]]*))?\]\]/g, (_m, t: string, a: string) => a ?? t)
    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
    .replace(/[*_~`]+/g, '')
    .replace(/^#+\s*/, '')
    .replace(/\s+/g, ' ')
    .trim()
}

const splitOnce = (s: string, sep: string): [string, string | undefined] => {
  const i = s.indexOf(sep)
  return i < 0 ? [s, undefined] : [s.slice(0, i), s.slice(i + sep.length)]
}

// ---- one note --------------------------------------------------------------

export interface PendingImage {
  /** the image block, by reference — the importer rewrites it in place */
  block: Block
  /** the address exactly as the note wrote it */
  ref: string
  /** the folder the note lived in, for resolving a relative address */
  dir: string
}

export interface ParsedNote {
  title: string
  blocks: Block[]
  /** the YAML between the leading `---` fences, verbatim */
  frontmatter?: string
  /** `design:` from the front matter — what this app's own export writes */
  design?: string
  /** `designs:` from the front matter: a design the file carried with it */
  designs?: Record<string, unknown>
  images: PendingImage[]
  /** images pointing at the web: kept, but not loaded until a reader asks */
  remoteImages: number
  /** markdown tables, which this model has no block for yet */
  tables: number
  /**
   * `[^1]: the note.` definitions, by label — absent when the file has none.
   *
   * TAKEN OUT BEFORE THE BLOCK PARSER RUNS. A definition line left in the
   * stream parses as an ordinary paragraph, which is the silent downgrade this
   * importer has produced once before (`![[embed]]` arriving as a plain link):
   * nothing errors, the words are all still there, and the construct is gone.
   * The REFERENCES need no handling at all — `[^1]` is the same text in
   * markdown and in this model (src/footnotes.ts).
   */
  footnotes?: Record<string, string>
}

const mk = (type: string, extra: Partial<Block> = {}): Block => ({ id: uid('b'), type, ...extra })

// The title may hold `\"` and `\\` — CommonMark's escapes, and what the
// exporter writes for a caption containing either (blocks.ts image toMd).
// A trailing `{…}` is a Pandoc attribute list: `{width=60% w=640 h=300}`.
const IMG_LINE = /^!\[([^\]]*)\]\(\s*<?([^\s)>]*)>?(?:\s+"((?:[^"\\]|\\.)*)")?\s*\)(\{[^{}\n]*\})?$/

/**
 * A PANDOC ATTRIBUTE LIST — `{#id .class key=value key="quoted value"}` — the
 * syntax Pandoc, markdown-it-attrs and kramdown-alikes already read after an
 * image, a link or a heading. Parsed into plain strings and NOTHING is
 * interpreted here: each caller takes only the keys it knows, validates each
 * value against its own pattern, and ignores the rest. An attribute list out
 * of a mailed file is data, and the only way it can matter is through a
 * validator that says yes.
 *
 * A malformed list (an unterminated quote, a token that is none of the three
 * forms) yields null, and the caller treats the line as ordinary text.
 */
export interface Attrs { id?: string; classes: string[]; kv: Map<string, string> }
export function parseAttrs(src: string): Attrs | null {
  const m = /^\{([^{}\n]*)\}$/.exec(src.trim())
  if (!m) return null
  const out: Attrs = { classes: [], kv: new Map() }
  const re = /\s*(?:#([A-Za-z][\w-]*)|\.([A-Za-z][\w-]*)|([A-Za-z][\w-]*)=(?:"([^"]*)"|([^\s"]+)))\s*/y
  let at = 0
  const body = m[1]
  while (at < body.length) {
    re.lastIndex = at
    const t = re.exec(body)
    if (!t || re.lastIndex === at) return null
    at = re.lastIndex
    if (t[1] !== undefined) out.id = t[1]
    else if (t[2] !== undefined) out.classes.push(t[2])
    else if (!out.kv.has(t[3])) out.kv.set(t[3], t[4] ?? t[5] ?? '')
  }
  return out
}

/**
 * An image's (or a clip's) SIZE out of its attribute list, validated.
 *
 * `width` is the block's percentage of the text column, 10..100, written with
 * its `%` exactly as Pandoc spells a relative width. `w`/`h` are the intrinsic
 * pixels the block keeps to hold its aspect box while it decodes — not a
 * display size, so they are NOT Pandoc's `width`/`height` (a foreign
 * `width=300px` means something else and is ignored rather than guessed at).
 * Both or neither: one of the pair is not an aspect ratio.
 */
export function sizeOf(a: Attrs | null): { width?: number; w?: number; h?: number } {
  if (!a) return {}
  const out: { width?: number; w?: number; h?: number } = {}
  const pct = /^(\d{1,3}(?:\.\d{1,3})?)%$/.exec(a.kv.get('width') ?? '')
  if (pct) { const n = Number(pct[1]); if (n >= 10 && n <= 100) out.width = n }
  const w = /^[1-9]\d{0,4}$/.test(a.kv.get('w') ?? '') ? Number(a.kv.get('w')) : 0
  const h = /^[1-9]\d{0,4}$/.test(a.kv.get('h') ?? '') ? Number(a.kv.get('h')) : 0
  if (w && h) { out.w = w; out.h = h }
  return out
}
const IMG_EMBED = /^!\[\[([^\]|]+)(?:\|[^\]]*)?\]\]$/
const IMAGE_EXT = /\.(png|jpe?g|gif|webp|avif|svg|bmp|ico)$/i

// ---- link cards -------------------------------------------------------------

/**
 * A LINK CARD's line: a link, an optional ` — description`, and the marker
 * comment blocks.ts cardComment() writes — or, for a card with no url, any
 * text before the marker (its title and desc are in the comment). The marker is
 * what makes it a card; the same line without it is an ordinary paragraph.
 */
const CARD_LINE = /^(?:\[((?:\\.|[^\]\\])*)\]\(\s*(?:<([^>\n]*)>|([^\s()<>]*))\s*\)(?: — (.*?))?|(.*?))\s*<!-- bento:card((?:\s+[a-z]+="[^"<>]*")*)\s*-->$/

const uncomment = (v: string): string =>
  v.replace(/&#45;/g, '-').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&amp;/g, '&')

/** A thumbnail a card may point at: an asset key, or an inline raster image.
 *  Never a remote address (linkCard() would drop one anyway) and never svg. */
const CARD_IMAGE = /^(?:asset:[A-Za-z0-9_-]{1,128}|data:image\/(?:png|jpeg|gif|webp|avif);base64,[A-Za-z0-9+/]+=*)$/

/**
 * A card line → the card's fields, every one validated, or null when the line
 * is not a card. Plain-text fields (title, desc, site, icon) are stored as
 * TEXT — the renderer writes them with textContent — and capped; the url must
 * pass externalHref(), the same allowlist the editor's card dialog uses, and
 * a url that fails it is dropped rather than stored (the card keeps its
 * title and is a dead card, which is what render.ts draws for one).
 */
function cardOf(line: string): Partial<Block> | null {
  const m = CARD_LINE.exec(line)
  if (!m) return null
  const kv = new Map<string, string>()
  for (const a of m[6].matchAll(/([a-z]+)="([^"]*)"/g)) if (!kv.has(a[1])) kv.set(a[1], uncomment(a[2]))
  const text = (v: string | undefined, cap: number): string => (v ?? '').replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, cap)
  const out: Partial<Block> = {}
  const linked = m[2] !== undefined || m[3] !== undefined
  if (linked) {
    const url = externalHref(m[2] ?? m[3])
    const shown = text(m[1].replace(/\\([\\[\]])/g, '$1'), 500)
    if (url) out.url = url
    // an untitled card exports its url as its text; that is not a title
    if (shown && shown !== url) out.title = shown
    const desc = text(m[4], 2000)
    if (desc) out.desc = desc
  } else {
    // no title in the marker: the visible words are the title, as plain text
    // — a line whose link could not be read (`[Evil](javascript:…)`, whose
    // parentheses the url pattern refuses) keeps its words, not its address
    const shown = m[5] ?? ''
    // a second marker (or any comment) in the words is not a card line: it is
    // someone trying to close ours early, and the line stays text
    if (shown.includes('<!--')) return null
    const words = /^\[((?:\\.|[^\]\\])*)\]\(.*\)$/.exec(shown)?.[1].replace(/\\([\\[\]])/g, '$1') ?? plainText(shown)
    const title = text(kv.get('title') ?? words, 500)
    const desc = text(kv.get('desc'), 2000)
    if (title) out.title = title
    if (desc) out.desc = desc
  }
  const site = text(kv.get('site'), 200)
  if (site) out.site = site
  const icon = text(kv.get('icon'), 16)
  if (icon) out.icon = icon
  const image = kv.get('image') ?? ''
  if (CARD_IMAGE.test(image)) out.image = image
  return out
}

// ---- media ------------------------------------------------------------------

const unattr = (v: string): string =>
  v.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, '&')

/** An html tag's attributes, lower-cased names, values decoded. Booleans map
 *  to ''. Parsing only: what any name MEANS is decided by the caller. */
function htmlAttrs(src: string): Map<string, string> {
  const out = new Map<string, string>()
  for (const m of src.matchAll(/([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g)) {
    const k = m[1].toLowerCase()
    if (!out.has(k)) out.set(k, unattr(m[2] ?? m[3] ?? m[4] ?? ''))
  }
  return out
}

/**
 * Where a clip or its poster may point: an asset key, an inline file of the
 * right kind, or an http(s) address — the three forms the model has, and the
 * same allowlist the editor's "Use a link…" box applies. An ALLOWLIST, like
 * HREF_OK: `javascript:`, `file:`, `blob:`, a relative path and anything
 * the URL parser would normalise into one of those all fail it.
 */
const MEDIA_SRC = /^(?:asset:[A-Za-z0-9_-]{1,128}|data:(?:video|audio)\/[\w.+-]{1,40};base64,[A-Za-z0-9+/]+=*|https?:\/\/[^\s"'<>]+)$/i
const POSTER_SRC = /^(?:asset:[A-Za-z0-9_-]{1,128}|data:image\/(?:png|jpeg|gif|webp|avif);base64,[A-Za-z0-9+/]+=*|https?:\/\/[^\s"'<>]+)$/i

/**
 * `<video …>…</video>` or `<audio …>…</audio>` (already joined onto one line)
 * → a media block's fields, or null when the source is not one the model may
 * hold. Reads the element blocks.ts media toMd writes, and the shapes READMEs
 * use: a `<source src>` child instead of a `src` attribute, and a real
 * `autoplay` (recorded, never obeyed — mediaPlayback). Every value is checked;
 * no attribute is copied by name, so `onerror`, `style` and the rest have
 * nowhere to go.
 */
function mediaOf(html: string): { fields: Partial<Block> } | { refused: string; label: string } | null {
  const m = /^<(video|audio)(\s[^>]*)?>([\s\S]*?)<\/\1\s*>$/i.exec(html.trim())
  if (!m) return null
  const kind = m[1].toLowerCase()
  const a = htmlAttrs(m[2] ?? '')
  const inner = m[3]
  const source = /<source(\s[^>]*)?>/i.exec(inner)
  const raw = (a.get('src') ?? (source ? htmlAttrs(source[1] ?? '').get('src') : undefined) ?? '').trim()
  const fallback = /<a(?:\s[^>]*)?>([\s\S]*?)<\/a>/i.exec(inner)?.[1] ?? inner
  const label = unattr(fallback.replace(/<[^>]*>/g, '')).replace(/\s+/g, ' ').trim()
  if (!MEDIA_SRC.test(raw)) return { refused: raw, label }
  const f: Partial<Block> = { kind, src: raw }
  const alt = (a.get('title') ?? a.get('aria-label') ?? '').replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, 500)
  if (alt) f.alt = alt
  f.controls = a.has('controls')
  if (a.has('loop')) f.loop = true
  if (a.has('muted')) f.muted = true
  if (a.has('autoplay') || a.has('data-autoplay')) f.autoplay = true
  const poster = (a.get('poster') ?? '').trim()
  if (POSTER_SRC.test(poster)) f.poster = poster
  const px = (v: string | undefined) => (/^[1-9]\d{0,4}$/.test(v ?? '') ? Number(v) : 0)
  const w = px(a.get('width')), h = px(a.get('height'))
  if (w && h) { f.w = w; f.h = h }
  const pct = /^(\d{1,3}(?:\.\d{1,3})?)$/.exec(a.get('data-width') ?? '')
  if (pct && Number(pct[1]) >= 10 && Number(pct[1]) <= 100) f.width = Number(pct[1])
  const caption = (a.get('data-caption') ?? '').trim()
  if (caption) f.caption = caption.slice(0, 2000)
  return { fields: f }
}

// ---- views and canvases -------------------------------------------------------

/** What a structured fence may hold at most. A file can be hand-edited or
 *  generated; a view's settings are a few hundred bytes. */
const FENCE_MAX = 65536
/** A field name a fence may set: a plain identifier. Excludes `__proto__`
 *  by construction (it starts with `_`), and the reserved names below by
 *  list. */
const FIELD_KEY = /^[A-Za-z][A-Za-z0-9]{0,31}$/
const RESERVED = new Set(['id', 'type', 'parent', 'html', 'comments', 'name', 'cards', 'constructor', 'prototype'])

/**
 * A ```` ```bento-view ```` or ```` ```bento-canvas ```` fence → the block.
 *
 * The body is ONE JSON object (blocks.ts fenceJson writes it): `name` is the
 * block's text as inline markdown, `cards` (canvas only) the card positions,
 * and every other key is a field of the block, copied as data — so a field a
 * newer build adds to a view round-trips through this one. Lines starting `//`
 * are the readable summary the exporter adds for people reading the file
 * elsewhere, and are ignored. JSON.parse, never eval; the object's OWN keys
 * only, each a plain identifier; nothing structural (`id`, `type`, `parent`,
 * `html`, `comments`) can be set from the fence. Anything malformed returns
 * null and the fence stays the code block it looks like.
 *
 * This is no more trust than the app already extends to a `.bento.html` file
 * someone mails you, whose blocks are JSON with every one of these fields.
 */
function fencedBlock(kind: 'view' | 'canvas' | string, body: string[]): { block: Block; cards?: Array<[number, number] | null> } | null {
  const json = body.filter((l) => l.trim() && !l.trim().startsWith('//'))
  if (json.length !== 1 || json[0].length > FENCE_MAX) return null
  let obj: unknown
  try { obj = JSON.parse(json[0]) } catch { return null }
  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return null
  const o = obj as Record<string, unknown>
  const block = mk(kind, { html: typeof o.name === 'string' ? inlineHtml(o.name) : '' })
  for (const k of Object.keys(o)) {
    if (!Object.hasOwn(o, k) || !FIELD_KEY.test(k) || RESERVED.has(k)) continue
    block[k] = o[k]
  }
  if (kind !== 'canvas') return { block }
  const cards: Array<[number, number] | null> = []
  if (Array.isArray(o.cards)) {
    for (const c of o.cards.slice(0, 1000)) {
      cards.push(Array.isArray(c) && c.length === 2 && c.every((n) => typeof n === 'number' && Number.isFinite(n))
        ? [c[0] as number, c[1] as number] : null)
    }
  }
  return { block, cards }
}

/**
 * Turn the `[[Title]]` page links parseNote left pending into real page ids.
 *
 * One that names no page becomes the paragraph it would otherwise have been,
 * holding the literal `[[Title]]` — the same rule as an inline wikilink that
 * finds nothing (resolveWikilinks): honest text, never a card to nowhere.
 */
export function resolvePageLinks(blocks: Block[], lookup: (target: string) => string | undefined): { linked: number; dangling: number } {
  let linked = 0, dangling = 0
  for (const b of blocks) {
    if (b.type !== 'pagelink' || typeof b.page !== 'string' || !b.page.startsWith(WIKI_SCHEME)) continue
    let target = b.page.slice(WIKI_SCHEME.length)
    try { target = decodeURIComponent(target) } catch { /* keep the raw form */ }
    const id = lookup(target)
    if (id) { b.page = id; linked++; continue }
    dangling++
    b.type = 'p'
    delete b.page
    b.html = `[[${esc(target)}]]`
  }
  return { linked, dangling }
}

/** A line that is nothing but an image. `![[x]]` counts only when it names an
 *  image FILE — otherwise it is an embed of another note, which is a link. */
function imageOf(line: string): { ref: string; alt: string; caption?: string; attrs?: Attrs | null } | null {
  const m = IMG_LINE.exec(line.trim())
  if (m) {
    return {
      ref: m[2], alt: m[1],
      ...(m[3] ? { caption: m[3].replace(/\\(["\\])/g, '$1') } : {}),
      ...(m[4] ? { attrs: parseAttrs(m[4]) } : {}),
    }
  }
  const e = IMG_EMBED.exec(line.trim())
  if (e && IMAGE_EXT.test(e[1].trim())) return { ref: e[1].trim(), alt: '' }
  return null
}

/**
 * One markdown file → one page's worth of blocks.
 *
 * THE TITLE RULE, which has to be predictable above all else: a leading
 * `# Heading` becomes the page title AND is removed from the body; otherwise
 * the file name without its extension is the title. Frontmatter is NOT
 * consulted for it — wikilinks resolve by FILE NAME, so a title taken from a
 * `title:` key that disagreed with the file name would leave `[[Note]]`
 * pointing at a page whose name is nowhere in the sidebar.
 */
export function parseNote(text: string, fileTitle: string): ParsedNote {
  // FOOTNOTE DEFINITIONS COME OUT FIRST, before a single line is classified.
  // They are a document-level table, not blocks, and a line the block parser
  // has already turned into a paragraph cannot be un-turned.
  const { rest: lines, notes: footnotes } =
    takeDefinitions(text.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n').split('\n'))
  const blocks: Block[] = []
  const images: PendingImage[] = []
  let remoteImages = 0
  let tables = 0
  let frontmatter: string | undefined
  let i = 0

  if (lines[0]?.trim() === '---') {
    for (let j = 1; j < lines.length; j++) {
      if (/^(---|\.\.\.)\s*$/.test(lines[j])) {
        frontmatter = lines.slice(1, j).join('\n')
        i = j + 1
        break
      }
    }
  }

  // A DESIGN RIDES IN THE FRONT MATTER (designs.ts designFrontMatter). When
  // design keys are ALL it holds — which is exactly what this app's export
  // writes — it is consumed, not kept as a folded yaml block: a space that
  // goes out and comes back must not grow a "Frontmatter" toggle each trip.
  // Anything else keeps the old rule and is kept verbatim.
  let design: string | undefined
  let designs: Record<string, unknown> | undefined
  if (frontmatter !== undefined) {
    const fm = readDesignFrontMatter(frontmatter)
    design = fm.design
    designs = fm.designs
    if (fm.onlyOurs && (design !== undefined || designs !== undefined)) frontmatter = undefined
  }

  let title = ''
  {
    let j = i
    while (j < lines.length && !lines[j].trim()) j++
    const m = /^ {0,3}#\s+(.+?)\s*#*$/.exec(lines[j] ?? '')
    if (m) { title = plainText(m[1]); i = j + 1 }
  }

  /** open list levels, innermost last */
  const stack: Array<{ indent: number; id: string }> = []
  /**
   * Open GitHub alerts, innermost last: the line index where each one's
   * blockquote ENDS, and how deep `stack` was before it opened. An alert is a
   * container whose body is ordinary markdown — lists, fences, nested alerts —
   * so its lines are un-quoted IN PLACE and read by this same loop, with the
   * callout on `stack` as their owner until `end`.
   */
  const alerts: Array<{ end: number; depth: number }> = []
  /**
   * Open `<details>` folds, innermost last: how deep `stack` was before each
   * opened. A fold is a container like an alert, but it ends at an explicit
   * `</details>` rather than at the end of a blockquote.
   */
  const folds: Array<{ depth: number }> = []
  /** canvases read from a `bento-canvas` fence, and the card positions each
   *  one carries — the cards themselves are the blocks that follow it */
  const canvases: Array<{ block: Block; cards: Array<[number, number] | null> }> = []
  /** a callout whose tag line held no text: its next line, if adjacent, is its text */
  let alertText: Block | null = null
  /** the paragraph a soft line break continues, and the quote a `>` continues */
  let para: Block | null = null
  let quote: Block | null = null

  const ownerFor = (indent: number): string | undefined => {
    while (stack.length && stack[stack.length - 1].indent >= indent) stack.pop()
    return stack[stack.length - 1]?.id || undefined
  }
  /** the block the line being read created or continued — where a trailing
   *  `{#id}` on that line belongs */
  let touched: Block | null = null
  /** the id a line carried, waiting for that line to finish */
  let pendingId: string | null = null
  const add = (b: Block, parent?: string): Block => {
    if (parent) b.parent = parent
    blocks.push(b)
    touched = b
    return b
  }
  const taken = new Set<string>()
  /**
   * Give the block the line just read the id that line carried. The block was
   * minted with a fresh id when the line began, and anything opened since
   * (a list level, a callout's body) points at that one — so it is a RENAME,
   * of the stack entries and of any `parent` already written. An id this note
   * has already given out stays with its first holder: a paragraph another
   * editor duplicated keeps its words and gets a fresh id.
   */
  const settleId = () => {
    const id = pendingId
    pendingId = null
    if (!id || !touched || taken.has(id)) return
    taken.add(id)
    const old = touched.id
    touched.id = id
    for (const e of stack) if (e.id === old) e.id = id
    for (const b of blocks) if (b.parent === old) b.parent = id
  }
  // NOT model.isRemote(): that answers "would loading this touch the network",
  // where a relative path counts as remote. The question here is different —
  // "could a file the user picked satisfy this address" — and a relative path
  // is the one case where the answer is yes.
  const imageBlock = (ref: string, alt: string, caption: string | undefined, parent?: string, attrs?: Attrs | null) => {
    // `html: ''` is the shape model.newBlock gives every block, so an image
    // that goes out and comes back is the same JSON the editor made
    const b = mk('image', { html: '', src: ref, ...(alt ? { alt } : {}), ...(caption ? { caption } : {}), ...sizeOf(attrs ?? null) })
    add(b, parent)
    if (/^(https?:)?\/\//i.test(ref)) remoteImages++
    else if (!/^data:/i.test(ref)) images.push({ block: b, ref, dir: '' })
    return b
  }

  for (; i < lines.length; i++) {
    settleId()
    while (alerts.length && i >= alerts[alerts.length - 1].end) {
      stack.length = alerts.pop()!.depth
      // a fold left open inside the box ends with it
      while (folds.length && folds[folds.length - 1].depth > stack.length) folds.pop()
      para = null; quote = null; alertText = null
    }
    const ownText = alertText
    alertText = null
    const line = lines[i].replace(/\t/g, TAB)
    const indent = /^ */.exec(line)![0].length
    let body = line.slice(indent).trimEnd()

    // A BLOCK ID — ` {#id}` ending a line, Pandoc's heading-attribute
    // spelling and what markdown-it-attrs reads after any block. Taken off
    // the line before anything else reads it, and given to whichever block
    // this line creates or continues (settleId, at the next line). Only a
    // plain identifier, and never a name Object.prototype already has.
    const idm = / \{#([A-Za-z][A-Za-z0-9_-]{0,63})\}$/.exec(body)
    if (idm && !(idm[1] in Object.prototype)) {
      body = body.slice(0, idm.index).trimEnd()
      pendingId = idm[1]
      touched = null
    }

    if (!body) { para = null; quote = null; pendingId = null; continue }

    // fenced code — taken whole, so nothing inside is interpreted
    const fence = /^(`{3,}|~{3,})\s*(\S*)/.exec(body)
    if (fence) {
      para = null; quote = null
      const owner = ownerFor(indent)
      const mark = fence[1][0]
      const buf: string[] = []
      let j = i + 1
      for (; j < lines.length; j++) {
        const t = lines[j].trim()
        if (t.length >= 3 && t[0] === mark && t === mark.repeat(t.length)) break
        buf.push(lines[j].startsWith(' '.repeat(indent)) ? lines[j].slice(indent) : lines[j])
      }
      i = j
      const lang = fence[2].toLowerCase()
      const structured = lang === 'bento-view' || lang === 'bento-canvas' ? fencedBlock(lang.slice(6), buf) : null
      if (structured) {
        add(structured.block, owner)
        if (structured.cards) canvases.push({ block: structured.block, cards: structured.cards })
        continue
      }
      add(mk('code', { html: esc(buf.join('\n')), ...(fence[2] ? { lang } : {}) }), owner)
      continue
    }

    // A PIPE TABLE. This used to be kept verbatim inside a CODE BLOCK —
    // aligned, searchable and exportable, but not a table — under a comment
    // saying it was "mechanically upgradable the day a table block ships".
    // This is that day, and the upgrade is this branch.
    if (body.includes('|') && isTableRule(lines[i + 1])) {
      para = null; quote = null
      const owner = ownerFor(indent)
      const head = splitRow(body)
      const align = splitRow(lines[i + 1]).map(alignOf)
      const raw = [head]
      let j = i + 2
      for (; j < lines.length && lines[j].includes('|'); j++) raw.push(splitRow(lines[j]))
      i = j - 1
      tables++
      // THE HEADER ROW IS THE COLUMN COUNT, which is GFM's own rule: a body row
      // with more cells is cut and one with fewer is padded (tableOf pads at
      // read time, so only the overflow is handled here). A ragged table is
      // completely ordinary in hand-written markdown.
      const w = Math.max(1, head.length)
      const table = mk('table')
      // An EMPTY header row is how a headerless table is written in GFM — there
      // is no other way to say it — and it is what this app's own exporter
      // emits. So it reads back as `header: false` AND the empty row goes: a
      // table that grows a blank first row every time it goes out and comes
      // back is not a round trip.
      const headed = head.some((c) => c.trim() !== '')
      const rows = headed ? raw : raw.slice(1)
      writeTable(table, {
        rows: (rows.length ? rows : [[]]).map((r) => Array.from({ length: w }, (_, k) => inlineHtml(r[k] ?? ''))),
        cols: Array<number>(w).fill(1),
        colAlign: Array.from({ length: w }, (_, k) => align[k] ?? ''),
        header: headed,
      })
      add(table, owner)
      continue
    }

    // setext: `===` under a paragraph promotes it. `---` deliberately does NOT
    // — in a folder of notes a lone rule is a divider far more often than it
    // is a heading, and silently eating the line above it is unforgivable.
    if (para && /^=+$/.test(body)) { para.type = 'h1'; para = null; continue }

    if (/^([-*_])\s*(?:\1\s*){2,}$/.test(body)) {
      para = null; quote = null
      // `html: ''`, as model.newBlock writes it — see imageBlock
      add(mk('divider', { html: '' }), ownerFor(indent))
      continue
    }

    const head = /^(#{1,6})\s+(.*?)\s*#*$/.exec(body)
    if (head) {
      para = null; quote = null
      // h4–h6 land on h3: the model has three heading levels, and dropping a
      // deep heading to a paragraph would lose the outline entirely
      add(mk(`h${Math.min(head[1].length, 3)}`, { html: inlineHtml(head[2]) }), ownerFor(indent))
      continue
    }

    // A `<details>` FOLD is a toggle. GitHub renders it, Obsidian renders it,
    // and it is what this app's exporter writes (blocks.ts toggle toMd).
    //
    // THE TAG IS READ, NEVER KEPT. Of everything the opening tag may carry,
    // the one fact taken from it is whether it says `open`; no attribute value
    // is copied anywhere, so `<details onclick=…>` or `<details ontoggle=…>`
    // costs the importer nothing to refuse — there is no html built from it to
    // refuse. The summary is inline markdown and goes through inlineHtml like
    // any other line (and sanitizeInline after it, in the importer).
    const det = /^<details(\s[^>]*)?>(.*)$/i.exec(body)
    if (det) {
      para = null; quote = null
      // quoted values out first, so `title="open"` does not read as the flag
      const attrs = (det[1] ?? '').replace(/"[^"]*"|'[^']*'/g, '""')
      const open = /(?:^|\s)open(?:\s|=|$)/i.test(attrs)
      let rest = det[2].trim()
      if (!rest) {
        // the summary on the next non-blank line, as GitHub READMEs indent it
        let j = i + 1
        while (j < lines.length && !lines[j].trim()) j++
        if (/^<summary(?:\s[^>]*)?>/i.test(lines[j]?.trim() ?? '')) { rest = lines[j].trim(); i = j }
      }
      const sum = /^<summary(?:\s[^>]*)?>(.*?)<\/summary>(.*)$/i.exec(rest)
      const toggle = add(mk('toggle', { html: inlineHtml(sum ? sum[1].trim() : ''), open }), ownerFor(indent))
      // anything after the summary on the same line is the fold's first line,
      // and a `</details>` there closes it at once
      let after = (sum ? sum[2] : rest).trim()
      const shut = /<\/details>\s*$/i.test(after)
      after = after.replace(/<\/details>\s*$/i, '').trim()
      if (after) add(mk('p', { html: inlineHtml(after) }), toggle.id)
      if (!shut) {
        folds.push({ depth: stack.length })
        // below `indent`, so no line of the body can pop it; `</details>` does
        stack.push({ indent: indent - 0.5, id: toggle.id })
      }
      continue
    }
    if (/^<\/details\s*>$/i.test(body)) {
      para = null; quote = null
      const f = folds.pop()
      // a stray closer (no fold open) is dropped, as the raw-tag sweep would
      if (f) stack.length = Math.min(stack.length, f.depth)
      continue
    }

    // A GITHUB ALERT — `> [!WARNING]` opening a blockquote — is a callout, and
    // the five tags ARE the five tones (blocks.ts CALLOUT_TONES), so this is
    // the exporter read backwards. Obsidian's spelling reads too: lower case,
    // a fold marker (`[!tip]-`, dropped: a callout does not fold) and text on
    // the tag line. Any other tag stays a quote, word for word — and so does
    // a tag that does not OPEN its blockquote.
    const alert = quote ? null : /^>\s?\[!(note|tip|important|warning|caution)\][+-]?(?:\s+(.*))?$/i.exec(body)
    if (alert) {
      para = null
      const callout = add(mk('callout', { html: inlineHtml(alert[2] ?? ''), tone: alert[1].toLowerCase() }), ownerFor(indent))
      let j = i + 1
      for (; j < lines.length; j++) {
        const m = /^( *)>\s?(.*)$/.exec(lines[j].replace(/\t/g, TAB))
        if (!m || m[1].length < indent) break
        lines[j] = ' '.repeat(indent) + m[2]
      }
      alerts.push({ end: j, depth: stack.length })
      // below `indent`, so no line of the body can pop it before `end` does
      stack.push({ indent: indent - 0.5, id: callout.id })
      if (callout.html) para = callout
      else alertText = callout
      continue
    }

    const q = /^>\s?(.*)$/.exec(body)
    if (q) {
      para = null
      const text = inlineHtml(q[1].replace(/^[>\s]+/, ''))
      if (quote) { quote.html = `${quote.html}<br>${text}`; touched = quote }
      else quote = add(mk('quote', { html: text }), ownerFor(indent))
      continue
    }
    quote = null

    const item = /^([-*+]|\d{1,9}[.)])(?:\s+(.*)|\s*)$/.exec(body)
    if (item) {
      para = null
      const owner = ownerFor(indent)
      const text = item[2] ?? ''
      const todo = /^\[([ xX])\]\s*(.*)$/.exec(text)
      const pic = imageOf(text)
      const block = todo
        ? add(mk('todo', { html: inlineHtml(todo[2]), done: todo[1] !== ' ' }), owner)
        : pic
          ? imageBlock(pic.ref, pic.alt, pic.caption, owner, pic.attrs)
          : add(mk(/^\d/.test(item[1]) ? 'number' : 'bullet', { html: inlineHtml(text) }), owner)
      // An IMAGE is not a container and holds no text, so it is neither a
      // continuation target nor a parent.
      //
      // It was both. A continuation line did `${para.html}<br>${text}` against a
      // block with no html, writing the literal string "undefined" into the
      // document and hiding the author's line — invisible in the editor, the
      // reading view, print and the markdown export, but there in the saved
      // file and findable by search. `- ![[pic.png]]` with an indented caption
      // is an ordinary Obsidian shape.
      //
      // Pushing the image's OWNER (not the image) keeps the caption a SIBLING
      // of the image, under the same list item. Parenting it to the image would
      // leave the model saying nested while the renderer, which only opens a
      // body for a registered container, draws it at root.
      stack.push({ indent, id: pic ? (owner ?? '') : block.id })
      para = pic ? null : block
      continue
    }

    const pic = imageOf(body)
    if (pic) {
      para = null
      imageBlock(pic.ref, pic.alt, pic.caption, ownerFor(indent), pic.attrs)
      continue
    }

    // A CLIP — `<video>`/`<audio>`, on one line as the exporter writes it or
    // spread over a few as READMEs do (bounded: an unclosed tag is text).
    const clipOpen = /^<(video|audio)(?:\s|>)/i.exec(body)
    if (clipOpen) {
      let html = body
      let j = i
      const closer = new RegExp(`</${clipOpen[1]}\\s*>`, 'i')
      while (!closer.test(html) && j + 1 < lines.length && j - i < 20) html += `\n${lines[++j].trim()}`
      const clip = closer.test(html) ? mediaOf(html) : null
      if (clip) {
        para = null
        i = j
        if ('fields' in clip) add(mk('media', { html: '', ...clip.fields }), ownerFor(indent))
        // A SOURCE THE MODEL MAY NOT HOLD is shown, never loaded: the words
        // and the address as inert code, the same way an image that could
        // not be imported is reported. `javascript:` ends up as text.
        else add(mk('p', { html: `${esc(clip.label || clipOpen[1].toLowerCase())}${clip.refused ? ` <code>${esc(clip.refused)}</code>` : ''}` }), ownerFor(indent))
        continue
      }
    }

    // A PAGE LINK is a wikilink ALONE on its line — `[[Title]]`, which
    // Obsidian and Foam already read as a link to that note. Resolved to a
    // page id with the other wikilinks, once every page exists; one that
    // names no page falls back to the paragraph it would have been
    // (resolvePageLinks). An aliased `[[a|b]]` stays inline: the alias is
    // words a page card has no place for.
    const lone = /^\[\[([^[\]|#^\n]+)\]\]$/.exec(body)
    if (lone && lone[1].trim()) {
      para = null
      add(mk('pagelink', { html: '', page: `${WIKI_SCHEME}${encodeURIComponent(lone[1].trim())}` }), ownerFor(indent))
      continue
    }

    const card = body.includes('<!-- bento:card') ? cardOf(body) : null
    if (card) {
      para = null
      const b = mk('link', card)
      // the readable fallback an old build renders, written from the fields
      // by the one function the editor also uses (model.ts)
      b.html = linkCardHtml(linkCard(b))
      add(b, ownerFor(indent))
      continue
    }

    // A WHOLE LINE THAT IS AN EMBED BECOMES ONE. Strictly after `imageOf`,
    // which owns the image-extension list: `![[diagram.png]]` is a picture and
    // `![[Design notes]]` is a transclusion, and the two are told apart in
    // exactly one place.
    //
    // The block leaves here with NO `page` — at parse time a wikilink names a
    // file and no page exists yet — carrying the same `#w/` placeholder link
    // every other block carries. planImport resolves it and embed.ts
    // `linkEmbeds` reads the answer back off the html.
    const emb = parseEmbedLine(body)
    if (emb) {
      para = null
      add(mk('embed', {
        html: `<a href="${WIKI_SCHEME}${encodeURIComponent(emb.target)}">${esc(emb.target)}</a>`,
        ...(emb.anchor ? { anchor: emb.anchor } : {}),
      }), ownerFor(indent))
      continue
    }

    // a plain line: a continuation of the block above, or a new paragraph.
    //
    // A SOFT LINE BREAK BECOMES <br> rather than a space. Notes are written
    // with the line breaks the author put there (addresses, verse, one-line
    // facts), and joining them into a paragraph is not reversible — while
    // keeping them is, by deleting the break.
    const text = inlineHtml(body)
    if (ownText) { ownText.html = text; para = ownText; touched = ownText }
    else if (para) { para.html = `${para.html}<br>${text}`; touched = para }
    else para = add(mk('p', { html: text }), ownerFor(indent))
  }
  settleId()

  // A CANVAS OWNS THE CARDS ITS FENCE COUNTS: the next `cards.length` blocks
  // at the canvas's own level, in order, each taking its position. Their own
  // children stay theirs. Counting rather than indenting, because a card is
  // any block type and several types export without indentation.
  for (const { block, cards } of canvases) {
    let k = blocks.indexOf(block) + 1
    for (const pos of cards) {
      while (k < blocks.length && blocks[k].parent !== block.parent) k++
      if (k >= blocks.length) break
      const card = blocks[k++]
      card.parent = block.id
      if (pos) { card.x = pos[0]; card.y = pos[1] }
    }
  }

  return {
    title: title || fileTitle,
    blocks,
    ...(frontmatter !== undefined ? { frontmatter } : {}),
    ...(design !== undefined ? { design } : {}),
    ...(designs !== undefined ? { designs } : {}),
    images,
    remoteImages,
    tables,
    // absent when the file had none — a default is never stored (PLATFORM §3)
    ...(Object.keys(footnotes).length ? { footnotes } : {}),
  }
}

/** `|---|:--:|` — the row that makes the line above it a table header. */
function isTableRule(line: string | undefined): boolean {
  if (!line) return false
  const t = line.trim()
  return t.includes('-') && t.includes('|') && /^\|?[\s:|-]+$/.test(t)
}

/**
 * One pipe-table row into its cells.
 *
 * The leading and trailing pipes are OPTIONAL in GFM — `a | b` is a row — so
 * they are stripped only when present; splitting a fully-piped row without
 * stripping them yields a phantom empty cell at each end, which would shift
 * every column by one against the rule row.
 *
 * `\|` is the escape for a literal pipe and is unescaped after the split, not
 * before: a lookbehind-free split has to keep the backslash to know not to cut
 * there.
 */
function splitRow(line: string): string[] {
  const t = line.trim().replace(/^\|/, '').replace(/\|$/, '')
  const out: string[] = []
  let cur = ''
  for (let k = 0; k < t.length; k++) {
    if (t[k] === '\\' && t[k + 1] === '|') { cur += '|'; k++; continue }
    if (t[k] === '|') { out.push(cur.trim()); cur = ''; continue }
    cur += t[k]
  }
  out.push(cur.trim())
  return out
}

/** `:---:` → 'center'. The colons in the rule row are the only thing GFM can
 *  say about alignment, which is why `colAlign` is per column. */
function alignOf(rule: string): string {
  const t = rule.trim()
  const l = t.startsWith(':'), r = t.endsWith(':')
  return l && r ? 'center' : r ? 'right' : l ? 'left' : ''
}

// ---- a folder of notes -----------------------------------------------------

export interface SourceFile {
  /** path relative to the import root, `/` separated (webkitRelativePath) */
  path: string
  text: string
}

export interface ImportStats {
  files: number
  pages: number
  blocks: number
  /** `[[wikilinks]]` that found a page in this import */
  linked: number
  /** …and those that named a note that was not in the selection */
  dangling: number
  frontmatter: number
  /** notes that shared a NAME with an earlier one, so links to them resolved to
   *  the first — the reader is told rather than left to find out */
  duplicateNames: number
  tables: number
  remoteImages: number
}

export interface ImportPlan {
  pages: Page[]
  /** the first design a note named in its front matter (path order). Each
   *  note's own is ALSO on its page as `page.design`, which is what the
   *  editor uses; this stays for callers that want one space-level name. */
  design?: string
  /** designs the notes carried, first writer wins per name */
  designs?: Record<string, unknown>
  /** local image references, still to be resolved against picked files */
  images: PendingImage[]
  stats: ImportStats
  /**
   * The document's footnotes AFTER the import — `opts.existingNotes` with
   * every imported note merged in, so the caller assigns it whole.
   *
   * A SUPERSET, never a patch, because merging renames: two vaults both number
   * their footnotes from 1, so importing more than one file collides by
   * construction, and the second file's `[^1]` must not be answered by the
   * first file's note. Whatever was renamed has already been rewritten in that
   * file's blocks, here, where it is still known which blocks came from which
   * file.
   */
  footnotes: Record<string, string>
}

const normalizePath = (p: string): string =>
  p.replace(/\\/g, '/').replace(/^\.?\//, '').replace(/\/+/g, '/').trim()

const dirOf = (p: string): string => p.slice(0, Math.max(0, p.lastIndexOf('/')))
const fileOf = (p: string): string => p.slice(p.lastIndexOf('/') + 1)
const stemOf = (p: string): string => fileOf(p).replace(/\.[^.]+$/, '')
const lastSeg = (p: string): string => p.slice(p.lastIndexOf('/') + 1)

/**
 * Many notes → the pages of a space, with the folder tree rebuilt.
 *
 * Pure: no files are read here and no ids leave this document, so the whole
 * plan can be asserted in node. The caller does the two things that need a
 * browser — reading image bytes, and running the sanitizer — and then commits
 * the pages in ONE step.
 */
export function planImport(
  files: SourceFile[],
  opts: {
    rootTitle: string
    /**
     * Pages the space ALREADY has, by title — consulted only after the import's
     * own index misses.
     *
     * Order matters and it is this way round on purpose: a vault imported whole
     * must link to itself, never to a stranger page that happens to share a
     * title. But someone adding one note to a space they have been keeping for
     * a year expects `[[Home]]` to mean their Home, and without this it would
     * arrive as dead text.
     */
    resolveExisting?: (target: string) => string | undefined
    /** the footnotes the space already has, so an imported label that would
     *  land on a DIFFERENT note is renamed rather than silently reused */
    existingNotes?: Record<string, string>
    /**
     * Is this id already used in the space the import lands in — by a block
     * or a page? A `{#id}` a note carries is kept only when the answer is no
     * and no earlier note in this import took it; otherwise the block gets a
     * fresh id. Ids are unique document-wide, and a Markdown file is the one
     * place an id arrives that this app did not mint.
     */
    idTaken?: (id: string) => boolean
  },
): ImportPlan {
  const src = files
    .map((f) => ({ path: normalizePath(f.path), text: f.text }))
    .filter((f) => f.path)
    .sort((a, b) => a.path.localeCompare(b.path))

  // A picked FOLDER already has a common first segment, and that folder is the
  // root of the tree — so only a flat, mixed selection needs a container page
  // invented for it. Either way the import lands under exactly one new root:
  // it is undoable in one step and deletable in one gesture.
  const tops = new Set(src.map((f) => (f.path.includes('/') ? f.path.split('/')[0] : '')))
  const wrap = src.length > 1 && !(tops.size === 1 && !tops.has(''))

  const pages: Page[] = []
  const images: PendingImage[] = []
  const footnotes: Record<string, string> = { ...(opts.existingNotes ?? {}) }
  const usedLabels = new Set(Object.keys(footnotes))
  const stats: ImportStats = {
    files: src.length, pages: 0, blocks: 0, linked: 0, dangling: 0,
    frontmatter: 0, tables: 0, remoteImages: 0, duplicateNames: 0,
  }

  let rootId: string | undefined
  if (wrap) {
    const root: Page = { id: uid('p'), title: opts.rootTitle, icon: 'folder', blocks: [] }
    pages.push(root)
    rootId = root.id
  }

  // A folder note — `Notes/Notes.md` or `Notes/index.md` — IS the folder's
  // page rather than a child of an empty one. That convention is what Obsidian
  // and Foam vaults use for a section's overview, and importing it as a
  // sibling of its own subtree reads as a mistake.
  const folderNote = new Map<string, string>()
  for (const f of src) {
    const dir = dirOf(f.path)
    if (!dir) continue
    const stem = stemOf(f.path).toLowerCase()
    if (stem === 'index' || stem === lastSeg(dir).toLowerCase()) {
      if (!folderNote.has(dir)) folderNote.set(dir, f.path)
    }
  }

  // A folder note falls back to the FOLDER's name, not the file's: measured on
  // a real vault, `Meetings/index.md` otherwise titles the whole section
  // "index". Its own `# Heading` still wins, as everywhere else.
  const parsed = new Map<string, ParsedNote>()
  for (const f of src) {
    const dir = dirOf(f.path)
    const fallback = folderNote.get(dir) === f.path ? lastSeg(dir) : stemOf(f.path)
    parsed.set(f.path, parseNote(f.text, fallback))
  }

  // directories first, parents before children, so `parent` always resolves
  const dirs = new Set<string>()
  for (const f of src) {
    for (let d = dirOf(f.path); d; d = dirOf(d)) dirs.add(d)
  }
  const dirPage = new Map<string, Page>()
  for (const dir of [...dirs].sort()) {
    const note = folderNote.get(dir)
    const page: Page = note
      ? { id: uid('p'), title: parsed.get(note)!.title, icon: 'folder', blocks: [] }
      : { id: uid('p'), title: lastSeg(dir), icon: 'folder', blocks: [] }
    const parent = dirPage.get(dirOf(dir))?.id ?? rootId
    if (parent) page.parent = parent
    dirPage.set(dir, page)
    pages.push(page)
  }

  const filePage = new Map<string, Page>()
  for (const f of src) {
    const dir = dirOf(f.path)
    if (folderNote.get(dir) === f.path) { filePage.set(f.path, dirPage.get(dir)!); continue }
    const page: Page = { id: uid('p'), title: parsed.get(f.path)!.title, blocks: [] }
    const parent = dirPage.get(dir)?.id ?? rootId
    if (parent) page.parent = parent
    filePage.set(f.path, page)
    pages.push(page)
  }

  // ---- fill the pages ------------------------------------------------------
  let design: string | undefined
  const designs: Record<string, unknown> = {}
  for (const f of src) {
    const note = parsed.get(f.path)!
    const page = filePage.get(f.path)!
    const dir = dirOf(f.path)

    if (note.frontmatter !== undefined) {
      stats.frontmatter++
      page.blocks.push(...frontmatterBlocks(note.frontmatter))
    }
    page.blocks.push(...note.blocks)
    if (note.design !== undefined && design === undefined) design = note.design
    // A NOTE'S `design:` IS ITS PAGE'S (per-page designs): set on this page
    // exactly as written, even a name this build does not know — it renders
    // the default look, round-trips, and validate() names it.
    if (note.design !== undefined) page.design = note.design
    for (const [k, v] of Object.entries(note.designs ?? {})) if (!Object.hasOwn(designs, k)) designs[k] = v
    if (note.footnotes) {
      // PER FILE, while it is still known which blocks are this file's — after
      // the loop every page is just a page and a rename could not be aimed.
      const renames = mergeNotes(footnotes, note.footnotes, usedLabels)
      if (renames.size) {
        for (const b of note.blocks) if (b.html) b.html = renameRefs(b.html, renames)
      }
    }
    for (const img of note.images) images.push({ ...img, dir })
    stats.tables += note.tables
    stats.remoteImages += note.remoteImages
  }

  // ---- block ids: unique across the import and the space ------------------
  // Each note already refused a repeat of its own ids; this is the same rule
  // across notes (a vault where one note was copied to make another) and
  // against the space being imported into (a space's own export, imported
  // back into it). The later holder is renamed, children and all.
  {
    const seen = new Set<string>(pages.map((p) => p.id))
    for (const page of pages) {
      for (const b of page.blocks) {
        if (!seen.has(b.id) && !opts.idTaken?.(b.id)) { seen.add(b.id); continue }
        const old = b.id
        b.id = uid('b')
        seen.add(b.id)
        for (const c of page.blocks) if (c.parent === old) c.parent = b.id
      }
    }
  }

  // ---- wikilinks, once every page exists ----------------------------------
  const { index, collisions } = linkIndex(src, parsed, filePage, tops.size === 1 ? [...tops][0] : '')
  for (const page of pages) {
    const pl = resolvePageLinks(page.blocks, (target) =>
      index.get(linkKey(target)) ?? opts.resolveExisting?.(linkKey(target)))
    stats.linked += pl.linked
    stats.dangling += pl.dangling
    for (const b of page.blocks) {
      if (!b.html) continue
      const r = resolveWikilinks(b.html, (target) =>
        index.get(linkKey(target)) ?? opts.resolveExisting?.(linkKey(target)))
      b.html = r.html
      stats.linked += r.linked
      stats.dangling += r.dangling
    }
  }

  // …and then the EMBEDS, which read their target back out of the html the
  // sweep above just resolved. It has to be after, not folded into the loop:
  // an embed's `page` is whatever `#p/<id>` the resolver decided on, and
  // deciding it twice in two places is how the block and its own fallback link
  // would come to point at different pages.
  linkEmbeds(pages)

  // NO PAGE ARRIVES WITH ZERO BLOCKS.
  //
  // A folder without a folder note, an empty .md, and the invented root all
  // produced one — and the importer then navigates to plan.pages[0], which in a
  // real vault IS a folder page. A zero-block page has no editable host, no
  // gutter and no `/` menu, so the first thing you saw after importing a vault
  // was a page you could not put a caret in, permanently: nothing ever adds a
  // block to a folder page.
  //
  // The editor cannot produce this state (mergeBack refuses to remove the last
  // block) and validate() grades it `error`. DECISIONS.md recorded the
  // invariant against the editor; the importer landed in the same tree and
  // broke it, which is exactly the kind of gap parallel work opens.
  for (const p of pages) if (!p.blocks.length) p.blocks.push(mk('p', { html: '' }))

  for (const p of pages) stats.blocks += p.blocks.length
  stats.duplicateNames = collisions
  stats.pages = pages.length
  return {
    pages, images, stats, footnotes,
    ...(design !== undefined ? { design } : {}),
    ...(Object.keys(designs).length ? { designs } : {}),
  }
}

/**
 * WHERE FRONTMATTER GOES, and this is a permanent decision because it is in
 * every file an import writes: verbatim, into a `code` block marked
 * `frontmatter: true`, folded inside a toggle so it does not shout from the
 * top of every page.
 *
 * NOT parsed into fields. Spaces has no properties model yet, and a properties
 * model designed here — in an importer, from whatever keys one person's vault
 * happens to use — would pre-empt the real design and be impossible to change,
 * because the shape would already be in files on disks. Nothing is interpreted
 * and nothing is lost: the yaml is still exactly the author's text, it is
 * searchable, it prints (toggles always print open), it exports back out as a
 * fenced yaml block, and `frontmatter: true` is the marker that makes adopting
 * these into real properties a mechanical sweep on the day that ships.
 */
function frontmatterBlocks(yaml: string): Block[] {
  const fold = mk('toggle', { html: 'Frontmatter', open: false })
  const body = mk('code', { html: esc(yaml), lang: 'yaml', frontmatter: true, parent: fold.id })
  return [fold, body]
}

/** Everything a `[[wikilink]]` may name, lowercased. First writer wins, so the
 *  result does not depend on the order a file picker happened to hand us. */
function linkIndex(
  src: SourceFile[],
  parsed: Map<string, ParsedNote>,
  filePage: Map<string, Page>,
  root: string,
): { index: Map<string, string>; collisions: number } {
  const index = new Map<string, string>()
  // Two notes can share a NAME in different folders, and a [[wikilink]] names
  // only the name. First one wins — which is the standard behaviour and the
  // only thing a bare name CAN mean — but it must be reported: silently, every
  // link to the second note pointed at the first, including that note's links
  // to ITSELF, and the import claimed unqualified success. Counted here and
  // surfaced in the summary, so the reader knows which links to check.
  const collisions = new Set<string>()
  const put = (k: string, id: string) => {
    const key = linkKey(k)
    if (key && index.has(key) && index.get(key) !== id) collisions.add(key)
    if (key && !index.has(key)) index.set(key, id)
  }
  for (const f of src) {
    const id = filePage.get(f.path)!.id
    put(stemOf(f.path), id)                                   // [[Note]]
    put(f.path.replace(/\.[^.]+$/, ''), id)                   // [[folder/Note]]
    if (root && f.path.startsWith(`${root}/`)) {
      put(f.path.slice(root.length + 1).replace(/\.[^.]+$/, ''), id)  // vault-relative
    }
    put(parsed.get(f.path)!.title, id)                        // [[The title]]
  }
  return { index, collisions: collisions.size }
}

/** Wikilink targets ignore case, a `.md` suffix, and a `#heading`/`^block`
 *  anchor — the model has no in-page anchors, so those land on the page. */
const linkKey = (raw: string): string =>
  raw.replace(/^\.?\//, '').replace(/[#^].*$/, '').replace(/\.(md|markdown)$/i, '')
    .trim().toLowerCase()

export interface Resolution { html: string; linked: number; dangling: number }

/**
 * Turn the parser's `#w/` placeholders into real `#p/<id>` links.
 *
 * A target that is not in this import stays as the literal `[[Name]]` the
 * author wrote: honest, searchable, and still correct markdown if it is
 * exported again — and it resolves for real if the missing note is imported
 * later and the author re-links it. A silent unlink would be a lie about what
 * the file said.
 */
export function resolveWikilinks(html: string, lookup: (target: string) => string | undefined): Resolution {
  let linked = 0
  let dangling = 0
  const out = html.replace(
    /<a href="#w\/([^"]*)">([\s\S]*?)<\/a>/g,
    (_m, enc: string, text: string) => {
      let target = enc
      try { target = decodeURIComponent(enc) } catch { /* keep the raw form */ }
      const id = lookup(target)
      if (id) { linked++; return `<a href="#p/${esc(id)}">${text}</a>` }
      dangling++
      const shown = esc(target)
      return text === shown ? `[[${text}]]` : `[[${shown}|${text}]]`
    },
  )
  return { html: out, linked, dangling }
}