@effected/markdown 0.6.2 → 0.7.0

package/index.d.ts

@@ -353,11 +353,14 @@ declare class FootnoteReference extends FootnoteReference_base {}
  */
 declare const PhrasingContent: Schema.Codec<PhrasingContent>;
 /**
- * The union of all phrasing-content node types.
+ * The union of all phrasing-content node types. Widened for MDX with
+ * {@link MdxJsxTextElement} and {@link MdxTextExpression}, per
+ * mdast-util-mdx's `PhrasingContentMap` registrations — the parser never
+ * produces either; they serve constructed trees.
  *
  * @public
  */
-type PhrasingContent = Break | Delete | Emphasis | FootnoteReference | Html | Image | ImageReference | InlineCode | Link | LinkReference | Strong | Text;
+type PhrasingContent = Break | Delete | Emphasis | FootnoteReference | Html | Image | ImageReference | InlineCode | Link | LinkReference | MdxJsxTextElement | MdxTextExpression | Strong | Text;
 declare const ThematicBreak_base: Schema.Class<ThematicBreak, Schema.Struct<{
   readonly type: Schema.tag<"thematicBreak">;
   readonly position: Schema.withConstructorDefault<typeof Position>;
@@ -618,11 +621,14 @@ declare const FlowContent: Schema.Codec<FlowContent>;
 /**
  * The union of all flow-content node types. Includes mdast's `Content`
  * category (`Definition | Paragraph`) inline, as the spec's `FlowContent`
- * definition does, and the GFM extras `FootnoteDefinition` and `Table`.
+ * definition does, the GFM extras `FootnoteDefinition` and `Table`, and the
+ * MDX extras {@link MdxJsxFlowElement} and {@link MdxFlowExpression} per
+ * mdast-util-mdx's `BlockContentMap` registrations — the parser never
+ * produces the MDX members; they serve constructed trees.
  *
  * @public
  */
-type FlowContent = Blockquote | Code | Definition | FootnoteDefinition | Heading | Html | List | Paragraph | Table | ThematicBreak;
+type FlowContent = Blockquote | Code | Definition | FootnoteDefinition | Heading | Html | List | MdxFlowExpression | MdxJsxFlowElement | Paragraph | Table | ThematicBreak;
 /**
  * The union of every node that may appear where mdast expects **list**
  * content. A one-member union, kept because mdast names the category and
@@ -638,6 +644,155 @@ declare const ListContent: Schema.Codec<ListContent>;
  * @public
  */
 type ListContent = ListItem;
+declare const MdxJsxAttributeValueExpression_base: Schema.Class<MdxJsxAttributeValueExpression, Schema.Struct<{
+  readonly type: Schema.tag<"mdxJsxAttributeValueExpression">;
+  readonly value: Schema.String;
+  readonly position: Schema.withConstructorDefault<typeof Position>;
+}>, {}>;
+/**
+ * MdxJsxAttributeValueExpression — a JSX attribute value written as an
+ * expression (`<a b={c} />`); `value` holds the expression source text
+ * between the braces, never evaluated or parsed.
+ *
+ * The primary construction path is a JSON-encoded prop:
+ * `MdxJsxAttributeValueExpression.make({ value: JSON.stringify(props) })`.
+ *
+ * @public
+ */
+declare class MdxJsxAttributeValueExpression extends MdxJsxAttributeValueExpression_base {}
+declare const MdxJsxAttribute_base: Schema.Class<MdxJsxAttribute, Schema.Struct<{
+  readonly type: Schema.tag<"mdxJsxAttribute">;
+  readonly name: Schema.String;
+  readonly value: Schema.optionalKey<Schema.NullOr<Schema.Union<readonly [typeof MdxJsxAttributeValueExpression, Schema.String]>>>;
+  readonly position: Schema.withConstructorDefault<typeof Position>;
+}>, {}>;
+/**
+ * MdxJsxAttribute — a named JSX attribute (`<a b="c" />`). `value` is a
+ * string literal, a {@link MdxJsxAttributeValueExpression}, or — for a
+ * boolean attribute (`<a b />`) — absent or `null`, both of which the
+ * mdast-util-mdx-jsx contract spells (its parser writes `null`; absence is
+ * the constructed-tree spelling). The serializer treats the two identically.
+ *
+ * `name` must be non-empty — an attribute without a name has no MDX spelling,
+ * so the schema refuses it at construction and decode (the oracle's
+ * serialize-time crash, moved to the admission boundary).
+ *
+ * @public
+ */
+declare class MdxJsxAttribute extends MdxJsxAttribute_base {}
+declare const MdxJsxExpressionAttribute_base: Schema.Class<MdxJsxExpressionAttribute, Schema.Struct<{
+  readonly type: Schema.tag<"mdxJsxExpressionAttribute">;
+  readonly value: Schema.String;
+  readonly position: Schema.withConstructorDefault<typeof Position>;
+}>, {}>;
+/**
+ * MdxJsxExpressionAttribute — a JSX attribute written whole as an expression
+ * (`<a {...b} />`); `value` holds the expression source text between the
+ * braces.
+ *
+ * @public
+ */
+declare class MdxJsxExpressionAttribute extends MdxJsxExpressionAttribute_base {}
+/**
+ * The union of every node that may appear in a JSX element's `attributes`
+ * array. A real `Schema.Union` for the construction pass-through documented
+ * on `RowContent`.
+ *
+ * Attribute carriers are node-shaped values — they carry `type` and
+ * `position` per the mdast-util-mdx-jsx contract — but they are **not tree
+ * content**: they never appear in a `children` array, so they are excluded
+ * from `MarkdownNode` and invisible to the visitor and to
+ * `MarkdownDocument.find`.
+ *
+ * @public
+ */
+declare const MdxJsxAttributeContent: Schema.Codec<MdxJsxAttributeContent>;
+/**
+ * The union of all JSX attribute node types.
+ *
+ * @public
+ */
+type MdxJsxAttributeContent = MdxJsxAttribute | MdxJsxExpressionAttribute;
+declare const MdxJsxFlowElement_base: Schema.Class<MdxJsxFlowElement, Schema.Struct<{
+  readonly type: Schema.tag<"mdxJsxFlowElement">;
+  readonly name: Schema.NullOr<Schema.String>;
+  readonly attributes: Schema.$Array<Schema.Codec<MdxJsxAttributeContent, MdxJsxAttributeContent, never, never>>;
+  readonly children: Schema.$Array<Schema.suspend<Schema.Codec<FlowContent, FlowContent, never, never>>>;
+  readonly position: Schema.withConstructorDefault<typeof Position>;
+}>, {}>;
+/**
+ * MdxJsxFlowElement — a JSX element in flow (block) position (`<Component />`
+ * on its own lines). `name` is `null` for a fragment (`<></>`); children are
+ * flow content, per the oracle's `BlockContent | DefinitionContent` model.
+ *
+ * A fragment cannot carry attributes — that shape has no MDX spelling — so
+ * the schema refuses it at construction and decode. A **named** element's
+ * name must be non-empty on the same terms: `""` has no MDX spelling either
+ * (the oracle's parser only ever produces a real name or `null`, and its
+ * serializer treats a falsy name as the fragment), so `null` is the one
+ * fragment spelling and the empty string fails typed.
+ *
+ * @public
+ */
+declare class MdxJsxFlowElement extends MdxJsxFlowElement_base {}
+declare const MdxJsxTextElement_base: Schema.Class<MdxJsxTextElement, Schema.Struct<{
+  readonly type: Schema.tag<"mdxJsxTextElement">;
+  readonly name: Schema.NullOr<Schema.String>;
+  readonly attributes: Schema.$Array<Schema.Codec<MdxJsxAttributeContent, MdxJsxAttributeContent, never, never>>;
+  readonly children: Schema.$Array<Schema.suspend<Schema.Codec<PhrasingContent, PhrasingContent, never, never>>>;
+  readonly position: Schema.withConstructorDefault<typeof Position>;
+}>, {}>;
+/**
+ * MdxJsxTextElement — a JSX element in text (phrasing) position
+ * (`a <b>c</b> d`). `name` is `null` for a fragment; children are phrasing
+ * content. Refuses attributes on a fragment and an empty-string name, on the
+ * same terms as {@link MdxJsxFlowElement}.
+ *
+ * @public
+ */
+declare class MdxJsxTextElement extends MdxJsxTextElement_base {}
+declare const MdxFlowExpression_base: Schema.Class<MdxFlowExpression, Schema.Struct<{
+  readonly type: Schema.tag<"mdxFlowExpression">;
+  readonly value: Schema.String;
+  readonly position: Schema.withConstructorDefault<typeof Position>;
+}>, {}>;
+/**
+ * MdxFlowExpression — an expression in flow (block) position (`{a + b}` on
+ * its own lines); `value` holds the expression source text between the
+ * braces.
+ *
+ * @public
+ */
+declare class MdxFlowExpression extends MdxFlowExpression_base {}
+declare const MdxTextExpression_base: Schema.Class<MdxTextExpression, Schema.Struct<{
+  readonly type: Schema.tag<"mdxTextExpression">;
+  readonly value: Schema.String;
+  readonly position: Schema.withConstructorDefault<typeof Position>;
+}>, {}>;
+/**
+ * MdxTextExpression — an expression in text (phrasing) position
+ * (`a {b} c`); `value` holds the expression source text between the braces.
+ *
+ * @public
+ */
+declare class MdxTextExpression extends MdxTextExpression_base {}
+declare const MdxjsEsm_base: Schema.Class<MdxjsEsm, Schema.Struct<{
+  readonly type: Schema.tag<"mdxjsEsm">;
+  readonly value: Schema.String;
+  readonly position: Schema.withConstructorDefault<typeof Position>;
+}>, {}>;
+/**
+ * MdxjsEsm — an MDX ESM block (`import`/`export` statements); `value` holds
+ * the statement source verbatim.
+ *
+ * Only ever a child of {@link Root}, per the mdast-util-mdxjs-esm content
+ * registration — ESM cannot nest inside a JSX element or any other
+ * container. As with the frontmatter head node, the constraint is structural
+ * (the `Root` children union admits it, no other union does), not validated.
+ *
+ * @public
+ */
+declare class MdxjsEsm extends MdxjsEsm_base {}
 /**
  * The frontmatter formats the capture recognizes, keyed by their opening
  * fence: `---` is yaml, `+++` is toml and `---json` is json.
@@ -694,7 +849,7 @@ declare const FrontmatterContent: Schema.Codec<FrontmatterContent>;
 type FrontmatterContent = Frontmatter;
 declare const Root_base: Schema.Class<Root, Schema.Struct<{
   readonly type: Schema.tag<"root">;
-  readonly children: Schema.$Array<Schema.suspend<Schema.Codec<Frontmatter | FlowContent, Frontmatter | FlowContent, never, never>>>;
+  readonly children: Schema.$Array<Schema.suspend<Schema.Codec<Frontmatter | MdxjsEsm | FlowContent, Frontmatter | MdxjsEsm | FlowContent, never, never>>>;
   readonly position: Schema.withConstructorDefault<typeof Position>;
 }>, {}>;
 /**
@@ -703,7 +858,8 @@ declare const Root_base: Schema.Class<Root, Schema.Struct<{
  * mdast leaves a root's content model open; a parsed markdown document is
  * flow content, optionally headed by one {@link Frontmatter} node — mdast's
  * `FlowContentFrontmatter` merge, which admits frontmatter at the root and
- * nowhere else.
+ * nowhere else. {@link MdxjsEsm} is likewise admitted at the root and nowhere
+ * else, per mdast-util-mdxjs-esm's `RootContentMap` registration.
  *
  * @public
  */
@@ -714,7 +870,7 @@ declare class Root extends Root_base {}
  *
  * @public
  */
-type MarkdownNode = Root | FrontmatterContent | FlowContent | ListContent | PhrasingContent | RowContent | TableContent;
+type MarkdownNode = Root | FrontmatterContent | FlowContent | ListContent | MdxjsEsm | PhrasingContent | RowContent | TableContent;
 /**
  * A schema matching any node in the tree.
  *
@@ -929,6 +1085,67 @@ declare class Markdown {
    *   fails with {@link MarkdownParseError}.
    */
   static readonly parse: (text: string, options?: MarkdownParseOptions | undefined) => Effect.Effect<Root, MarkdownParseError, never>;
+  /**
+   * Parse a text fragment as a single paragraph's inline content,
+   * synchronously, as a `Result` — the phrasing-level twin of
+   * {@link Markdown.parseResult}, for callers holding already-markdown
+   * prose (a link-carrying sentence, a backtick span) who want its
+   * phrasing nodes without a full document parse and a paragraph splice.
+   *
+   * @remarks
+   * The whole input is prepared exactly the way the block pass prepares one
+   * paragraph's content — leading and trailing whitespace trimmed, line
+   * terminators normalized to `\n` — and handed to the inline pass, so the
+   * result matches the `children` of the paragraph a full parse of the same
+   * fragment would produce. Node positions are correct relative to the
+   * input string.
+   *
+   * Two consequences of the single-paragraph contract:
+   *
+   * - **Blank lines do not break blocks.** A `\n\n` in the input stays
+   *   inline content (literal newlines in a text node); nothing at this
+   *   level opens a heading, list or code block — `# foo` is the text
+   *   `# foo`.
+   * - **No reference context exists.** The fragment carries no definitions,
+   *   so `[foo]`, `![foo]` and `[^foo]` remain literal text — the same
+   *   result a full parse of the isolated fragment produces.
+   *
+   * `options.dialect` selects the inline dialect (default `"gfm"`);
+   * `options.frontmatter` has no effect at phrasing level. Failure is rare
+   * by design, on {@link Markdown.parseResult}'s terms: only a
+   * hardening-guard trip (delimiter or bracket nesting past the cap) fails.
+   *
+   * @example
+   * ```ts
+   * import { Markdown } from "@effected/markdown";
+   * import { Result } from "effect";
+   *
+   * const ok = Markdown.parsePhrasingResult("see [the docs](./docs.md)");
+   * if (Result.isSuccess(ok)) {
+   *   console.log(ok.success.map((node) => node.type)); // => ["text", "link"]
+   * }
+   * ```
+   *
+   * @param text - The prose fragment to parse.
+   * @param options - Optional {@link MarkdownParseOptions}; the dialect
+   *   defaults to `"gfm"`.
+   * @returns A `Result` succeeding with the fragment's phrasing content, or
+   *   failing with {@link MarkdownParseError}.
+   */
+  static parsePhrasingResult(text: string, options?: MarkdownParseOptions): Result.Result<ReadonlyArray<PhrasingContent>, MarkdownParseError>;
+  /**
+   * Parse a text fragment as a single paragraph's inline content. Defined
+   * in terms of {@link Markdown.parsePhrasingResult} — synchronous callers
+   * can use that variant directly; the single-paragraph contract (blank
+   * lines stay inline, references never form) is documented there.
+   *
+   * @param text - The prose fragment to parse.
+   * @param options - Optional {@link MarkdownParseOptions}; the dialect
+   *   defaults to `"gfm"`.
+   * @returns An `Effect` that succeeds with the fragment's phrasing
+   *   content, or fails with {@link MarkdownParseError}.
+   */
+  static readonly parsePhrasing: (text: string, options?: MarkdownParseOptions | undefined) => Effect.Effect<readonly PhrasingContent[], MarkdownParseError, never>;
   /**
    * Serialize a {@link Root} tree to canonical markdown, synchronously, as a
    * `Result`. The pure primitive twin of {@link Markdown.stringify}, on the
@@ -946,6 +1163,66 @@ declare class Markdown {
    * contract — but is not a byte-level round-trip of any original source;
    * surgical editing goes through the offset-splice edit layer instead.
    *
+   * **The canonical form is a stability commitment, so a test may assert
+   * against these bytes.** There are no options to configure and therefore
+   * nothing to drift, the choices below are pinned by byte-level tests, and
+   * the engine is cross-checked against commonmark.js over the full
+   * CommonMark 0.31.2 corpus. Changing any of them is a **breaking** change
+   * to this package, never a patch. A consumer asserting on rendered
+   * markdown should serialize through here rather than through a third-party
+   * stringifier whose defaults are free to move.
+   *
+   * The canonical choices a byte-level assertion depends on, for a node
+   * carrying no fidelity field:
+   *
+   * | Construct | Canonical form |
+   * | --- | --- |
+   * | Heading | ATX (`## x`), at every depth |
+   * | Thematic break | `***` |
+   * | Bullet list marker | `-` |
+   * | Ordered list delimiter | `.`, flipping to `)` to separate an immediately adjacent sibling list |
+   * | Emphasis / strong | `*` / `**` |
+   * | Code block | fenced when the node carries a `lang` or a `fenceChar`, with the fence grown past any interior backtick run; otherwise indented — **except where indenting would not re-parse as a code block**, which forces a fence (see below) |
+   * | Block separation | exactly one blank line |
+   * | Document | a single trailing newline |
+   *
+   * A node carrying a fidelity field overrides the corresponding row —
+   * `headingStyle: "setext"`, `markerChar`, `fenceChar`, `delimiter` — which
+   * is how a parsed document re-serializes in its author's spelling. The
+   * rows describe a synthesized node, which is the case a test asserting on
+   * generated markdown actually has.
+   *
+   * **Representability wins over the table.** The canonical form never emits
+   * text that would re-parse as something else, so a row yields where the two
+   * conflict. The case that reaches a consumer is the indented code block: an
+   * indented block directly after a list is absorbed as list content, so a
+   * `Code` node with neither `lang` nor `fenceChar` emits **fenced** in that
+   * position and indented everywhere else. A byte-level assertion over
+   * synthesized code blocks therefore depends on the preceding sibling.
+   *
+   * **The posture that makes this a non-issue**, and the one a consumer
+   * building trees for byte-level assertion should adopt: set `fenceChar` on
+   * every `Code` node that carries neither a `lang` nor one already, in a
+   * post-decode walk that reaches nested nodes. The choice then leaves the
+   * emitter entirely and no output depends on a node's neighbours.
+   *
+   * **MDX nodes (constructed trees only — the parser reads no MDX syntax)**
+   * serialize to valid MDX with the mdast-util-mdx defaults, and these
+   * choices are part of the same stability commitment: attribute values
+   * quote with `"` (the quote escaped as `&#x22;`), an empty element
+   * self-closes spaced (`<a />`), a fragment is `<></>`, flow children take
+   * block layout indented two spaces per JSX ancestor, attributes move onto
+   * their own lines only when one carries a line ending, expressions emit
+   * `{expr}` with two-space continuation indent, and ESM values emit
+   * verbatim. A tree containing any MDX node additionally escapes `{` in
+   * text — MDX makes it significant — while a tree with none serializes
+   * byte-identically to the table above.
+   *
+   * To *normalize* a document to different choices — a `-` list rewritten to
+   * `*`, setext headings rewritten to ATX — use `MarkdownFormat` with
+   * `MarkdownFormattingOptions`. That is the configurable surface; this one
+   * deliberately is not.
+   *
    * Failure is rare by design, symmetric with parse: only a hardening-guard
    * trip on a tree nesting past the depth cap fails, and only synthesized
    * or decoded trees can nest that far.
@@ -960,6 +1237,18 @@ declare class Markdown {
    * {@link Markdown.stringifyResult} — synchronous callers can use that
    * variant directly.
    *
+   * @remarks
+   * The canonical form is a **stability commitment** and safe to assert
+   * against byte-for-byte; the choices it makes, and the reason changing one
+   * is a breaking change, are documented on
+   * {@link Markdown.stringifyResult}.
+   *
+   * **Fidelity fields must be set on the DECODED tree.** `Mdast.fromMdast`
+   * admits spec mdast and strips everything outside it, so a `fenceChar`,
+   * `headingStyle`, `markerChar` or `delimiter` placed on a plain mdast tree
+   * before admission is silently dropped and the canonical default applies.
+   * Set them on the nodes that come back.
+   *
    * @param root - The document tree to serialize.
    * @returns An `Effect` that succeeds with markdown source, or fails with
    *   {@link MarkdownStringifyError}.
@@ -1903,6 +2192,144 @@ declare class SchemaResolver {
   static fromRegistry(registrations: Readonly<Record<string, Schema.Top>>): FrontmatterSchemaResolver;
 }
 //#endregion
+//#region src/FrontmatterSource.d.ts
+/**
+ * The three line-terminator spellings a fence line may end with. Recorded by
+ * {@link FrontmatterSource.split} as fidelity — what the source's fence
+ * lines actually used — and consumed by {@link FrontmatterSource.join}.
+ *
+ * @public
+ */
+declare const FrontmatterNewline: Schema.Literals<readonly ["\n", "\r\n", "\r"]>;
+/**
+ * The union of all fence line-terminator literals.
+ *
+ * @public
+ */
+type FrontmatterNewline = typeof FrontmatterNewline.Type;
+declare const FrontmatterSourceBlock_base: Schema.Class<FrontmatterSourceBlock, Schema.Struct<{
+  readonly format: Schema.Literals<readonly ["yaml", "toml", "json"]>;
+  readonly value: Schema.String;
+  readonly newline: Schema.optionalKey<Schema.Literals<readonly ["\n", "\r\n", "\r"]>>;
+}>, {}>;
+/**
+ * A frontmatter block at string level: the format its fence declared, the
+ * exact bytes between the fence lines, and the fence lines' terminator.
+ *
+ * @remarks
+ * `value` is the exact source slice strictly between the opening fence line
+ * (its terminator included) and the closing fence line: every value line
+ * WITH its own terminator, verbatim — so a block whose value is one blank
+ * line (`"\n"`) stays distinct from a block with no value lines (`""`), and
+ * interior CRLF terminators survive untouched. This deliberately differs
+ * from the parsed `Frontmatter` NODE's `value`, which drops the final
+ * terminator; the node feeds codecs, this feeds byte-exact reconstruction.
+ * {@link FrontmatterSource.join} accepts a value without a trailing
+ * terminator too, appending `newline` so a hand-built block cannot fuse its
+ * last line into the closing fence.
+ *
+ * `newline` is a fidelity field: `split` always records the terminator
+ * following the opening fence; when absent (a hand-built block), `join`
+ * uses `"\n"`.
+ *
+ * @public
+ */
+declare class FrontmatterSourceBlock extends FrontmatterSourceBlock_base {}
+declare const FrontmatterSourceSplit_base: Schema.Class<FrontmatterSourceSplit, Schema.Struct<{
+  readonly frontmatter: Schema.optionalKey<typeof FrontmatterSourceBlock>;
+  readonly body: Schema.String;
+  readonly bodyOffset: Schema.withConstructorDefault<Schema.Number>;
+}>, {}>;
+/**
+ * The result of {@link FrontmatterSource.split}: the frontmatter block when
+ * one exists, the exact body remainder, and the body's byte offset.
+ *
+ * @remarks
+ * `body` is exactly `source.slice(bodyOffset)` — the string and the offset
+ * can never disagree. With no block, `body` is the whole source and
+ * `bodyOffset` is `0`. With a block, `bodyOffset` sits immediately after
+ * the closing fence line and its line terminator (the terminator belongs to
+ * the fence line, as every line's terminator belongs to its line), which is
+ * gray-matter's body boundary; when the closing fence ends the document
+ * there is no terminator and the body is empty.
+ *
+ * `bodyOffset` is informational output of `split`; `join` never reads it,
+ * and it constructor-defaults to `0` so a hand-built value for `join` can
+ * omit it.
+ *
+ * @public
+ */
+declare class FrontmatterSourceSplit extends FrontmatterSourceSplit_base {}
+/**
+ * The string-level frontmatter facade: split raw source at the fence
+ * boundaries and join it back, without parsing anything.
+ *
+ * @public
+ */
+declare class FrontmatterSource {
+  private constructor();
+  /**
+   * Split raw source into its frontmatter block and body, at string level.
+   * Total: never fails, never parses — absence of a block (including an
+   * opening fence with no closing fence, which per the grammar is not
+   * frontmatter) is a representable result, not an error.
+   *
+   * @remarks
+   * The grammar is the parser's own offset-0 pre-scan, over raw bytes:
+   * the fence set is closed (`---` yaml, `+++` toml, `---json` json), a
+   * fence line is exactly the fence with no surrounding whitespace, and a
+   * leading BOM means offset 0 is not a fence — strip one before calling
+   * if the source may carry it. Unlike the parse path there is no capture
+   * toggle here, so absence is one fact: the source has no closed block.
+   * (`MarkdownDocument`'s two-reason absence exists because parsing can be
+   * asked not to look; this surface always looks.)
+   *
+   * Byte exactness: `source.slice(0, result.bodyOffset) + result.body`
+   * reassembles `source` exactly, and {@link FrontmatterSource.join}
+   * reproduces the original bytes for an unmodified round-trip — see
+   * `join` for the two normalizations at the contract's edge.
+   *
+   * @example
+   * ```ts
+   * import { FrontmatterSource } from "@effected/markdown";
+   *
+   * const split = FrontmatterSource.split("---\ntitle: hi\n---\n\n# Body\n");
+   * console.log(split.frontmatter?.format); // => "yaml"
+   * console.log(split.frontmatter?.value); // => "title: hi\n"
+   * console.log(split.body); // => "\n# Body\n"
+   * ```
+   *
+   * @param source - The raw document source, body format irrelevant.
+   * @returns A {@link FrontmatterSourceSplit}; `frontmatter` is absent when
+   *   the source opens with no closed fence block.
+   */
+  static split(source: string): FrontmatterSourceSplit;
+  /**
+   * Serialize a split back to one source string. Total and pure.
+   *
+   * @remarks
+   * With no block the body is returned verbatim. With a block the output
+   * is the opening fence, `newline` (default `"\n"`), the value — a
+   * non-empty value missing a final line terminator gets `newline`
+   * appended, so the closing fence always starts its own line — the
+   * closing fence, `newline`, then the body verbatim.
+   *
+   * **Round-trip contract:** `join(split(source)) === source`, byte for
+   * byte, for every source whose closing fence line ends with a line
+   * terminator matching the opening fence's. The two edges where join
+   * normalizes instead: a closing fence at end-of-document gains a final
+   * `newline` (the block's one unterminated spelling), and fence lines
+   * with MISMATCHED terminators (say `---\r\n … ---\n`) re-emit both with
+   * the opening one. Value and body bytes survive verbatim in every case.
+   *
+   * @param split - The parts to serialize, typically from
+   *   {@link FrontmatterSource.split} or built with
+   *   `FrontmatterSourceSplit.make`.
+   * @returns The combined source string.
+   */
+  static join(split: FrontmatterSourceSplit): string;
+}
+//#endregion
 //#region src/JsonFrontmatter.d.ts
 /**
  * The json frontmatter codec, over `@effected/jsonc`.
@@ -2344,6 +2771,14 @@ declare class Mdast {
    * decode into the {@link Frontmatter} capture. Unknown node types fail
    * typed.
    *
+   * **This package's fidelity fields are among the fields dropped**, because
+   * they are not spec mdast. A `fenceChar`, `headingStyle`, `markerChar` or
+   * `delimiter` set on the tree BEFORE admission is silently discarded, and
+   * the node then serializes with the canonical default — set them on the
+   * decoded nodes this returns instead. The drop is correct (the boundary
+   * admits spec mdast and nothing else) but it is silent, which is why it is
+   * called out here.
+   *
    * @param input - A plain mdast tree, typically a `root`.
    * @returns A `Result` succeeding with the decoded {@link Root}, or
    *   failing with {@link MdastDecodeError} carrying the structured issue.
@@ -2412,5 +2847,5 @@ declare const TomlFrontmatter: FrontmatterCodec;
  */
 declare const YamlFrontmatter: FrontmatterCodec;
 //#endregion
-export { Blockquote, Break, BreakStyle, BulletChar, Code, CodeBlockStyle, Definition, Delete, type DocumentHeading, type DocumentLink, DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, type FrontmatterCodec, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, type FrontmatterResolveError, type FrontmatterSchemaError, type FrontmatterSchemaResolver, FrontmatterValidationError, type FrontmatterWriteError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, type LinkBearingNode, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, type MarkdownNodeOfType, type MarkdownNodeType, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, type MarkdownPath, MarkdownRange, type MarkdownRangeLike, type MarkdownSegment, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, type MdastNode, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, type SectionHeadingMatch, type SectionQueryOptions, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };
+export { Blockquote, Break, BreakStyle, BulletChar, Code, CodeBlockStyle, Definition, Delete, type DocumentHeading, type DocumentLink, DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, type FrontmatterCodec, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, FrontmatterNewline, type FrontmatterResolveError, type FrontmatterSchemaError, type FrontmatterSchemaResolver, FrontmatterSource, FrontmatterSourceBlock, FrontmatterSourceSplit, FrontmatterValidationError, type FrontmatterWriteError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, type LinkBearingNode, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, type MarkdownNodeOfType, type MarkdownNodeType, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, type MarkdownPath, MarkdownRange, type MarkdownRangeLike, type MarkdownSegment, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, type MdastNode, MdxFlowExpression, MdxJsxAttribute, MdxJsxAttributeContent, MdxJsxAttributeValueExpression, MdxJsxExpressionAttribute, MdxJsxFlowElement, MdxJsxTextElement, MdxTextExpression, MdxjsEsm, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, type SectionHeadingMatch, type SectionQueryOptions, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,7 +1,8 @@
 import { MarkdownEdit, MarkdownRange } from "./MarkdownEdit.js";
-import { Blockquote, Break, BreakStyle, BulletChar, Code, Definition, Delete, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterFormat, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, MarkdownNode, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar } from "./MarkdownNode.js";
+import { Blockquote, Break, BreakStyle, BulletChar, Code, Definition, Delete, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterFormat, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, MarkdownNode, MdxFlowExpression, MdxJsxAttribute, MdxJsxAttributeContent, MdxJsxAttributeValueExpression, MdxJsxExpressionAttribute, MdxJsxFlowElement, MdxJsxTextElement, MdxTextExpression, MdxjsEsm, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar } from "./MarkdownNode.js";
 import { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, FrontmatterValidationError, MarkdownFrontmatter } from "./Frontmatter.js";
 import { SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError } from "./FrontmatterResolver.js";
+import { FrontmatterNewline, FrontmatterSource, FrontmatterSourceBlock, FrontmatterSourceSplit } from "./FrontmatterSource.js";
 import { JsonFrontmatter } from "./JsonFrontmatter.js";
 import { MarkdownDiagnostic, MarkdownParseErrorCode } from "./MarkdownDiagnostic.js";
 import { Markdown, MarkdownDialect, MarkdownParseError, MarkdownParseOptions, MarkdownStringifyError } from "./Markdown.js";
@@ -12,4 +13,4 @@ import { Mdast, MdastDecodeError } from "./Mdast.js";
 import { TomlFrontmatter } from "./TomlFrontmatter.js";
 import { YamlFrontmatter } from "./YamlFrontmatter.js";
 
-export { Blockquote, Break, BreakStyle, BulletChar, Code, CodeBlockStyle, Definition, Delete, DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, FrontmatterValidationError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, MarkdownRange, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };
+export { Blockquote, Break, BreakStyle, BulletChar, Code, CodeBlockStyle, Definition, Delete, DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, FrontmatterNewline, FrontmatterSource, FrontmatterSourceBlock, FrontmatterSourceSplit, FrontmatterValidationError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, MarkdownRange, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, MdxFlowExpression, MdxJsxAttribute, MdxJsxAttributeContent, MdxJsxAttributeValueExpression, MdxJsxExpressionAttribute, MdxJsxFlowElement, MdxJsxTextElement, MdxTextExpression, MdxjsEsm, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };

package/internal/blockParser.js

@@ -1,9 +1,9 @@
 import { Frontmatter, Point, Position, Root } from "../MarkdownNode.js";
+import { scanFrontmatter } from "./blocks/frontmatter.js";
 import { makeBlockNode } from "./blockTypes.js";
 import { columnsToNextTabStop, preprocessLines } from "./preprocess.js";
 import { isHtmlBlockEnd } from "./blocks/htmlBlock.js";
 import { blockDialect } from "./blockRegistry.js";
-import { scanFrontmatter } from "./blocks/frontmatter.js";
 import { GuardExceeded } from "./carriers.js";
 import { LineIndex } from "./lineIndex.js";
 import { prepareInline } from "./rawInline.js";

package/internal/blocks/frontmatter.js

@@ -51,6 +51,52 @@ const scanFrontmatter = (lines, text) => {
 	}
 	return null;
 };
+/** The terminator starting at `offset`, or null when none does. */
+const terminatorAt = (source, offset) => {
+	const code = source.charCodeAt(offset);
+	if (code === 10) return "\n";
+	if (code === 13) return source.charCodeAt(offset + 1) === 10 ? "\r\n" : "\r";
+	return null;
+};
+/**
+* Scan raw source for a frontmatter block — the same closed fence grammar as
+* {@link scanFrontmatter}, over unpreprocessed bytes, returning exact
+* offsets. The two scans agree on every input about WHETHER a block exists
+* (the preprocessor's substitutions are length-preserving and can only break
+* a fence match both scans require); this one exists for the string-level
+* split/join surface, whose contract is byte exactness.
+*
+* Returns `null` when the document has no frontmatter — no fence at offset
+* 0, or an opening fence with no closing fence, which per the grammar is not
+* frontmatter at all.
+*/
+const scanRawFrontmatter = (source) => {
+	let index = 0;
+	while (index < source.length && terminatorAt(source, index) === null) index += 1;
+	const openNewline = index < source.length ? terminatorAt(source, index) : null;
+	const rule = FENCES.get(source.slice(0, index));
+	if (rule === void 0 || openNewline === null) return null;
+	const valueStart = index + openNewline.length;
+	let lineStart = valueStart;
+	index = valueStart;
+	while (index <= source.length) {
+		const terminator = index === source.length ? null : terminatorAt(source, index);
+		if (terminator === null && index < source.length) {
+			index += 1;
+			continue;
+		}
+		if (source.slice(lineStart, index) === rule.close) return {
+			format: rule.format,
+			value: source.slice(valueStart, lineStart),
+			newline: openNewline,
+			bodyOffset: terminator === null ? index : index + terminator.length
+		};
+		if (terminator === null) break;
+		index += terminator.length;
+		lineStart = index;
+	}
+	return null;
+};
 
 //#endregion
-export { scanFrontmatter };
+export { scanFrontmatter, scanRawFrontmatter };