@zudojs/docs 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -11,24 +11,47 @@ npm install @zudojs/docs
 ## Quick Start
 
 ```typescript
-import { createDocumentRegistry } from "@zudojs/docs";
+import {
+  createDocumentRegistry,
+  createMarkdownDocument,
+  validateAll,
+  generateIndex,
+} from "@zudojs/docs";
 
 const registry = createDocumentRegistry();
 
+registry.register(
+  createMarkdownDocument(
+    "getting-started",
+    "Getting Started",
+    "# Getting Started\n\nWelcome to Zudojs...",
+    { category: "introduction", tags: ["intro"] },
+  ),
+);
+
+// Or build the document object yourself
 registry.register({
-  id: "getting-started",
-  title: "Getting Started",
-  content: "# Getting Started\n\nWelcome to Zudojs...",
+  id: "guides.http.routing",
+  title: "HTTP Routing",
+  content: { type: "markdown", value: "# Routing\n\n..." },
 });
+
+const result = validateAll(registry.getAll());
+if (!result.valid) {
+  console.error(result.issues);
+}
+
+const index = generateIndex(registry.getAll()); // SERVER-only docs excluded
 ```
 
 ## Features
 
-- Document model with frontmatter
-- Document registry and discovery
-- Navigation tree generation
-- Markdown and JSON generation
-- Document validation
+- Document model with frontmatter (`parseFrontmatter` / `serializeFrontmatter` round-trip safely)
+- Document registry and discovery (`DuplicateDocumentError` on duplicate IDs, deep-frozen copies)
+- Navigation tree helpers (breadcrumbs, siblings, previous/next, cycle-safe walkers)
+- Markdown and JSON generation with escaping for untrusted content and `visibility` filtering
+- Document, link and navigation validation with a single `valid` rule (errors only)
+- Documentation error classes re-exported from `@zudojs/errors`
 
 ## Use Cases
 

package/dist/docsTypes/index.d.ts

@@ -4,7 +4,7 @@
  * Core type definitions for the documentation model.
  */
 export type { DocumentationNode, HeadingNode, ParagraphNode, CodeNode, ListNode, LinkNode, TableNode, QuoteNode, CalloutNode, MarkdownContent, MDXContent, HTMLContent, StructuredContent, DocumentationContent, } from "./documentationContent.js";
-export type { DocumentationCategory, DocumentationStatus, APISymbolKind, SourceLocation, APISymbol, APIParameter, DocumentationMetadata, DocumentationVersion, } from "./documentationMetadata.js";
+export type { DocumentationCategory, DocumentationStatus, APISymbolKind, SourceLocation, APISymbol, APIExample, APIParameter, DocumentationMetadata, DocumentationVersion, } from "./documentationMetadata.js";
 export type { DocumentationDocument } from "./documentationDocument.js";
 export type { DocumentationNavigationItem, DocumentationBreadcrumb, SearchDocument, SearchResult, } from "./documentationNavigation.js";
 export type { DocumentationProvider, DocumentationSourceLoader, DocumentationSanitizer, } from "./documentationProvider.js";

package/dist/document/documentBuilder.core.d.ts

@@ -4,7 +4,7 @@
  * Provides a chainable API that validates inputs and
  * produces immutable DocumentationDocument objects.
  */
-import type { DocumentationContent, DocumentationDocument, DocumentationCategory, DocumentationMetadata, DocumentationStatus } from "../docsTypes/index.js";
+import type { DocumentationContent, DocumentationDocument, DocumentationCategory, DocumentationMetadata, DocumentationNode, DocumentationStatus } from "../docsTypes/index.js";
 /**
  * Options for creating a document via the builder.
  */
@@ -22,9 +22,21 @@ export interface DocumentBuilderOptions {
     readonly deprecatedMessage?: string;
     readonly visibility?: "SERVER" | "CLIENT";
 }
