@kevinpeckham/barkdown 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Peckham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# barkdown
+
+**A Markdown ⇄ DOM round-trip codec, guaranteed to invert marked.** Parse markdown to HTML with [marked](https://github.com/markedjs/marked); edit it as a live DOM (contenteditable, WYSIWYG, programmatic transforms); serialize the DOM back to markdown that is *provably* the same document.
+
+barkdown is the sibling of [@kevinpeckham/barkup](https://github.com/kevinpeckham/barkup):
+barkup guards the tree's identity; barkdown guards the prose's.
+
+```ts
+import { toDom, toMarkdown, roundTrip } from "@kevinpeckham/barkdown";
+
+const html = toDom("# Hello\n\nSome **bold** prose.\n"); // marked + footnotes
+element.innerHTML = html;                                 // …user edits the DOM…
+const markdown = toMarkdown(element);                     // back to markdown
+```
+
+The serializer came out of a production blog CMS — a contenteditable
+WYSIWYG whose every keystroke round-trips through this exact pair of
+functions — and the round-trip guarantee is enforced by a corpus suite
+plus fast-check property tests (~2,000 random documents per run).
+
+## The four guarantees
+
+1. **Canonical identity.** For markdown in barkdown's canonical dialect
+   (ATX headings, `**bold**`/`*italic*`, `-` bullets, fenced code, GFM
+   tables), `toMarkdown(toDom(md)) === md` — byte for byte.
+2. **Fixed-point convergence.** For ANY input markdown, one round trip
+   reaches the canonical form and a second round trip is byte-identical
+   to the first — serialize∘parse is idempotent.
+3. **Footnote identity.** marked-footnote's output shape (`footnote-N` /
+   `footnote-ref-N`, the `data-footnotes` section, back-reference
+   stripping) round-trips exactly, including the legacy
+   `data-footnote-ref` shape and non-numeric labels (`[^note]`).
+4. **No silent loss.** Unknown elements pass through as raw HTML (stable
+   across cycles via markdown's HTML passthrough); every DOM text node
+   reaches the output.
+
+Guarantee 2 is the hard one, and it is exactly why this package exists:
+most DOM-to-markdown serializers produce output that marked reads back
+*differently* — emphasis that stops pairing, escapes that double every
+cycle, footnotes that vanish a trip late. barkdown's serializer models
+marked's actual parsing behavior (including its documented-by-test
+deviations from CommonMark) and falls back to raw HTML — which is stable
+— whenever a construct cannot be expressed reliably in markdown.
+
+## Install
+
+```bash
+npm install @kevinpeckham/barkdown marked marked-footnote
+```
+
+`marked` and `marked-footnote` are peer dependencies — you own the
+version, barkdown guarantees against it (see the version policy below).
+
+## API
+
+```ts
+toMarkdown(input: HTMLElement | string, options?: { adapter?: DomAdapter }): string
+```
+Serialize a DOM subtree (or an HTML string) to GFM markdown. Element
+input is walked directly through a structural interface — browser
+elements, happy-dom, and linkedom all satisfy it. String input needs a
+`document` to parse with: the browser's global one by default, or an
+adapter on the server.
+
+```ts
+toDom(markdown: string): string
+```
+Markdown → HTML string via marked (`gfm: true`) + marked-footnote.
+barkdown configures its own `Marked` instance and never mutates the
+`marked` singleton. DOM construction is your side (`innerHTML`, or any
+DOM library).
+
+```ts
+roundTrip(markdown: string, adapter?: DomAdapter): string
+```
+`toMarkdown(toDom(markdown))` — one application canonicalizes; a second
+is a fixed point.
+
+## Server-side usage (Node, Bun)
+
+Runtimes without a global `document` pass one explicitly:
+
+```ts
+// happy-dom
+import { Window } from "happy-dom";
+import { documentAdapter, toMarkdown } from "@kevinpeckham/barkdown";
+const adapter = documentAdapter(new Window().document);
+
+// linkedom
+import { parseHTML } from "linkedom";
+const adapter = documentAdapter(parseHTML("<html><body></body></html>").document);
+
+toMarkdown("<p>Some <strong>html</strong></p>", { adapter });
+```
+
+Both are covered by a conformance suite, including the CSS-styled-span
+emphasis path (`style="font-weight: 700"` → `**bold**`).
+
+## The canonical dialect
+
+What `roundTrip` normalizes any markdown into:
+
+- **Headings**: ATX (`## Title`), single-line; setext converts. Emphasis
+  inside headings flattens away (editor-safety inherited from the
+  serializer's WYSIWYG origins).
+- **Emphasis**: `**bold**`, `*italic*`, `~~strikethrough~~`. Nesting the
+  markers can't express reliably (empty content, delimiter runs adjacent
+  to punctuation, marked's pairing quirks) serializes as raw inline tags
+  (`<em>…</em>`) around markdown-escaped content — which reparses to the
+  identical DOM.
+- **Lists**: `-` bullets, tight; loose lists flatten (paragraphs inside
+  an item become continuation lines). Ordered lists use `1.` and
+  preserve their `start` number. Task lists keep `[x]` / `[ ]`.
+  Adjacent same-marker lists are held apart by a round-tripping
+  `<!-- -->` comment (a blank line alone would merge them).
+- **Code**: backtick fences with the language info string; inline code
+  picks a backtick run longer than any in the content.
+- **Tables**: GFM pipe tables, alignment as `:---` / `:---:` / `---:`,
+  pipes escaped in cells.
+- **Breaks**: two-space hard breaks; `---` thematic breaks.
+- **Links**: `[text](dest "title")`; destinations are pre-normalized
+  with marked's own `cleanUrl` (encodeURI) transform so they're
+  byte-stable. Self-links (`text === href`, incl. `mailto:`) emit as
+  bare GFM autolinks when the surrounding context re-linkifies safely
+  *and* the URL is already in cleanUrl's canonical percent-encoded form.
+  URLs carrying raw unicode or DOM-decoded entities (`…/café`,
+  `…#&#169;`) canonicalize to the full form — readable text, encoded
+  destination — because re-linkifying them bare would percent-encode
+  the href out from under the text.
+- **Images**: `![alt](src "title")`.
+- **Footnotes**: `[^label]` + `[^label]: text`, multi-paragraph
+  definitions via 4-space continuation. Definitions never referenced
+  outside the footnote section are dropped (marked-footnote renders them
+  to nothing, so they'd silently vanish a trip late otherwise).
+- **Escaping**: `\` `` ` `` `*` `_` `[` `]` `~` `<` always; `&` when it
+  reads as a character entity; `#` `>` `|` `-` `+` `N.` only at line
+  starts. Bare URLs/emails in plain text are defused (`https\://…`,
+  `user\@host`) because marked linkifies them at any position — real
+  links serialize as links instead.
+- **Passthrough**: `<div>`/plain `<span>` wrappers are transparent
+  (contenteditable artifacts). HTML comments round-trip. Elements on
+  CommonMark's HTML-block tag list pass through as raw `outerHTML`;
+  other unknown elements are rebuilt attribute-for-attribute around
+  their markdown-escaped children.
+
+Whitespace inside paragraphs is canonicalized (continuation-line indent
+and trailing whitespace stripped, hard breaks normalized to exactly two
+spaces) — markdown cannot represent the alternatives, so keeping them
+would defeat idempotence.
+
+## Sanitization is out of scope
+
+`toDom` returns whatever marked produces; `toMarkdown` preserves unknown
+elements as raw HTML *by design*. If any input is untrusted, sanitize
+before rendering or storing — e.g. [DOMPurify](https://github.com/cure53/DOMPurify)
+between `toDom()` and `innerHTML`.
+
+## Version policy
+
+The identity guarantee is **with respect to the tested marked range**
+(currently `marked@^18`, `marked-footnote@^1.4`). CI runs the full
+round-trip suite against the pinned versions, and marked upgrades land
+only with a green suite. This is barkdown's one ongoing maintenance
+commitment; the API surface is otherwise frozen at v1, like barkup's.
+
+## Maintenance posture
+
+barkdown is **scoped and stable**: the v1 surface (`toMarkdown` /
+`toDom` / `roundTrip` + the adapter seam) is the whole product, and it
+is intentionally small. Bug reports and guarantee violations are always
+welcome; feature scope is frozen by design.
+
+## License & credit
+
+MIT © Kevin Peckham. Built at [Lightning Jar](https://www.lightningjar.com).
+Pairs with [@kevinpeckham/barkup](https://github.com/kevinpeckham/barkup) —
+typed trees as HTML, with round-trip guarantees of its own.

package/dist/adapter.d.ts

@@ -0,0 +1,78 @@
+/**
+ * DOM adapter seam. barkdown's serializer walks a DOM subtree through a
+ * small structural interface (`HtmlElementLike`), so any standards-shaped
+ * DOM works: the browser's, happy-dom's, linkedom's.
+ *
+ * The adapter is only needed for the string-input branch of
+ * `toMarkdown()` (and therefore `roundTrip()`): turning an HTML string
+ * into a container element requires a `document`. In browsers the global
+ * document is used automatically; on servers pass one explicitly:
+ *
+ *   // happy-dom
+ *   import { Window } from "happy-dom";
+ *   const adapter = documentAdapter(new Window().document);
+ *
+ *   // linkedom
+ *   import { parseHTML } from "linkedom";
+ *   const adapter = documentAdapter(
+ *     parseHTML("<html><body></body></html>").document,
+ *   );
+ */
+/** Error type for barkdown misuse (e.g. no DOM available). */
+export declare class BarkdownError extends Error {
+    name: string;
+}
+/** Structural subset of CSSStyleDeclaration the serializer reads. */
+export interface StyleLike {
+    fontWeight?: string;
+    fontStyle?: string;
+    textDecoration?: string;
+    textDecorationLine?: string;
+    textAlign?: string;
+}
+/** Structural subset of Node the serializer reads. */
+export interface DomNodeLike {
+    readonly nodeType: number;
+    readonly textContent: string | null;
+}
+/**
+ * Structural subset of HTMLElement the serializer reads. Browser
+ * `HTMLElement`, happy-dom and linkedom elements all satisfy it.
+ */
+export interface HtmlElementLike extends DomNodeLike {
+    readonly tagName: string;
+    readonly id: string;
+    readonly childNodes: ArrayLike<DomNodeLike>;
+    readonly children: ArrayLike<HtmlElementLike>;
+    readonly outerHTML: string;
+    getAttribute(name: string): string | null;
+    /** Optional: used to rebuild unknown elements attribute-for-attribute;
+     * without it the serializer falls back to `outerHTML`. */
+    getAttributeNames?(): string[];
+    hasAttribute(name: string): boolean;
+    querySelector(selectors: string): HtmlElementLike | null;
+    querySelectorAll(selectors: string): ArrayLike<HtmlElementLike>;
+    cloneNode(deep?: boolean): DomNodeLike;
+    remove(): void;
+    readonly style?: StyleLike;
+}
+/** Structural subset of Document the adapter needs. */
+export interface DocumentLike {
+    createElement(tagName: string): HtmlElementLike & {
+        innerHTML: string;
+    };
+}
+export interface DomAdapter {
+    /**
+     * Parse an HTML fragment and return a container element whose
+     * children are the fragment's top-level nodes.
+     */
+    containerFromHtml(html: string): HtmlElementLike;
+}
+/** Wrap any standards-shaped document (browser, happy-dom, linkedom, …). */
+export declare function documentAdapter(document: DocumentLike): DomAdapter;
+/**
+ * Resolve the platform document (browsers). Throws a helpful error in
+ * runtimes without one — pass an adapter explicitly there.
+ */
+export declare function defaultAdapter(): DomAdapter;

package/dist/adapter.js

@@ -0,0 +1,48 @@
+/**
+ * DOM adapter seam. barkdown's serializer walks a DOM subtree through a
+ * small structural interface (`HtmlElementLike`), so any standards-shaped
+ * DOM works: the browser's, happy-dom's, linkedom's.
+ *
+ * The adapter is only needed for the string-input branch of
+ * `toMarkdown()` (and therefore `roundTrip()`): turning an HTML string
+ * into a container element requires a `document`. In browsers the global
+ * document is used automatically; on servers pass one explicitly:
+ *
+ *   // happy-dom
+ *   import { Window } from "happy-dom";
+ *   const adapter = documentAdapter(new Window().document);
+ *
+ *   // linkedom
+ *   import { parseHTML } from "linkedom";
+ *   const adapter = documentAdapter(
+ *     parseHTML("<html><body></body></html>").document,
+ *   );
+ */
+/** Error type for barkdown misuse (e.g. no DOM available). */
+export class BarkdownError extends Error {
+    name = "BarkdownError";
+}
+/** Wrap any standards-shaped document (browser, happy-dom, linkedom, …). */
+export function documentAdapter(document) {
+    return {
+        containerFromHtml(html) {
+            const container = document.createElement("div");
+            container.innerHTML = html;
+            return container;
+        },
+    };
+}
+/**
+ * Resolve the platform document (browsers). Throws a helpful error in
+ * runtimes without one — pass an adapter explicitly there.
+ */
+export function defaultAdapter() {
+    const doc = globalThis.document;
+    if (!doc || typeof doc.createElement !== "function") {
+        throw new BarkdownError("No global document in this runtime. Pass an adapter explicitly, " +
+            "e.g. `documentAdapter(new Window().document)` with happy-dom, or " +
+            '`documentAdapter(parseHTML("<html><body></body></html>").document)` ' +
+            "with linkedom.");
+    }
+    return documentAdapter(doc);
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * barkdown — a Markdown ⇄ DOM round-trip codec, guaranteed to invert
+ * marked. Sibling of @kevinpeckham/barkup (barkup guards the tree's
+ * identity; barkdown guards the prose's).
+ *
+ *   toMarkdown(input, options?) — DOM subtree (or HTML string) → markdown
+ *   toDom(markdown)             — markdown → HTML string (marked + footnotes)
+ *   roundTrip(markdown, adapter?) — toMarkdown(toDom(markdown))
+ *
+ * Guarantees (see README):
+ *   1. Canonical identity: toMarkdown(toDom(md)) === md for canonical md.
+ *   2. Fixed-point convergence: one round trip canonicalizes; a second is
+ *      byte-identical to the first.
+ *   3. Footnote identity: marked-footnote's output shape round-trips
+ *      exactly, including the legacy data-footnote-ref shape.
+ *   4. No silent loss: unknown elements pass through as raw HTML; every
+ *      DOM text node reaches the output.
+ */
+import type { DomAdapter } from "./adapter.js";
+/**
+ * Parse markdown with marked, serialize the resulting DOM back to
+ * markdown. One application canonicalizes; a second is a fixed point.
+ */
+export declare function roundTrip(markdown: string, adapter?: DomAdapter): string;
+export type { DocumentLike, DomAdapter, DomNodeLike, HtmlElementLike, StyleLike, } from "./adapter.js";
+export { BarkdownError, defaultAdapter, documentAdapter, } from "./adapter.js";
+export { toDom } from "./parse.js";
+export type { ToMarkdownOptions } from "./serialize.js";
+export { toMarkdown } from "./serialize.js";

package/dist/index.js

@@ -0,0 +1,30 @@
+/**
+ * barkdown — a Markdown ⇄ DOM round-trip codec, guaranteed to invert
+ * marked. Sibling of @kevinpeckham/barkup (barkup guards the tree's
+ * identity; barkdown guards the prose's).
+ *
+ *   toMarkdown(input, options?) — DOM subtree (or HTML string) → markdown
+ *   toDom(markdown)             — markdown → HTML string (marked + footnotes)
+ *   roundTrip(markdown, adapter?) — toMarkdown(toDom(markdown))
+ *
+ * Guarantees (see README):
+ *   1. Canonical identity: toMarkdown(toDom(md)) === md for canonical md.
+ *   2. Fixed-point convergence: one round trip canonicalizes; a second is
+ *      byte-identical to the first.
+ *   3. Footnote identity: marked-footnote's output shape round-trips
+ *      exactly, including the legacy data-footnote-ref shape.
+ *   4. No silent loss: unknown elements pass through as raw HTML; every
+ *      DOM text node reaches the output.
+ */
+import { toDom } from "./parse.js";
+import { toMarkdown } from "./serialize.js";
+/**
+ * Parse markdown with marked, serialize the resulting DOM back to
+ * markdown. One application canonicalizes; a second is a fixed point.
+ */
+export function roundTrip(markdown, adapter) {
+    return toMarkdown(toDom(markdown), adapter ? { adapter } : {});
+}
+export { BarkdownError, defaultAdapter, documentAdapter, } from "./adapter.js";
+export { toDom } from "./parse.js";
+export { toMarkdown } from "./serialize.js";

package/dist/parse.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Render markdown to an HTML string with marked (GFM) + marked-footnote.
+ * This is the parse half of the codec that `toMarkdown` inverts.
+ *
+ * barkdown configures its own `Marked` instance — it never mutates the
+ * `marked` singleton, so a consumer's own marked configuration is
+ * untouched.
+ *
+ * Footnotes emit `<sup><a data-footnote-ref …>` refs + a trailing
+ * `<section data-footnotes>` — which `toMarkdown` inverts back to `[^N]`
+ * + `[^N]: text` GFM footnote syntax.
+ *
+ * NOTE: no sanitization is performed (marked does not sanitize).
+ * Sanitize the output (e.g. DOMPurify) before trusting it in a live DOM.
+ */
+/** Markdown → HTML string. DOM construction is the consumer's side. */
+export declare function toDom(markdown: string): string;

package/dist/parse.js

@@ -0,0 +1,32 @@
+/**
+ * Render markdown to an HTML string with marked (GFM) + marked-footnote.
+ * This is the parse half of the codec that `toMarkdown` inverts.
+ *
+ * barkdown configures its own `Marked` instance — it never mutates the
+ * `marked` singleton, so a consumer's own marked configuration is
+ * untouched.
+ *
+ * Footnotes emit `<sup><a data-footnote-ref …>` refs + a trailing
+ * `<section data-footnotes>` — which `toMarkdown` inverts back to `[^N]`
+ * + `[^N]: text` GFM footnote syntax.
+ *
+ * NOTE: no sanitization is performed (marked does not sanitize).
+ * Sanitize the output (e.g. DOMPurify) before trusting it in a live DOM.
+ */
+import { Marked } from "marked";
+import markedFootnote from "marked-footnote";
+// Lazy singleton: the footnote extension registers exactly once, and
+// only when toDom is first used.
+let instance;
+function getMarked() {
+    if (!instance) {
+        instance = new Marked({ gfm: true }).use(markedFootnote());
+    }
+    return instance;
+}
+/** Markdown → HTML string. DOM construction is the consumer's side. */
+export function toDom(markdown) {
+    if (!markdown)
+        return "";
+    return getMarked().parse(markdown, { async: false });
+}

package/dist/serialize-emphasis.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Emphasis-delimiter machinery: decide whether inline content can be
+ * wrapped in `**` / `*` / `~~` markers and still reparse (via marked) to
+ * the same bytes. Encodes CommonMark flanking rules plus the empirical
+ * quirks of marked's emStrong/del run accounting. Callers fall back to
+ * raw inline tags when wrapping is unrepresentable (`tryWrapDelimited`
+ * returns null).
+ */
+import type { DomNodeLike } from "./adapter.js";
+/**
+ * Wrap inline content in an emphasis delimiter, or return null when the
+ * result would not reparse as written:
+ * - CommonMark delimiters can't face whitespace, so leading/trailing
+ *   whitespace is hoisted outside the markers; empty or whitespace-only
+ *   content is unrepresentable (`****` reparses as literal asterisks).
+ * - Content whose edges already carry *unescaped* marker characters
+ *   (nested emphasis) merges into a longer delimiter run. Symmetric
+ *   runs reparse to the same bytes; asymmetric ones (`**0*!*`) do not.
+ *   Tilde runs beyond `~~` never delimit, so any edge tilde bails.
+ * (`escapeMarkdownText` escapes `*`/`~` in text, so a backslash-preceded
+ * edge char is literal text, not a delimiter — hence the lookbehind.)
+ */
+export declare function tryWrapDelimited(inner: string, marker: string, before: string, next: DomNodeLike | undefined): string | null;

package/dist/serialize-emphasis.js

@@ -0,0 +1,186 @@
+/**
+ * Emphasis-delimiter machinery: decide whether inline content can be
+ * wrapped in `**` / `*` / `~~` markers and still reparse (via marked) to
+ * the same bytes. Encodes CommonMark flanking rules plus the empirical
+ * quirks of marked's emStrong/del run accounting. Callers fall back to
+ * raw inline tags when wrapping is unrepresentable (`tryWrapDelimited`
+ * returns null).
+ */
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+/**
+ * Wrap inline content in an emphasis delimiter, or return null when the
+ * result would not reparse as written:
+ * - CommonMark delimiters can't face whitespace, so leading/trailing
+ *   whitespace is hoisted outside the markers; empty or whitespace-only
+ *   content is unrepresentable (`****` reparses as literal asterisks).
+ * - Content whose edges already carry *unescaped* marker characters
+ *   (nested emphasis) merges into a longer delimiter run. Symmetric
+ *   runs reparse to the same bytes; asymmetric ones (`**0*!*`) do not.
+ *   Tilde runs beyond `~~` never delimit, so any edge tilde bails.
+ * (`escapeMarkdownText` escapes `*`/`~` in text, so a backslash-preceded
+ * edge char is literal text, not a delimiter — hence the lookbehind.)
+ */
+export function tryWrapDelimited(inner, marker, before, next) {
+    const match = inner.match(/^(\s*)([\s\S]*?)(\s*)$/);
+    if (!match)
+        return null;
+    const lead = match[1] ?? "";
+    const core = match[2] ?? "";
+    const trail = match[3] ?? "";
+    if (core === "")
+        return null;
+    const isTilde = marker[0] === "~";
+    const delimiterChar = isTilde ? "~" : "*";
+    if (hasUnsafeMarkerRuns(core, isTilde))
+        return null;
+    // Adjacency: a neighboring same-kind character — escaped or not, in
+    // either direction — merges into (or corrupts) the delimiter run.
+    if (lead === "" && before.endsWith(delimiterChar))
+        return null;
+    if (trail === "" && peekNextChar(next) === delimiterChar)
+        return null;
+    if (hasMarkedPairingHazard(core, marker.length, isTilde))
+        return null;
+    if (flankingFails(core, lead, trail, before, next))
+        return null;
+    return lead + marker + core + marker + trail;
+}
+/**
+ * Interior shapes that empirically corrupt marked's delimiter pairing:
+ * - Interior delimiter runs (nested markers): the wrapper's opener can
+ *   pair early with the first interior run when that run is
+ *   closer-capable and CommonMark's rule of three doesn't block the
+ *   pairing ("**" + interior "**" mispairs; "**" + "*" is blocked —
+ *   which is why plain bold-with-italic content stays wrappable).
+ * - Interior runs directly adjacent to punctuation corrupt marked's
+ *   pairing regardless of CommonMark's flanking math (`*!**0**0*` and
+ *   `*a**b**!*` fail while `**a*b*c**` and `**a *b* c**` pair fine).
+ * - Raw inline tags combined with interior marker characters corrupt
+ *   marked's run scanning (`*<c>**x**</c>*` fails to pair while
+ *   `*<c>x</c>*` is fine). Text `<` is always escaped, so an unescaped
+ *   `<` here is one of our own raw-tag emissions.
+ * - A trailing escape pair (e.g. `…\~`) corrupts marked's closing-run
+ *   scan the same way escaped marker chars do.
+ */
+function hasMarkedPairingHazard(core, markerLength, isTilde) {
+    if (!isTilde && firstInteriorRunSteals(core, markerLength))
+        return true;
+    if (!isTilde && interiorRunTouchesPunctuation(core))
+        return true;
+    if (/(?<!\\)</.test(core) && (isTilde ? /~/ : /\*/).test(core))
+        return true;
+    return /\\[\s\S]$/.test(core);
+}
+/**
+ * Marker-run hazards inside the core content:
+ * - Edge delimiter runs. marked's emStrong run accounting does not honor
+ *   backslash escapes adjacent to a run, so an *escaped* edge star is
+ *   just as hazardous as a real one. Symmetric unescaped asterisk runs
+ *   reparse to the same bytes (`***x***`); anything else bails to the
+ *   raw-tag fallback. Tilde runs beyond `~~` never delimit, so any edge
+ *   tilde bails.
+ * - marked's emStrong/del run arithmetic miscounts around
+ *   backslash-escaped marker characters (anywhere in the content, not
+ *   just at the edges), so any escaped marker char bails. Strikethrough
+ *   pairs additionally match first-come — a `~~` anywhere inside the
+ *   core would close the wrap early.
+ */
+function hasUnsafeMarkerRuns(core, isTilde) {
+    const leadRun = core.match(isTilde ? /^~+/ : /^\*+/)?.[0].length ?? 0;
+    const trailRun = core.match(isTilde ? /~+$/ : /\*+$/)?.[0].length ?? 0;
+    const escapedMarkerChar = isTilde ? /\\~/.test(core) : /\\\*/.test(core);
+    const tildeInterior = isTilde && /~~/.test(core);
+    return (escapedMarkerChar ||
+        tildeInterior ||
+        (isTilde ? leadRun > 0 || trailRun > 0 : leadRun !== trailRun));
+}
+/**
+ * CommonMark flanking (and marked applies the same rules to `~~`): a
+ * delimiter followed by punctuation only *opens* if preceded by
+ * whitespace/punctuation, and one preceded by punctuation only *closes*
+ * if followed by whitespace/punctuation.
+ */
+function flankingFails(core, lead, trail, before, next) {
+    const beforeChar = lead !== "" ? " " : before.slice(-1);
+    const afterChar = trail !== "" ? " " : peekNextChar(next);
+    const coreFirst = core.slice(0, 1);
+    const coreLast = core.slice(-1);
+    const openFails = isPunctuation(coreFirst) &&
+        !(isFlankWhitespace(beforeChar) || isPunctuation(beforeChar));
+    const closeFails = isPunctuation(coreLast) &&
+        !(isFlankWhitespace(afterChar) || isPunctuation(afterChar));
+    return openFails || closeFails;
+}
+/** Iterate the interior `*`-runs of `core` (edge runs merge — skipped). */
+function* interiorStarRuns(core) {
+    for (const m of core.matchAll(/\*+/g)) {
+        const start = m.index ?? 0;
+        const end = start + m[0].length;
+        if (start === 0 || end === core.length)
+            continue; // edge runs merge
+        yield { run: m[0], prev: core[start - 1] ?? "", next: core[end] ?? "" };
+    }
+}
+/**
+ * Would the first interior `*`-run of `core` close against a wrapper
+ * opener of `markerLength` stars? Closer-capable = not preceded by
+ * whitespace and (not preceded by punctuation, or followed by
+ * whitespace/punctuation). The rule of three blocks the pairing when the
+ * combined lengths are a multiple of 3 (and the run lengths aren't).
+ */
+function firstInteriorRunSteals(core, markerLength) {
+    for (const { run, prev, next } of interiorStarRuns(core)) {
+        if (prev === "\\")
+            return false; // escaped → already bailed upstream
+        const precededByWhitespace = /\s/.test(prev);
+        const precededByPunct = isPunctuation(prev);
+        const canClose = !precededByWhitespace &&
+            (!precededByPunct || /\s/.test(next) || isPunctuation(next));
+        if (!canClose)
+            return false; // first run opens; later runs pair inward
+        return (markerLength + run.length) % 3 !== 0;
+    }
+    return false;
+}
+/**
+ * True when any interior (non-edge) `*`-run has punctuation immediately
+ * on either side — the empirically unsafe shape in marked's emphasis
+ * pairing. (Whitespace- and alphanumeric-adjacent runs pair reliably.)
+ */
+function interiorRunTouchesPunctuation(core) {
+    for (const { prev, next } of interiorStarRuns(core)) {
+        if (isPunctuation(prev) || isPunctuation(next))
+            return true;
+    }
+    return false;
+}
+/** Start/end of block counts as whitespace for flanking purposes. */
+function isFlankWhitespace(char) {
+    return char === "" || /\s/.test(char);
+}
+function isPunctuation(char) {
+    return /[\p{P}\p{S}]/u.test(char);
+}
+/**
+ * First character that will follow the current construct in the emitted
+ * markdown — used for flanking checks. Unknown elements return a
+ * conservative non-space, non-punctuation placeholder.
+ */
+function peekNextChar(next) {
+    if (!next)
+        return ""; // end of the inline run — block boundary
+    if (next.nodeType === TEXT_NODE) {
+        return (next.textContent ?? "").slice(0, 1);
+    }
+    if (next.nodeType === ELEMENT_NODE) {
+        const tag = next.tagName.toLowerCase();
+        if (tag === "br")
+            return "\n";
+        // Unknown until serialized: treat as a letter so the flanking
+        // check stays conservative (more raw-tag fallbacks, never a broken
+        // delimiter).
+        return "a";
+    }
+    return "";
+}

package/dist/serialize-footnote-defs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Post-processing pass for footnote definitions in serialized markdown.
+ *
+ * marked-footnote renders nothing for a definition that is never
+ * referenced outside the footnote section itself, so emitting such a
+ * definition would vanish one trip late. This pass canonicalizes the
+ * output by dropping unreferenced definitions up front. Pure
+ * string → string; no DOM involvement.
+ */
+/**
+ * Drop footnote definitions that nothing references. Dropping a
+ * definition can orphan another (its content held the only ref) —
+ * iterate to a fixpoint. Bounded by the number of definitions.
+ */
+export declare function dropUnreferencedFootnoteDefs(markdown: string): string;