@endevops/effect-codec-xml 0.0.1 → 0.1.0-beta.1

package/src/namespaces.ts

@@ -19,21 +19,21 @@
 //   - `xmlValue` marks one field as the element's character data, the `#text`
 //     value, for an element that also carries attributes or children.
 //
-// The namespace of an element is inherited by its descendants, the way an XML
-// default namespace is. An attribute never inherits: it is in a namespace only
-// when it is annotated with one explicitly, because a default namespace does
-// not apply to attributes.
+// An element's namespace is inherited by its descendants, as an XML default
+// namespace is. An attribute never inherits: it is in a namespace only when it
+// is annotated with one explicitly, because a default namespace does not apply
+// to attributes.
 //
-// On the way out, each element writes its own declaration when the prefix or
-// default is not already in scope. On the way in, the parser's own declarations
-// are read into scope and every name is resolved to its URI, so a document that
-// binds the same URI to a different prefix still decodes to the same value. The
-// declaration attributes are dropped from the decoded value; they are the
-// codec's to manage, not the schema's.
+// On encode, each element writes its own declaration when the prefix or default
+// is not already in scope. On decode, the parser's own declarations are read
+// into scope and every name is resolved to its URI, so a document that binds the
+// same URI to a different prefix still decodes to the same value. The
+// declaration attributes are dropped from the decoded value; the codec manages
+// them, not the schema.
 //
-// The plan is built per local name, which is what a schema field is. One local
-// name cannot belong to two namespaces in one codec; that is reported when the
-// codec is built rather than guessed at.
+// The plan is built per local name, and a schema field is one local name. One
+// local name cannot belong to two namespaces in one codec; the plan reports that
+// when the codec is built rather than guessing.
 
 import type { Schema } from 'effect';
 
@@ -396,7 +396,7 @@ interface Scan {
   readonly problems: Array<string>;
   /**
    * @description The AST nodes on the current scan path. A recursive schema terminates because the `Suspend` node is still on the path when its thunk is reached,
-   * and a schema reused under two sibling paths is scanned once per path because each node is removed again on the way out.
+   * and a schema reused under two sibling paths is scanned once per path because each node is removed again on the way back out.
    */
   readonly seen: Set<SchemaAST.AST>;
 }
@@ -634,7 +634,7 @@ const scanNode = (scan: Scan, ast: SchemaAST.AST, inherited: XmlNamespace | unde
 };
 
 /**
- * @description Collects the namespace and name of every field in a schema. A namespace is inherited by descendant elements, the way a default namespace is, and an
+ * @description Collects the namespace and name of every field in a schema. Descendant elements inherit a namespace, as they inherit a default namespace, and an
  * element field records its own namespace, so encode and decode can find it by the local name alone.
  *
  * @param schema - The schema to walk.
@@ -900,7 +900,7 @@ const schemaKey = (plan: NamespacePlan, parent: string, key: string, scope: Reco
 /**
  * @description The scope a child element resolves its own name against: the declarations it carries on itself, layered over the parent scope. An element may
  * declare the prefix it uses on the element itself, so its own name is read with those bindings in scope. A repeated element arrives as an array, so
- * the first member stands in for the run — every member describes the same element and carries the same declaration.
+ * the first member stands in for the run; every member describes the same element and carries the same declaration.
  *
  * @param child - The child value.
  * @param scope - The bindings in scope above the child.

package/src/naming.ts

@@ -8,10 +8,10 @@
 //
 // The five predicates and `sanitize` are plain synchronous functions: a regex
 // test cannot fail and a character substitution has nothing to fail about, so
-// there is no effect to model. `validate` does have one failure to report — an
+// there is no effect to model. `validate` does have one failure to report: an
 // unknown production, unreachable from TypeScript where `Production` is a
 // closed union but reachable for an untyped JavaScript caller, or a value that
-// crossed a boundary as `unknown` — so it answers with an `Effect` whose error
+// crossed a boundary as `unknown`. It answers with an `Effect` whose error
 // channel is that {@link XmlError}. The value it produces is still a plain
 // result.
 
@@ -20,7 +20,7 @@ import { Effect } from 'effect';
 import { XmlError } from '#/xml-error.ts';
 
 /**
- * @description The XML specification version a production is validated against. The two differ only in their non-ASCII character ranges — see {@link getRegexes}.
+ * @description The XML specification version a production is validated against. The two differ only in their non-ASCII character ranges. See {@link getRegexes}.
  */
 export type XmlVersion = '1.0' | '1.1';
 