+/**
+ * Options accepted by the convenience builders. The positional
+ * arguments (`id`, `title`, content) always win over these.
+ */
+export type DocumentBuilderExtras = Omit<Partial<DocumentBuilderOptions>, "id" | "title" | "content">;
 /**
  * Creates a documentation document from structured options.
  *
+ * The returned document is a deep-frozen copy: later mutation of the
+ * options object (or of nested `content`, `metadata`, `tags`) does not
+ * affect it.
+ *
+ * @throws {DocumentValidationError} when `id`, `title` or `content` is missing
+ *   or the ID is not a valid dot-separated identifier.
+ *
  * @example
  * ```ts
  * const doc = createDocument({
@@ -40,11 +52,9 @@ export declare function createDocument(options: DocumentBuilderOptions): Documen
 /**
  * Creates a markdown document.
  */
-export declare function createMarkdownDocument(id: string, title: string, markdown: string, options?: Partial<DocumentBuilderOptions>): DocumentationDocument;
+export declare function createMarkdownDocument(id: string, title: string, markdown: string, options?: DocumentBuilderExtras): DocumentationDocument;
 /**
  * Creates a structured document from AST nodes.
  */
-export declare function createStructuredDocument(id: string, title: string, nodes: DocumentationContent extends {
-    readonly nodes: infer N;
-} ? N : never, options?: Partial<DocumentBuilderOptions>): DocumentationDocument;
+export declare function createStructuredDocument(id: string, title: string, nodes: readonly DocumentationNode[], options?: DocumentBuilderExtras): DocumentationDocument;
 //# sourceMappingURL=documentBuilder.core.d.ts.map

package/dist/document/documentBuilder.core.js

@@ -4,9 +4,19 @@
  * Provides a chainable API that validates inputs and
  * produces immutable DocumentationDocument objects.
  */
