@frontlit/text-editor 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/docs.js

@@ -0,0 +1,905 @@
+import { getSchema, Node } from '@tiptap/core';
+import StarterKit from '@tiptap/starter-kit';
+import Image from '@tiptap/extension-image';
+import Link from '@tiptap/extension-link';
+import { TableRow, Table, TableCell, TableHeader } from '@tiptap/extension-table';
+import { parseDocument, stringify } from 'yaml';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkStringify from 'remark-stringify';
+
+// src/docs/diagnostics.ts
+function diagnostic(code, message, location = {}) {
+  return {
+    code,
+    message,
+    severity: "error",
+    blocksSave: true,
+    blocksPublish: true,
+    ...location
+  };
+}
+function sortDiagnostics(items) {
+  return items.sort(
+    (a, b) => (a.file ?? a.documentId ?? "").localeCompare(b.file ?? b.documentId ?? "") || (a.line ?? 0) - (b.line ?? 0) || (a.column ?? 0) - (b.column ?? 0) || (a.fieldPath ?? "").localeCompare(b.fieldPath ?? "") || a.code.localeCompare(b.code)
+  );
+}
+var DocsContentError = class extends Error {
+  constructor(diagnostics) {
+    super("Documentation content is invalid.");
+    this.name = "DocsContentError";
+    this.diagnostics = sortDiagnostics(diagnostics);
+  }
+};
+
+// src/docs/urls.ts
+function isSafeDocsUrl(value, image = false) {
+  if (typeof value !== "string" || !value || value !== value.trim()) return false;
+  if (
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: Browsers ignore controls in dangerous protocols.
+    /[\u0000-\u0020\u007f\\]/.test(value) || /%(?:0[0-9a-f]|1[0-9a-f]|7f|5c)/i.test(value)
+  )
+    return false;
+  if (value.startsWith("//")) return false;
+  const privatePath = /\/(?:attachments|private|ticket-attachments|conversation-attachments)(?:\/|$)/i;
+  const signedKey = /^(?:x-amz-.+|x-goog-.+|signature|sig|token|access_token|expires)$/i;
+  if (/^(?:https?:|mailto:)/i.test(value)) {
+    try {
+      const url = new URL(value);
+      if (image && url.protocol !== "https:") return false;
+      if (url.username || url.password) return false;
+      if (url.protocol === "mailto:") return !image && Boolean(url.pathname);
+      if (privatePath.test(decodeURIComponent(url.pathname))) return false;
+      for (const key of url.searchParams.keys()) {
+        if (signedKey.test(key)) return false;
+      }
+      return Boolean(url.hostname);
+    } catch {
+      return false;
+    }
+  }
+  if (image) return false;
+  if (/^[^/?#]*:/.test(value) || /%(?:2f|3a)/i.test(value)) return false;
+  try {
+    const url = new URL(value, "https://docs.invalid/");
+    return !privatePath.test(decodeURIComponent(url.pathname)) && ![...url.searchParams.keys()].some((key) => signedKey.test(key));
+  } catch {
+    return false;
+  }
+}
+
+// src/docs/extensions.ts
+function createDocsExtensions() {
+  return [
+    StarterKit.configure({
+      document: false,
+      underline: false,
+      link: false,
+      dropcursor: false,
+      gapcursor: false,
+      trailingNode: false
+    }),
+    Node.create({ name: "doc", topNode: true, content: "block*" }),
+    Link.extend({
+      addAttributes() {
+        return { ...this.parent?.(), title: { default: null } };
+      }
+    }).configure({ openOnClick: false, isAllowedUri: (url) => isSafeDocsUrl(url) }),
+    Image.configure({ allowBase64: false, resize: false }),
+    Table.configure({ resizable: false }),
+    TableRow,
+    TableCell.extend({ content: "paragraph" }),
+    TableHeader.extend({ content: "paragraph" })
+  ];
+}
+var docsSchema = getSchema(createDocsExtensions());
+var DOCS_SCHEMA_VERSION = 1;
+
+// src/docs/headings.ts
+var DOCS_HEADING_POLICY_VERSION = 1;
+function docsNodeText(node) {
+  if (typeof node.text === "string") return node.text;
+  if (node.type === "hardBreak") return "\n";
+  return (node.content ?? []).map(docsNodeText).join("");
+}
+function createHeadingIdGenerator() {
+  const used = /* @__PURE__ */ new Set();
+  return (text) => {
+    const base = text.normalize("NFKC").toLowerCase().trim().replace(/[^\p{L}\p{N}\s_-]/gu, "").replace(/\s+/g, "-") || "section";
+    let id = base;
+    let suffix = 2;
+    while (used.has(id)) id = `${base}-${suffix++}`;
+    used.add(id);
+    return id;
+  };
+}
+function extractDocsHeadings(json) {
+  const nextId = createHeadingIdGenerator();
+  const headings = [];
+  function walk(node) {
+    if (node.type === "heading") {
+      const text = docsNodeText(node);
+      headings.push({ level: Number(node.attrs?.level ?? 1), text, id: nextId(text) });
+    }
+    for (const child of node.content ?? []) walk(child);
+  }
+  if (json) walk(json);
+  return headings;
+}
+
+// src/docs/validate.ts
+var DOCS_LIMITS = {
+  bytes: 1024 * 1024,
+  nodes: 2e4,
+  depth: 64,
+  metadataBytes: 32768
+};
+var record = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+var nullableString = (v) => v === null || typeof v === "string";
+var attributes = {
+  heading: { level: (v) => Number.isInteger(v) && Number(v) >= 1 && Number(v) <= 6 },
+  orderedList: {
+    start: (v) => Number.isSafeInteger(v) && Number(v) >= 1,
+    type: (v) => v === null
+  },
+  codeBlock: {
+    language: (v) => v === null || typeof v === "string" && /^[\w+-]+$/.test(v)
+  },
+  image: {
+    src: (v) => typeof v === "string",
+    alt: nullableString,
+    title: nullableString,
+    width: (v) => v === null,
+    height: (v) => v === null
+  },
+  tableCell: {
+    colspan: (v) => v === 1,
+    rowspan: (v) => v === 1,
+    colwidth: (v) => v === null,
+    align: (v) => v === null
+  },
+  tableHeader: {
+    colspan: (v) => v === 1,
+    rowspan: (v) => v === 1,
+    colwidth: (v) => v === null,
+    align: (v) => v === null
+  },
+  link: {
+    href: (v) => typeof v === "string",
+    title: nullableString,
+    target: (v) => v === null || v === "_blank",
+    rel: (v) => v === null || v === "noopener noreferrer nofollow",
+    class: (v) => v === null
+  }
+};
+function validateDocsContent(input) {
+  const errors = [];
+  const add = (code, message, fieldPath) => errors.push(diagnostic(code, message, { fieldPath }));
+  let nodes = 0;
+  let textBytes = 0;
+  function attrs(value, type, path) {
+    if (value === void 0) return;
+    if (!record(value)) {
+      add("INVALID_DOCUMENT", "Attributes must be an object.", path);
+      return;
+    }
+    for (const [key, v] of Object.entries(value)) {
+      const allowed = attributes[type];
+      const check = allowed && Object.hasOwn(allowed, key) ? allowed[key] : void 0;
+      if (!check)
+        add(
+          "UNSUPPORTED_ATTRIBUTE",
+          `Unsupported ${type} attribute: ${key}.`,
+          `${path}.${key}`
+        );
+      else if (!check(v))
+        add("INVALID_DOCUMENT", `Invalid ${type} attribute: ${key}.`, `${path}.${key}`);
+    }
+  }
+  function walk(node, path, depth) {
+    if (++nodes > DOCS_LIMITS.nodes || depth > DOCS_LIMITS.depth) {
+      if (nodes === DOCS_LIMITS.nodes + 1 || depth > DOCS_LIMITS.depth)
+        add("INVALID_DOCUMENT", "Document exceeds structural limits.", path);
+      return;
+    }
+    if (!record(node) || typeof node.type !== "string") {
+      add("INVALID_DOCUMENT", "Expected a document node with a type.", path);
+      return;
+    }
+    if (!Object.hasOwn(docsSchema.nodes, node.type)) {
+      add("UNSUPPORTED_NODE", `Unsupported node: ${node.type}.`, `${path}.type`);
+      return;
+    }
+    for (const key of Object.keys(node)) {
+      if (!["type", "attrs", "content", "marks", "text"].includes(key))
+        add(
+          "UNSUPPORTED_ATTRIBUTE",
+          `Unsupported node field: ${key}.`,
+          `${path}.${key}`
+        );
+    }
+    attrs(node.attrs, node.type, `${path}.attrs`);
+    if (node.type === "text") {
+      if (typeof node.text !== "string" || !node.text.length)
+        add("INVALID_DOCUMENT", "Text nodes require nonempty text.", `${path}.text`);
+      else textBytes += new TextEncoder().encode(node.text).length;
+      if (node.content !== void 0 || node.attrs !== void 0)
+        add("INVALID_DOCUMENT", "Text cannot contain children or attributes.", path);
+    } else if (node.text !== void 0)
+      add("INVALID_DOCUMENT", "Only text nodes can contain text.", `${path}.text`);
+    if (node.marks !== void 0) {
+      if (!Array.isArray(node.marks))
+        add("INVALID_DOCUMENT", "Marks must be an array.", `${path}.marks`);
+      else {
+        const seen = /* @__PURE__ */ new Set();
+        node.marks.forEach((mark, i) => {
+          const mp = `${path}.marks[${i}]`;
+          if (!record(mark) || typeof mark.type !== "string") {
+            add("INVALID_DOCUMENT", "Invalid mark.", mp);
+            return;
+          }
+          if (!Object.hasOwn(docsSchema.marks, mark.type)) {
+            add("UNSUPPORTED_MARK", `Unsupported mark: ${mark.type}.`, `${mp}.type`);
+            return;
+          }
+          if (node.type !== "text" || seen.has(mark.type))
+            add("INVALID_DOCUMENT", "Marks must be unique and applied to text.", mp);
+          seen.add(mark.type);
+          for (const key of Object.keys(mark))
+            if (!["type", "attrs"].includes(key))
+              add(
+                "UNSUPPORTED_ATTRIBUTE",
+                `Unsupported mark field: ${key}.`,
+                `${mp}.${key}`
+              );
+          attrs(mark.attrs, mark.type, `${mp}.attrs`);
+          if (mark.type === "link" && (!record(mark.attrs) || !isSafeDocsUrl(mark.attrs.href)))
+            add("UNSAFE_URL", "Link URL is unsafe.", `${mp}.attrs.href`);
+        });
+        if (seen.has("code") && seen.size > 1)
+          add(
+            "INVALID_DOCUMENT",
+            "Inline code cannot carry other marks.",
+            `${path}.marks`
+          );
+      }
+    }
+    if (node.type === "image" && (!record(node.attrs) || !isSafeDocsUrl(node.attrs.src, true)))
+      add("UNSAFE_URL", "Images require a stable HTTPS URL.", `${path}.attrs.src`);
+    if (node.type === "heading" && (!record(node.attrs) || !Number.isInteger(node.attrs.level)))
+      add("INVALID_DOCUMENT", "Heading level is required.", `${path}.attrs.level`);
+    if (node.content !== void 0) {
+      if (!Array.isArray(node.content)) {
+        add("INVALID_DOCUMENT", "Content must be an array.", `${path}.content`);
+        return;
+      }
+      node.content.forEach((child, i) => {
+        walk(child, `${path}.content[${i}]`, depth + 1);
+      });
+    }
+    if (!errors.some((error) => error.fieldPath?.startsWith(path))) {
+      try {
+        docsSchema.nodeFromJSON(node).check();
+      } catch {
+        add("INVALID_DOCUMENT", "Invalid child ordering, cardinality, or marks.", path);
+      }
+    }
+    if (node.type === "table" && Array.isArray(node.content)) {
+      let width;
+      node.content.forEach((row, i) => {
+        if (!record(row) || !Array.isArray(row.content)) return;
+        width ?? (width = row.content.length);
+        if (row.content.length !== width || row.content.some(
+          (cell) => !record(cell) || cell.type !== (i === 0 ? "tableHeader" : "tableCell")
+        ))
+          add(
+            "INVALID_DOCUMENT",
+            "Simple tables require a rectangular header row followed by body rows.",
+            `${path}.content[${i}]`
+          );
+      });
+    }
+  }
+  if (!record(input) || input.type !== "doc")
+    add("INVALID_DOCUMENT", "Root must be a doc node.", "content.type");
+  else walk(input, "content", 0);
+  if (textBytes > DOCS_LIMITS.bytes)
+    add("INVALID_DOCUMENT", "Document exceeds the text size limit.", "content");
+  if (errors.length) return { diagnostics: sortDiagnostics(errors) };
+  const normalize = (node) => ({
+    ...node,
+    ...node.type === "image" ? { attrs: { ...node.attrs, alt: node.attrs?.alt ?? "" } } : {},
+    ...node.content ? { content: node.content.map(normalize) } : {}
+  });
+  const content = normalize(docsSchema.nodeFromJSON(input).toJSON());
+  return { content: { ...content, content: content.content ?? [] }, diagnostics: [] };
+}
+function requireDocsContent(input) {
+  const result = validateDocsContent(input);
+  if (!result.content) throw new DocsContentError(result.diagnostics);
+  return result.content;
+}
+
+// src/docs/routes.ts
+function normalizeDocsSlug(value) {
+  return normalizePath(value, true);
+}
+function normalizePath(value, reserveRoutes) {
+  if (typeof value !== "string")
+    throw new DocsContentError([
+      diagnostic("INVALID_SLUG", "Slug must be a relative documentation path.", {
+        fieldPath: "slug"
+      })
+    ]);
+  const slug = value.toLowerCase().replace(/\/$/, "");
+  if (!slug || slug.length > 512 || !/^[a-z0-9-]+(?:\/[a-z0-9-]+)*$/.test(slug))
+    throw new DocsContentError([
+      diagnostic(
+        "INVALID_SLUG",
+        "Use lowercase ASCII letters, digits, and hyphens in slash-separated segments.",
+        { fieldPath: "slug" }
+      )
+    ]);
+  if (reserveRoutes && ["collections", "search"].includes(slug.split("/")[0]))
+    throw new DocsContentError([
+      diagnostic(
+        "RESERVED_ROUTE",
+        "This path is reserved for documentation navigation.",
+        { route: `/docs/${slug}`, fieldPath: "slug" }
+      )
+    ]);
+  return slug;
+}
+function normalizeDocsSourceDirectory(value) {
+  const directory = value.replace(/\/$/, "");
+  if (!directory || directory.startsWith("/") || // biome-ignore lint/suspicious/noControlCharactersInRegex: Reject control characters in repository paths.
+  /[\\\u0000-\u001f]/.test(directory) || directory.split("/").some((segment) => !segment || segment === "." || segment === ".."))
+    throw new DocsContentError([
+      diagnostic("INVALID_REFERENCE", "Select a directory within the repository.", {
+        fieldPath: "directory"
+      })
+    ]);
+  return directory;
+}
+function resolveDocsSourcePath(path, directory, explicitSlug) {
+  const root = normalizeDocsSourceDirectory(directory);
+  if (!path.startsWith(`${root}/`))
+    throw new DocsContentError([
+      diagnostic(
+        "INVALID_REFERENCE",
+        "File is outside the configured docs directory.",
+        { file: path }
+      )
+    ]);
+  const relativePath = path.slice(root.length + 1);
+  const segments = relativePath.split("/");
+  if (!relativePath.endsWith(".md") || // biome-ignore lint/suspicious/noControlCharactersInRegex: Reject control characters in repository paths.
+  /[\\\u0000-\u001f]/.test(relativePath) || segments.some((segment) => !segment || segment === "." || segment === ".."))
+    throw new DocsContentError([
+      diagnostic("INVALID_REFERENCE", "Invalid Markdown source path.", { file: path })
+    ]);
+  const defaultSlug = relativePath.slice(0, -3).replace(/\/index$/, "");
+  const slug = normalizeDocsSlug(explicitSlug ?? defaultSlug);
+  return {
+    relativePath,
+    slug,
+    route: `/docs/${slug}`,
+    sectionSlug: segments.length > 1 ? normalizePath(segments[0], false) : null
+  };
+}
+
+// src/docs/frontmatter.ts
+function requireDocsFrontmatter(value, file) {
+  const fail = (message, fieldPath = "frontmatter") => {
+    throw new DocsContentError([
+      diagnostic("INVALID_FRONTMATTER", message, { fieldPath, file })
+    ]);
+  };
+  let count = 0;
+  function check(v, depth, path) {
+    if (++count > 2e3 || depth > 16) fail("Metadata exceeds structural limits.", path);
+    if (v === null || typeof v === "string" || typeof v === "boolean" || typeof v === "number" && Number.isFinite(v))
+      return;
+    if (Array.isArray(v)) {
+      v.forEach((item, i) => {
+        check(item, depth + 1, `${path}[${i}]`);
+      });
+      return;
+    }
+    if (typeof v !== "object" || ![Object.prototype, null].includes(Object.getPrototypeOf(v)))
+      fail("Metadata must contain only plain data.", path);
+    for (const [key, item] of Object.entries(v)) {
+      if (["__proto__", "prototype", "constructor"].includes(key))
+        fail("Reserved metadata key.", `${path}.${key}`);
+      check(item, depth + 1, `${path}.${key}`);
+    }
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    fail("Frontmatter must be an object.");
+  check(value, 0, "frontmatter");
+  const meta = value;
+  if (new TextEncoder().encode(JSON.stringify(meta)).length > DOCS_LIMITS.metadataBytes)
+    fail("Metadata exceeds size limit.");
+  if (typeof meta.title !== "string" || !meta.title.trim())
+    fail("Title is required.", "frontmatter.title");
+  for (const key of ["description", "slug", "nav_title"])
+    if (meta[key] !== void 0 && typeof meta[key] !== "string")
+      fail(`${key} must be a string.`, `frontmatter.${key}`);
+  if (meta.slug !== void 0) {
+    try {
+      normalizeDocsSlug(meta.slug);
+    } catch (error) {
+      if (error instanceof DocsContentError)
+        throw new DocsContentError(
+          error.diagnostics.map((item) => ({
+            ...item,
+            fieldPath: "frontmatter.slug",
+            file
+          }))
+        );
+      throw error;
+    }
+  }
+  if (meta.nav_order !== void 0 && !Number.isSafeInteger(meta.nav_order))
+    fail("nav_order must be an integer.", "frontmatter.nav_order");
+  for (const key of ["published", "indexable"])
+    if (meta[key] !== void 0 && typeof meta[key] !== "boolean")
+      fail(`${key} must be a boolean.`, `frontmatter.${key}`);
+  if (meta.featured_image !== void 0) {
+    const image = meta.featured_image;
+    if (!image || typeof image !== "object" || Array.isArray(image) || Object.keys(image).some((key) => !["url", "alt"].includes(key)) || !isSafeDocsUrl(image.url, true) || typeof image.alt !== "string")
+      fail(
+        "featured_image must contain a stable HTTPS url and alt string.",
+        "frontmatter.featured_image"
+      );
+  }
+  return meta;
+}
+function splitDocsFrontmatter(source, file) {
+  const normalized = source.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+  if (!normalized.startsWith("---\n"))
+    throw new DocsContentError([
+      diagnostic("INVALID_FRONTMATTER", "Markdown requires frontmatter with a title.", {
+        file,
+        line: 1,
+        column: 1
+      })
+    ]);
+  const end = /^---[ \t]*$/gm;
+  end.lastIndex = 4;
+  const delimiter = end.exec(normalized);
+  if (!delimiter)
+    throw new DocsContentError([
+      diagnostic("INVALID_FRONTMATTER", "Frontmatter is not closed.", {
+        file,
+        line: 1,
+        column: 1
+      })
+    ]);
+  const raw = normalized.slice(4, delimiter.index);
+  if (new TextEncoder().encode(raw).length > DOCS_LIMITS.metadataBytes)
+    throw new DocsContentError([
+      diagnostic("INVALID_FRONTMATTER", "Frontmatter exceeds size limit.", { file })
+    ]);
+  const doc = parseDocument(raw, {
+    schema: "core",
+    uniqueKeys: true,
+    strict: true,
+    merge: false
+  });
+  if (doc.errors.length || doc.warnings.length) {
+    throw new DocsContentError(
+      [...doc.errors, ...doc.warnings].map((error) => {
+        const offset = error.pos[0];
+        const prefix = raw.slice(0, offset);
+        return diagnostic("INVALID_FRONTMATTER", "Invalid YAML frontmatter.", {
+          file,
+          line: prefix.split("\n").length + 1,
+          column: prefix.length - prefix.lastIndexOf("\n")
+        });
+      })
+    );
+  }
+  let value;
+  try {
+    value = doc.toJS({ maxAliasCount: 0 });
+  } catch {
+    throw new DocsContentError([
+      diagnostic("INVALID_FRONTMATTER", "YAML aliases are not supported.", {
+        file,
+        line: 2,
+        column: 1
+      })
+    ]);
+  }
+  let frontmatter;
+  try {
+    frontmatter = requireDocsFrontmatter(value, file);
+  } catch (error) {
+    if (!(error instanceof DocsContentError)) throw error;
+    throw new DocsContentError(
+      error.diagnostics.map((item) => {
+        const key = item.fieldPath?.split(".")[1];
+        const field = key ? doc.get(key, true) : void 0;
+        const offset = field && typeof field === "object" && "range" in field ? field.range?.[0] ?? 0 : 0;
+        const prefix = raw.slice(0, offset);
+        return {
+          ...item,
+          file,
+          line: prefix.split("\n").length + 1,
+          column: prefix.length - prefix.lastIndexOf("\n")
+        };
+      })
+    );
+  }
+  const start = delimiter.index + delimiter[0].length + (normalized[delimiter.index + delimiter[0].length] === "\n" ? 1 : 0);
+  return {
+    frontmatter,
+    body: normalized.slice(start),
+    lineOffset: normalized.slice(0, start).split("\n").length - 1
+  };
+}
+function serializeDocsFrontmatter(meta) {
+  return `---
+${stringify(requireDocsFrontmatter(meta), { sortMapEntries: true, aliasDuplicateObjects: false, lineWidth: 0 })}---
+
+`;
+}
+var DOCS_PARSER_VERSION = 1;
+var parser = unified().use(remarkParse).use(remarkGfm);
+var writer = unified().use(remarkGfm).use(remarkStringify, {
+  bullet: "-",
+  emphasis: "*",
+  strong: "*",
+  fences: true,
+  incrementListMarker: true
+});
+function parseDocsMarkdown(markdown, options = {}) {
+  if (typeof markdown !== "string" || new TextEncoder().encode(markdown).length > DOCS_LIMITS.bytes)
+    throw new DocsContentError([
+      diagnostic("INVALID_DOCUMENT", "Markdown exceeds size limit.", {
+        file: options.file
+      })
+    ]);
+  const source = options.frontmatter === false ? {
+    body: markdown.replace(/\r\n?/g, "\n"),
+    lineOffset: 0,
+    frontmatter: void 0
+  } : splitDocsFrontmatter(markdown, options.file);
+  const tree = parser.parse(source.body);
+  const definitions = /* @__PURE__ */ new Map();
+  function error(node, message, code = "UNSUPPORTED_NODE") {
+    throw new DocsContentError([
+      diagnostic(code, message, {
+        file: options.file,
+        line: node.position ? node.position.start.line + source.lineOffset : void 0,
+        column: node.position?.start.column
+      })
+    ]);
+  }
+  let nodes = 0;
+  function inspect(node, depth) {
+    if (++nodes > DOCS_LIMITS.nodes || depth > DOCS_LIMITS.depth)
+      error(node, "Markdown exceeds structural limits.", "INVALID_DOCUMENT");
+    if (node.type === "definition") definitions.set(node.identifier, node);
+    if ("children" in node)
+      for (const child of node.children) inspect(child, depth + 1);
+  }
+  inspect(tree, 0);
+  function url(node, value, image2 = false) {
+    if (image2 && !/^[a-z]+:/i.test(value))
+      error(
+        node,
+        "Local image binaries must be uploaded to MediaLit.",
+        "UNMANAGED_BINARY"
+      );
+    if (!isSafeDocsUrl(value, image2))
+      error(node, "URL is unsafe or expiring.", "UNSAFE_URL");
+    return value;
+  }
+  function inline(items, marks = []) {
+    return items.flatMap((node) => {
+      switch (node.type) {
+        case "text": {
+          const raw = source.body.slice(
+            node.position?.start.offset ?? 0,
+            node.position?.end.offset ?? 0
+          );
+          if (/(?<!\\)<\/?[A-Za-z][^>]*>/.test(raw) || /^(?:import|export)\s/m.test(raw))
+            error(node, "MDX/JSX and module syntax are unsupported.");
+          return node.value ? [{ type: "text", text: node.value, ...marks.length ? { marks } : {} }] : [];
+        }
+        case "strong":
+          return inline(node.children, [...marks, { type: "bold" }]);
+        case "emphasis":
+          return inline(node.children, [...marks, { type: "italic" }]);
+        case "delete":
+          return inline(node.children, [...marks, { type: "strike" }]);
+        case "inlineCode":
+          if (marks.length) error(node, "Inline code cannot carry other marks.");
+          return [{ type: "text", text: node.value, marks: [{ type: "code" }] }];
+        case "break":
+          if (marks.length) error(node, "Marked line breaks are unsupported.");
+          return [{ type: "hardBreak" }];
+        case "link":
+          return inline(node.children, [
+            ...marks,
+            {
+              type: "link",
+              attrs: { href: url(node, node.url), title: node.title ?? null }
+            }
+          ]);
+        case "linkReference": {
+          const def = definitions.get(node.identifier);
+          if (!def) error(node, "Missing link definition.", "BROKEN_LINK");
+          return inline(node.children, [
+            ...marks,
+            {
+              type: "link",
+              attrs: { href: url(node, def.url), title: def.title ?? null }
+            }
+          ]);
+        }
+        default:
+          return error(node, `Unsupported inline construct: ${node.type}.`);
+      }
+    });
+  }
+  function image(node) {
+    const def = node.type === "imageReference" ? definitions.get(node.identifier) : node;
+    if (!def) error(node, "Missing image definition.", "BROKEN_LINK");
+    return {
+      type: "image",
+      attrs: {
+        src: url(node, def.url, true),
+        alt: node.alt ?? "",
+        title: def.title ?? null
+      }
+    };
+  }
+  function block(node) {
+    switch (node.type) {
+      case "definition":
+        return [];
+      case "paragraph": {
+        if (node.children.length === 1 && ["image", "imageReference"].includes(node.children[0].type))
+          return [
+            image(
+              node.children[0]
+            )
+          ];
+        return [{ type: "paragraph", content: inline(node.children) }];
+      }
+      case "heading":
+        return [
+          {
+            type: "heading",
+            attrs: { level: node.depth },
+            content: inline(node.children)
+          }
+        ];
+      case "blockquote":
+        return [{ type: "blockquote", content: node.children.flatMap(block) }];
+      case "thematicBreak":
+        return [{ type: "horizontalRule" }];
+      case "code":
+        if (node.meta)
+          error(node, "Code fence metadata is unsupported.", "UNSUPPORTED_ATTRIBUTE");
+        return [
+          {
+            type: "codeBlock",
+            attrs: { language: node.lang ?? null },
+            content: node.value ? [{ type: "text", text: node.value }] : []
+          }
+        ];
+      case "list":
+        return [
+          {
+            type: node.ordered ? "orderedList" : "bulletList",
+            ...node.ordered ? { attrs: { start: node.start ?? 1 } } : {},
+            content: node.children.map((item) => {
+              if (item.checked !== null && item.checked !== void 0)
+                error(item, "Task lists are unsupported.");
+              const content2 = item.children.flatMap(block);
+              return {
+                type: "listItem",
+                content: content2.length ? content2 : [{ type: "paragraph" }]
+              };
+            })
+          }
+        ];
+      case "table":
+        if (node.align?.some((alignment) => alignment !== null))
+          error(node, "Table alignment is unsupported.", "UNSUPPORTED_ATTRIBUTE");
+        return [
+          {
+            type: "table",
+            content: node.children.map((row, i) => ({
+              type: "tableRow",
+              content: row.children.map((cell) => ({
+                type: i === 0 ? "tableHeader" : "tableCell",
+                content: [{ type: "paragraph", content: inline(cell.children) }]
+              }))
+            }))
+          }
+        ];
+      default:
+        return error(node, `Unsupported block construct: ${node.type}.`);
+    }
+  }
+  const content = requireDocsContent({
+    type: "doc",
+    content: tree.children.flatMap(block)
+  });
+  return { content, frontmatter: source.frontmatter };
+}
+function toInline(children) {
+  const rank = ["link", "bold", "italic", "strike", "code"];
+  const nodes = children.map((node) => ({
+    ...node,
+    marks: [...node.marks ?? []].sort(
+      (a, b) => rank.indexOf(a.type) - rank.indexOf(b.type)
+    )
+  }));
+  function group(items, depth) {
+    const output = [];
+    for (let i = 0; i < items.length; ) {
+      const node = items[i];
+      const mark = node.marks?.[depth];
+      if (!mark) {
+        if (node.type === "hardBreak") output.push({ type: "break" });
+        else output.push({ type: "text", value: node.text });
+        i++;
+        continue;
+      }
+      let end = i + 1;
+      while (end < items.length && JSON.stringify(items[end].marks?.[depth]) === JSON.stringify(mark))
+        end++;
+      const children2 = group(items.slice(i, end), depth + 1);
+      switch (mark.type) {
+        case "link":
+          output.push({
+            type: "link",
+            url: mark.attrs.href,
+            title: mark.attrs?.title ?? null,
+            children: children2
+          });
+          break;
+        case "bold":
+          output.push({ type: "strong", children: children2 });
+          break;
+        case "italic":
+          output.push({ type: "emphasis", children: children2 });
+          break;
+        case "strike":
+          output.push({ type: "delete", children: children2 });
+          break;
+        case "code":
+          output.push({
+            type: "inlineCode",
+            value: items.slice(i, end).map((item) => item.text).join("")
+          });
+          break;
+      }
+      i = end;
+    }
+    return output;
+  }
+  return group(nodes, 0);
+}
+function serializeDocsMarkdown(input, frontmatter) {
+  const content = requireDocsContent(input);
+  function block(node) {
+    const children = node.content ?? [];
+    switch (node.type) {
+      case "paragraph":
+        return { type: "paragraph", children: toInline(children) };
+      case "heading":
+        return {
+          type: "heading",
+          depth: node.attrs.level,
+          children: toInline(children)
+        };
+      case "horizontalRule":
+        return { type: "thematicBreak" };
+      case "image":
+        return {
+          type: "paragraph",
+          children: [
+            {
+              type: "image",
+              url: node.attrs.src,
+              alt: node.attrs?.alt ?? "",
+              title: node.attrs?.title ?? null
+            }
+          ]
+        };
+      case "codeBlock":
+        return {
+          type: "code",
+          lang: node.attrs?.language ?? null,
+          value: children.map((child) => child.text ?? "").join("")
+        };
+      case "blockquote":
+        return {
+          type: "blockquote",
+          children: children.map(block)
+        };
+      case "bulletList":
+      case "orderedList":
+        return {
+          type: "list",
+          ordered: node.type === "orderedList",
+          start: node.type === "orderedList" ? node.attrs?.start ?? 1 : null,
+          spread: true,
+          children: children.map((item) => ({
+            type: "listItem",
+            spread: true,
+            children: (item.content ?? []).map(block)
+          }))
+        };
+      case "table":
+        return {
+          type: "table",
+          children: children.map((row) => ({
+            type: "tableRow",
+            children: (row.content ?? []).map((cell) => ({
+              type: "tableCell",
+              children: toInline(cell.content[0].content ?? [])
+            }))
+          }))
+        };
+      default:
+        throw new DocsContentError([
+          diagnostic("UNSUPPORTED_NODE", `Cannot serialize ${node.type}.`)
+        ]);
+    }
+  }
+  const tree = { type: "root", children: (content.content ?? []).map(block) };
+  const markdown = writer.stringify(tree);
+  const roundtrip = parseDocsMarkdown(markdown, { frontmatter: false }).content;
+  const semantic = (doc) => ({
+    ...doc,
+    content: doc.content?.filter(
+      (node) => node.type !== "paragraph" || node.content?.length
+    ) ?? []
+  });
+  if (JSON.stringify(semantic(roundtrip)) !== JSON.stringify(semantic(content)))
+    throw new DocsContentError([
+      diagnostic(
+        "INVALID_DOCUMENT",
+        "Content has no lossless Markdown representation."
+      )
+    ]);
+  return (frontmatter ? serializeDocsFrontmatter(frontmatter) : "") + markdown;
+}
+
+// src/docs/hash.ts
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [key, stable(value[key])])
+    );
+  return value;
+}
+async function hashDocsContent(input) {
+  const canonical = stable({
+    content: requireDocsContent(input.content),
+    metadata: input.metadata,
+    versions: {
+      schema: DOCS_SCHEMA_VERSION,
+      parser: DOCS_PARSER_VERSION,
+      headings: DOCS_HEADING_POLICY_VERSION,
+      embeddingConfiguration: input.embeddingConfigurationVersion
+    }
+  });
+  const bytes = new TextEncoder().encode(JSON.stringify(canonical));
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export { DOCS_HEADING_POLICY_VERSION, DOCS_LIMITS, DOCS_PARSER_VERSION, DOCS_SCHEMA_VERSION, DocsContentError, createDocsExtensions, createHeadingIdGenerator, diagnostic, docsNodeText, docsSchema, extractDocsHeadings, hashDocsContent, isSafeDocsUrl, normalizeDocsSlug, normalizeDocsSourceDirectory, parseDocsMarkdown, requireDocsContent, requireDocsFrontmatter, resolveDocsSourcePath, serializeDocsFrontmatter, serializeDocsMarkdown, sortDiagnostics, splitDocsFrontmatter, validateDocsContent };
+//# sourceMappingURL=docs.js.map
+//# sourceMappingURL=docs.js.map