@effected/markdown 0.6.3 → 0.8.0

package/README.md

@@ -174,6 +174,8 @@ The three codecs — `YamlFrontmatter` (`---`), `TomlFrontmatter` (`+++`) and `J
 
 Frontmatter blocks can also describe their own schema. `SchemaResolver.classify` sorts a `$schema` value into a tagged union — `ByUrl`, `ByPath`, `Inline` and `ByName` — and `SchemaResolver.fromRegistry` resolves `ByName` declarations like `skill@2.1.0` against schemas you register. URLs, paths and inline documents are carried as data and never fetched: this is a pure package and it performs no IO.
 
+When the body should not go through the CommonMark engine at all — an MDX page, a template, a snapshot-hash contract that needs byte-exact boundaries — `FrontmatterSource.split` runs the same closed fence grammar over the raw string and nothing else. It is total: it returns the block's format, the exact bytes between the fence lines and the body remainder (`body` is always exactly `source.slice(bodyOffset)`), with absence a representable result rather than an error. `FrontmatterSource.join` serializes the parts back, reproducing the original bytes for an unmodified round-trip. Two edges normalize instead of reproducing: a closing fence that ends the document without a line terminator gains one, and fence lines with mismatched terminators (say `---\r\n … ---\n`) re-emit both with the opening fence's. The value and body bytes survive verbatim in every case, and neither is ever parsed at this level — decoding stays the codec modules' business.
+
 ## Working with the tree
 
 `MarkdownDocument` derives its navigation accessors from the tree, so they can never disagree with it. `links` collects every URL-bearing node and passes `url` through exactly as written — bundle-relative hrefs are never normalized:
@@ -261,6 +263,37 @@ if (Result.isSuccess(parsed)) {
 
 `Mdast.fromMdast` goes the other way as a checked admission boundary: it validates a foreign tree and synthesizes zero-width sentinel positions where one is absent or incomplete. Trees admitted that way serve tree-level workflows and canonical `stringify`; offset-splice editing needs the real positions only a parse produces.
 
+## MDX trees
+
+The MDX node vocabulary — `MdxJsxFlowElement` and `MdxJsxTextElement` (with `MdxJsxAttribute`, `MdxJsxExpressionAttribute` and `MdxJsxAttributeValueExpression` as their attribute carriers), `MdxFlowExpression`, `MdxTextExpression` and `MdxjsEsm` — is shaped exactly to the `mdast-util-mdx` contracts and constructs like every other node class. The parser does not read MDX syntax; these nodes exist so a **synthesized** tree can carry JSX and serialize to valid MDX instead of joining strings:
+
+```ts
+import { Markdown, MdxJsxAttribute, MdxJsxAttributeValueExpression, MdxJsxFlowElement, Root } from "@effected/markdown";
+import { Result } from "effect";
+
+const page = Root.make({
+  children: [
+    MdxJsxFlowElement.make({
+      name: "ApiSignature",
+      attributes: [
+        MdxJsxAttribute.make({
+          name: "code",
+          value: MdxJsxAttributeValueExpression.make({ value: JSON.stringify({ lang: "ts" }) }),
+        }),
+      ],
+      children: [],
+    }),
+  ],
+});
+
+const mdx = Markdown.stringifyResult(page);
+if (Result.isSuccess(mdx)) {
+  console.log(mdx.success); // <ApiSignature code={{"lang":"ts"}} />
+}
+```
+
+Serialization matches `mdxJsxToMarkdown`'s defaults — `"` quotes, spaced self-closing `<a />`, `<></>` fragments, flow children indented two spaces per JSX ancestor, `{expr}` expressions, ESM values verbatim — and a tree containing any MDX node escapes `{` in text the way MDX requires, while a tree with none serializes byte-identically to the table below. The shapes that have no MDX spelling are unconstructible rather than serialization errors: a fragment cannot carry attributes and an attribute requires a non-empty name, refused at `make` and at decode.
+
 ## The canonical form is stable
 
 `Markdown.stringify` takes no options. It emits one canonical form, that form is pinned by byte-level tests, the engine behind it is cross-checked against commonmark.js over the full CommonMark 0.31.2 corpus, and **changing any of it is a breaking change to this package rather than a patch**. So a test may assert on these bytes, and a pipeline that needs stable rendered markdown should serialize through here instead of a third-party stringifier whose defaults are free to move between releases.
@@ -278,6 +311,8 @@ For a node carrying no fidelity field:
 | Block separation | exactly one blank line |
 | Document | a single trailing newline |
 
+MDX nodes are part of the same commitment: the serialization choices listed under [MDX trees](#mdx-trees) are pinned the same way, and only trees that actually carry an MDX node pay the extra `{` escape.
+
 **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 to adopt if you build trees and assert on their bytes — is to set `fenceChar` on every `Code` node carrying 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.
@@ -291,8 +326,11 @@ To *normalize* an existing document to different choices, use `MarkdownFormat` w
 ## Features
 
 - `Markdown` — `parse`/`stringify` as `Effect`s with typed `MarkdownParseError`/`MarkdownStringifyError` channels, the pure `parseResult`/`stringifyResult` twins for synchronous callers, and the `MarkdownFromString` two-way codec.
+- `Markdown.parsePhrasing`/`parsePhrasingResult` — parse a prose fragment as a single paragraph's inline content, without a full document parse and a paragraph splice: blank lines stay inline, references never form (no reference context), and positions are correct relative to the input string.
 - `MarkdownDocument` — source, tree, diagnostics and the link-definition index, plus the derived `headings`, `sections` and `links` accessors, the `firstSection`/`sectionByHeading` finders over a `DocumentSection` (heading, depth, range, body), the `find`/`findAll` tree queries over type-narrowed selectors, and the `frontmatter` capture with `hasFrontmatterBlock` to tell an absent block from an uncaptured one.
 - The mdast-shaped node classes — the CommonMark types plus GFM's `delete`, `table`, `tableRow`, `tableCell`, `footnoteDefinition`, `footnoteReference` and task-list `checked`, each carrying unist positions with byte offsets and this package's fidelity fields. `position` defaults to the zero-width synthetic sentinel, so a replacement fragment constructs in one line — `Text.make({ value: "shipped" })`.
+- The MDX node vocabulary — `MdxJsxFlowElement`/`MdxJsxTextElement` with their attribute carriers, `MdxFlowExpression`/`MdxTextExpression` and `MdxjsEsm`, shaped to the `mdast-util-mdx` contracts for construction and serialization (the parser reads no MDX syntax).
+- `FrontmatterSource` — string-level frontmatter `split`/`join` over the same closed fence grammar, byte-exact boundaries, no parsing of value or body; for bodies the CommonMark engine should not touch.
 - `MarkdownEdit` / `MarkdownRange` (with `applyAll`) — the non-mutating text-edit vocabulary, field-identical to `@effected/jsonc`'s, `@effected/yaml`'s and `@effected/toml`'s.
 - `MarkdownFormat` — `format`/`formatToString` compute conservative marker-normalization edits; `modify`/`modifyToString` replace a node by identity through the canonical stringifier.
 - `MarkdownVisitor` — walk a parsed tree as a lazy `Stream` of `Enter`/`Exit` events with child-index paths and depth.

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
@@ -989,6 +1206,18 @@ declare class Markdown {
    * 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
@@ -1963,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`.
@@ -2480,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 };