@mirrordown/core 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+## 0.1.0
+<sub>2026-10-28</sub>
+
+- *(minor)*
+  Backslash-escaped delimiters are now literal in `remd-mark`, `remd-ins`, `remd-del`, `remd-kbd`, `remd-spoiler`, `remd-sub` and `remd-sup`, as they already were in the `mdit-*` plugins: `\==not marked==` renders as `==not marked==` instead of a `<mark>`, while an escaped backslash (`\==marked==`) still allows the markup. These plugins now depend on the new `@mirrordown/core` package, which holds logic shared across Mirrordown's engines.
+- *(minor)*
+  `mdit-github-alerts` and `remd-github-alerts` now share their alert keywords, default titles, icons, option resolution and (for remark and Sätteri) the marker-line rule through `@mirrordown/core`, instead of keeping duplicate copies. Their output and public exports are unchanged.
+- *(minor)*
+  `remd-mark` now runs its `==mark==` scan through `createDelimitedTransform` and `MARK_DELIMITERS` from `@mirrordown/core`, which the Sätteri plugin shares, and drops its `unist-util-find-*` and `unist-builder` dependencies. Its output is unchanged.
+- *(minor)*
+  `~subscript~` and `^superscript^` now parse the same way in markdown-it, remark and Sätteri: a single `~` or `^` is a delimiter run with emphasis-style flanking, its content is inline markup (spaces, emphasis, links, code and each other), and crossing runs resolve leftmost-first.
+
+  - `mdit-sub` and `mdit-sup` used to keep the content as plain text and reject any space inside it. They now parse it as inline markup, so `~*a* b~` renders emphasis and `^a~b~c^` nests.
+  - `remd-sub` and `remd-sup` are now micromark syntax extensions sharing one resolver from `@mirrordown/core` (`scriptSyntax`), instead of text scans run one after another. Crossing runs such as `^a~b^c~` no longer depend on which plugin was registered first, `~~a~~` without GFM is no longer turned into empty subscripts, and the packages drop their `unist-util-*` dependencies.
+  - The sub guide now shows `remark-gfm` with `singleTilde: false`: GFM's single-tilde strikethrough, which Astro enables by default, otherwise claims `~text~` first.
+- *(minor)*
+  `==mark==`, `++ins++` and `--del--` now pair delimiters the same way in every engine. `@mirrordown/core`'s `createDelimitedTransform` ports markdown-it's delimiter algorithm (the one markdown-it-mark and markdown-it-ins use), and the remark and Sätteri plugins run on it:
+
+  - A closer pairs with the nearest opener: `==a ==b==` highlights only `b`, as markdown-it does.
+  - Spans nest: `==a ==b== c==` is a highlight inside a highlight.
+  - The extra marker of an odd-length run stays outside the span (`===a===` → `=<mark>a</mark>=`); `mdit-del` compared against `+` instead of `-` here, so its marker ended up inside.
+  - `remd-del` no longer mishandles runs such as `--a --- b--` or `--+a+--`, which came from patterns copied from the ins plugin.
+
+  New Sätteri plugins `@mirrordown/sat-ins` and `@mirrordown/sat-del`, also included in `@mirrordown/preset-satteri`. The `del` guide notes that smart punctuation, on by default in Astro, turns `--` into an en dash before the plugin runs.
+- *(minor)*
+  `[[key]]` now scans the same way in every engine. `@mirrordown/core`'s new `createKbdTransform` ports markdown-it-kbd's tokenizer, and `remd-kbd` and the new `@mirrordown/sat-kbd` run on it:
+
+  - Keys nest: `[[a [[b]] c]]`.
+  - A single `]` stays inside a key: `[[a]b]]`.
+  - A line ending before the closing `]]` cancels the key even when formatting sits in between.
+  - `[[[a]]` keeps the extra `[` outside the key.
+
+  `remd-kbd` drops its `unist-util-find-*` and `unist-builder` dependencies. One difference is inherent to the engines and documented in the guide: markdown-it reads `[[*a]]*` as a key, while remark and Sätteri have already read the emphasis.
+
+  `@mirrordown/sat-kbd` is included in `@mirrordown/preset-satteri`.
+- *(minor)*
+  `||spoiler||` now pairs delimiters with markdown-it's rules in every engine: `remd-spoiler` runs on `@mirrordown/core`'s delimiter scan (which gains the `|` marker), so a closer pairs with the nearest opener, spoilers nest, and an odd-length run's extra `|` stays outside; it drops its `unist-util-find-*` and `unist-builder` dependencies.
+
+  New `@mirrordown/sat-spoiler` renders the same JavaScript-free click-to-reveal markup, ships the same stylesheet, and is included in `@mirrordown/preset-satteri`.
+- *(minor)*
+  Sätteri ports of the hast plugins: `@mirrordown/sat-squeeze-paragraphs`, `sat-unwrap-images`, `sat-sectionize`, `sat-lightbox` and `sat-autolink-headings`, all included in `@mirrordown/preset-satteri` (whose stylesheet now also imports the lightbox and autolink-headings styles). Their output is identical to the markdown-it and rehype plugins'. `sat-autolink-headings` takes the same options as `remd-autolink-headings`, including the hast-node ones (`content`, `group`, `properties`, `headingProperties`, `test`).
+
+  The rules these engines must compute identically move into `@mirrordown/core` (`isEmptyParagraph`, `isImageParagraph`, `sectionize`, `headingRank`, and the lightbox's marker, ids and markup), which the rehype plugins now use too; their output is unchanged, and squeeze-paragraphs and unwrap-images drop `hast-util-whitespace`.
+- *(minor)*
+  New `@mirrordown/sat-abbr`: abbreviations (`*[term]: definition`) for Sätteri, with the same output as `remd-abbr` and `mdit-abbr`, and included in `@mirrordown/preset-satteri`. The definition and term rules move into `@mirrordown/core` (`parseAbbreviations`, `createAbbreviationScan`), which `remd-abbr` now uses too; its output is unchanged.
+- *(minor)*
+  New `@mirrordown/sat-steps`: numbered step sequences (`@1. Title` with `>` bodies) for Sätteri, with the same output as `remd-steps` and `mdit-steps`, and included in `@mirrordown/preset-satteri` along with its stylesheet. Step recognition moves into `@mirrordown/core` (`processSteps`), which `remd-steps` now uses too; its output is unchanged.
+- *(minor)*
+  Tab labels behave the same in every engine:
+
+  - `remd-tabs` keeps a tab's label in the tree, as a `tabsLabel` node that is the first child of each `tabsItem` (the `label` field is gone), so remark plugins that run after it also apply to the label, and a panel's `aria-label` is the label's final text.
+  - `data-tabs-group` hashes each label's plain text without a trailing attrs block, as the tabs specification describes. `mdit-tabs` hashed the raw markdown, so labels with links, images, entities or escapes got different ids in markdown-it and remark; labels with a trailing `{…}` change id in both.
+  - `mdit-tabs` escapes a panel's `aria-label` once: `npm & yarn` rendered as `aria-label="npm &amp;amp; yarn"`.
+  - `mdit-tabs` nests its panel tokens inside the tabs tokens, so `mdit-sectionize` no longer opens a `<section>` around a heading in a tab panel that closed outside the panel.
+- *(minor)*
+  `@mirrordown/sat-steps` writes back only the parts of the tree that step recognition changed, through core's new `editableTree`, so every node it leaves alone stays Sätteri's own and keeps its source position for the plugins after it (tabs reads positions to end a group at a blank line). It also recognizes a step header directly after a list marker (`- @1. Step`), as the remark and markdown-it plugins do.
+- *(minor)*
+  A step header written right after nested content (`> > Quoted.` then `@2. Next`) starts the next step in every engine. CommonMark lazily continues the nested paragraph with it, so the remark and Sätteri plugins rendered the header as text inside the previous step; they now read the source's `>` markers as markdown-it does, recovering the header and the blockquote structure of the lines after it. `processSteps` takes the document's source for this.
+- *(minor)*
+  Tab groups nested in step bodies and other containers work in every engine:
+
+  - Block ids (the radio `name` and input ids) number the document's tab groups in the order they open, combined with the group id, instead of hashing a start line that nested groups don't reliably have. Two groups with the same labels in different steps shared radio names, so the first loaded with no panel open and the second's tabs switched the first. Ids of the first group on a page are unchanged; later groups' ids change. Core exports `tabsBlockId`, and `TabsListNode` no longer carries a `blockId`.
+  - `mdit-tabs` keeps a group together across blank lines inside a container (a step body, tab panel, blockquote or list item) when another entry follows, as `remd-tabs` does: the empty `>` lines between entries are the container's own. At the top level a blank line still ends a group.
+- *(minor)*
+  New `@mirrordown/sat-inline-svg`: inlines referenced local `.svg` images as `<svg>` elements in Sätteri, resolving them against the `fileURL` compile option, with the same output as `mdit-inline-svg` and `remd-inline-svg`. The size limits, deduplication and markup move into `@mirrordown/core` (`inlineSvgMarkup`, `svgSpriteId`), which the markdown-it and rehype plugins now use too; their output is unchanged. Like the other presets, `@mirrordown/preset-satteri` leaves it out because it reads files from disk.
+- *(minor)*
+  A tab header written right after nested tab content (`> > Option C body.` then `% Code`) starts a tab in the outer group in every engine. CommonMark lazily continues the nested paragraph with it, so the remark and Sätteri plugins put it in the inner group (the tabs guide's own "Default open tab" demo showed `Code` beside `Option C`); they now read the source's `>` markers as markdown-it does, keeping the header at the depth it was written with and the blockquote structure of the lines after it. `processTabs` takes the document's source for this; the marker handling is shared with steps.
+- *(minor)*
+  A tab header that skips a level no longer loses content in the remark and Sätteri plugins, which dropped it and its body; they now render it as `mdit-tabs` does. In a tab's explicit `> %` body it stays in that panel as text, after any group nested there; in a group of plain `>` bodies it ends the group, and it and the lines after it follow the group as ordinary content, with the blockquotes their `>` markers give. A panel's content now also renders in document order in both plugins, rather than its body before its nested groups.
+- *(patch)*
+  `@mirrordown/core` declares `"sideEffects": false`, so bundlers drop the parts a plugin doesn't import (the escape helpers, the sub/sup micromark syntax) without having to prove them unused.
+- *(patch)*
+  Paragraphs in tab panels and step bodies keep what they had when recognition splits them around a header:
+
+  - A hard break (`line\` then `more`) stays a `<br>` in `remd-tabs`, `remd-steps`, `sat-tabs` and `sat-steps`; it became a plain line break, unlike in `mdit-tabs` and `mdit-steps`.
+  - Text split around a header keeps its source position, and the lines left together are one text node again, as remark gives them.
+  - In `sat-tabs` and `sat-steps`, a paragraph keeps the attributes Sätteri read from its end. A header right after a panel's last paragraph continues that paragraph in CommonMark, so Sätteri saw the paragraph's attribute block mid-paragraph; with Sätteri's `attributes` feature on, the plugins now place that block once the header is split off, where Sätteri would have.
+  - `mdit-tabs` and `mdit-steps` give the panel's opening token its body as `meta.attrsSource`, since the tokens inside index the body's lines, so `mdit-attrs` can read a line's indentation there.
+- *(patch)*
+  Sätteri 0.11 reads attribute blocks and definition lists the way Mirrordown's other engines do, so the Sätteri suite now covers every feature:
+
+  - `preset-satteri` has `attrs` and `definitionList` options, on by default like the other presets, which turn on Sätteri's own `attributes` and `definitionList` features. With them, the preset renders every shared fixture as `preset-remark` and `preset-markdown-it` do.
+  - The `sat-*` packages accept Sätteri 0.11 as well as 0.10 (`^0.10.5 || ^0.11.0`); Astro's Sätteri integration is still on 0.10, where the plugins work as before.
+  - An attribute block ending a tab or step header (`% Tab {.tab}`, `@1. Step {.step}`) now goes on the item in `sat-tabs` and `sat-steps`, as in the other engines: Sätteri read it off the header's paragraph before recognition, and the item didn't get it.
+  - `sat-ruby` parses a ruby's base and reading with the document's features, which Sätteri 0.11.3 and later tell plugins; its `features` option is only needed with an older Sätteri.

package/README.md

@@ -1,9 +1,13 @@
 # @mirrordown/core
 
-🐣 This package name has been claimed with [fledgling](https://github.com/dmno-dev/fledgling) for [https://github.com/mirrordown/mirrordown](https://github.com/mirrordown/mirrordown), and a real release will land here soon.
+> Part of [Mirrordown](https://github.com/mirrordown/mirrordown) — a suite of markdown syntax extensions for the unified and markdown-it ecosystems.
 
-This is a placeholder — there is nothing to install yet.
+Shared, engine-agnostic logic used by Mirrordown's plugins, so the markdown-it (`mdit-*`), remark/rehype (`remd-*`) and Sätteri plugins for a feature behave identically. It has no dependencies and is installed automatically with the plugins that need it; you don't need to depend on it directly.
 
----
+## Escapes
 
-Want to claim a name of your own? Run `npx fledgling add <name> --new --yes` — it reserves the name on npm and can set up token-less (OIDC trusted) publishing for when you are ready.
+Parsers resolve backslash escapes before any post-parse transform runs, so a plugin that scans text for delimiters would see `\==not marked==` as `==not marked==`. These helpers recover which characters of a text node were escaped, by aligning the node's value with its source, and mask them while the plugin scans:
+
+- `escapedIndices(value, source, start, end)` — indices of `value` whose character was backslash-escaped in `source[start..end]`.
+- `maskEscaped(value, indices)` / `unmaskEscaped(value)` — replace those characters with stand-ins no delimiter matches, and restore them.
+- `maskTreeEscapes(tree, source)` — mask every positioned `text` node of a unist tree; returns a function that restores them.

package/dist/index.d.mts

@@ -0,0 +1,329 @@
+import { BlockContent, DefinitionContent, PhrasingContent, Root, RootContent } from "mdast";
+import { Properties } from "hast";
+/**
+ * Indices of `value` whose character was backslash-escaped in `source`, where
+ * `start`–`end` is the source range the text came from. Characters the parser
+ * dropped (backslashes, container prefixes such as `> `, trailing spaces) are
+ * skipped, and a character reference stands for the character it decodes to.
+ */
+export declare const escapedIndices: (value: string, source: string, start: number, end: number) => Set<number>;
+/** Replace the characters at `escaped` with stand-ins no delimiter matches. */
+export declare const maskEscaped: (value: string, escaped: Set<number>) => string;
+/** Restore characters replaced by {@link maskEscaped}. */
+export declare const unmaskEscaped: (value: string) => string;
+/** The shape of a unist text node this module reads and writes. */
+interface TextLikeNode {
+  type: string;
+  value?: unknown;
+  position?: {
+    start: {
+      offset?: number | undefined;
+    };
+    end: {
+      offset?: number | undefined;
+    };
+  } | undefined;
+  children?: TextLikeNode[] | undefined;
+}
+/**
+ * Mask escaped characters in every positioned `text` node of a unist tree, so
+ * a delimiter scan skips them. Returns a function that restores them in every
+ * node afterwards, including nodes the scan created from masked text.
+ */
+export declare const maskTreeEscapes: (tree: TextLikeNode, source: string) => (() => void);
+/** A recognized alert keyword (e.g. `note`, `warning`, `caution`). */
+type AlertType = "note" | "tip" | "important" | "warning" | "caution" | "abstract" | "info" | "todo" | "success" | "question" | "failure" | "danger" | "bug" | "example" | "quote";
+/** Maps every recognized alert keyword (lowercase) to its canonical {@link AlertType}. */
+export declare const ALERT_ALIASES: Record<string, AlertType>;
+/** Default display title for each {@link AlertType}. */
+export declare const DEFAULT_TITLE: Record<AlertType, string>;
+/** Options shared by the GitHub alerts plugins for every engine. */
+interface AlertOptions {
+  /**
+   * Extra alert types beyond the built-in set. Keys are lowercase keywords
+   * (including any aliases you want), values are the canonical type string
+   * that appears in the data-alert attribute and CSS class.
+   */
+  types?: Record<string, string>;
+  /** Default display titles, keyed by canonical type. */
+  titles?: Partial<Record<AlertType, string>>;
+  /** Set false to require exact case on the [!TYPE] keyword. Default: true. */
+  matchCaseInsensitive?: boolean;
+  /** Set false to suppress the SVG icon in the title. Default: true. */
+  icons?: boolean;
+  /** CSS class applied to the alert container. Default: "markdown-alert". */
+  containerClass?: string;
+}
+/** Inline SVG icon markup for each {@link AlertType}. */
+export declare const ICONS: Record<AlertType, string>;
+/** How an alert keyword resolves under a plugin's options. */
+interface AlertResolver {
+  /** The canonical type for a `[!KEYWORD]`, or `undefined` if it is not an alert. */
+  resolve: (keyword: string) => string | undefined;
+  /** The title shown when the alert has no custom title. */
+  titleFor: (type: string) => string;
+  /** The icon SVG for the title, or `""` when icons are off. */
+  iconFor: (type: string) => string;
+  /** The alert container's CSS class. */
+  containerClass: string;
+}
+/** Resolve alert keywords, titles and icons the same way in every engine. */
+export declare const createAlertResolver: (options?: AlertOptions) => AlertResolver;
+/** The shape of an mdast phrasing node this module reads and builds. */
+interface PhrasingLike {
+  type: string;
+  value?: string;
+  alt?: string | null | undefined;
+  children?: readonly PhrasingLike[];
+}
+/** A paragraph that opens with an alert marker, split into its parts. */
+interface AlertParagraph<N extends PhrasingLike> {
+  /** The `[!KEYWORD]` text, before alias resolution. */
+  keyword: string;
+  /** `+` (open) or `-` (closed) for a foldable alert, else `undefined`. */
+  fold: `+` | `-` | undefined;
+  /** The first line after the marker: the custom title, formatting included. */
+  titleNodes: N[];
+  /** The title's plain text (text, inline code and image alt), for `aria-label`. */
+  titleText: string;
+  /** Everything after the first line break (soft or hard): the paragraph's body. */
+  bodyNodes: N[];
+}
+/** Plain text of inline content: text, inline code and image alt count; raw HTML does not. */
+export declare const plainText: (nodes: readonly PhrasingLike[]) => string;
+/**
+ * Split an alert's first paragraph (an mdast `paragraph`'s children) into its marker, title and body, or return `null` when it does not open with a `[!KEYWORD]` marker in plain text. The first line is the marker plus an optional title; everything after the first line break — a newline inside a text node (soft) or a `break` node (hard) — is the body. Nothing is dropped. Text nodes are copied; other nodes are reused as they are.
+ */
+export declare const splitAlertParagraph: <N extends PhrasingLike>(children: readonly N[]) => AlertParagraph<N> | null;
+/** How a scanned span becomes nodes. */
+interface SpanNodes<N extends PhrasingLike> {
+  /** A text node with the given value. */
+  text: (value: string) => N;
+  /** The node a span's content is wrapped in (e.g. an mdast `mark`). */
+  wrap: (children: N[]) => N;
+}
+/** A node's source range, as unist positions carry it. */
+interface Positioned {
+  position?: {
+    start: {
+      offset?: number | undefined;
+    };
+    end: {
+      offset?: number | undefined;
+    };
+  } | undefined;
+}
+/** A scan over one parent's children, and the nodes it created. */
+interface SpanTransform<N extends PhrasingLike> {
+  /** Scan `children`, the children of a node of type `parentType`. Returns `children` itself when no span forms. */
+  (children: readonly N[], parentType?: string): readonly N[];
+  /** Whether `node` was built by this transform (a wrapper or a text node). */
+  built: (node: object) => boolean;
+  /**
+   * The transform for engines whose text values have escapes resolved and whose nodes are read-only, such as Sätteri: escaped characters are masked by aligning each positioned text node with `source`, using copies, and restored in the result. Returns the new children, or `undefined` when no span forms.
+   */
+  withSource: (children: ReadonlyArray<N & Positioned>, parentType: string, source: string) => N[] | undefined;
+}
+/** A marker whose doubled form delimits a span: `==`, `++`, `--` or `||`. */
+type DelimiterMarker = `=` | `+` | `-` | `|`;
+/** Build the delimiter scan for one marker: `=` (mark), `+` (ins), `-` (del) or `|` (spoiler). */
+export declare const createDelimitedTransform: <N extends PhrasingLike>(marker: DelimiterMarker, nodes: SpanNodes<N>) => SpanTransform<N>;
+/** Build the `[[key]]` scan. */
+export declare const createKbdTransform: <N extends PhrasingLike>(nodes: SpanNodes<N>) => SpanTransform<N>;
+/** The marker characters, and the micromark token types each produces. */
+declare const SCRIPTS: {
+  readonly "~": {
+    readonly code: 126;
+    readonly type: "subscript";
+  };
+  readonly "^": {
+    readonly code: 94;
+    readonly type: "superscript";
+  };
+};
+type Marker = keyof typeof SCRIPTS;
+/** The shape of a micromark syntax extension this module builds. */
+interface ScriptSyntax {
+  text: Record<number, unknown>;
+  insideSpan: {
+    null: unknown[];
+  };
+}
+/**
+ * The micromark syntax extension for one of the two markers: `~` (subscript, `subscript` tokens) or `^` (superscript, `superscript` tokens). The constructs of both markers resolve together.
+ */
+export declare const scriptSyntax: (marker: Marker) => ScriptSyntax;
+/** The shape of a hast node this module reads and builds. */
+interface HastLike {
+  type: string;
+  tagName?: string;
+  value?: string;
+  properties?: Record<string, unknown>;
+  children?: readonly HastLike[];
+}
+/** A hast element as this module builds it; its properties fit hast's `Properties`. */
+interface HastElementLike<C> {
+  type: `element`;
+  tagName: string;
+  properties: Record<string, string | string[]>;
+  children: C[];
+}
+/** A `<p>` with no children, or only whitespace text: squeeze-paragraphs removes it. */
+export declare const isEmptyParagraph: (node: HastLike) => boolean;
+/**
+ * A `<p>` whose content is only images (each possibly inside a link or a lightbox button) and whitespace: unwrap-images replaces it with its children.
+ */
+export declare const isImageParagraph: (node: HastLike) => boolean;
+/** The rank of an `h1`–`h6` element, or `undefined`. */
+export declare const headingRank: (node: HastLike) => number | undefined;
+/**
+ * Wrap heading-delimited runs of `nodes` into `<section data-depth>` elements, nesting deeper headings inside shallower ones. Content before the first heading stays unwrapped.
+ */
+export declare const sectionize: <N extends HastLike>(nodes: readonly N[], section: (depth: number, children: N[]) => N, floor?: number) => N[];
+/**
+ * The lightbox opt-in: an image directly after a text run that ends in a `!` at a boundary (start of the run or after whitespace), which is what `!![alt](src)` leaves behind.
+ */
+export declare const LIGHTBOX_MARKER: RegExp;
+/**
+ * A short, stable lightbox id from an image src (FNV-1a, base36): the same image always gets the same id, so repeated references share one dialog.
+ */
+export declare const lightboxId: (src: string) => string;
+/** The button that replaces an opted-in image and opens its dialog. */
+export declare const lightboxTrigger: <C>(id: string, image: C) => HastElementLike<C>;
+/** The modal dialog, appended at the document end, showing the image full size. */
+export declare const lightboxDialog: <C>(id: string, image: C) => HastElementLike<HastElementLike<C>>;
+/**
+ * The `[term, title]` pairs a paragraph's text defines, when every line of it is a `*[term]: title` definition; otherwise `undefined` (the paragraph is ordinary text).
+ */
+export declare const parseAbbreviations: (text: string) => Array<[string, string]> | undefined;
+/** A piece of text: plain, or a defined term with its title. */
+type AbbreviationPart = {
+  text: string;
+} | {
+  term: string;
+  title: string;
+};
+/**
+ * Build the scan for a document's abbreviations. Terms match on word boundaries, longest first; the scan returns the pieces of a text value, or `undefined` when it holds no term.
+ */
+export declare const createAbbreviationScan: (abbreviations: ReadonlyMap<string, string>) => ((value: string) => AbbreviationPart[] | undefined);
+/** A list of steps at one depth, rendered as an `<ol>`. */
+interface StepsListNode {
+  type: "stepsList";
+  depth: number;
+  containerClass?: string;
+  children: StepsItemNode[];
+  data?: {
+    attrsRole?: string;
+    hProperties?: Properties;
+  };
+}
+/** A step's title, rendered as its title `<p>` unless it is empty. */
+interface StepsTitleNode {
+  type: "stepsTitle";
+  children: PhrasingContent[];
+}
+/** One step: its title (always the first child, so transforms that walk children reach it), body and nested steps, rendered as an `<li>`. */
+interface StepsItemNode {
+  type: "stepsItem";
+  depth: number;
+  number: number;
+  children: Array<StepsTitleNode | BlockContent | DefinitionContent | StepsListNode>;
+  data?: {
+    attrsRole?: string;
+    attrsTitle?: PhrasingContent[];
+    hProperties?: Properties;
+  };
+}
+export declare const processStepsInChildren: (children: Array<BlockContent | DefinitionContent | Root["children"][number]>, containerClass: string, sourceLines?: readonly string[]) => void;
+/**
+ * Turn every step sequence in `root` into `stepsList` nodes, at the top level and inside any container (blockquotes, list items, tab panels…), walking into the lists it builds so nested sequences are found too. With the document's `source`, a step header that CommonMark lazily continued into a nested paragraph is recognized too, as markdown-it reads it.
+ */
+export declare const processSteps: (root: Root, containerClass: string, source?: string) => void;
+/** A group of tabs at one depth, rendered as the tabs container. */
+interface TabsListNode {
+  type: "tabsList";
+  depth: number;
+  containerClass?: string;
+  groupId: string;
+  children: TabsItemNode[];
+  data?: {
+    attrsRole?: string;
+    hProperties?: Properties;
+  };
+}
+/** A tab's label, rendered as its `<label>`. */
+interface TabsLabelNode {
+  type: "tabsLabel";
+  children: PhrasingContent[];
+}
+/** One tab: its label (always the first child, so transforms that walk children reach it), panel body and nested tabs. */
+interface TabsItemNode {
+  type: "tabsItem";
+  depth: number;
+  labelText: string;
+  open: boolean;
+  children: Array<TabsLabelNode | BlockContent | DefinitionContent | TabsListNode>;
+  data?: {
+    attrsRole?: string;
+    attrsTitle?: PhrasingContent[];
+    attrsItemTitle?: boolean;
+    hProperties?: Properties;
+  };
+}
+/** Strip a trailing attrs block like `{.class #id}` from plain label text, so attrs-consumed markers don't leak into `aria-label`. */
+export declare const stripAttrs: (text: string) => string;
+/**
+ * A group's block id, unique on the page even when label sets match: its group id with the group's index among the document's tab groups, counted in the order they open (each nested group after the group around it), so every engine counts the same groups the same way.
+ */
+export declare const tabsBlockId: (index: number, groupId: string) => string;
+/** The plain text of a tab label (text and inline code; other markup contributes its text, images nothing), for its group id and `aria-label`. */
+export declare const tabLabelText: (nodes: PhrasingContent[]) => string;
+export declare const processTabsInChildren: (children: Array<BlockContent | DefinitionContent | RootContent>, containerClass: string, checkBlankLines?: boolean, sourceLines?: readonly string[]) => void;
+/**
+ * Recognize every tab group in the tree: at the root, then inside every container (step bodies, list items, other tabs' panels). Blank-line checks only apply at the root: blank lines inside a blockquote leave position gaps that would wrongly end a group once its content has been lifted out of the blockquote. With the document's `source`, a tab header that CommonMark lazily continued into a nested panel is placed by its `>` markers, as markdown-it reads it.
+ */
+export declare const processTabs: (root: Root, containerClass: string, source?: string) => void;
+/** The part of a node the copy reads: its children, if it has any. */
+interface TreeNode {
+  type: string;
+  children?: readonly TreeNode[];
+  data?: unknown;
+}
+/** A copy of a tree, and how to write the changes made to it back. */
+interface EditableTree<N extends TreeNode> {
+  /** A plain, mutable copy of the tree, for recognition to rewrite. */
+  tree: N;
+  /**
+   * Write a node of the (rewritten) copy back: a node recognition left alone becomes the engine's own node again, so it keeps what the engine tracks for it (such as its source position, which later plugins read), and `setChildren` is called only where a children list changed, `setData` only where its `data` was replaced. `build` converts a node recognition created, writing back any copied nodes inside it.
+   */
+  writeBack: (node: N) => N;
+}
+export declare const editableTree: <N extends TreeNode>(root: N, build: (node: N, writeBack: (node: N) => N) => N, setChildren: (node: N, children: N[]) => void, setData?: (node: N, data: unknown) => void) => EditableTree<N>;
+/** The properties an attribute block written after text gives the text's paragraph, as the parser reads them, or `undefined` if it isn't one. */
+type ReadAttributes = (block: string) => Properties | undefined;
+/**
+ * Places the attribute block now ending each paragraph recognition rebuilt (one a header was cut from), as the parser places one: a block on a line of its own goes on the block it's written after, at the level its `>` markers and indentation put it (the paragraph, its list item in a tight list, or the outermost blockquote or list item it's written outside of, a list item giving its list); a block after text goes on the paragraph, or its list item from the item's first paragraph.
+ */
+export declare const placeCutAttributes: (root: Root, sourceLines: readonly string[], read: ReadAttributes) => void;
+/** The limits and mode that decide how an SVG's occurrences are inlined. */
+interface InlineSvgLimits {
+  /** Skip inlining SVGs larger than this many characters. */
+  maxImageSize: number;
+  /** Skip inlining an SVG referenced more than this many times. */
+  maxOccurrences: number;
+  /** Skip inlining an SVG whose occurrences add up to more than this many characters. */
+  maxTotalSize: number;
+  /** Reuse a repeated SVG through a hidden `<symbol>` and `<use>`. */
+  deduplication: boolean;
+}
+/**
+ * The id of a deduplicated SVG's sprite: a hash of its path relative to the document, with `/` separators, so the same document renders the same ids on any machine or OS (an absolute path would leak the build machine into the HTML).
+ */
+export declare const svgSpriteId: (relativePath: string) => string;
+/**
+ * The markup for every occurrence of one SVG file, given each occurrence's alt text in document order: the SVG itself, or, with deduplication and more than one occurrence, a hidden sprite on the first and a `<use>` of it on each. `null` when the limits leave the images as they are. `relativePath` is the file's path relative to the document, with `/` separators, for the sprite id.
+ */
+export declare const inlineSvgMarkup: (content: string, alts: readonly string[], relativePath: string, limits: InlineSvgLimits) => string[] | null;
+export type { AbbreviationPart, AlertOptions, AlertParagraph, AlertResolver, AlertType, DelimiterMarker, EditableTree, HastElementLike, HastLike, InlineSvgLimits, PhrasingLike, Positioned, ReadAttributes, ScriptSyntax, SpanNodes, SpanTransform, StepsItemNode, StepsListNode, StepsTitleNode, TabsItemNode, TabsLabelNode, TabsListNode, TextLikeNode, TreeNode };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/escapes.ts","../src/github-alerts/types.ts","../src/github-alerts/icons.ts","../src/github-alerts/index.ts","../src/spans.ts","../src/delimited.ts","../src/kbd.ts","../src/scripts.ts","../src/hast.ts","../src/abbr.ts","../src/steps.ts","../src/tabs.ts","../src/editable.ts","../src/cut-attributes.ts","../src/inline-svg.ts"],"mappings":"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"}