@@ -42,7 +42,7 @@ export interface ValidationOptions {
   /**
    * @description Restrict matching to the ASCII subset of the NameStartChar/NameChar productions and skip unicode-aware regex matching entirely. Faster,
    * especially for XML 1.1 (which otherwise requires the `/u` regex flag), but rejects legitimate non-ASCII XML names. Off by default for backward
-   * compatibility — opt in only when inputs are known to be ASCII. Defaults to false.
+   * compatibility. Opt in only when inputs are known to be ASCII. Defaults to false.
    */
   asciiOnly?: boolean;
 }
@@ -60,7 +60,7 @@ export interface SanitizeOptions {
    */
   asciiOnly?: boolean;
   /**
-   * @description Accepted and ignored. Sanitizing is not version-dependent — the character set it considers illegal is the union of both versions — but the option
+   * @description Accepted and ignored. Sanitizing is not version-dependent: the character set it considers illegal is the union of both versions. But the option
    * is part of the published signature, so dropping it would break callers that pass it through a shared options object.
    */
   xmlVersion?: XmlVersion;
@@ -94,7 +94,7 @@ const PRODUCTIONS = ['name', 'ncName', 'qName', 'nmToken', 'nmTokens'] as const
 type ProductionRegexes = Record<Production, RegExp>;
 
 // ---------------------------------------------------------------------------
-// Character class strings — XML 1.0
+// Character class strings: XML 1.0
 //
 // NameStartChar ::= ":" | [A-Z] | "_" | [a-z]
 //   | [#xC0-#xD6]   | [#xD8-#xF6]   | [#xF8-#x2FF]
@@ -127,7 +127,7 @@ const nameStartChar10 =
 const nameChar10 = nameStartChar10 + '\\-\\.\\d' + '\u00B7' + '\u0300-\u036F' + '\u203F-\u2040';
 
 // ---------------------------------------------------------------------------
-// Character class strings — XML 1.1
+// Character class strings: XML 1.1
 //
 // Differences from XML 1.0:
 //
@@ -138,7 +138,7 @@ const nameChar10 = nameStartChar10 + '\\-\\.\\d' + '\u00B7' + '\u0300-\u036F' +
 //
 //   1.0 tops out at \uFFFD (BMP only)
 //   1.1 adds \u{10000}-\u{EFFFF} (supplementary planes)
-//   These require the /u flag on the RegExp — see buildRegexes below.
+//   These require the /u flag on the RegExp. See buildRegexes below.
 //
 // NameChar:
 //   1.1 adds \u0487 (Combining Cyrillic Millions Sign, added in Unicode 4.0)
@@ -146,7 +146,7 @@ const nameChar10 = nameStartChar10 + '\\-\\.\\d' + '\u00B7' + '\u0300-\u036F' +
 
 const nameStartChar11 =
   ':A-Za-z_' +
-  '\u00C0-\u02FF' + // merged — 1.0 had three split ranges here
+  '\u00C0-\u02FF' + // merged: 1.0 had three split ranges here
   '\u0370-\u037D' +
   '\u037F-\u0486\u0488-\u1FFF' + // split to exclude \u0487 (combining mark, never a NameStartChar)
   '\u200C-\u200D' +
@@ -155,21 +155,21 @@ const nameStartChar11 =
   '\u3001-\uD7FF' +
   '\uF900-\uFDCF' +
   '\uFDF0-\uFFFD' +
-  '\u{10000}-\u{EFFFF}'; // supplementary planes — REQUIRES /u flag on RegExp
+  '\u{10000}-\u{EFFFF}'; // supplementary planes: REQUIRES /u flag on RegExp
 
 const nameChar11 =
   nameStartChar11 +
   '\\-\\.\\d' +
   '\u00B7' +
   '\u0300-\u036F' +
-  '\u0487' + // Combining Cyrillic Millions Sign — valid in 1.1, not 1.0
+  '\u0487' + // Combining Cyrillic Millions Sign: valid in 1.1, not 1.0
   '\u203F-\u2040';
 
 // ---------------------------------------------------------------------------
 // Regex builders
 //
-// XML 1.0 regexes: no flags — BMP only, standard JS regex behaviour.
-// XML 1.1 regexes: /u flag — required for \u{10000}-\u{EFFFF} to match actual
+// XML 1.0 regexes: no flags, BMP only, standard JS regex behaviour.
+// XML 1.1 regexes: /u flag, required for \u{10000}-\u{EFFFF} to match actual
 //   supplementary code points rather than lone surrogates (which are illegal XML).
 // ---------------------------------------------------------------------------
 
@@ -196,34 +196,33 @@ const buildRegexes = (startChar: string, char: string, flags = ''): ProductionRe
   };
 };
 
