@leavepulse/ui 0.43.4 → 0.45.0

package/src/components/codeHighlight.ts

@@ -79,19 +79,67 @@ const BOOLEANS = new Set([
   "Some", "Ok", "Err", // rust common variants read as constants
 ])
 
-// One master regex, alternation ordered so longer/greedier rules win first.
-// Order: comments → strings → numbers → identifiers → punctuation.
-const MASTER = new RegExp(
-  [
-    "(\\/\\/[^\\n]*|#[^\\n]*|\\/\\*[\\s\\S]*?\\*\\/)", // 1 comment
-    "(\"(?:\\\\.|[^\"\\\\])*\"|'(?:\\\\.|[^'\\\\])*'|`(?:\\\\.|[^`\\\\])*`)", // 2 string
-    "(@[A-Za-z_$][\\w$]*)", // 3 annotation (@Override, @ConfigSerializable — JVM)
-    "(\\b\\d[\\d_]*(?:\\.\\d+)?(?:e[+-]?\\d+)?[fFlLdD]?\\b)", // 4 number (JVM suffixes)
-    "([A-Za-z_$][\\w$]*)", // 5 identifier (keyword/bool/func/prop/plain)
-    "([{}()\\[\\];:,.<>=+\\-*/%!&|?]+)", // 6 punctuation
-  ].join("|"),
-  "g",
-)
+/*
+ * Comment syntax is the one thing the shared tokenizer cannot guess: `#` opens
+ * a comment in shell, Python, YAML and TOML but is a private field in
+ * TypeScript, and `//` is a comment in C-family code but part of every URL in a
+ * YAML file. So each language names its own comment forms.
+ */
+type CommentStyle = "c" | "hash" | "html" | "none"
+
+const COMMENTS: Record<CodeLang, CommentStyle> = {
+  ts: "c",
+  js: "c",
+  json: "none",
+  bash: "hash",
+  html: "html",
+  python: "hash",
+  rust: "c",
+  yaml: "hash",
+  toml: "hash",
+  kotlin: "c",
+  java: "c",
+  groovy: "c",
+  plain: "none",
+}
+
+const COMMENT_PATTERN: Record<CommentStyle, string> = {
+  c: "\\/\\/[^\\n]*|\\/\\*[\\s\\S]*?\\*\\/",
+  // A `#` only starts a comment at the start of a word, so `a#b` in a URL or
+  // `${#arr[@]}` in shell stay code.
+  hash: "(?<![\\w$])#[^\\n]*",
+  html: "<!--[\\s\\S]*?-->",
+  none: "(?!)",
+}
+
+/** Where an unterminated block comment opens on a line, and what closes it. */
+const BLOCK: Partial<Record<CommentStyle, { open: string; close: string }>> = {
+  c: { open: "/*", close: "*/" },
+  html: { open: "<!--", close: "-->" },
+}
+
+const masters = new Map<CommentStyle, RegExp>()
+
+// One master regex per comment style, alternation ordered so longer/greedier
+// rules win first. Order: comments → strings → numbers → identifiers → punctuation.
+function masterFor(style: CommentStyle): RegExp {
+  let re = masters.get(style)
+  if (!re) {
+    re = new RegExp(
+      [
+        `(${COMMENT_PATTERN[style]})`, // 1 comment
+        "(\"(?:\\\\.|[^\"\\\\])*\"|'(?:\\\\.|[^'\\\\])*'|`(?:\\\\.|[^`\\\\])*`)", // 2 string
+        "(@[A-Za-z_$][\\w$]*)", // 3 annotation (@Override, @ConfigSerializable — JVM)
+        "(\\b\\d[\\d_]*(?:\\.\\d+)?(?:e[+-]?\\d+)?[fFlLdD]?\\b)", // 4 number (JVM suffixes)
+        "(#?[A-Za-z_$][\\w$]*)", // 5 identifier (keyword/bool/func/prop/plain), incl. #private
+        "([{}()\\[\\];:,.<>=+\\-*/%!&|?]+)", // 6 punctuation
+      ].join("|"),
+      "g",
+    )
+    masters.set(style, re)
+  }
+  return re
+}
 
 function classifyIdent(name: string, before: string, after: string): string {
   if (KEYWORDS.has(name)) return C.keyword
@@ -103,11 +151,13 @@ function classifyIdent(name: string, before: string, after: string): string {
 
 /** Tokenize one line into coloured spans. JSON keys get the property colour. */
 export function tokenizeLine(line: string, lang: CodeLang): Token[] {
+  if (lang === "plain") return line ? [{ text: line, cls: "" }] : []
   const out: Token[] = []
   let last = 0
   let m: RegExpExecArray | null
-  MASTER.lastIndex = 0
-  while ((m = MASTER.exec(line)) !== null) {
+  const master = masterFor(COMMENTS[lang])
+  master.lastIndex = 0
+  while ((m = master.exec(line)) !== null) {
     if (m.index > last) out.push({ text: line.slice(last, m.index), cls: "" })
     const [full, comment, str, annotation, num, ident, punct] = m
     if (comment != null) out.push({ text: full, cls: C.comment })
@@ -135,3 +185,49 @@ export function tokenizeLine(line: string, lang: CodeLang): Token[] {
   if (last < line.length) out.push({ text: line.slice(last), cls: "" })
   return out
 }
+
+/**
+ * Tokenize a whole snippet, carrying a block comment (`/* … *\/`, `<!-- … -->`)
+ * across the lines it spans. `tokenizeLine` alone sees each line in isolation
+ * and coloured the middle of a doc comment as code.
+ */
+export function tokenizeLines(lines: string[], lang: CodeLang): Token[][] {
+  const block = BLOCK[COMMENTS[lang]]
+  if (!block) return lines.map((line) => tokenizeLine(line, lang))
+  const out: Token[][] = []
+  let open = false
+  for (const line of lines) {
+    let rest = line
+    const tokens: Token[] = []
+    if (open) {
+      const end = rest.indexOf(block.close)
+      if (end === -1) {
+        out.push(rest ? [{ text: rest, cls: C.comment }] : [])
+        continue
+      }
+      tokens.push({ text: rest.slice(0, end + block.close.length), cls: C.comment })
+      rest = rest.slice(end + block.close.length)
+      open = false
+    }
+    const lineTokens = tokenizeLine(rest, lang)
+    // A closed comment is already a comment token, so an opener left in plain
+    // code is one the line never closes: from there on, the line is comment.
+    const at = lineTokens.findIndex(
+      (t) => t.cls !== C.comment && t.cls !== C.string && t.text.includes(block.open),
+    )
+    if (at >= 0) {
+      const cut = lineTokens[at].text.indexOf(block.open)
+      const tail = lineTokens
+        .slice(at)
+        .map((t) => t.text)
+        .join("")
+        .slice(cut)
+      tokens.push(...lineTokens.slice(0, at))
+      if (cut > 0) tokens.push({ text: lineTokens[at].text.slice(0, cut), cls: lineTokens[at].cls })
+      tokens.push({ text: tail, cls: C.comment })
+      open = true
+    } else tokens.push(...lineTokens)
+    out.push(tokens)
+  }
+  return out
+}

package/src/components/color.ts

@@ -50,7 +50,15 @@ export function clampHsv(c: Hsv): Hsv {
   }
 }
 
-export function hsvToRgb({ h, s, v, a }: Hsv): Rgb {
+// NaN and Infinity read as 0: one bad channel must not throw out of a public
+// conversion or poison the others.
+const finite = (n: number) => (Number.isFinite(n) ? n : 0)
+
+export function hsvToRgb(color: Hsv): Rgb {
+  const h = finite(color.h)
+  const s = clamp(finite(color.s), 0, 1)
+  const v = clamp(finite(color.v), 0, 1)
+  const a = Number.isFinite(color.a) ? color.a : 1
   const hue = normalizeHue(h) / 60
   const c = v * s
   const x = c * (1 - Math.abs((hue % 2) - 1))
@@ -99,10 +107,20 @@ export function rgbToHsv({ r, g, b, a }: Rgb): Hsv {
 
 const hex2 = (n: number) => clamp(Math.round(n), 0, 255).toString(16).padStart(2, "0")
 
+/**
+ * Alpha quantised to the one precision every format can carry, a byte, so hex,
+ * rgb and hsl agree on whether a colour is opaque: 0.996 used to print as an
+ * opaque rgb() and as "#…fe" in hex.
+ */
+function alphaByte(a: number): number {
+  return Math.round(clamp(a, 0, 1) * 255)
+}
+
 /** "#rrggbb", or "#rrggbbaa" when the colour is not fully opaque. */
 export function rgbToHex({ r, g, b, a }: Rgb): string {
   const base = `#${hex2(r)}${hex2(g)}${hex2(b)}`
-  return a >= 1 ? base : base + hex2(a * 255)
+  const byte = alphaByte(a)
+  return byte >= 255 ? base : base + hex2(byte)
 }
 
 /**
@@ -199,20 +217,23 @@ export function hsvToHsl({ h, s, v }: Hsv): { h: number; s: number; l: number }
 /** The colour as a CSS string in the requested format. */
 export function formatColor(c: Hsv, format: ColorFormat): string {
   const rgb = hsvToRgb(c)
-  const a = Math.round(clamp(c.a, 0, 1) * 100) / 100
+  const byte = alphaByte(rgb.a)
+  const a = Math.round((byte / 255) * 1000) / 1000
 
   if (format === "hex") return rgbToHex(rgb)
   if (format === "rgb") {
-    return a >= 1
+    return byte >= 255
       ? `rgb(${rgb.r}, ${rgb.g}, ${rgb.b})`
       : `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${a})`
   }
 
-  const { h, s, l } = hsvToHsl(c)
-  const hh = Math.round(h)
-  const ss = Math.round(s * 100)
-  const ll = Math.round(l * 100)
-  return a >= 1 ? `hsl(${hh}, ${ss}%, ${ll}%)` : `hsla(${hh}, ${ss}%, ${ll}%, ${a})`
+  // One decimal: whole percentages drift up to 4 per channel on the way back.
+  const { h, s, l } = hsvToHsl({ ...c, h: finite(c.h), s: clamp(finite(c.s), 0, 1), v: clamp(finite(c.v), 0, 1) })
+  const dec = (n: number) => Math.round(n * 10) / 10
+  const hh = dec(h) % 360
+  const ss = dec(s * 100)
+  const ll = dec(l * 100)
+  return byte >= 255 ? `hsl(${hh}, ${ss}%, ${ll}%)` : `hsla(${hh}, ${ss}%, ${ll}%, ${a})`
 }
 
 /** Always opaque — for the swatch behind an alpha checkerboard, and for rails. */

package/src/components/commandSearch.ts

@@ -63,6 +63,12 @@ function score(command: SearchableCommand, terms: CommandSearchTerms): number {
     if (!hit) return 0
     total += hit
   }
+  // A label that IS what was typed, or starts with it, is what the person is
+  // naming: "theme" must put the Theme command above ThemeSwitcher, which only
+  // contains the word but also matches its keywords and description.
+  const typed = terms.include.join(" ")
+  if (typed && label === typed) total += 6
+  else if (typed && label.startsWith(typed)) total += 2
   return total
 }
 

package/src/components/confirm.ts

@@ -0,0 +1,58 @@
+import { reactive } from "vue"
+
+/*
+ * Imperative confirmation: `if (await confirm({ title: "Delete?" })) ...`.
+ * Requests queue here and the one mounted LpConfirmHost shows them one at a
+ * time. Pinned to a global symbol like the toast queue, so a barrel and a deep
+ * import share one host.
+ */
+
+export interface ConfirmOptions {
+  title: string
+  description?: string
+  danger?: boolean
+  icon?: string
+  confirmLabel?: string
+  cancelLabel?: string
+  loadingLabel?: string
+  /**
+   * Work to run on confirm. The dialog stays open with a loading state while it
+   * runs and shows the error's message if it rejects; the promise from
+   * `confirm()` resolves true only once it succeeded.
+   */
+  action?: () => unknown
+}
+
+export interface ConfirmRequest extends ConfirmOptions {
+  id: number
+  resolve: (confirmed: boolean) => void
+}
+
+const STATE_KEY = Symbol.for("@leavepulse/ui:confirm-queue")
+type GlobalWithConfirm = typeof globalThis & {
+  [STATE_KEY]?: { queue: ConfirmRequest[]; nextId: number }
+}
+const g = globalThis as GlobalWithConfirm
+const state = (g[STATE_KEY] ??= { queue: reactive<ConfirmRequest[]>([]), nextId: 0 })
+
+export const confirmQueue = state.queue
+
+/** Ask for confirmation. Resolves false when the user cancels or dismisses. */
+export function confirm(options: ConfirmOptions): Promise<boolean> {
+  if (typeof window === "undefined") return Promise.resolve(false)
+  return new Promise((resolve) => {
+    state.queue.push({ ...options, id: state.nextId++, resolve })
+  })
+}
+
+/** Settle a request and drop it from the queue. Used by the host. */
+export function settleConfirm(id: number, confirmed: boolean): void {
+  const i = state.queue.findIndex((r) => r.id === id)
+  if (i === -1) return
+  const [request] = state.queue.splice(i, 1)
+  request?.resolve(confirmed)
+}
+
+export function useConfirm(): typeof confirm {
+  return confirm
+}

package/src/components/countries.ts

@@ -65,3 +65,15 @@ export function matchCountryByValue(
   }
   return best
 }
+
+/**
+ * Countries matching a search query: by name, or by dial code when the query
+ * carries digits ("+44", "44"). A query without digits must not match on the
+ * dial code at all, or every country would match the empty string.
+ */
+export function filterCountries(list: Country[], query: string): Country[] {
+  const q = query.trim().toLowerCase()
+  if (!q) return list
+  const digits = q.replace(/\D/g, "")
+  return list.filter((c) => c.name.toLowerCase().includes(q) || (digits !== "" && c.dial.includes(digits)))
+}

package/src/components/dateRange.ts

@@ -0,0 +1,134 @@
+import {
+  type CalendarDate,
+  endOfMonth,
+  getLocalTimeZone,
+  parseDate,
+  startOfMonth,
+  today,
+} from "@internationalized/date"
+
+/*
+ * Date ranges as the kit models them: two ISO "YYYY-MM-DD" strings, inclusive
+ * on both ends, the same shape LpDatePicker uses for a single day. Presets are
+ * plain functions so a consumer can add "This quarter" or "Year to date"
+ * without the kit knowing about it.
+ */
+export interface DateRange {
+  start: string
+  end: string
+}
+
+export interface DateRangePreset {
+  label: string
+  range: () => DateRange
+}
+
+export interface DateRangePresetLabels {
+  today: string
+  last7: string
+  last30: string
+  thisMonth: string
+  lastMonth: string
+}
+
+function span(start: CalendarDate, end: CalendarDate): DateRange {
+  return { start: start.toString(), end: end.toString() }
+}
+
+/** The default preset list. `now` is injectable so the set can be tested. */
+export function defaultRangePresets(
+  labels: DateRangePresetLabels,
+  now: () => CalendarDate = () => today(getLocalTimeZone()),
+): DateRangePreset[] {
+  return [
+    { label: labels.today, range: () => span(now(), now()) },
+    { label: labels.last7, range: () => span(now().subtract({ days: 6 }), now()) },
+    { label: labels.last30, range: () => span(now().subtract({ days: 29 }), now()) },
+    { label: labels.thisMonth, range: () => span(startOfMonth(now()), endOfMonth(now())) },
+    {
+      label: labels.lastMonth,
+      range: () => {
+        const previous = now().subtract({ months: 1 })
+        return span(startOfMonth(previous), endOfMonth(previous))
+      },
+    },
+  ]
+}
+
+export function parseIsoDay(iso: string | undefined): CalendarDate | undefined {
+  if (!iso) return undefined
+  try {
+    return parseDate(iso.slice(0, 10))
+  } catch {
+    return undefined
+  }
+}
+
+/** A range with both ends parsed and in order, or undefined. */
+export function normalizeRange(range: Partial<DateRange> | undefined): DateRange | undefined {
+  const start = parseIsoDay(range?.start)
+  const end = parseIsoDay(range?.end)
+  if (!start || !end) return undefined
+  return start.compare(end) <= 0 ? span(start, end) : span(end, start)
+}
+
+export function sameRange(a: Partial<DateRange> | undefined, b: Partial<DateRange> | undefined): boolean {
+  const x = normalizeRange(a)
+  const y = normalizeRange(b)
+  return !!x && !!y && x.start === y.start && x.end === y.end
+}
+
+/** Clip a preset to the allowed bounds; undefined when nothing of it is left. */
+export function clampRange(range: DateRange, min?: string, max?: string): DateRange | undefined {
+  const r = normalizeRange(range)
+  if (!r) return undefined
+  const start = min && r.start < min ? min : r.start
+  const end = max && r.end > max ? max : r.end
+  return start <= end ? { start, end } : undefined
+}
+
+/**
+ * "Jun 3 – 18, 2026" style text: Intl's own range formatting collapses the
+ * shared month and year, which is how a range reads naturally in every locale.
+ */
+export function formatRange(
+  range: DateRange,
+  locale?: string,
+  format: Intl.DateTimeFormatOptions = { year: "numeric", month: "short", day: "numeric" },
+): string {
+  const start = parseIsoDay(range.start)
+  const end = parseIsoDay(range.end)
+  if (!start || !end) return ""
+  const zone = "UTC"
+  const fmt = new Intl.DateTimeFormat(locale, { ...format, timeZone: zone })
+  return fmt.formatRange(start.toDate(zone), end.toDate(zone))
+}
+
+export interface ReshapeRules {
+  /** Whether the moving end may land on this day (min, max, disabled). */
+  allowed?: (iso: string) => boolean
+  /** Days a range may not include. */
+  unavailable?: (iso: string) => boolean
+  /** Longest range, in days, counting both ends. */
+  maximumDays?: number
+}
+
+/**
+ * The range one end makes when it is dragged to `moving` while the other stays
+ * at `anchor`; passing the anchor flips which end is which. Null when the result
+ * would break a rule, so a drag simply does not follow onto that day.
+ */
+export function reshapeRange(anchor: string, moving: string, rules: ReshapeRules = {}): DateRange | null {
+  const a = parseIsoDay(anchor)
+  const m = parseIsoDay(moving)
+  if (!a || !m) return null
+  if (rules.allowed && !rules.allowed(m.toString())) return null
+  const [start, end] = a.compare(m) <= 0 ? [a, m] : [m, a]
+  if (rules.maximumDays && end.compare(start) + 1 > rules.maximumDays) return null
+  if (rules.unavailable) {
+    for (let d = start; d.compare(end) <= 0; d = d.add({ days: 1 })) {
+      if (rules.unavailable(d.toString())) return null
+    }
+  }
+  return { start: start.toString(), end: end.toString() }
+}

package/src/components/exportData.ts

@@ -0,0 +1,228 @@
+/*
+ * Data export shared by the table and the chart: CSV text, a file download,
+ * and an SVG rasterised with its theme resolved.
+ */
+
+export interface CsvColumn<Row> {
+  key: string
+  /** Header cell. Defaults to the key. */
+  label?: string
+  /** The value written for a row; the row's `key` field when omitted. */
+  value?: (row: Row) => unknown
+}
+
+export interface CsvOptions {
+  /** Field separator. Default ",". Some locales' spreadsheets expect ";". */
+  separator?: string
+  /** Prefix a UTF-8 byte order mark so Excel reads non-ASCII text correctly. */
+  bom?: boolean
+  /**
+   * Neutralise cells a spreadsheet would run as a formula (leading = + - @,
+   * tab or CR) by prefixing a quote. On by default: exported data is often
+   * user-supplied, and opening it is enough to trigger a formula.
+   */
+  guardFormulas?: boolean
+  /** Line ending. Default "\r\n", as RFC 4180 specifies. */
+  newline?: string
+}
+
+const FORMULA_START = /^[=+\-@\t\r]/
+
+function cellText(value: unknown): string {
+  if (value == null) return ""
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? "" : value.toISOString()
+  if (typeof value === "object") return JSON.stringify(value)
+  return String(value)
+}
+
+/** One CSV field, quoted when it holds a separator, a quote or a line break. */
+export function csvField(value: unknown, options: CsvOptions = {}): string {
+  const separator = options.separator ?? ","
+  let text = cellText(value)
+  if ((options.guardFormulas ?? true) && typeof value === "string" && FORMULA_START.test(text)) {
+    text = `'${text}`
+  }
+  const needsQuotes = text.includes(separator) || /["\r\n]/.test(text) || /^\s|\s$/.test(text)
+  return needsQuotes ? `"${text.replace(/"/g, '""')}"` : text
+}
+
+/** Rows as CSV text, a header line first. */
+export function toCsv<Row>(rows: readonly Row[], columns: readonly CsvColumn<Row>[], options: CsvOptions = {}): string {
+  const separator = options.separator ?? ","
+  const newline = options.newline ?? "\r\n"
+  const line = (cells: unknown[]) => cells.map((c) => csvField(c, options)).join(separator)
+  const out = [line(columns.map((c) => c.label ?? c.key))]
+  for (const row of rows) {
+    out.push(
+      line(columns.map((c) => (c.value ? c.value(row) : (row as Record<string, unknown>)[c.key]))),
+    )
+  }
+  return (options.bom ? "" : "") + out.join(newline) + newline
+}
+
+/**
+ * Hand the viewer a file to save. Does nothing outside a browser, so a call
+ * that runs during SSR is harmless.
+ */
+export function downloadFile(name: string, data: Blob | string, type = "text/plain;charset=utf-8"): void {
+  if (typeof document === "undefined" || typeof URL === "undefined") return
+  const blob = typeof data === "string" ? new Blob([data], { type }) : data
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement("a")
+  a.href = url
+  a.download = name
+  a.rel = "noopener"
+  a.style.display = "none"
+  document.body.append(a)
+  a.click()
+  a.remove()
+  setTimeout(() => URL.revokeObjectURL(url), 0)
+}
+
+const PAINT_PROPS = [
+  "fill",
+  "fill-opacity",
+  "fill-rule",
+  "stroke",
+  "stroke-opacity",
+  "stroke-width",
+  "stroke-dasharray",
+  "stroke-dashoffset",
+  "stroke-linecap",
+  "stroke-linejoin",
+  "opacity",
+  "stop-color",
+  "stop-opacity",
+  "color",
+  "font-family",
+  "font-size",
+  "font-weight",
+  "letter-spacing",
+  "text-anchor",
+  "dominant-baseline",
+  "visibility",
+  "display",
+] as const
+
+/**
+ * A standalone copy of a live SVG: every element carries its computed paint as
+ * an inline style, so CSS custom properties and classes from the page's
+ * stylesheet survive being rendered as an image, and running SMIL animations
+ * are frozen at their end state.
+ */
+export function inlineSvg(svg: SVGSVGElement): SVGSVGElement {
+  const clone = svg.cloneNode(true) as SVGSVGElement
+  const source = [svg, ...svg.querySelectorAll("*")]
+  const target = [clone, ...clone.querySelectorAll("*")]
+  source.forEach((el, i) => {
+    const copy = target[i]
+    if (!(copy instanceof Element)) return
+    const computed = getComputedStyle(el)
+    const style = PAINT_PROPS.map((p) => `${p}:${computed.getPropertyValue(p)}`)
+      .filter((d) => !d.endsWith(":"))
+      .join(";")
+    copy.setAttribute("style", style)
+    copy.removeAttribute("class")
+  })
+  // Comment nodes (Vue leaves them in development builds) may hold "--", which
+  // is invalid inside an XML comment and makes the whole image fail to load.
+  const comments = document.createTreeWalker(clone, NodeFilter.SHOW_COMMENT)
+  const dead: Node[] = []
+  while (comments.nextNode()) dead.push(comments.currentNode)
+  for (const node of dead) node.parentNode?.removeChild(node)
+  for (const anim of clone.querySelectorAll("animate")) {
+    const attr = anim.getAttribute("attributeName")
+    const to = anim.getAttribute("to")
+    if (attr && to != null) anim.parentElement?.setAttribute(attr, to)
+    anim.remove()
+  }
+  clone.setAttribute("xmlns", "http://www.w3.org/2000/svg")
+  const { width, height } = svg.getBoundingClientRect()
+  clone.setAttribute("width", String(width))
+  clone.setAttribute("height", String(height))
+  clone.style.overflow = "visible"
+  return clone
+}
+
+export interface RasterOptions {
+  /** Device pixels per CSS pixel. Default: the screen's ratio, at least 2. */
+  scale?: number
+  /** Fill behind the drawing; transparent when omitted. */
+  background?: string
+  /** Extra space around the drawing, in CSS pixels. */
+  padding?: number
+  /** Drawn above the SVG, in the page's own font. */
+  header?: (ctx: CanvasRenderingContext2D, width: number) => number
+}
+
+/** Rasterise an SVG element to a PNG blob with its theme resolved. */
+export async function svgToPng(svg: SVGSVGElement, options: RasterOptions = {}): Promise<Blob> {
+  const copy = inlineSvg(svg)
+  const width = Number(copy.getAttribute("width"))
+  const height = Number(copy.getAttribute("height"))
+  const markup = new XMLSerializer().serializeToString(copy)
+  const url = URL.createObjectURL(new Blob([markup], { type: "image/svg+xml;charset=utf-8" }))
+  try {
+    const img = new Image()
+    img.decoding = "async"
+    const loaded = new Promise<void>((resolve, reject) => {
+      img.onload = () => resolve()
+      img.onerror = () => reject(new Error("SVG could not be rasterised"))
+    })
+    img.src = url
+    await loaded
+
+    const scale = options.scale ?? Math.max(2, globalThis.devicePixelRatio || 1)
+    const pad = options.padding ?? 0
+    const measure = document.createElement("canvas").getContext("2d")
+    const headerHeight = measure && options.header ? options.header(measure, width) : 0
+    const canvas = document.createElement("canvas")
+    canvas.width = Math.ceil((width + pad * 2) * scale)
+    canvas.height = Math.ceil((height + headerHeight + pad * 2) * scale)
+    const ctx = canvas.getContext("2d")
+    if (!ctx) throw new Error("Canvas 2D is unavailable")
+    ctx.scale(scale, scale)
+    if (options.background) {
+      ctx.fillStyle = options.background
+      ctx.fillRect(0, 0, width + pad * 2, height + headerHeight + pad * 2)
+    }
+    ctx.translate(pad, pad)
+    if (options.header) options.header(ctx, width)
+    ctx.drawImage(img, 0, headerHeight, width, height)
+    return await new Promise<Blob>((resolve, reject) =>
+      canvas.toBlob((b) => (b ? resolve(b) : reject(new Error("PNG encoding failed"))), "image/png"),
+    )
+  } finally {
+    URL.revokeObjectURL(url)
+  }
+}
+
+/** The first non-transparent background at or above an element. */
+export function backgroundOf(el: Element | null): string | undefined {
+  for (let node = el; node; node = node.parentElement) {
+    const bg = getComputedStyle(node).backgroundColor
+    if (bg && bg !== "transparent" && !/rgba\([^)]*,\s*0\)$/.test(bg)) return bg
+  }
+  return undefined
+}
+
+/**
+ * A colour as the browser resolves it where `within` sits, for APIs that cannot
+ * read custom properties (canvas, an SVG drawn as an image).
+ */
+export function resolveCssColor(value: string, within: Element): string {
+  if (!value.includes("var(") && !value.toLowerCase().includes("currentcolor")) return value
+  const probe = document.createElement("span")
+  probe.style.color = value
+  probe.style.display = "none"
+  within.append(probe)
+  const resolved = getComputedStyle(probe).color
+  probe.remove()
+  return resolved || value
+}
+
+/** A filesystem-safe name from a title. */
+export function fileStem(title: string | undefined, fallback: string): string {
+  const stem = (title ?? "").trim().replace(/[\\/:*?"<>|\u0000-\u001f]+/g, "").replace(/\s+/g, "-")
+  return stem || fallback
+}