@effected/markdown 0.13.0 → 0.15.0

package/Frontmatter.js

@@ -115,9 +115,8 @@ reason: FrontmatterMissingReason }) {
 * @remarks
 * `issue` carries the **structured** schema failure — at runtime a
 * `SchemaIssue.Issue` tree, reachable through `_tag` and nested `issues` —
-* never a stringified rendering (the `ConfigValidationError` precedent from
-* `@effected/config-file`). It is typed `unknown` because v4 exposes no
-* `Schema` for `Issue`; narrow it with the `SchemaIssue` module.
+* never a stringified rendering. It is typed `unknown` because core exposes
+* no `Schema` for `Issue`; narrow it with the `SchemaIssue` module.
 *
 * @public
 */
@@ -159,13 +158,27 @@ const renderBlock = (format, body) => {
 	return `${open}\n${body === "" || body.endsWith("\n") ? body : `${body}\n`}${close}`;
 };
 /**
-* The frontmatter schema composition facade — typed gray-matter parity.
+* The frontmatter schema composition facade: decodes a parsed document's frontmatter into typed data, and writes typed data back as a frontmatter block.
 *
 * @remarks
-* The design doc's indicative spelling was `Frontmatter.schema`, but
-* `Frontmatter` names the capture node class (the node classes co-locate in
-* `MarkdownNode.ts` and are named after their mdast types), so the facade
-* follows the package's Markdown-prefix convention instead.
+* Named `MarkdownFrontmatter` rather than `Frontmatter` because `Frontmatter`
+* names the capture node class (the node classes are named after their mdast
+* types).
+*
+* @example
+* ```ts
+* import { MarkdownDocument, MarkdownFrontmatter, MarkdownParseOptions, YamlFrontmatter } from "@effected/markdown";
+* import { Effect, Schema } from "effect";
+*
+* const Meta = Schema.Struct({ title: Schema.String });
+*
+* const program = Effect.gen(function* () {
+*   // Frontmatter capture is opt-in at parse time.
+*   const source = "---\ntitle: Hello\n---\n\n# Body\n";
+*   const doc = yield* MarkdownDocument.parse(source, MarkdownParseOptions.make({ frontmatter: true }));
+*   return yield* MarkdownFrontmatter.schema(Meta, YamlFrontmatter)(doc); // { title: "Hello" }
+* });
+* ```
 *
 * @public
 */
@@ -233,7 +246,7 @@ var MarkdownFrontmatter = class MarkdownFrontmatter {
 	* parity, not surgical editing — so anything the format's data model does
 	* not carry is not preserved: comments inside a yaml frontmatter block do
 	* **not** survive `set`. A per-key surgical mode over the format packages'
-	* edit layers is a documented future refinement, not current scope.
+	* edit layers is not offered.
 	*
 	* Schema-producing in spirit: bind the returned writer to a `const` when
 	* writing many documents.

package/FrontmatterResolver.js

@@ -197,9 +197,7 @@ var SchemaResolver = class SchemaResolver {
 	* @remarks
 	* Non-mapping data and a mapping without a `$schema` key both carry no
 	* declaration: the result succeeds with `undefined` by default, or fails
-	* with {@link SchemaDeclarationMissingError} under `requireDeclaration` —
-	* the design's strictness knob, applied at extraction where the
-	* present-or-absent branch actually lives.
+	* with {@link SchemaDeclarationMissingError} under `requireDeclaration`.
 	*
 	* @param data - The decoded frontmatter data.
 	* @param options - `requireDeclaration` makes a missing `$schema` a typed
@@ -212,7 +210,7 @@ var SchemaResolver = class SchemaResolver {
 		return SchemaResolver.classify(data.$schema);
 	}
 	/**
-	* The package's one built-in resolver: a name-keyed registry with day-one
+	* The package's one built-in resolver: a name-keyed registry with
 	* exact version-segment resolution.
 	*
 	* @remarks

package/FrontmatterSource.js

@@ -4,21 +4,6 @@ import { Effect, Schema } from "effect";
 
 //#region src/FrontmatterSource.ts
 /**
-* String-level frontmatter split and join — the raw-source surface, usable
-* without parsing the body at all.
-*
-* @remarks
-* The `MarkdownFrontmatter` seam requires a parsed `MarkdownDocument`; this
-* module serves the consumer whose body the CommonMark engine cannot or
-* should not parse (an MDX page, a template) and whose contract is
-* byte-exact boundaries (a snapshot hash over the body). It runs the SAME
-* closed fence grammar as the parser's offset-0 pre-scan — `---` yaml,
-* `+++` toml, `---json` json, fence lines exactly the fence, an unclosed
-* fence is not frontmatter — over raw bytes, and never parses the
-* frontmatter value or the body: string level only, decoding is the codec
-* modules' business.
-*/
-/**
 * 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}.

package/Markdown.js

@@ -45,7 +45,7 @@ var MarkdownParseOptions = class extends Schema.Class("MarkdownParseOptions")({
 *
 * @remarks
 * CommonMark has no syntax errors — every string is a valid document — so
-* this error carries only hardening-guard trips (P1: `NestingDepthExceeded`).
+* this error carries only hardening-guard trips (`NestingDepthExceeded`).
 * Recoverable oddities are diagnostics on {@link MarkdownDocument}, not
 * failures. A malformed-looking document parses; a nesting bomb fails here
 * rather than crashing with a `RangeError`.
@@ -89,7 +89,7 @@ var MarkdownStringifyError = class extends Schema.TaggedError()("MarkdownStringi
 const dialectOf = (options) => options?.dialect ?? "gfm";
 /**
 * Whether an options object opts into frontmatter capture. The default —
-* `false`, a P3 ruling — is spelled exactly once, here: capture changes how
+* `false` — is spelled exactly once, here: capture changes how
 * a `---` at offset 0 parses, so the spec-conformant reading is the default
 * and frontmatter is the consumer's explicit choice.
 */

package/MarkdownDiagnostic.js

@@ -3,9 +3,9 @@ import { Schema } from "effect";
 
 //#region src/MarkdownDiagnostic.ts
 /**
-* Error codes `Markdown.parse`/`MarkdownDocument.parse` can fail with. P1
-* registers exactly the hardening-guard trip; later phases widen the union
-* as new fatal (as opposed to diagnostic-only) conditions are identified.
+* Error codes `Markdown.parse`/`MarkdownDocument.parse` can fail with.
+* Currently exactly one, `"NestingDepthExceeded"`, the hardening-guard trip;
+* the union may widen as new fatal conditions are identified.
 *
 * @public
 */
@@ -22,9 +22,8 @@ const MarkdownParseErrorCode = Schema.Literals(MARKDOWN_PARSE_ERROR_CODES);
 * shape and `@effected/yaml`'s `YamlDiagnostic`); `message` is this
 * package's additive extra. `line`/`character` here are zero-based to match
 * that contract — a different numbering from the one-based `line`/`column`
-* unist `Point`s carried on `MarkdownNode` positions (`internal/lineIndex.ts`),
-* which is a deliberate, unrelated convention for the AST rather than a
-* mismatch to reconcile.
+* unist `Point`s carried on `MarkdownNode` positions, which is a deliberate,
+* unrelated convention for the AST rather than a mismatch to reconcile.
 *
 * @public
 */
@@ -38,8 +37,12 @@ var MarkdownDiagnostic = class MarkdownDiagnostic extends Schema.Class("Markdown
 }) {
 	/**
 	* Materialize an engine record, deriving zero-based `line`/`character`
-	* from `offset` against the source `text`. Advanced — the parse entry
+	* from `offset` against the source text. Advanced — the parse entry
 	* points call this for you.
+	*
+	* @param source - The source text the record's `offset` indexes into.
+	* @param raw - The engine record: `code`, `message`, `offset` and `length`.
+	* @returns The diagnostic with `line` and `character` filled in.
 	*/
 	static fromRaw(source, raw) {
 		const { line, character } = lineChar(source, raw.offset);

package/MarkdownDocument.js

@@ -127,27 +127,36 @@ const phrasingText = (nodes) => {
 *
 * @remarks
 * The document is the lossless unit — `source` is retained so offsets on the
-* tree stay meaningful and so P4's edit/format layer can splice against the
-* exact bytes that were parsed.
+* tree stay meaningful and so the edit and format layer can splice against
+* the exact bytes that were parsed.
 *
 * `definitions` is an index over the {@link Definition} nodes that remain in
 * the tree, keyed by case-folded label with the first definition winning; it
 * is not a place they were moved to. References are emitted unresolved, so
 * resolution happens against this map.
 *
-* `diagnostics` is empty for every input the P1 parser accepts, and that is
-* the current state of the world rather than a missing feature: the plumbing
-* from the engine through to this field is real and exercised, but no P1
-* construct emits a non-fatal diagnostic yet. The producers arrive with the
-* conditions that warrant them — unresolved link references, and
-* present-but-unparseable frontmatter in P3. Read an empty array as "nothing
-* to report", not as "not implemented", and do not code against it staying
-* empty.
+* `diagnostics` is empty for every input the parser currently accepts: the
+* plumbing from the engine through to this field exists, but no construct
+* emits a non-fatal diagnostic yet. Read an empty array as "nothing to
+* report", and do not code against it staying empty — fatal conditions fail
+* through `MarkdownParseError` instead.
 *
 * The navigation accessors (`headings`, `sections`, `links`) are derived
 * getters over the tree — no stored state, no parse-time cost, and they can
 * never disagree with the tree they read.
 *
+* @example
+* ```ts
+* import { MarkdownDocument } from "@effected/markdown";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const doc = yield* MarkdownDocument.parse("# Title\n\nSee [docs](./docs.md).\n\n## Usage\n");
+*   doc.headings.map((heading) => heading.text); // ["Title", "Usage"]
+*   doc.links.map((link) => link.url); // ["./docs.md"]
+* });
+* ```
+*
 * @public
 */
 var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocument")({

package/MarkdownEdit.js

@@ -34,6 +34,10 @@ var MarkdownEdit = class extends Schema.Class("MarkdownEdit")({
 	* reverse-offset order so earlier offsets stay valid; the input `edits`
 	* array is not mutated. Overlapping edits are a programmer error and throw
 	* as a defect — `MarkdownFormat` never produces them.
+	*
+	* @param text - The source text to edit.
+	* @param edits - The edits to apply, in any order.
+	* @returns The edited text.
 	*/
 	static applyAll(text, edits) {
 		const sorted = [...edits].sort((a, b) => b.offset - a.offset);

package/MarkdownFormat.js

@@ -23,7 +23,7 @@ const CodeBlockStyle = Schema.Literals(["fenced", "indented"]);
 * source with (same defaults as `Markdown.parse`). Every marker option is
 * optional and independent; an absent option normalizes nothing.
 *
-* Day-one scope is marker normalization only — heading style, bullet
+* Scope is marker normalization only — heading style, bullet
 * character, emphasis/strong marker, fence character, thematic-break
 * character, code-block style. Content is never rewritten, rewrapped or
 * reflowed.
@@ -71,7 +71,7 @@ const MarkdownModificationErrorCode = Schema.Literals([
 /**
 * Raised when `MarkdownFormat.modify` cannot perform the requested
 * replacement: the target node is not in the document (`NodeNotInDocument`),
-* the target kind or splice context is outside the day-one scope
+* the target kind or splice context is outside the supported scope
 * (`UnsupportedTarget`), the fragment's content category does not fit the
 * target's slot (`FragmentCategoryMismatch`), or the fragment trips the
 * stringifier's hardening guard (`FragmentUnrenderable`). Carries the typed
@@ -337,7 +337,26 @@ const findAncestry = (root, target) => {
 	return search(root, []);
 };
 /**
-* Formatting and modification statics. Not instantiable.
+* Normalizes markdown markers and replaces a single node, as byte-minimal
+* edits that leave the rest of the source untouched. Not instantiable.
+*
+* @example
+* ```ts
+* import { MarkdownDocument, MarkdownFormat, MarkdownFormattingOptions } from "@effected/markdown";
+* import { Effect } from "effect";
+*
+* const options = MarkdownFormattingOptions.make({ bulletChar: "-", headingStyle: "atx" });
+* const normalized = MarkdownFormat.formatToString("* a\n* b\n\nSetext\n======\n", undefined, options);
+* // => "- a\n- b\n\n# Setext\n"
+*
+* const program = Effect.gen(function* () {
+*   const doc = yield* MarkdownDocument.parse("# Title\n\nHello world\n");
+*   const paragraph = doc.root.children[1];
+*   if (paragraph === undefined) return doc.source;
+*   return yield* MarkdownFormat.modifyToString(doc, paragraph, "Goodbye");
+*   // => "# Title\n\nGoodbye\n"
+* });
+* ```
 *
 * @remarks
 * `format`/`formatToString` are pure and total: input that trips a parse
@@ -368,6 +387,15 @@ var MarkdownFormat = class MarkdownFormat {
 	* code block keeps whichever spelling it has — `fenceChar` alone
 	* normalizes existing fences and deliberately leaves indented blocks
 	* indented.
+	*
+	* @param text - The markdown source to format.
+	* @param range - Optional sub-range; only edits whose node intersects it are
+	*   returned.
+	* @param options - Optional {@link MarkdownFormattingOptions}; an absent
+	*   marker option normalizes nothing.
+	* @returns The edits that normalize the requested markers; apply them with
+	*   `MarkdownEdit.applyAll`. Empty when the input trips a parse hardening
+	*   guard.
 	*/
 	static format(text, range, options) {
 		const parsed = Markdown.parseResult(text, MarkdownParseOptions.make({
@@ -394,6 +422,12 @@ var MarkdownFormat = class MarkdownFormat {
 	/**
 	* Format `text` and apply the resulting edits in one step
 	* (`MarkdownEdit.applyAll ∘ format`). Pure and total.
+	*
+	* @param text - The markdown source to format.
+	* @param range - Optional sub-range; only edits whose node intersects it are
+	*   applied.
+	* @param options - Optional {@link MarkdownFormattingOptions}.
+	* @returns The formatted text.
 	*/
 	static formatToString(text, range, options) {
 		return MarkdownEdit.applyAll(text, MarkdownFormat.format(text, range, options));
@@ -405,11 +439,19 @@ var MarkdownFormat = class MarkdownFormat {
 	* node) or a node fragment whose content category must fit the target's
 	* slot (flow for flow targets, phrasing for phrasing targets and table
 	* cells). Every replacement renders through the canonical stringifier, so
-	* the modified document re-parses cleanly by construction. Day-one scope:
-	* list items, table rows, frontmatter and the root refuse with
+	* the modified document re-parses cleanly by construction. List
+	* items, table rows, frontmatter and the root refuse with
 	* `UnsupportedTarget`, as does a multi-line replacement whose target sits
 	* inside a container (a blockquote, list, table or heading) whose
 	* continuation lines the splice cannot prefix.
+	*
+	* @param document - The parsed {@link MarkdownDocument} the target belongs to.
+	* @param target - The node to replace; it must be a node of
+	*   `document.root`, matched by identity.
+	* @param replacement - A plain string (literal text) or a node fragment of
+	*   the target's content category.
+	* @returns An `Effect` that succeeds with the edit to apply (via
+	*   `MarkdownEdit.applyAll`), or fails with {@link MarkdownModificationError}.
 	*/
 	static modify = Effect.fn("MarkdownFormat.modify")(function* (document, target, replacement) {
 		const { start, end } = spanOf(target);
@@ -454,6 +496,14 @@ var MarkdownFormat = class MarkdownFormat {
 	/**
 	* Modify `document` and apply the resulting edit in one step
 	* (`MarkdownEdit.applyAll ∘ modify`).
+	*
+	* @param document - The parsed {@link MarkdownDocument} the target belongs to.
+	* @param target - The node to replace; it must be a node of
+	*   `document.root`, matched by identity.
+	* @param replacement - A plain string (literal text) or a node fragment of
+	*   the target's content category.
+	* @returns An `Effect` that succeeds with the modified source, or fails with
+	*   {@link MarkdownModificationError}.
 	*/
 	static modifyToString = Effect.fn("MarkdownFormat.modifyToString")(function* (document, target, replacement) {
 		const edits = yield* MarkdownFormat.modify(document, target, replacement);

package/MarkdownNode.js

@@ -792,11 +792,11 @@ const FrontmatterFormat = Schema.Literals([
 *
 * mdast has no single frontmatter node: it names `yaml` in the readme and
 * `toml` through the frontmatter extension, and json has no mdast name at
-* all. This package captures all three through ONE node — the design doc's
-* "text plus a format marker" — and the `Mdast` projection (P5) maps
-* `format` onto the mdast type names where they exist. Decoding the value is
-* the codec modules' job (`YamlFrontmatter`/`TomlFrontmatter`/
-* `JsonFrontmatter`, P3 Task 2); the engine never looks inside it.
+* all. This package captures all three through ONE node — text plus a format
+* marker — and the `Mdast` projection maps `format` onto the mdast type
+* names where they exist. Decoding the value is the codec modules' job
+* (`YamlFrontmatter`/`TomlFrontmatter`/`JsonFrontmatter`); the engine never
+* looks inside it.
 *
 * Only ever the first child of {@link Root}, and only when parsing opted in
 * via `MarkdownParseOptions.frontmatter` — mdast's "limited to one node, only

package/MarkdownVisitor.js

@@ -11,7 +11,24 @@ import { Data, Stream } from "effect";
 */
 const MarkdownVisitorEvent = Data.taggedEnum();
 /**
-* SAX-style markdown tree visitor statics. Not instantiable.
+* Walks a parsed markdown tree as a lazy `Stream` of `Enter`/`Exit` events in
+* document pre-order. Not instantiable.
+*
+* @example
+* ```ts
+* import { Markdown, MarkdownVisitor, MarkdownVisitorEvent } from "@effected/markdown";
+* import { Effect, Stream } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const root = yield* Markdown.parse("# Hi\n\ntext\n");
+*   return yield* MarkdownVisitor.visit(root).pipe(
+*     Stream.filter(MarkdownVisitorEvent.$is("Enter")),
+*     Stream.map((event) => event.node.type),
+*     Stream.runCollect,
+*   );
+*   // => ["root", "heading", "text", "paragraph", "text"]
+* });
+* ```
 *
 * @public
 */
@@ -31,6 +48,10 @@ var MarkdownVisitor = class {
 	* as a terminal `MarkdownVisitorEvent` `Error` event carrying a
 	* `NestingDepthExceeded` {@link MarkdownDiagnostic}, mirroring the typed
 	* failure `Markdown.stringify` produces for the same tree.
+	*
+	* @param root - The tree to walk.
+	* @returns A lazy `Stream` of `MarkdownVisitorEvent`, infallible at the type
+	*   level.
 	*/
 	static visit(root) {
 		return Stream.fromIterable(walkIterable(root));

package/Mdast.js

@@ -4,41 +4,14 @@ import { Effect, Result, Schema } from "effect";
 
 //#region src/Mdast.ts
 /**
-* The remark-ecosystem interop boundary: projection between this package's
-* node classes and plain mdast JSON.
-*
-* @remarks
-* `Mdast.toMdast` projects a parsed {@link Root} to plain spec-valid mdast
-* objects — fidelity extras stripped, optional fields spelled the way
-* `mdast-util-from-markdown` spells them (explicit `null`/`false` where the
-* reference utility emits them), so the output deep-equals what the remark
-* ecosystem produces and consumes. `Mdast.fromMdast` admits foreign plain
-* mdast back into the package's Schema node classes, synthesizing zero-width
-* sentinel positions where unist leaves them optional.
-*
-* The emission target is `mdast-util-from-markdown@2.0.3` (the vendored
-* interop corpus pin): `list.ordered`/`start`/`spread` and
-* `listItem.spread`/`checked` always explicit (`null` for unknown `start`/
-* `checked`), `code.lang`/`meta` and every `title` explicit `null` when
-* absent, `image.alt`/`imageReference.alt` always a string. Under unist's
-* null-equals-absent convention for optional fields this stays spec-valid
-* mdast; it is also byte-identical to the reference utility's output, which
-* is what interop means operationally. GFM shapes follow the same convention
-* from `mdast-util-gfm`; the frontmatter capture projects to mdast's
-* `yaml`/`toml` literal nodes, and a `json` capture projects to a
-* `json`-typed literal node per the `mdast-util-frontmatter` custom-preset
-* convention (presets name the node type after the language).
-*/
-/**
 * Indicates that foreign mdast input failed to decode into the package's
 * node classes.
 *
 * @remarks
 * `issue` carries the **structured** schema failure — at runtime a
 * `SchemaIssue.Issue` tree, reachable through `_tag` and nested `issues` —
-* never a stringified rendering (the `FrontmatterValidationError`
-* precedent). It is typed `unknown` because v4 exposes no `Schema` for
-* `Issue`; narrow it with the `SchemaIssue` module.
+* never a stringified rendering. It is typed `unknown` because core exposes
+* no `Schema` for `Issue`; narrow it with the `SchemaIssue` module.
 *
 * @public
 */
@@ -391,7 +364,41 @@ const normalizeMdxAttribute = (value) => {
 };
 const decodeRoot = Schema.decodeUnknownResult(Root);
 /**
-* The mdast projection facade — the remark-ecosystem interop boundary.
+* Projects parsed markdown trees to plain mdast JSON and admits foreign mdast
+* back into this package's node classes, for interop with the remark
+* ecosystem.
+*
+* @remarks
+* `Mdast.toMdast` projects a parsed {@link Root} to plain spec-valid mdast
+* objects — fidelity extras stripped, optional fields spelled the way
+* `mdast-util-from-markdown@2.0.3` spells them (explicit `null`/`false` where
+* the reference utility emits them), so the output deep-equals what the
+* remark ecosystem produces and consumes: `list.ordered`/`start`/`spread` and
+* `listItem.spread`/`checked` are always explicit (`null` for unknown
+* `start`/`checked`), `code.lang`/`meta` and every `title` are explicit
+* `null` when absent, and `image.alt`/`imageReference.alt` are always
+* strings. Under unist's null-equals-absent convention for optional fields
+* this stays spec-valid mdast. GFM shapes follow the same convention from
+* `mdast-util-gfm`; the frontmatter capture projects to mdast's `yaml`/`toml`
+* literal nodes, and a `json` capture projects to a `json`-typed literal node
+* per the `mdast-util-frontmatter` custom-preset convention (presets name the
+* node type after the language).
+*
+* `Mdast.fromMdast` admits foreign plain mdast back into the package's Schema
+* node classes, synthesizing zero-width sentinel positions where unist leaves
+* them optional.
+*
+* @example
+* ```ts
+* import { Markdown, Mdast } from "@effected/markdown";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const root = yield* Markdown.parse("# Hello\n");
+*   const plain = Mdast.toMdast(root); // plain mdast JSON
+*   return yield* Mdast.fromMdast(plain); // back to node classes
+* });
+* ```
 *
 * @public
 */

package/README.md

@@ -7,10 +7,10 @@
 
 Zero-dependency CommonMark 0.31.2 and GFM parsing, editing and transformation expressed as Effect schemas and pure functions. Parse markdown into mdast-shaped nodes carrying byte offsets, navigate headings, sections and links, compute surgical offset-splice edits, normalize markers, decode frontmatter into a validated domain schema, project to and from plain mdast for the remark ecosystem, and walk a document as a `Stream`.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered

package/TomlFrontmatter.js

@@ -15,8 +15,8 @@ import { Toml } from "@effected/toml";
 *
 * Encodes with `Toml.stringify`; a value toml cannot represent fails as a
 * {@link FrontmatterEncodeError} carrying the `TomlStringifyError`
-* structurally. An empty object encodes to the **empty body** — the exact
-* mirror of the decode ruling above, rendering as adjacent `+++` fences —
+* structurally. An empty object encodes to the **empty body** — the mirror
+* of an empty capture decoding to `{}` — rendering as adjacent `+++` fences,
 * so `set`-then-decode recovers `{}` exactly.
 *
 * `@effected/toml` is an optional peer — importing this module is what

package/index.d.ts

@@ -868,11 +868,11 @@ declare const Frontmatter_base: Schema.Class<Frontmatter, Schema.Struct<{
  *
  * mdast has no single frontmatter node: it names `yaml` in the readme and
  * `toml` through the frontmatter extension, and json has no mdast name at
- * all. This package captures all three through ONE node — the design doc's
- * "text plus a format marker" — and the `Mdast` projection (P5) maps
- * `format` onto the mdast type names where they exist. Decoding the value is
- * the codec modules' job (`YamlFrontmatter`/`TomlFrontmatter`/
- * `JsonFrontmatter`, P3 Task 2); the engine never looks inside it.
+ * all. This package captures all three through ONE node — text plus a format
+ * marker — and the `Mdast` projection maps `format` onto the mdast type
+ * names where they exist. Decoding the value is the codec modules' job
+ * (`YamlFrontmatter`/`TomlFrontmatter`/`JsonFrontmatter`); the engine never
+ * looks inside it.
  *
  * Only ever the first child of {@link Root}, and only when parsing opted in
  * via `MarkdownParseOptions.frontmatter` — mdast's "limited to one node, only
@@ -944,9 +944,9 @@ type MarkdownNodeOfType<T extends MarkdownNodeType> = Extract<MarkdownNode, {
 //#endregion
 //#region src/MarkdownDiagnostic.d.ts
 /**
- * Error codes `Markdown.parse`/`MarkdownDocument.parse` can fail with. P1
- * registers exactly the hardening-guard trip; later phases widen the union
- * as new fatal (as opposed to diagnostic-only) conditions are identified.
+ * Error codes `Markdown.parse`/`MarkdownDocument.parse` can fail with.
+ * Currently exactly one, `"NestingDepthExceeded"`, the hardening-guard trip;
+ * the union may widen as new fatal conditions are identified.
  *
  * @public
  */
@@ -977,17 +977,20 @@ declare const MarkdownDiagnostic_base: Schema.Class<MarkdownDiagnostic, Schema.S
  * shape and `@effected/yaml`'s `YamlDiagnostic`); `message` is this
  * package's additive extra. `line`/`character` here are zero-based to match
  * that contract — a different numbering from the one-based `line`/`column`
- * unist `Point`s carried on `MarkdownNode` positions (`internal/lineIndex.ts`),
- * which is a deliberate, unrelated convention for the AST rather than a
- * mismatch to reconcile.
+ * unist `Point`s carried on `MarkdownNode` positions, which is a deliberate,
+ * unrelated convention for the AST rather than a mismatch to reconcile.
  *
  * @public
  */
 export declare class MarkdownDiagnostic extends MarkdownDiagnostic_base {
   /**
    * Materialize an engine record, deriving zero-based `line`/`character`
-   * from `offset` against the source `text`. Advanced — the parse entry
+   * from `offset` against the source text. Advanced — the parse entry
    * points call this for you.
+   *
+   * @param source - The source text the record's `offset` indexes into.
+   * @param raw - The engine record: `code`, `message`, `offset` and `length`.
+   * @returns The diagnostic with `line` and `character` filled in.
    */
   static fromRaw(source: string, raw: {
     readonly code: MarkdownParseErrorCode;
@@ -1046,7 +1049,7 @@ declare const MarkdownParseError_base: Schema.Class<MarkdownParseError, Schema.T
  *
  * @remarks
  * CommonMark has no syntax errors — every string is a valid document — so
- * this error carries only hardening-guard trips (P1: `NestingDepthExceeded`).
+ * this error carries only hardening-guard trips (`NestingDepthExceeded`).
  * Recoverable oddities are diagnostics on {@link MarkdownDocument}, not
  * failures. A malformed-looking document parses; a nesting bomb fails here
  * rather than crashing with a `RangeError`.
@@ -1337,8 +1340,7 @@ export declare class Markdown {
 //#region src/MarkdownEdit.d.ts
 /**
  * A single path segment: a `number` for child indices in the node tree, or a
- * `string` for named addressing (reserved for the navigation surface — e.g.
- * definition identifiers — which arrives with the visitor phase).
+ * `string` for named addressing (reserved, e.g. for definition identifiers).
  *
  * @public
  */
@@ -1385,6 +1387,10 @@ export declare class MarkdownEdit extends MarkdownEdit_base {
    * reverse-offset order so earlier offsets stay valid; the input `edits`
    * array is not mutated. Overlapping edits are a programmer error and throw
    * as a defect — `MarkdownFormat` never produces them.
+   *
+   * @param text - The source text to edit.
+   * @param edits - The edits to apply, in any order.
+   * @returns The edited text.
    */
   static applyAll(text: string, edits: ReadonlyArray<MarkdownEdit>): string;
 }
@@ -1540,27 +1546,36 @@ declare const MarkdownDocument_base: Schema.Class<MarkdownDocument, Schema.Struc
  *
  * @remarks
  * The document is the lossless unit — `source` is retained so offsets on the
- * tree stay meaningful and so P4's edit/format layer can splice against the
- * exact bytes that were parsed.
+ * tree stay meaningful and so the edit and format layer can splice against
+ * the exact bytes that were parsed.
  *
  * `definitions` is an index over the {@link Definition} nodes that remain in
  * the tree, keyed by case-folded label with the first definition winning; it
  * is not a place they were moved to. References are emitted unresolved, so
  * resolution happens against this map.
  *
- * `diagnostics` is empty for every input the P1 parser accepts, and that is
- * the current state of the world rather than a missing feature: the plumbing
- * from the engine through to this field is real and exercised, but no P1
- * construct emits a non-fatal diagnostic yet. The producers arrive with the
- * conditions that warrant them — unresolved link references, and
- * present-but-unparseable frontmatter in P3. Read an empty array as "nothing
- * to report", not as "not implemented", and do not code against it staying
- * empty.
+ * `diagnostics` is empty for every input the parser currently accepts: the
+ * plumbing from the engine through to this field exists, but no construct
+ * emits a non-fatal diagnostic yet. Read an empty array as "nothing to
+ * report", and do not code against it staying empty — fatal conditions fail
+ * through `MarkdownParseError` instead.
  *
  * The navigation accessors (`headings`, `sections`, `links`) are derived
  * getters over the tree — no stored state, no parse-time cost, and they can
  * never disagree with the tree they read.
  *
+ * @example
+ * ```ts
+ * import { MarkdownDocument } from "@effected/markdown";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const doc = yield* MarkdownDocument.parse("# Title\n\nSee [docs](./docs.md).\n\n## Usage\n");
+ *   doc.headings.map((heading) => heading.text); // ["Title", "Usage"]
+ *   doc.links.map((link) => link.url); // ["./docs.md"]
+ * });
+ * ```
+ *
  * @public
  */
 export declare class MarkdownDocument extends MarkdownDocument_base {
@@ -1891,9 +1906,8 @@ declare const FrontmatterValidationError_base: Schema.Class<FrontmatterValidatio
  * @remarks
  * `issue` carries the **structured** schema failure — at runtime a
  * `SchemaIssue.Issue` tree, reachable through `_tag` and nested `issues` —
- * never a stringified rendering (the `ConfigValidationError` precedent from
- * `@effected/config-file`). It is typed `unknown` because v4 exposes no
- * `Schema` for `Issue`; narrow it with the `SchemaIssue` module.
+ * never a stringified rendering. It is typed `unknown` because core exposes
+ * no `Schema` for `Issue`; narrow it with the `SchemaIssue` module.
  *
  * @public
  */
@@ -1918,13 +1932,27 @@ type FrontmatterSchemaError = FrontmatterMissingError | FrontmatterFormatMismatc
  */
 type FrontmatterWriteError = FrontmatterFormatMismatchError | FrontmatterEncodeError | FrontmatterValidationError;
 /**
- * The frontmatter schema composition facade — typed gray-matter parity.
+ * The frontmatter schema composition facade: decodes a parsed document's frontmatter into typed data, and writes typed data back as a frontmatter block.
  *
  * @remarks
- * The design doc's indicative spelling was `Frontmatter.schema`, but
- * `Frontmatter` names the capture node class (the node classes co-locate in
- * `MarkdownNode.ts` and are named after their mdast types), so the facade
- * follows the package's Markdown-prefix convention instead.
+ * Named `MarkdownFrontmatter` rather than `Frontmatter` because `Frontmatter`
+ * names the capture node class (the node classes are named after their mdast
+ * types).
+ *
+ * @example
+ * ```ts
+ * import { MarkdownDocument, MarkdownFrontmatter, MarkdownParseOptions, YamlFrontmatter } from "@effected/markdown";
+ * import { Effect, Schema } from "effect";
+ *
+ * const Meta = Schema.Struct({ title: Schema.String });
+ *
+ * const program = Effect.gen(function* () {
+ *   // Frontmatter capture is opt-in at parse time.
+ *   const source = "---\ntitle: Hello\n---\n\n# Body\n";
+ *   const doc = yield* MarkdownDocument.parse(source, MarkdownParseOptions.make({ frontmatter: true }));
+ *   return yield* MarkdownFrontmatter.schema(Meta, YamlFrontmatter)(doc); // { title: "Hello" }
+ * });
+ * ```
  *
  * @public
  */
@@ -1987,7 +2015,7 @@ export declare class MarkdownFrontmatter {
    * parity, not surgical editing — so anything the format's data model does
    * not carry is not preserved: comments inside a yaml frontmatter block do
    * **not** survive `set`. A per-key surgical mode over the format packages'
-   * edit layers is a documented future refinement, not current scope.
+   * edit layers is not offered.
    *
    * Schema-producing in spirit: bind the returned writer to a `const` when
    * writing many documents.
@@ -2210,9 +2238,7 @@ export declare class SchemaResolver {
    * @remarks
    * Non-mapping data and a mapping without a `$schema` key both carry no
    * declaration: the result succeeds with `undefined` by default, or fails
-   * with {@link SchemaDeclarationMissingError} under `requireDeclaration` —
-   * the design's strictness knob, applied at extraction where the
-   * present-or-absent branch actually lives.
+   * with {@link SchemaDeclarationMissingError} under `requireDeclaration`.
    *
    * @param data - The decoded frontmatter data.
    * @param options - `requireDeclaration` makes a missing `$schema` a typed
@@ -2224,7 +2250,7 @@ export declare class SchemaResolver {
     readonly requireDeclaration?: boolean;
   }): Result.Result<SchemaDeclaration | undefined, SchemaDeclarationInvalidError | SchemaDeclarationMissingError>;
   /**
-   * The package's one built-in resolver: a name-keyed registry with day-one
+   * The package's one built-in resolver: a name-keyed registry with
    * exact version-segment resolution.
    *
    * @remarks
@@ -2461,7 +2487,7 @@ declare const MarkdownFormattingOptions_base: Schema.Class<MarkdownFormattingOpt
  * source with (same defaults as `Markdown.parse`). Every marker option is
  * optional and independent; an absent option normalizes nothing.
  *
- * Day-one scope is marker normalization only — heading style, bullet
+ * Scope is marker normalization only — heading style, bullet
  * character, emphasis/strong marker, fence character, thematic-break
  * character, code-block style. Content is never rewritten, rewrapped or
  * reflowed.
@@ -2507,7 +2533,7 @@ declare const MarkdownModificationError_base: Schema.Class<MarkdownModificationE
 /**
  * Raised when `MarkdownFormat.modify` cannot perform the requested
  * replacement: the target node is not in the document (`NodeNotInDocument`),
- * the target kind or splice context is outside the day-one scope
+ * the target kind or splice context is outside the supported scope
  * (`UnsupportedTarget`), the fragment's content category does not fit the
  * target's slot (`FragmentCategoryMismatch`), or the fragment trips the
  * stringifier's hardening guard (`FragmentUnrenderable`). Carries the typed
@@ -2520,7 +2546,26 @@ export declare class MarkdownModificationError extends MarkdownModificationError
   get message(): string;
 }
 /**
- * Formatting and modification statics. Not instantiable.
+ * Normalizes markdown markers and replaces a single node, as byte-minimal
+ * edits that leave the rest of the source untouched. Not instantiable.
+ *
+ * @example
+ * ```ts
+ * import { MarkdownDocument, MarkdownFormat, MarkdownFormattingOptions } from "@effected/markdown";
+ * import { Effect } from "effect";
+ *
+ * const options = MarkdownFormattingOptions.make({ bulletChar: "-", headingStyle: "atx" });
+ * const normalized = MarkdownFormat.formatToString("* a\n* b\n\nSetext\n======\n", undefined, options);
+ * // => "- a\n- b\n\n# Setext\n"
+ *
+ * const program = Effect.gen(function* () {
+ *   const doc = yield* MarkdownDocument.parse("# Title\n\nHello world\n");
+ *   const paragraph = doc.root.children[1];
+ *   if (paragraph === undefined) return doc.source;
+ *   return yield* MarkdownFormat.modifyToString(doc, paragraph, "Goodbye");
+ *   // => "# Title\n\nGoodbye\n"
+ * });
+ * ```
  *
  * @remarks
  * `format`/`formatToString` are pure and total: input that trips a parse
@@ -2551,11 +2596,26 @@ export declare class MarkdownFormat {
    * code block keeps whichever spelling it has — `fenceChar` alone
    * normalizes existing fences and deliberately leaves indented blocks
    * indented.
+   *
+   * @param text - The markdown source to format.
+   * @param range - Optional sub-range; only edits whose node intersects it are
+   *   returned.
+   * @param options - Optional {@link MarkdownFormattingOptions}; an absent
+   *   marker option normalizes nothing.
+   * @returns The edits that normalize the requested markers; apply them with
+   *   `MarkdownEdit.applyAll`. Empty when the input trips a parse hardening
+   *   guard.
    */
   static format(text: string, range?: MarkdownRangeLike, options?: MarkdownFormattingOptions): ReadonlyArray<MarkdownEdit>;
   /**
    * Format `text` and apply the resulting edits in one step
    * (`MarkdownEdit.applyAll ∘ format`). Pure and total.
+   *
+   * @param text - The markdown source to format.
+   * @param range - Optional sub-range; only edits whose node intersects it are
+   *   applied.
+   * @param options - Optional {@link MarkdownFormattingOptions}.
+   * @returns The formatted text.
    */
   static formatToString(text: string, range?: MarkdownRangeLike, options?: MarkdownFormattingOptions): string;
   /**
@@ -2565,16 +2625,32 @@ export declare class MarkdownFormat {
    * node) or a node fragment whose content category must fit the target's
    * slot (flow for flow targets, phrasing for phrasing targets and table
    * cells). Every replacement renders through the canonical stringifier, so
-   * the modified document re-parses cleanly by construction. Day-one scope:
-   * list items, table rows, frontmatter and the root refuse with
+   * the modified document re-parses cleanly by construction. List
+   * items, table rows, frontmatter and the root refuse with
    * `UnsupportedTarget`, as does a multi-line replacement whose target sits
    * inside a container (a blockquote, list, table or heading) whose
    * continuation lines the splice cannot prefix.
+   *
+   * @param document - The parsed {@link MarkdownDocument} the target belongs to.
+   * @param target - The node to replace; it must be a node of
+   *   `document.root`, matched by identity.
+   * @param replacement - A plain string (literal text) or a node fragment of
+   *   the target's content category.
+   * @returns An `Effect` that succeeds with the edit to apply (via
+   *   `MarkdownEdit.applyAll`), or fails with {@link MarkdownModificationError}.
    */
   static readonly modify: (document: MarkdownDocument, target: MarkdownNode, replacement: string | MarkdownNode) => Effect.Effect<readonly MarkdownEdit[], MarkdownModificationError, never>;
   /**
    * Modify `document` and apply the resulting edit in one step
    * (`MarkdownEdit.applyAll ∘ modify`).
+   *
+   * @param document - The parsed {@link MarkdownDocument} the target belongs to.
+   * @param target - The node to replace; it must be a node of
+   *   `document.root`, matched by identity.
+   * @param replacement - A plain string (literal text) or a node fragment of
+   *   the target's content category.
+   * @returns An `Effect` that succeeds with the modified source, or fails with
+   *   {@link MarkdownModificationError}.
    */
   static readonly modifyToString: (document: MarkdownDocument, target: MarkdownNode, replacement: string | MarkdownNode) => Effect.Effect<string, MarkdownModificationError, never>;
 }
@@ -2730,7 +2806,24 @@ export declare const MarkdownVisitorEvent: {
   }, "_tag">;
 };
 /**
- * SAX-style markdown tree visitor statics. Not instantiable.
+ * Walks a parsed markdown tree as a lazy `Stream` of `Enter`/`Exit` events in
+ * document pre-order. Not instantiable.
+ *
+ * @example
+ * ```ts
+ * import { Markdown, MarkdownVisitor, MarkdownVisitorEvent } from "@effected/markdown";
+ * import { Effect, Stream } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const root = yield* Markdown.parse("# Hi\n\ntext\n");
+ *   return yield* MarkdownVisitor.visit(root).pipe(
+ *     Stream.filter(MarkdownVisitorEvent.$is("Enter")),
+ *     Stream.map((event) => event.node.type),
+ *     Stream.runCollect,
+ *   );
+ *   // => ["root", "heading", "text", "paragraph", "text"]
+ * });
+ * ```
  *
  * @public
  */
@@ -2750,6 +2843,10 @@ export declare class MarkdownVisitor {
    * as a terminal `MarkdownVisitorEvent` `Error` event carrying a
    * `NestingDepthExceeded` {@link MarkdownDiagnostic}, mirroring the typed
    * failure `Markdown.stringify` produces for the same tree.
+   *
+   * @param root - The tree to walk.
+   * @returns A lazy `Stream` of `MarkdownVisitorEvent`, infallible at the type
+   *   level.
    */
   static visit(root: Root): Stream.Stream<MarkdownVisitorEvent>;
 }
@@ -2780,9 +2877,8 @@ declare const MdastDecodeError_base: Schema.Class<MdastDecodeError, Schema.Tagge
  * @remarks
  * `issue` carries the **structured** schema failure — at runtime a
  * `SchemaIssue.Issue` tree, reachable through `_tag` and nested `issues` —
- * never a stringified rendering (the `FrontmatterValidationError`
- * precedent). It is typed `unknown` because v4 exposes no `Schema` for
- * `Issue`; narrow it with the `SchemaIssue` module.
+ * never a stringified rendering. It is typed `unknown` because core exposes
+ * no `Schema` for `Issue`; narrow it with the `SchemaIssue` module.
  *
  * @public
  */
@@ -2790,7 +2886,41 @@ export declare class MdastDecodeError extends MdastDecodeError_base {
   get message(): string;
 }
 /**
- * The mdast projection facade — the remark-ecosystem interop boundary.
+ * Projects parsed markdown trees to plain mdast JSON and admits foreign mdast
+ * back into this package's node classes, for interop with the remark
+ * ecosystem.
+ *
+ * @remarks
+ * `Mdast.toMdast` projects a parsed {@link Root} to plain spec-valid mdast
+ * objects — fidelity extras stripped, optional fields spelled the way
+ * `mdast-util-from-markdown@2.0.3` spells them (explicit `null`/`false` where
+ * the reference utility emits them), so the output deep-equals what the
+ * remark ecosystem produces and consumes: `list.ordered`/`start`/`spread` and
+ * `listItem.spread`/`checked` are always explicit (`null` for unknown
+ * `start`/`checked`), `code.lang`/`meta` and every `title` are explicit
+ * `null` when absent, and `image.alt`/`imageReference.alt` are always
+ * strings. Under unist's null-equals-absent convention for optional fields
+ * this stays spec-valid mdast. GFM shapes follow the same convention from
+ * `mdast-util-gfm`; the frontmatter capture projects to mdast's `yaml`/`toml`
+ * literal nodes, and a `json` capture projects to a `json`-typed literal node
+ * per the `mdast-util-frontmatter` custom-preset convention (presets name the
+ * node type after the language).
+ *
+ * `Mdast.fromMdast` admits foreign plain mdast back into the package's Schema
+ * node classes, synthesizing zero-width sentinel positions where unist leaves
+ * them optional.
+ *
+ * @example
+ * ```ts
+ * import { Markdown, Mdast } from "@effected/markdown";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const root = yield* Markdown.parse("# Hello\n");
+ *   const plain = Mdast.toMdast(root); // plain mdast JSON
+ *   return yield* Mdast.fromMdast(plain); // back to node classes
+ * });
+ * ```
  *
  * @public
  */
@@ -2872,8 +3002,8 @@ export declare class Mdast {
  *
  * Encodes with `Toml.stringify`; a value toml cannot represent fails as a
  * {@link FrontmatterEncodeError} carrying the `TomlStringifyError`
- * structurally. An empty object encodes to the **empty body** — the exact
- * mirror of the decode ruling above, rendering as adjacent `+++` fences —
+ * structurally. An empty object encodes to the **empty body** — the mirror
+ * of an empty capture decoding to `{}` — rendering as adjacent `+++` fences,
  * so `set`-then-decode recovers `{}` exactly.
  *
  * `@effected/toml` is an optional peer — importing this module is what

package/internal/carriers.js

@@ -1,7 +1,7 @@
 //#region src/internal/carriers.ts
 /**
-* P1's error-code vocabulary. Widens as later phases add parse-error kinds;
-* P1 registers exactly one, the hardening-guard trip.
+* The engine's error-code vocabulary: currently exactly one, the
+* hardening-guard trip. Widens as new parse-error kinds are added.
 */
 const MARKDOWN_PARSE_ERROR_CODES = ["NestingDepthExceeded"];
 /** The engine's carrier for a recoverable-turned-fatal parse condition. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/markdown",
-	"version": "0.13.0",
+	"version": "0.15.0",
 	"private": false,
 	"description": "CommonMark and GFM markdown parse, edit and transform schemas for Effect",
 	"keywords": [
@@ -39,10 +39,10 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/jsonc": "^0.13.0",
-		"@effected/toml": "^0.9.0",
-		"@effected/yaml": "^0.17.0",
-		"effect": "4.0.0-rc.117"
+		"@effected/jsonc": "^0.15.0",
+		"@effected/toml": "^0.11.0",
+		"@effected/yaml": "^0.19.0",
+		"effect": "^4.0.0"
 	},
 	"peerDependenciesMeta": {
 		"@effected/jsonc": {