+import { DocumentValidationError } from "@zudojs/errors";
+import { deepFreezeClone } from "../utils/utils.freeze.js";
+import { isValidDocumentId } from "../utils/utils.helper.js";
 /**
  * Creates a documentation document from structured options.
  *
+ * The returned document is a deep-frozen copy: later mutation of the
+ * options object (or of nested `content`, `metadata`, `tags`) does not
+ * affect it.
+ *
+ * @throws {DocumentValidationError} when `id`, `title` or `content` is missing
+ *   or the ID is not a valid dot-separated identifier.
+ *
  * @example
  * ```ts
  * const doc = createDocument({
@@ -20,34 +30,39 @@
  */
 export function createDocument(options) {
     validateDocumentOptions(options);
-    return Object.freeze({
+    const document = {
         id: options.id,
         title: options.title,
         description: options.description,
         content: options.content,
         category: options.category,
-        tags: options.tags ? Object.freeze([...options.tags]) : undefined,
+        tags: options.tags ? [...options.tags] : undefined,
         version: options.version,
         status: options.status,
         metadata: options.metadata,
         deprecated: options.deprecated,
         deprecatedMessage: options.deprecatedMessage,
         visibility: options.visibility,
-    });
+    };
+    return deepFreezeClone(document);
 }
 /**
  * Validates document builder options.
  * Throws on invalid input.
  */
 function validateDocumentOptions(options) {
-    if (!options.id || options.id.trim().length === 0) {
-        throw new Error("Document ID is required.");
+    if (typeof options.id !== "string" || options.id.trim().length === 0) {
+        throw new DocumentValidationError("Document ID is required.");
+    }
+    if (!isValidDocumentId(options.id)) {
+        throw new DocumentValidationError(`Document ID "${options.id}" is invalid. Use dot-separated segments of letters, digits, "_" and "-".`, options.id);
     }
-    if (!options.title || options.title.trim().length === 0) {
-        throw new Error("Document title is required.");
+    if (typeof options.title !== "string" ||
+        options.title.trim().length === 0) {
+        throw new DocumentValidationError("Document title is required.", options.id);
     }
-    if (!options.content) {
-        throw new Error("Document content is required.");
+    if (!options.content || typeof options.content !== "object") {
+        throw new DocumentValidationError("Document content is required.", options.id);
     }
 }
 /**
@@ -55,10 +70,10 @@ function validateDocumentOptions(options) {
  */
 export function createMarkdownDocument(id, title, markdown, options) {
     return createDocument({
+        ...options,
         id,
         title,
         content: { type: "markdown", value: markdown },
-        ...options,
     });
 }
 /**
@@ -66,13 +81,10 @@ export function createMarkdownDocument(id, title, markdown, options) {
  */
 export function createStructuredDocument(id, title, nodes, options) {
     return createDocument({
+        ...options,
         id,
         title,
-        content: {
-            type: "structured",
-            value: nodes,
-        },
-        ...options,
+        content: { type: "structured", nodes },
     });
 }
 //# sourceMappingURL=documentBuilder.core.js.map

package/dist/document/index.d.ts

@@ -4,5 +4,5 @@
  * Document model and builder for creating documentation pages.
  */
 export { createDocument, createMarkdownDocument, createStructuredDocument, } from "./documentBuilder.core.js";
-export type { DocumentBuilderOptions } from "./documentBuilder.core.js";
+export type { DocumentBuilderOptions, DocumentBuilderExtras, } from "./documentBuilder.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @zudojs/docs/errors
+ *
+ * The documentation error hierarchy is defined in `@zudojs/errors` and
+ * re-exported here so consumers can discriminate registry and builder
+ * failures with `instanceof` without a second import.
+ */
+import { DocumentationError } from "@zudojs/errors";
+import type { DocumentationErrorOptions } from "@zudojs/errors";
+export { DocumentationError, DocumentParseError, DocumentValidationError, DuplicateDocumentError, DocumentNotFoundError, BrokenDocumentationLinkError, InvalidFrontmatterError, InvalidNavigationError, ExampleValidationError, GenerationError, DocumentationVersionError, } from "@zudojs/errors";
+export type { DocumentationErrorOptions } from "@zudojs/errors";
+/** Creates a generic documentation error. */
+export declare function createDocumentationError(message: string, options?: DocumentationErrorOptions): DocumentationError;
+/** Determines whether an unknown value is a `DocumentationError`. */
+export declare function isDocumentationError(value: unknown): value is DocumentationError;
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.js

@@ -0,0 +1,18 @@
+/**
+ * @zudojs/docs/errors
+ *
+ * The documentation error hierarchy is defined in `@zudojs/errors` and
+ * re-exported here so consumers can discriminate registry and builder
+ * failures with `instanceof` without a second import.
+ */
+import { DocumentationError } from "@zudojs/errors";
+export { DocumentationError, DocumentParseError, DocumentValidationError, DuplicateDocumentError, DocumentNotFoundError, BrokenDocumentationLinkError, InvalidFrontmatterError, InvalidNavigationError, ExampleValidationError, GenerationError, DocumentationVersionError, } from "@zudojs/errors";
+/** Creates a generic documentation error. */
+export function createDocumentationError(message, options) {
+    return new DocumentationError(message, options);
+}
+/** Determines whether an unknown value is a `DocumentationError`. */
+export function isDocumentationError(value) {
+    return value instanceof DocumentationError;
+}
+//# sourceMappingURL=index.js.map

package/dist/examples/examples.core.d.ts

@@ -29,6 +29,10 @@ export interface ExampleValidationResult {
 export declare function validateExample(example: DocumentationExample): ExampleValidationResult;
 /**
  * Renders an example as a markdown code block.
+ *
+ * The fence is chosen longer than any backtick run inside the code and
+ * the language is reduced to fence-safe characters, so example content
+ * cannot escape its code block.
  */
 export declare function renderExampleMarkdown(example: DocumentationExample): string;
 /**

package/dist/examples/examples.core.js

@@ -4,19 +4,22 @@
  * Examples are first-class objects that can be validated,
  * rendered, and included in generated documentation.
  */
+import { fenceFor, sanitizeLanguage } from "../generator/generatorMarkdownNodes.js";
 /**
  * Validates a documentation example.
  */
 export function validateExample(example) {
     const errors = [];
-    if (!example.id || example.id.trim().length === 0) {
+    const hasId = typeof example.id === "string" && example.id.trim().length > 0;
+    const label = hasId ? `Example "${example.id}"` : "Example";
+    if (!hasId) {
         errors.push("Example ID is required.");
     }
     if (!example.language || example.language.trim().length === 0) {
-        errors.push(`Example "${example.id}" requires a language.`);
+        errors.push(`${label} requires a language.`);
     }
     if (!example.code || example.code.trim().length === 0) {
-        errors.push(`Example "${example.id}" requires code content.`);
+        errors.push(`${label} requires code content.`);
     }
     return {
         valid: errors.length === 0,
@@ -25,20 +28,26 @@ export function validateExample(example) {
 }
 /**
  * Renders an example as a markdown code block.
+ *
+ * The fence is chosen longer than any backtick run inside the code and
+ * the language is reduced to fence-safe characters, so example content
+ * cannot escape its code block.
  */
 export function renderExampleMarkdown(example) {
     const lines = [];
+    const code = (example.code ?? "").trim();
+    const fence = fenceFor(code);
     if (example.title) {
-        lines.push(`### ${example.title}`);
+        lines.push(`### ${example.title.replace(/\r?\n/g, " ")}`);
         lines.push("");
     }
     if (example.description) {
         lines.push(example.description);
         lines.push("");
     }
-    lines.push("```" + example.language);
-    lines.push(example.code.trim());
-    lines.push("```");
+    lines.push(fence + sanitizeLanguage(example.language));
+    lines.push(code);
+    lines.push(fence);
     return lines.join("\n");
 }
 /**

package/dist/frontmatter/frontmatter.core.d.ts

@@ -3,5 +3,5 @@
  */
 export { parseFrontmatter } from "./frontmatter.parser.js";
 export { serializeFrontmatter } from "./frontmatter.serializer.js";
-export type { ParsedFrontmatter, FrontmatterMetadata, } from "./frontmatter.types.js";
+export type { ParsedFrontmatter, FrontmatterMetadata, FrontmatterScalar, FrontmatterValue, } from "./frontmatter.types.js";
 //# sourceMappingURL=frontmatter.core.d.ts.map

package/dist/frontmatter/frontmatter.parser.d.ts

@@ -3,13 +3,26 @@
  *
  * Parses YAML-like frontmatter delimited by `---` markers
  * and extracts metadata alongside the remaining content.
+ *
+ * Supported subset:
+ * - `key: scalar` (strings, canonical numbers, booleans, null)
+ * - single- and double-quoted strings with escapes
+ * - `key:` followed by `- item` lines (list of scalars)
+ * - one level of nested mapping (`key:` followed by indented `sub: value`)
+ * - `#` comments (outside quotes)
+ *
+ * Anything else is kept as a plain string. Keys that would alter the
+ * result object's prototype (`__proto__`, `constructor`, `prototype`)
+ * are rejected.
  */
 import type { ParsedFrontmatter } from "./frontmatter.types.js";
 /**
  * Parses YAML-like frontmatter from a markdown string.
  *
- * Expects content to begin with `---`, followed by key-value pairs,
- * followed by another `---`.
+ * The opening delimiter must be exactly `---` on the first non-blank
+ * line and the closing delimiter must be `---` on its own line.
+ * Documents without a well-formed block are returned unchanged with
+ * empty metadata.
  */
 export declare function parseFrontmatter(raw: string): ParsedFrontmatter;
 //# sourceMappingURL=frontmatter.parser.d.ts.map

package/dist/frontmatter/frontmatter.parser.js

@@ -3,80 +3,243 @@
  *
  * Parses YAML-like frontmatter delimited by `---` markers
  * and extracts metadata alongside the remaining content.
+ *
+ * Supported subset:
+ * - `key: scalar` (strings, canonical numbers, booleans, null)
+ * - single- and double-quoted strings with escapes
+ * - `key:` followed by `- item` lines (list of scalars)
+ * - one level of nested mapping (`key:` followed by indented `sub: value`)
+ * - `#` comments (outside quotes)
+ *
+ * Anything else is kept as a plain string. Keys that would alter the
+ * result object's prototype (`__proto__`, `constructor`, `prototype`)
+ * are rejected.
  */
 const FRONTMATTER_DELIMITER = "---";
+/** Keys that must never be assigned onto a plain object. */
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/** Valid frontmatter key syntax. */
+const KEY_PATTERN = /^[A-Za-z_][\w.-]*$/;
+/** Canonical number: optional sign, no leading zeros, optional fraction. */
+const CANONICAL_NUMBER = /^-?(0|[1-9]\d*)(\.\d+)?$/;
+/**
+ * Keys whose values are declared as strings in `FrontmatterMetadata`.
+ * Their scalars are never coerced, so `version: 1.0` stays `"1.0"`.
+ */
+const STRING_KEYS = new Set([
+    "title",
+    "description",
+    "category",
+    "version",
+    "status",
+    "deprecatedMessage",
+    "visibility",
+]);
+/** Keys whose list items are always strings. */
+const STRING_LIST_KEYS = new Set(["tags"]);
 /**
  * Parses YAML-like frontmatter from a markdown string.
  *
- * Expects content to begin with `---`, followed by key-value pairs,
- * followed by another `---`.
+ * The opening delimiter must be exactly `---` on the first non-blank
+ * line and the closing delimiter must be `---` on its own line.
+ * Documents without a well-formed block are returned unchanged with
+ * empty metadata.
  */
 export function parseFrontmatter(raw) {
-    const trimmed = raw.trimStart();
-    if (!trimmed.startsWith(FRONTMATTER_DELIMITER)) {
-        return { metadata: {}, content: raw };
+    const lines = raw.split(/\r?\n/);
+    let start = 0;
+    while (start < lines.length && lines[start]?.trim() === "") {
+        start++;
     }
-    const afterFirst = trimmed.slice(FRONTMATTER_DELIMITER.length);
-    const endIndex = afterFirst.indexOf(FRONTMATTER_DELIMITER);
-    if (endIndex === -1) {
-        return { metadata: {}, content: raw };
+    if (lines[start]?.trim() !== FRONTMATTER_DELIMITER) {
+        return { metadata: Object.freeze({}), content: raw };
     }
-    const yamlBlock = afterFirst.slice(0, endIndex).trim();
-    const remainingContent = afterFirst
-        .slice(endIndex + FRONTMATTER_DELIMITER.length)
+    let end = -1;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (lines[i]?.trim() === FRONTMATTER_DELIMITER) {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1) {
+        return { metadata: Object.freeze({}), content: raw };
+    }
+    const yamlLines = lines.slice(start + 1, end);
+    const remainingContent = lines
+        .slice(end + 1)
+        .join("\n")
+        .replace(/^\s*\n/, "")
         .trimStart();
-    const metadata = parseYamlLike(yamlBlock);
+    const metadata = parseYamlLike(yamlLines);
     return { metadata, content: remainingContent };
 }
 /**
  * Minimal YAML-like parser for frontmatter key-value pairs.
  */
-function parseYamlLike(yaml) {
-    const result = {};
-    const lines = yaml.split("\n");
+function parseYamlLike(lines) {
+    const result = Object.create(null);
     let currentKey = null;
     let currentArray = null;
-    for (const line of lines) {
+    let currentMap = null;
+    const flush = () => {
+        if (currentKey === null)
+            return;
+        if (currentArray) {
+            result[currentKey] = Object.freeze(currentArray);
+        }
+        else if (currentMap) {
+            result[currentKey] = Object.freeze(currentMap);
+        }
+        else {
+            result[currentKey] = "";
+        }
+        currentKey = null;
+        currentArray = null;
+        currentMap = null;
+    };
+    for (const rawLine of lines) {
+        const line = stripComment(rawLine);
         const trimmed = line.trim();
-        if (trimmed.startsWith("- ")) {
-            if (currentKey && currentArray) {
-                currentArray.push(trimmed.slice(2).trim());
-            }
+        if (trimmed === "")
             continue;
+        const indented = /^\s/.test(line);
+        if (currentKey !== null) {
+            if (trimmed.startsWith("- ") || trimmed === "-") {
+                if (currentMap) {
+                    flush();
+                }
+                else {
+                    currentArray ??= [];
+                    const item = trimmed.slice(1).trim();
+                    currentArray.push(STRING_LIST_KEYS.has(currentKey)
+                        ? parseStringScalar(item)
+                        : parseScalar(item));
+                    continue;
+                }
+            }
+            else if (indented && !currentArray) {
+                const entry = splitKeyValue(trimmed);
+                if (entry) {
+                    currentMap ??= Object.create(null);
+                    if (isAllowedKey(entry.key)) {
+                        currentMap[entry.key] = parseScalar(entry.value);
+                    }
+                    continue;
+                }
+                flush();
+            }
+            else {
+                flush();
+            }
         }
-        if (currentKey && currentArray) {
-            result[currentKey] = Object.freeze(currentArray);
-            currentArray = null;
-            currentKey = null;
-        }
-        const colonIndex = trimmed.indexOf(":");
-        if (colonIndex === -1)
+        const entry = splitKeyValue(trimmed);
+        if (!entry)
             continue;
-        const key = trimmed.slice(0, colonIndex).trim();
-        const value = trimmed.slice(colonIndex + 1).trim();
-        if (value === "") {
-            currentKey = key;
-            currentArray = [];
+        if (!isAllowedKey(entry.key))
+            continue;
+        if (entry.value === "") {
+            currentKey = entry.key;
             continue;
         }
-        result[key] = parseScalar(value);
+        result[entry.key] = STRING_KEYS.has(entry.key)
+            ? parseStringScalar(entry.value)
+            : parseScalar(entry.value);
     }
-    if (currentKey && currentArray) {
-        result[currentKey] = Object.freeze(currentArray);
+    flush();
+    return Object.freeze({ ...result });
+}
+/** Splits `key: value` into its parts; returns undefined when not a pair. */
+function splitKeyValue(line) {
+    const match = line.match(/^([^:]+?)\s*:(?:\s+(.*)|\s*)$/);
+    if (!match)
+        return undefined;
+    const key = match[1]?.trim() ?? "";
+    const value = match[2]?.trim() ?? "";
+    if (key === "")
+        return undefined;
+    return { key, value };
+}
+/** Rejects prototype-polluting and syntactically invalid keys. */
+function isAllowedKey(key) {
+    return !FORBIDDEN_KEYS.has(key) && KEY_PATTERN.test(key);
+}
+/** Removes a trailing `# comment` that is not inside quotes. */
+function stripComment(line) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === "\\" && inDouble) {
+            i++;
+            continue;
+        }
+        if (ch === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (ch === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (ch === "#" &&
+            !inSingle &&
+            !inDouble &&
+            (i === 0 || /\s/.test(line[i - 1] ?? ""))) {
+            return line.slice(0, i);
+        }
     }
-    return Object.freeze(result);
+    return line;
 }
 /**
  * Parses a scalar YAML value into its appropriate JS type.
+ *
+ * Quoted strings are unquoted (with escape handling) and never coerced.
+ * Only canonical numbers within the safe-integer range become numbers;
+ * anything else stays a string.
  */
 function parseScalar(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if (first === '"' && last === '"') {
+            return unescapeDoubleQuoted(value.slice(1, -1));
+        }
+        if (first === "'" && last === "'") {
+            return value.slice(1, -1).replace(/''/g, "'");
+        }
+    }
     if (value === "true")
         return true;
     if (value === "false")
         return false;
-    if (/^\d+$/.test(value)) {
-        return Number(value);
+    if (value === "null" || value === "~")
+        return null;
+    if (CANONICAL_NUMBER.test(value)) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed) && Math.abs(parsed) <= Number.MAX_SAFE_INTEGER) {
+            return parsed;
+        }
     }
     return value;
 }
+/** Parses a scalar that must remain a string (unquotes, never coerces). */
+function parseStringScalar(value) {
+    const parsed = parseScalar(value);
+    if (typeof parsed === "string")
+        return parsed;
+    if (parsed === null)
+        return "";
+    return value;
+}
+/** Handles `\"`, `\\`, `\n`, `\t`, `\r` escapes in double-quoted strings. */
+function unescapeDoubleQuoted(value) {
+    return value.replace(/\\(["\\nrt])/g, (_, ch) => {
+        switch (ch) {
+            case "n":
+                return "\n";
+            case "r":
+                return "\r";
+            case "t":
+                return "\t";
+            default:
+                return ch;
+        }
+    });
+}
 //# sourceMappingURL=frontmatter.parser.js.map