-const regexes10 = buildRegexes(nameStartChar10, nameChar10); // no /u — BMP only
-const regexes11 = buildRegexes(nameStartChar11, nameChar11, 'u'); // /u — enables \u{10000}-\u{EFFFF}
+const regexes10 = buildRegexes(nameStartChar10, nameChar10); // no /u, BMP only
+const regexes11 = buildRegexes(nameStartChar11, nameChar11, 'u'); // /u enables \u{10000}-\u{EFFFF}
 
 // ---------------------------------------------------------------------------
 // ASCII-only fast path (opt-in, off by default)
 //
-// The XML 1.0 vs 1.1 NameStartChar/NameChar productions differ *only* in
-// their non-ASCII ranges (merged vs split Latin-1 ranges, \u0487, and
-// supplementary planes). Restricted to ASCII, both versions collapse to the
-// same character classes, so a single regex pair covers both xmlVersion
-// values — no /u flag needed.
+// The XML 1.0 and 1.1 NameStartChar/NameChar productions differ only in their
+// non-ASCII ranges: merged vs split Latin-1 ranges, \u0487, and supplementary
+// planes. Restricted to ASCII, both versions collapse to the same character
+// classes, so one regex pair covers both xmlVersion values and no /u flag is
+// needed.
 //
-// Rationale: unicode-aware regexes (the /u flag, required for XML 1.1's
-// supplementary-plane range) are measurably slower in V8 than plain
-// non-unicode regexes on the same input, even when the input is pure ASCII.
-// For the common case — HTML/SVG ids, XML tags — names are ASCII, so callers
-// who know this can opt in to skip the unicode-aware matching path entirely.
-// This is a real but *conditional* win: mainly for XML 1.1 input (avoids /u),
-// or at scale where the larger unicode character classes add engine
-// overhead. It also changes behaviour (rejects legitimate non-ASCII XML
-// 1.0/1.1 names), so it must never be silently enabled — hence off by
-// default.
+// Unicode-aware regexes (the /u flag, required for XML 1.1's supplementary-
+// plane range) are measurably slower in V8 than plain non-unicode regexes on
+// the same input, even when the input is pure ASCII. For the common case
+// (HTML/SVG ids, XML tags) names are ASCII, so callers who know this can opt
+// in to skip the unicode-aware matching path entirely. The win is conditional:
+// it applies mainly to XML 1.1 input (avoids /u), or at scale where the larger
+// unicode character classes add engine overhead. The option also changes
+// behaviour (it rejects legitimate non-ASCII XML 1.0/1.1 names), so it must
+// never be enabled silently. That is why the default is off.
 // ---------------------------------------------------------------------------
 
 const nameStartCharAscii = ':A-Za-z_';
 const nameCharAscii = nameStartCharAscii + '\\-\\.\\d';
 
-const regexesAscii = buildRegexes(nameStartCharAscii, nameCharAscii); // no /u — ASCII only
+const regexesAscii = buildRegexes(nameStartCharAscii, nameCharAscii); // no /u, ASCII only
 
 /**
  * @description The compiled regex set for a version/ASCII combination. Only three sets are ever built, at module load; this is a lookup, not a compile.
@@ -242,7 +241,7 @@ const getRegexes = (xmlVersion: XmlVersion = '1.0', asciiOnly = false): Producti
 // Boolean validators
 //
 // One plain predicate per production. A regex test cannot fail, and every one of these is called per name
-// inside a parser's or codec's hot loop, so a boolean is the honest answer and there is no effect to
+// inside a parser's or codec's hot loop, so a boolean is the direct answer and there is no effect to
 // allocate or run.
 // ---------------------------------------------------------------------------
 
@@ -296,7 +295,7 @@ export const isNmToken = (str: string, { xmlVersion = '1.0', asciiOnly = false }
   getRegexes(xmlVersion, asciiOnly).nmToken.test(str);
 
 /**
- * @description Whether the string is a valid NMTokens value — a whitespace-separated list of NMToken values. Used for: DTD NMTOKENS attribute values.
+ * @description Whether the string is a valid NMTokens value: a whitespace-separated list of NMToken values. Used for: DTD NMTOKENS attribute values.
  *
  * @param str - The candidate list.
  * @param opts - `asciiOnly` skips unicode-aware matching, ASCII names only (default false).
@@ -455,7 +454,7 @@ const diagnoseWith = (str: string, production: Production, isValid: boolean, asc
  * @example
  *   ```typescript
  *   import { Effect } from 'effect';
- *   import { validate } from '@endevops/effect-xml-codec';
+ *   import { validate } from '@endevops/effect-codec-xml';
  *
  *   Effect.runSync(validate('not a name', 'ncName'));
  *   // { valid: false, production: 'ncName', input: 'not a name', reason: 'First character " " is not a valid NameStartChar', position: 0 }
@@ -466,7 +465,7 @@ const diagnoseWith = (str: string, production: Production, isValid: boolean, asc
  * @param opts - Version and ASCII-only selection, as for the boolean validators.
  *
  * @returns An effect producing a discriminated result: the plain triple when valid, or the offending `reason` and `position` when not. A name that
- *   fails to validate is a `valid: false` result, not a failure — an invalid name is the question being answered. The effect fails only with an
+ *   fails to validate is a `valid: false` result, not a failure: an invalid name is the question being answered. The effect fails only with an
  *   {@link XmlError} and the `InvalidProduction` reason for an unknown production, which is unreachable from TypeScript and is the guard for untyped
  *   JavaScript callers.
  */

package/src/parse.ts

@@ -34,7 +34,7 @@ export interface XmlParseOptions {
    * @description Keep the whitespace at the edges of every text run.
    *
    * @default false\
-   * which trims it — and trimming is what makes a pretty-printed document
+   * which trims it. Trimming makes a pretty-printed document
    * read as the same value as an unindented one, because the indentation around a child element and around a closing tag lands at the edges of its
    * parent's text. Whitespace _inside_ a run is content and is never touched either way, so `'one two'` and a paragraph with a newline in the middle
    * of it survive. Set it to `true` to keep leading and trailing spaces in text exactly as written, at the cost of a document that was laid out on
@@ -68,13 +68,13 @@ export interface XmlParseOptions {
 /**
  * @description Parses an XML document into its root element's content.\
  * The walk itself is synchronous, but it reports a malformed document by failing with an {@link XmlParseError} rather than by throwing, so the failure lands in the effect's error channel where `catchTag`, `retry` and a fallback can all
- * see it. A failed parse is an expected outcome of reading untrusted text — it is what those combinators key off — and only a defect would hide it.
+ * see it. A failed parse is an expected outcome of reading untrusted text, and those combinators key off it, so only a defect would hide it.
  * The span is the boundary a performance trace hangs off: it carries the document's length, which is the size that drives the parser's cost, so a
  * slow parse in a profile can be attributed to the input that produced it. A caller that wants the value outside an `Effect` uses
  * {@link parseXmlDocument}, which runs the same walk synchronously and throws instead. The walk is plain recursive descent rather than a chain of
- * `yield*`es. Publicly `parseXml` is still an `Effect` — it suspends the walk so it runs lazily under the span, and folds the failure the walk throws
- * into the typed error channel — but inside a document there is no effect boundary per tag, attribute or text run. A 500-row report is thousands of
- * those, and a fiber step for each of them was most of what the `parse 500 rows` row measured. The typed failure survives: the walk throws an
+ * `yield*`es. Publicly `parseXml` is still an `Effect`: it suspends the walk so it runs lazily under the span, and folds the failure the walk throws
+ * into the typed error channel, but inside a document there is no effect boundary per tag, attribute or text run. A 500-row report is thousands of
+ * those, and one fiber step per construct dominated the `parse 500 rows` benchmark. The typed failure survives: the walk throws an
  * {@link XmlParseError} and `parseXml` catches it into `Effect.fail`.
  *
  * @param text - The document to read.
@@ -140,8 +140,8 @@ const SLASH = 47;
 const EQUALS = 61;
 
 /**
- * @description One element as the parser saw it: the name it was written under, and the value it holds. Carrying the name alongside the value is what lets the
- * parent file it correctly — the value alone cannot say, because a text-only element reduces to a bare string.
+ * @description One element as the parser saw it: the name it was written under, and the value it holds. Carrying the name alongside the value lets the parent file
+ * it correctly, because the value alone cannot say: a text-only element reduces to a bare string.
  */
 interface Element {
   readonly name: string;
@@ -179,9 +179,9 @@ interface Content {
 }
 
 /**
- * @description What sits at the cursor inside an element's body. Naming what is there before deciding what to do with it is what lets the content loop stay a
- * dispatch: each construct is recognised in one place, against the ones that cannot be confused with it, rather than by a chain of `startsWith`
- * guesses where each had to remember what the last had already ruled out.
+ * @description What sits at the cursor inside an element's body. Naming what is there before deciding what to do with it lets the content loop stay a dispatch:
+ * each construct is recognised in one place, against the ones that cannot be confused with it, rather than by a chain of `startsWith` guesses where
+ * each had to remember what the last had already ruled out.
  */
 type Construct = 'text' | 'close' | 'comment' | 'cdata' | 'instruction' | 'child';
 
@@ -213,7 +213,7 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
   const nameOptions = { mode: resolved.name, xmlVersion: resolved.xmlVersion };
 
   /**
-   * @description Names already resolved by this parse. A document repeats names — every one of five hundred rows has a `sku` — and a validator that ran per
+   * @description Names already resolved by this parse. A document repeats names (every one of five hundred rows has a `sku`), and a validator that ran per
    * occurrence would pay for the same answer five hundred times.
    */
   const nameCache = new Map<string, string>();
@@ -258,7 +258,7 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
   };
 
   /**
-   * @description Consumes whitespace, comments, processing instructions and a DOCTYPE, leaving the cursor on the first character that is none of them — or at the
+   * @description Consumes whitespace, comments, processing instructions and a DOCTYPE, leaving the cursor on the first character that is none of them, or at the
    * end of the document.
    */
   const skipMisc = (): void => {
@@ -294,7 +294,7 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
     const start = at;
     while (at < text.length) {
       const char = text.charCodeAt(at);
-      // Whitespace, `/`, `=` and `>` all end a name. Stopping on `/` and `>` is what lets `<a/>` and `<a>` share one loop.
+      // Whitespace, `/`, `=` and `>` all end a name. Stopping on `/` and `>` lets `<a/>` and `<a>` share one loop.
       if (isWhitespace(char) || char === SLASH || char === EQUALS || char === GT) {
         break;
       }
@@ -322,7 +322,7 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
     at++;
 
     const end = text.indexOf(quote ?? '', at);
-    // A raw quote cannot appear inside a quoted value — it would have to be written `&quot;` — so the next quote of the same kind always closes it.
+    // A raw quote cannot appear inside a quoted value (it would have to be written `&quot;`), so the next quote of the same kind always closes it.
     if (end === -1) {
       throw new XmlParseError({ message: `Unterminated value for attribute "${name}"`, position: at, input: text });
     }
@@ -425,8 +425,8 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
   /**
    * @description What the cursor is sitting on inside an element's body. The two things the loop cannot read are refused here rather than in it: running out of
    * document and a declaration, which is markup the parser does not accept inside an element. Recognising the constructs that _are_ read is the rest,
-   * and the order is the one that rules out the shorter prefixes first — `</` before `<?` before any other `<!`, and `<![CDATA[` before the `<!` that
-   * would otherwise match it.
+   * and the order rules out the shorter prefixes first: `</` before `<?` before any other `<!`, and `<![CDATA[` before the `<!` that would otherwise
+   * match it.
    *
    * @param name - The name the enclosing element's start tag gave it, for the unterminated-body message.
    *
@@ -458,7 +458,7 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
   };
 
   /**
-   * @description Consumes a `</name>`, checking on the way that it is the tag that closes this element and that it is well-formed.
+   * @description Consumes a `</name>`, checking as it goes that it is the tag that closes this element and that it is well-formed.
    *
    * @param name - The name the start tag gave the element, which the closing tag has to match.
    */
@@ -490,7 +490,7 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
   };
 
   /**
-   * @description Reads a `<![CDATA[…]]>` section. CDATA is character data, and character data is what it holds, so it joins the element's text as it stands — the
+   * @description Reads a `<![CDATA[…]]>` section. CDATA is character data, and character data is what it holds, so it joins the element's text as it stands. The
    * entities in it are literal text and must not be expanded.
    *
    * @returns The section's contents.
@@ -522,15 +522,15 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
    */
   const finishElement = (record: Record<string, XmlValue>, hasAttributes: boolean, text: string, hasChildren: boolean): XmlValue => {
     // Whitespace at the edges of a text run is dropped unless the caller asked to
-    // keep it. This is what makes a pretty-printed document round trip: the
+    // keep it. Trimming here makes a pretty-printed document round trip: the
     // indentation a renderer puts around a child element and around a closing tag
     // lands at the edges of its parent's text, and trimming removes exactly that
-    // and nothing else. Whitespace *inside* the run — between two words, or a
-    // newline in the middle of a paragraph — is content and stays.
+    // and nothing else. Whitespace *inside* the run (between two words, or a
+    // newline in the middle of a paragraph) is content and stays.
     const content = resolved.preserveWhitespace ? text : text.trim();
 
     if (!hasAttributes && !hasChildren) {
-      // A leaf is character data on its own. Returning the string rather than a `{ '#text': … }` record is what lets
+      // A leaf is character data on its own. Returning the string rather than a `{ '#text': … }` record lets
       // `Schema.Struct({ name: Schema.String })` round-trip.
       return content;
     }
@@ -577,10 +577,10 @@ const parseDocumentResult = (text: string, options: XmlParseOptions): Result.Res
 };
 
 /**
- * @description Decodes character references, falling back to the raw text when the reference is not one the decoder recognises. The fallback is what makes a bare
- * `&` survivable: the decoder treats it as a malformed reference and fails, and a document containing one is far more likely to be worth reading than
- * to be rejected. The `&` is escaped on the way out, so the value still round-trips. The decoder answers with an `Effect`, and this is the one place
- * a parse still runs one. It is only reached when the raw text holds an `&` — the common case returns before it — and the effect is synchronous, so
+ * @description Decodes character references, falling back to the raw text when the reference is not one the decoder recognises. The fallback keeps a bare `&`
+ * survivable: the decoder treats it as a malformed reference and fails, and a document containing one is far more likely to be worth reading than to
+ * be rejected. The `&` is escaped on the way out, so the value still round-trips. The decoder answers with an `Effect`, and this is the one place a
+ * parse still runs one. It is only reached when the raw text holds an `&`, since the common case returns before it, and the effect is synchronous, so
  * the run is cheap next to the decoder's own work.
  *
  * @param raw - Text read straight from the source, with references unexpanded.

package/src/render.ts

@@ -7,23 +7,23 @@
 // string.
 //
 // The walk itself is plain synchronous functions rather than a chain of
-// `yield*`es. Publicly `renderXml` is still an `Effect` — it suspends the walk so
+// `yield*`es. Publicly `renderXml` is still an `Effect`: it suspends the walk so
 // it runs lazily, and folds the one failure the walk can report into the typed
-// error channel — but inside a document there is no effect boundary per element
-// or per attribute. A 500-row report is thousands of elements, and a fiber step
-// for each of them was most of what the `render 500 rows` row measured. The
-// typed failure survives: the walk throws an {@link XmlRenderError} and
-// `renderXml` catches it into `Effect.fail`.
+// error channel, but inside a document there is no effect boundary per element
+// or per attribute. A 500-row report is thousands of elements, and one fiber
+// step per element dominated the `render 500 rows` benchmark. The typed failure
+// survives: the walk throws an {@link XmlRenderError} and `renderXml` catches
+// it into `Effect.fail`.
 //
 // Escaping is the part that scales with the size of the document rather than
 // with its structure, and it is written out here rather than delegated, for a
 // measured reason. The entity encoder that used to live beside this package
 // escaped by applying five sequential global replacements, one per character,
 // so a document with a single `&` in twenty thousand characters was scanned
-// five times over to change one byte -- which is what the `render 20k` rows in
-// `bench/codec.bench.ts` measure. The table below covers the same five
-// characters that encoder escaped, and the explicit expectations in
-// `test/render.spec.ts` pin the fast path.
+// five times over to change one byte. The `render 20k` rows in
+// `bench/codec.bench.ts` measure that five-pass cost. The table below covers
+// the same five characters that encoder escaped, and the explicit expectations
+// in `test/render.spec.ts` pin the fast path.
 
 import { Effect, Predicate, Result } from 'effect';
 
@@ -65,11 +65,12 @@ const TEXT_TABLE = buildTable({});
 const ATTRIBUTE_TABLE = buildTable(ATTRIBUTE_WHITESPACE);
 
 /**
- * @description The characters each table escapes, as a pattern rather than as a set of replacement passes. Finding the first one with a pattern is what makes
- * clean text cheap: V8 compiles a single character class into a scan that is several times faster than a JavaScript loop reading the same string a
- * code unit at a time, and clean text is most text. `render 20k of clean text` in `bench/codec.bench.ts` is the row that says so — a hand-written
- * loop over the same twenty thousand characters is roughly two and a half times slower. Neither pattern is global, so `exec` ignores `lastIndex` and
- * always starts at the beginning. One module-level instance of each is therefore safe to reuse, and nothing has to be reset between calls.
+ * @description The characters each table escapes, as a pattern rather than as a set of replacement passes. A single pattern finds the first character that needs
+ * replacing, which keeps clean text cheap: V8 compiles a single character class into a scan that is several times faster than a JavaScript loop
+ * reading the same string a code unit at a time, and clean text is most text. The `render 20k of clean text` benchmark in `bench/codec.bench.ts`
+ * measures that difference: a hand-written loop over the same twenty thousand characters is roughly two and a half times slower. Neither pattern is
+ * global, so `exec` ignores `lastIndex` and always starts at the beginning. One module-level instance of each is therefore safe to reuse, and nothing
+ * has to be reset between calls.
  */
 const TEXT_UNSAFE = /[<>&"']/;
 const ATTRIBUTE_UNSAFE = /[<>&"'\n\r\t]/;
@@ -171,9 +172,9 @@ interface ResolvedOptions {
 /**
  * @description Builds the name resolver for one render. Every element and every attribute name goes through here, and a document repeats names: a thousand
  * `<item>` elements, or the same `id` on every row. A validator that runs a regex per occurrence pays that cost a thousand times for one answer, so
- * the first result is remembered and the rest are lookups. It also keeps the mode and version in one place, which is what stops a caller from
- * resolving a name with different settings than the render it is part of. A cache miss calls {@link resolveNameSync}, which throws an
- * {@link XmlParseError} in `'error'` mode; {@link renderXml} catches it and reports it as an {@link XmlRenderError}.
+ * the first result is remembered and the rest are lookups. Keeping the mode and version in one place also stops a caller from resolving a name with
+ * different settings than the render it is part of. A cache miss calls {@link resolveNameSync}, which throws an {@link XmlParseError} in `'error'`
+ * mode; {@link renderXml} catches it and reports it as an {@link XmlRenderError}.
  *
  * @param options - Resolved render options.
  *
@@ -193,8 +194,7 @@ const makeNamer = (options: Omit<ResolvedOptions, 'namer' | 'lineAt'>): ((name:
 /**
  * @description A boolean option's value, with an absent one read as the default. The three boolean options are spelled through here rather than through a `??` of
  * their own, so the table below reads as a list of what each option _is_ instead of a list of nine separate decisions about what an omitted option
- * means — and so a reader looking for "which options are on by default" finds three words rather than three mixes of `?? true` and `?? false` to
- * read.
+ * means, and a reader looking for "which options are on by default" finds three words rather than three mixes of `?? true` and `?? false` to read.
  *
  * @param value - The option as the caller wrote it, or `undefined` when the caller left it out.
  * @param fallback - The value to use when the caller left it out.
@@ -265,10 +265,10 @@ export const escapeAttribute = (value: string): string => escape(value, ATTRIBUT
 
 /**
  * @description Replaces every character the table has an entry for, in one pass over the string. The pattern finds the first character that needs replacing, and a
- * string with none is handed straight back — which is the common case, and the one the pattern is there to make fast. From there the rest of the
- * string is copied in runs between the replacements rather than a character at a time, so the cost is one pattern scan, one copy, and one
- * concatenation per replacement, rather than a whole pass per character class. Only ASCII is looked up. XML carries every other character natively,
- * and a code unit above 127 has no entity an XML parser is required to know.
+ * string with none is handed straight back. That is the common case, and the pattern exists to keep it fast. From there the rest of the string is
+ * copied in runs between the replacements rather than a character at a time, so the cost is one pattern scan, one copy, and one concatenation per
+ * replacement, rather than a whole pass per character class. Only ASCII is looked up. XML carries every other character natively, and a code unit
+ * above 127 has no entity an XML parser is required to know.
  *
  * @param value - The text to escape.
  * @param pattern - Matches the first character that needs replacing.
@@ -302,7 +302,7 @@ const escape = (value: string, pattern: RegExp, table: ReadonlyArray<string | un
  * A record becomes an element:
  *
  * - `@`-prefixed keys become attributes, the reserved `#text` key becomes character data, and every other key becomes a child element.
- * - An array repeats its name — a document whose root value is an array wraps it in the root element and names each member `itemName`.
+ * - An array repeats its name. A document whose root value is an array wraps it in the root element and names each member `itemName`.
  * - A string is character data. The walk is synchronous, and what can go wrong is reported by throwing an {@link XmlRenderError}; {@link renderXml}
  *   folds that into the effect's typed error channel. A caller not already in an `Effect` runs it with `Effect.runSync`, which throws the failure it
  *   produced.
@@ -379,9 +379,9 @@ const render = (value: XmlValue, options: XmlRenderOptions): string => {
 };
 
 /**
- * @description Renders one named element and its subtree. The value an {@link XmlValue} holds decides which of the four shapes below it takes — a repeated run of
- * children, character data, an absent field, or a record — and each of those is written by a function of its own, so this one is the dispatch rather
- * than the document.
+ * @description Renders one named element and its subtree. The value an {@link XmlValue} holds decides which of the four shapes below it takes: a repeated run of
+ * children, character data, an absent field, or a record. Each of those is written by a function of its own, so this one is the dispatch rather than
+ * the document.
  *
  * @param out - The chunk buffer to append to.
  * @param name - The element name, not yet resolved.
@@ -397,8 +397,8 @@ const renderElement = (out: Array<string>, name: string, value: XmlValue, depth:
     return;
   }
 
-  // An element opens its own line rather than having its caller do it, which is
-  // what keeps a repeated run of children on separate lines. The root is the
+  // An element opens its own line rather than having its caller do it, so a
+  // repeated run of children stays on separate lines. The root is the
   // one element that has nothing in front of it.
   if (options.format && depth > 0) openLine(out, depth, options);
 
@@ -417,7 +417,7 @@ const renderElement = (out: Array<string>, name: string, value: XmlValue, depth:
 
 /**
  * @description Refuses to walk deeper than the render allows. A value can nest without end, and every one of those levels costs a stack frame here, so the cap is
- * checked on the way down rather than trusted to the caller.
+ * checked as the walk descends rather than trusted to the caller.
  *
  * @param depth - The depth about to be written.
  * @param options - Resolved render options.
@@ -459,8 +459,8 @@ const renderRepeated = (out: Array<string>, name: string, members: ReadonlyArray
 
 /**
  * @description Renders an element whose value is character data, or nothing. An empty string is character data that happens to be empty, and an element holding
- * none of it is the same element as one holding nothing at all — as is an `undefined` element, which is an absent one. The renderer is handed values
- * that never went through the schema — a caller building a document by hand — so the absent case is reachable, and an empty element is the honest
+ * none of it is the same element as one holding nothing at all, as is an `undefined` element, which is an absent one. The renderer is handed values
+ * that never went through the schema (a caller building a document by hand), so the absent case is reachable, and an empty element is the correct
  * rendering of both.
  *
  * @param out - The chunk buffer to append to.
@@ -538,9 +538,9 @@ interface Fields {
  * @description One pass over a record's keys, collecting all three roles at once: the attributes are rendered as they are found, the child names are set aside for
  * the pass that writes them, and the text key is left to {@link textOf}. A pass for the attributes, a pass for the children and an index for the text
  * instead walks the keys three times and allocates the key array twice, which on a document of a few thousand elements is thousands of allocations
- * for nothing. Sorting is off by default, and the default path is the one that matters, so the attributes are built as they are found and there is
+ * for nothing. Sorting is off by default, and the default path is the important one, so the attributes are built as they are found and there is
  * nothing to sort. When it is on, the attribute keys are collected instead and rendered afterwards in sorted order, which costs an array per element
- * and buys output that does not depend on the order the fields happened to be declared in.
+ * and gives output independent of the order the fields happened to be declared in.
  *
  * @param record - The element's value.
  * @param options - Resolved render options.
@@ -557,10 +557,10 @@ const collectFields = (record: XmlRecord, options: ResolvedOptions): Fields => {
     const key = keys[i] as string;
     const child = record[key];
 
-    // An absent field is not written at all, which is what keeps an unset
-    // optional attribute out of the document rather than in it as `a=""`, and
-    // an absent child out of it rather than in it as `<a/>`. The text key is
-    // read by `textOf` either way, so skipping it here costs nothing.
+    // An absent field is not written at all, so an unset optional attribute
+    // stays out of the document rather than appearing as `a=""`, and an absent
+    // child stays out rather than appearing as `<a/>`. The text key is read by
+    // `textOf` either way, so skipping it here costs nothing.
     if (child === undefined) continue;
 
     if (isAttributeKey(key)) {
@@ -647,9 +647,9 @@ const openLine = (out: Array<string>, depth: number, options: ResolvedOptions):
 
 /**
  * @description Writes an element with no content, in whichever of the two forms the options ask for. Every path that produces an element with nothing in it goes
- * through here, so the self-closing decision is made in exactly one place. That matters because "nothing in it" arrives four different ways — an
- * empty string, an absent value, an empty array, and a record whose fields are all absent — and four separate decisions are four chances for one of
- * them to write the long form by accident.
+ * through here, so the self-closing decision is made in exactly one place. That is important because "nothing in it" arrives four different ways: an
+ * empty string, an absent value, an empty array, and a record whose fields are all absent. Four separate decisions are four chances for one of them
+ * to write the long form by accident.
  *
  * @param out - The chunk buffer to append to.
  * @param tag - The element's name, already resolved.
@@ -690,8 +690,8 @@ const attributeText = (value: XmlValue): string => {
 };
 
 /**
- * @description Renders a leaf that is not a string as the character data an XML document can hold. A schema-derived value never reaches here —
- * `Schema.toCodecStringTree` has already turned every scalar into a string — so this is for values a caller built by hand. A value with no sensible
+ * @description Renders a leaf that is not a string as the character data an XML document can hold. A schema-derived value never reaches here, because
+ * `Schema.toCodecStringTree` has already turned every scalar into a string, so this is for values a caller built by hand. A value with no sensible
  * text form is rendered as nothing rather than as `[object Object]`, which would silently write a document that parses back to something else.
  *
  * @param value - The leaf to render.