@dragon708/docmind-markdown 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,162 @@
+import { StructuredDocumentResult } from '@dragon708/docmind-shared';
+export { DocumentBlock, DocumentPage, DocumentTable, StructuredDocumentResult } from '@dragon708/docmind-shared';
+
+/** Options for {@link convertStructuredToMarkdown}. */
+interface ConvertStructuredToMarkdownOptions {
+    /**
+     * When an `image-ref` block has no resolvable `src`, emit this string (default: HTML comment).
+     */
+    readonly imagePlaceholder?: string;
+    /** If true, prepend a short human-readable metadata block when `result.metadata` has fields. */
+    readonly includeMetadataHeader?: boolean;
+    /**
+     * When `true` (default), insert {@link pageSeparator} between blocks when `pageIndex` increases
+     * (1-based page hint in italics when {@link StructuredDocumentResult.pages} is non-empty).
+     */
+    readonly pageTransitionMarkers?: boolean;
+    /** Line(s) used for `page-break` blocks and page transitions (default: `---`). */
+    readonly pageSeparator?: string;
+    /**
+     * Append markdown for entries in `tables` not referenced by any `table` block (default: `true`).
+     */
+    readonly appendUnreferencedTables?: boolean;
+    /**
+     * Append placeholders or `![alt]()` lines for `images` not referenced by any `image-ref` block (default: `false`).
+     */
+    readonly appendUnreferencedImages?: boolean;
+}
+/** @deprecated Use {@link ConvertStructuredToMarkdownOptions} instead. */
+type StructuredToMarkdownOptions = ConvertStructuredToMarkdownOptions;
+/**
+ * Converts a {@link StructuredDocumentResult} to readable, semantic Markdown (GFM-style tables).
+ *
+ * Uses `blocks` in order; resolves `table` / `image-ref` via `tables` and `images`. When blocks are
+ * empty or yield no output, falls back to the rollup `text`. Optional sections use `pages`, `metadata`,
+ * and unreferenced `tables` / `images` according to options.
+ */
+declare function convertStructuredToMarkdown(result: StructuredDocumentResult, options?: ConvertStructuredToMarkdownOptions): string;
+/**
+ * @deprecated Use {@link convertStructuredToMarkdown} — same behavior.
+ */
+declare function structuredDocumentToMarkdown(structured: StructuredDocumentResult, options?: ConvertStructuredToMarkdownOptions): string;
+
+/** Options for {@link convertStructuredToLlmText}. */
+interface ConvertStructuredToLlmTextOptions {
+    /**
+     * When true (default), use {@link StructuredDocumentResult.text} if block rendering is empty.
+     */
+    readonly fallbackToRollupText?: boolean;
+    /** Opening tag for table blocks (default `[TABLE]`). */
+    readonly tableSectionTag?: string;
+    /** Tag for image lines (default `[IMAGE]`). */
+    readonly imagePlaceholderTag?: string;
+    /**
+     * Line emitted for `page-break` blocks and for automatic page transitions (default `[PAGE]`).
+     */
+    readonly pageBreakMarker?: string;
+    /**
+     * When true (default), insert {@link pageBreakMarker} when `pageIndex` increases on a block
+     * and `pages` is non-empty (same idea as Markdown export, without markdown syntax).
+     */
+    readonly pageTransitionMarkers?: boolean;
+    /** Append `[WARNINGS]` when `result.warnings` is non-empty (default `true`). */
+    readonly includeWarnings?: boolean;
+    /**
+     * Prepend a short `[DOC]` block when `metadata` has title, author, pageCount, etc. (default `false`).
+     */
+    readonly includeDocumentMetadata?: boolean;
+    /** Max entries from `metadata.extra` to include (default `5`). */
+    readonly metadataExtraMaxKeys?: number;
+    /** Append tables not referenced by any `table` block (default `true`). */
+    readonly appendUnreferencedTables?: boolean;
+    /** Use single newlines between blocks instead of double (default `false`). */
+    readonly compact?: boolean;
+    /** Omit paragraph blocks whose trimmed text is empty (default `true`). */
+    readonly skipEmptyParagraphs?: boolean;
+}
+/** @deprecated Use {@link ConvertStructuredToLlmTextOptions}. */
+type StructuredToLlmTextOptions = ConvertStructuredToLlmTextOptions;
+/**
+ * Linearizes {@link StructuredDocumentResult} into plain text for prompts, RAG, and embeddings:
+ * explicit `[Hn]` headings, readable tables, compact list lines, configurable page markers,
+ * optional `[DOC]` metadata and `[WARNINGS]`. Not Markdown — tuned for density and clarity.
+ */
+declare function convertStructuredToLlmText(result: StructuredDocumentResult, options?: ConvertStructuredToLlmTextOptions): string;
+/**
+ * @deprecated Use {@link convertStructuredToLlmText} — same behavior.
+ */
+declare function structuredDocumentToLlmText(structured: StructuredDocumentResult, options?: ConvertStructuredToLlmTextOptions): string;
+
+/** One slice of a document for RAG / embeddings / chat. */
+interface StructuredChunk {
+    /** Zero-based order in the output array. */
+    readonly index: number;
+    /** Plain text (LLM-oriented, same family as {@link convertStructuredToLlmText}). */
+    readonly text: string;
+    /** Markdown slice when {@link SplitStructuredIntoChunksOptions.includeMarkdown} is true. */
+    readonly markdown?: string;
+    /** Breadcrumb of heading texts in scope for this chunk (best-effort). */
+    readonly headingPath?: readonly string[];
+    /** Smallest `pageIndex` among blocks in this chunk, when any. */
+    readonly pageIndex?: number;
+    /** Largest `pageIndex` among blocks in this chunk, when any. */
+    readonly pageEndIndex?: number;
+}
+/** Options for {@link splitStructuredIntoChunks}. */
+interface SplitStructuredIntoChunksOptions {
+    /** Soft maximum characters for `text` per chunk (default `4000`). Tables may exceed this when {@link preserveTables} is true. */
+    readonly maxChars?: number;
+    /** Suffix of the previous chunk's `text` prepended to the next (default `0`). */
+    readonly overlapChars?: number;
+    /**
+     * When true (default), start a new chunk before each `heading` block if the current chunk is non-empty.
+     */
+    readonly preferHeadings?: boolean;
+    /**
+     * When true (default), never split a `table` block across chunks; a large table may form a single oversized chunk.
+     */
+    readonly preserveTables?: boolean;
+    /** When true (default), fill {@link StructuredChunk.markdown} using {@link convertStructuredToMarkdown} per slice. */
+    readonly includeMarkdown?: boolean;
+}
+/**
+ * Splits a {@link StructuredDocumentResult} into ordered chunks for RAG / chat.
+ *
+ * First version: one unit per block, greedy packing with soft `maxChar` limits, optional heading-aligned
+ * cuts, and atomic tables. Intended to refine later (finer splits, row-level tables, token limits).
+ */
+declare function splitStructuredIntoChunks(result: StructuredDocumentResult, options?: SplitStructuredIntoChunksOptions): StructuredChunk[];
+
+/** Options for {@link renderMarkdown} (same as {@link ConvertStructuredToMarkdownOptions}). */
+type RenderMarkdownOptions = ConvertStructuredToMarkdownOptions;
+/** Options for {@link renderLlmText} (same as {@link ConvertStructuredToLlmTextOptions}). */
+type RenderLlmTextOptions = ConvertStructuredToLlmTextOptions;
+/**
+ * Ergonomic alias for {@link convertStructuredToMarkdown}: full document → Markdown string.
+ */
+declare function renderMarkdown(result: StructuredDocumentResult, options?: RenderMarkdownOptions): string;
+/**
+ * Ergonomic alias for {@link convertStructuredToLlmText}: full document → plain text for LLM prompts.
+ */
+declare function renderLlmText(result: StructuredDocumentResult, options?: RenderLlmTextOptions): string;
+/** One Markdown slice aligned with chunking (headings / size limits). */
+interface MarkdownSection {
+    readonly index: number;
+    readonly markdown: string;
+    readonly headingPath?: readonly string[];
+    readonly pageIndex?: number;
+    readonly pageEndIndex?: number;
+    /** Plain-text slice for the same block span (optional embedding / preview). */
+    readonly text?: string;
+}
+/**
+ * Options for {@link renderMarkdownSections}; same shape as {@link SplitStructuredIntoChunksOptions}.
+ */
+type RenderMarkdownSectionsOptions = SplitStructuredIntoChunksOptions;
+/**
+ * Markdown (and optional parallel plain text) per chunk — delegates to {@link splitStructuredIntoChunks}
+ * with `includeMarkdown: true`. Use for sectioned previews, TOC, or per-chunk storage without re-chunking.
+ */
+declare function renderMarkdownSections(result: StructuredDocumentResult, options?: RenderMarkdownSectionsOptions): MarkdownSection[];
+
+export { type ConvertStructuredToLlmTextOptions, type ConvertStructuredToMarkdownOptions, type MarkdownSection, type RenderLlmTextOptions, type RenderMarkdownOptions, type RenderMarkdownSectionsOptions, type SplitStructuredIntoChunksOptions, type StructuredChunk, type StructuredToLlmTextOptions, type StructuredToMarkdownOptions, convertStructuredToLlmText, convertStructuredToMarkdown, renderLlmText, renderMarkdown, renderMarkdownSections, splitStructuredIntoChunks, structuredDocumentToLlmText, structuredDocumentToMarkdown };

package/dist/index.js

@@ -0,0 +1,647 @@
+// src/structuredToMarkdown.ts
+function clampHeadingLevel(level) {
+  if (level === void 0 || !Number.isFinite(level)) return 2;
+  const n = Math.floor(level);
+  if (n < 1) return 1;
+  if (n > 6) return 6;
+  return n;
+}
+function escapeTableCell(text) {
+  return text.replace(/\|/g, "\\|").replace(/\r?\n/g, " ").trim();
+}
+function safeString(s) {
+  return typeof s === "string" ? s : "";
+}
+function safeArrays(result) {
+  return {
+    blocks: Array.isArray(result.blocks) ? result.blocks : [],
+    tables: Array.isArray(result.tables) ? result.tables : [],
+    pages: Array.isArray(result.pages) ? result.pages : [],
+    images: Array.isArray(result.images) ? result.images : []
+  };
+}
+function metadataHeaderLines(meta) {
+  const lines = [];
+  if (meta.title) lines.push(`**Title:** ${meta.title}`);
+  if (meta.author) lines.push(`**Author:** ${meta.author}`);
+  if (meta.language) lines.push(`**Language:** ${meta.language}`);
+  if (meta.created) lines.push(`**Created:** ${meta.created}`);
+  if (meta.modified) lines.push(`**Modified:** ${meta.modified}`);
+  if (meta.pageCount !== void 0 && Number.isFinite(meta.pageCount)) {
+    lines.push(`**Pages:** ${meta.pageCount}`);
+  }
+  const extra = meta.extra;
+  if (extra && typeof extra === "object") {
+    for (const [k, v] of Object.entries(extra)) {
+      if (v === void 0 || v === null) continue;
+      const rendered = typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? String(v) : JSON.stringify(v);
+      if (rendered.length > 200) continue;
+      lines.push(`**${k}:** ${rendered}`);
+    }
+  }
+  return lines;
+}
+function tableToMarkdown(table) {
+  const rows = table.rows;
+  if (rows.length === 0) {
+    return table.caption ? `_${escapeTableCell(table.caption)}_
+
+*(empty table)*
+` : "*(empty table)*\n";
+  }
+  const width = Math.max(...rows.map((r) => r.length));
+  const header = rows[0] ?? [];
+  const sep = Array.from({ length: width }, () => "---");
+  const line = (cells) => `| ${Array.from({ length: width }, (_, i) => escapeTableCell(cells[i]?.text ?? "")).join(" | ")} |`;
+  const out = [];
+  if (table.caption) {
+    out.push(`**${escapeTableCell(table.caption)}**`);
+    out.push("");
+  }
+  out.push(line(header));
+  out.push(`| ${sep.join(" | ")} |`);
+  for (let r = 1; r < rows.length; r++) {
+    out.push(line(rows[r]));
+  }
+  return `${out.join("\n")}
+`;
+}
+function resolveTable(tables, tableId) {
+  return tables.find((t) => t.id === tableId);
+}
+function resolveImage(images, imageId) {
+  return images.find((i) => i.id === imageId);
+}
+function referencedTableIds(blocks) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const b of blocks) {
+    if (b.type === "table" && typeof b.tableId === "string") ids.add(b.tableId);
+  }
+  return ids;
+}
+function referencedImageIds(blocks) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const b of blocks) {
+    if (b.type === "image-ref" && typeof b.imageId === "string") ids.add(b.imageId);
+  }
+  return ids;
+}
+function convertStructuredToMarkdown(result, options) {
+  const imagePlaceholder = options?.imagePlaceholder ?? "<!-- image: no src -->";
+  const pageSep = (options?.pageSeparator ?? "---").trimEnd();
+  const pageTransitions = options?.pageTransitionMarkers !== false;
+  const appendOrphanTables = options?.appendUnreferencedTables !== false;
+  const appendOrphanImages = options?.appendUnreferencedImages === true;
+  const { blocks, tables, pages, images } = safeArrays(result);
+  const hasPageModel = pages.length > 0;
+  const parts = [];
+  if (options?.includeMetadataHeader) {
+    const meta = result.metadata;
+    if (meta && typeof meta === "object") {
+      const lines = metadataHeaderLines(meta);
+      if (lines.length > 0) {
+        parts.push(lines.join("\n"));
+        parts.push("");
+      }
+    }
+  }
+  const orderedDepthCounters = [];
+  const resetListState = () => {
+    orderedDepthCounters.length = 0;
+  };
+  let lastPageIndex;
+  function pushPageTransitionIfNeeded(block) {
+    if (!pageTransitions) return;
+    if (block.type === "page-break") return;
+    const pi = block.pageIndex;
+    if (pi === void 0 || !Number.isFinite(pi)) return;
+    const n = Math.floor(pi);
+    if (lastPageIndex === void 0) {
+      lastPageIndex = n;
+      return;
+    }
+    if (n <= lastPageIndex) {
+      lastPageIndex = n;
+      return;
+    }
+    parts.push(pageSep);
+    if (hasPageModel) {
+      parts.push("");
+      parts.push(`*Page ${n + 1}*`);
+    }
+    parts.push("");
+    lastPageIndex = n;
+  }
+  for (const block of blocks) {
+    pushPageTransitionIfNeeded(block);
+    const chunk = blockToMarkdown(
+      block,
+      tables,
+      images,
+      imagePlaceholder,
+      orderedDepthCounters,
+      resetListState,
+      pageSep
+    );
+    parts.push(chunk);
+  }
+  if (appendOrphanTables) {
+    const used = referencedTableIds(blocks);
+    const orphans = tables.filter((t) => t.id && !used.has(t.id));
+    if (orphans.length > 0) {
+      parts.push("");
+      parts.push("### Additional tables");
+      parts.push("");
+      for (const t of orphans) {
+        parts.push(tableToMarkdown(t).trimEnd());
+      }
+    }
+  }
+  if (appendOrphanImages) {
+    const used = referencedImageIds(blocks);
+    const orphans = images.filter((i) => i.id && !used.has(i.id));
+    if (orphans.length > 0) {
+      parts.push("");
+      parts.push("### Additional images");
+      parts.push("");
+      for (const img of orphans) {
+        const alt = safeString(img.alt).replace(/]/g, "\\]");
+        if (img.src) {
+          parts.push(`![${alt}](${img.src})`);
+        } else {
+          parts.push(
+            `${imagePlaceholder} <!-- id: ${escapeCommentText(img.id)} -->`
+          );
+        }
+      }
+    }
+  }
+  let body = parts.join("\n\n").replace(/\n{3,}/g, "\n\n").trimEnd();
+  if (body.length === 0) {
+    body = safeString(result.text).trim();
+  }
+  return body;
+}
+function escapeCommentText(s) {
+  return s.replace(/-->/g, "-\\->");
+}
+function listItemLine(block, orderedDepthCounters) {
+  const depth = Math.max(0, block.depth ?? 0);
+  const indent = "  ".repeat(depth);
+  const style = block.listStyle ?? "unordered";
+  if (style === "ordered") {
+    while (orderedDepthCounters.length <= depth) orderedDepthCounters.push(0);
+    orderedDepthCounters.length = depth + 1;
+    orderedDepthCounters[depth] = (orderedDepthCounters[depth] ?? 0) + 1;
+    const n = orderedDepthCounters[depth];
+    return `${indent}${n}. ${block.text.trim()}`;
+  }
+  orderedDepthCounters.length = depth;
+  return `${indent}- ${block.text.trim()}`;
+}
+function blockToMarkdown(block, tables, images, imagePlaceholder, orderedDepthCounters, resetListState, pageSep) {
+  switch (block.type) {
+    case "heading": {
+      resetListState();
+      const level = clampHeadingLevel(block.level);
+      const hashes = "#".repeat(level);
+      return `${hashes} ${block.text.trim()}`;
+    }
+    case "paragraph": {
+      resetListState();
+      return block.text.trim();
+    }
+    case "list-item":
+      return listItemLine(block, orderedDepthCounters);
+    case "table": {
+      resetListState();
+      const t = resolveTable(tables, block.tableId);
+      if (!t) {
+        return `<!-- table not found: ${escapeCommentText(block.tableId)} -->`;
+      }
+      return tableToMarkdown(t).trimEnd();
+    }
+    case "image-ref": {
+      resetListState();
+      const img = resolveImage(images, block.imageId);
+      const altRaw = block.alt ?? img?.alt ?? "";
+      const alt = altRaw.replace(/]/g, "\\]");
+      const src = img?.src;
+      if (src) return `![${alt}](${src})`;
+      const kind = img?.kind;
+      const hint = kind === "placeholder" ? " (placeholder)" : kind === "embedded" ? " (embedded)" : "";
+      return `${imagePlaceholder}${hint}`;
+    }
+    case "page-break": {
+      resetListState();
+      return pageSep;
+    }
+    case "unknown": {
+      resetListState();
+      const raw = block.raw?.trim();
+      if (raw) return raw;
+      if (block.hint) return `<!-- ${escapeCommentText(block.hint)} -->`;
+      return "<!-- unknown block -->";
+    }
+    default: {
+      const _exhaustive = block;
+      return _exhaustive;
+    }
+  }
+}
+function structuredDocumentToMarkdown(structured, options) {
+  return convertStructuredToMarkdown(structured, options);
+}
+
+// src/structuredToLlmText.ts
+function clampHeadingLevel2(level) {
+  if (level === void 0 || !Number.isFinite(level)) return 2;
+  const n = Math.floor(level);
+  if (n < 1) return 1;
+  if (n > 6) return 6;
+  return n;
+}
+function safeArrays2(result) {
+  return {
+    blocks: Array.isArray(result.blocks) ? result.blocks : [],
+    tables: Array.isArray(result.tables) ? result.tables : [],
+    pages: Array.isArray(result.pages) ? result.pages : [],
+    images: Array.isArray(result.images) ? result.images : [],
+    warnings: Array.isArray(result.warnings) ? result.warnings : []
+  };
+}
+function metadataDocBlock(meta, extraMax) {
+  const lines = [];
+  if (meta.title) lines.push(`title: ${meta.title}`);
+  if (meta.author) lines.push(`author: ${meta.author}`);
+  if (meta.language) lines.push(`language: ${meta.language}`);
+  if (meta.pageCount !== void 0 && Number.isFinite(meta.pageCount)) {
+    lines.push(`pages: ${meta.pageCount}`);
+  }
+  if (meta.created) lines.push(`created: ${meta.created}`);
+  if (meta.modified) lines.push(`modified: ${meta.modified}`);
+  const extra = meta.extra;
+  if (extra && typeof extra === "object" && extraMax > 0) {
+    let n = 0;
+    for (const [k, v] of Object.entries(extra)) {
+      if (n >= extraMax) break;
+      if (v === void 0 || v === null) continue;
+      const s = typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? String(v) : JSON.stringify(v);
+      if (s.length > 120) continue;
+      lines.push(`${k}: ${s}`);
+      n++;
+    }
+  }
+  if (lines.length === 0) return void 0;
+  return `[DOC]
+${lines.join("\n")}`;
+}
+function tableToLlmBlock(table, tag) {
+  const lines = [];
+  lines.push(`${tag} id=${table.id}`);
+  if (table.caption) lines.push(`Caption: ${table.caption}`);
+  const rows = table.rows;
+  if (rows.length === 0) {
+    lines.push("(empty table)");
+    return lines.join("\n");
+  }
+  for (const row of rows) {
+    lines.push(row.map((c) => c.text.replace(/\r?\n/g, " ").trim()).join(" | "));
+  }
+  return lines.join("\n");
+}
+function resolveTable2(tables, tableId) {
+  return tables.find((t) => t.id === tableId);
+}
+function referencedTableIds2(blocks) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const b of blocks) {
+    if (b.type === "table" && typeof b.tableId === "string") ids.add(b.tableId);
+  }
+  return ids;
+}
+function listItemLine2(block, orderedDepthCounters) {
+  const depth = Math.max(0, block.depth ?? 0);
+  const indent = "  ".repeat(depth);
+  const style = block.listStyle ?? "unordered";
+  const text = block.text.replace(/\r?\n/g, " ").trim();
+  if (style === "ordered") {
+    while (orderedDepthCounters.length <= depth) orderedDepthCounters.push(0);
+    orderedDepthCounters.length = depth + 1;
+    orderedDepthCounters[depth] = (orderedDepthCounters[depth] ?? 0) + 1;
+    const n = orderedDepthCounters[depth];
+    return `${indent}${n}. ${text}`;
+  }
+  orderedDepthCounters.length = depth;
+  return `${indent}\u2022 ${text}`;
+}
+function blockToLlm(block, tables, images, tableTag, imageTag, pageMarker, orderedDepthCounters, resetListState, skipEmptyParagraphs) {
+  switch (block.type) {
+    case "heading": {
+      resetListState();
+      const lv = clampHeadingLevel2(block.level);
+      return `[H${lv}] ${block.text.replace(/\r?\n/g, " ").trim()}`;
+    }
+    case "paragraph": {
+      resetListState();
+      const t = block.text.trim();
+      if (t.length === 0 && skipEmptyParagraphs) return void 0;
+      return t.replace(/\r?\n/g, " ").replace(/\s+/g, " ").trim();
+    }
+    case "list-item":
+      return listItemLine2(block, orderedDepthCounters);
+    case "table": {
+      resetListState();
+      const t = resolveTable2(tables, block.tableId);
+      if (!t) return `${tableTag} MISSING id=${block.tableId}`;
+      return tableToLlmBlock(t, tableTag);
+    }
+    case "image-ref": {
+      resetListState();
+      const img = images.find((i) => i.id === block.imageId);
+      const alt = (block.alt ?? img?.alt ?? "").replace(/\r?\n/g, " ").trim();
+      if (img?.src) {
+        return `${imageTag} alt=${JSON.stringify(alt)} url=${JSON.stringify(img.src)}`;
+      }
+      return `${imageTag} id=${JSON.stringify(block.imageId)} alt=${JSON.stringify(alt)} (no url)`;
+    }
+    case "page-break": {
+      resetListState();
+      return pageMarker;
+    }
+    case "unknown": {
+      resetListState();
+      const raw = block.raw?.trim();
+      if (raw) return raw.replace(/\r?\n/g, "\n");
+      return block.hint ? `[UNKNOWN: ${block.hint}]` : "[UNKNOWN]";
+    }
+    default: {
+      const _exhaustive = block;
+      return _exhaustive;
+    }
+  }
+}
+function convertStructuredToLlmText(result, options) {
+  const fallback = options?.fallbackToRollupText !== false;
+  const tableTag = options?.tableSectionTag ?? "[TABLE]";
+  const imageTag = options?.imagePlaceholderTag ?? "[IMAGE]";
+  const pageMarker = options?.pageBreakMarker ?? "[PAGE]";
+  const pageTransitions = options?.pageTransitionMarkers !== false;
+  const includeWarnings = options?.includeWarnings !== false;
+  const includeMeta = options?.includeDocumentMetadata === true;
+  const extraMax = options?.metadataExtraMaxKeys ?? 5;
+  const appendOrphanTables = options?.appendUnreferencedTables !== false;
+  const compact = options?.compact === true;
+  const skipEmptyParagraphs = options?.skipEmptyParagraphs !== false;
+  const sep = compact ? "\n" : "\n\n";
+  const { blocks, tables, pages, images, warnings } = safeArrays2(result);
+  const hasPageModel = pages.length > 0;
+  const parts = [];
+  if (includeMeta && result.metadata && typeof result.metadata === "object") {
+    const docBlock = metadataDocBlock(result.metadata, extraMax);
+    if (docBlock) parts.push(docBlock);
+  }
+  const orderedDepthCounters = [];
+  const resetListState = () => {
+    orderedDepthCounters.length = 0;
+  };
+  let lastPageIndex;
+  function pushPageTransitionIfNeeded(block) {
+    if (!pageTransitions) return;
+    if (block.type === "page-break") return;
+    const pi = block.pageIndex;
+    if (pi === void 0 || !Number.isFinite(pi)) return;
+    const n = Math.floor(pi);
+    if (lastPageIndex === void 0) {
+      lastPageIndex = n;
+      return;
+    }
+    if (n <= lastPageIndex) {
+      lastPageIndex = n;
+      return;
+    }
+    parts.push(pageMarker);
+    if (hasPageModel) {
+      parts.push(`[PAGE ${n + 1}]`);
+    }
+    lastPageIndex = n;
+  }
+  for (const block of blocks) {
+    pushPageTransitionIfNeeded(block);
+    const chunk = blockToLlm(
+      block,
+      tables,
+      images,
+      tableTag,
+      imageTag,
+      pageMarker,
+      orderedDepthCounters,
+      resetListState,
+      skipEmptyParagraphs
+    );
+    if (chunk !== void 0 && chunk.length > 0) parts.push(chunk);
+  }
+  if (appendOrphanTables) {
+    const used = referencedTableIds2(blocks);
+    const orphans = tables.filter((t) => t.id && !used.has(t.id));
+    if (orphans.length > 0) {
+      parts.push(`[MORE_TABLES]`);
+      for (const t of orphans) {
+        parts.push(tableToLlmBlock(t, tableTag));
+      }
+    }
+  }
+  let out = parts.join(sep).replace(/\n{3,}/g, "\n\n").trim();
+  if (out.length === 0 && fallback) {
+    out = typeof result.text === "string" ? result.text.trim() : "";
+  }
+  if (includeWarnings && warnings.length > 0) {
+    const warnLines = warnings.map((w) => `- ${String(w).replace(/\r?\n/g, " ")}`).join("\n");
+    const block = `[WARNINGS]
+${warnLines}`;
+    out = out ? `${out}${sep}${block}` : block;
+  }
+  return out;
+}
+function structuredDocumentToLlmText(structured, options) {
+  return convertStructuredToLlmText(structured, options);
+}
+
+// src/splitStructuredIntoChunks.ts
+var SLICE_MARKDOWN_OPTS = {
+  includeMetadataHeader: false,
+  pageTransitionMarkers: false,
+  appendUnreferencedTables: false,
+  appendUnreferencedImages: false
+};
+var SLICE_LLM_OPTS = {
+  fallbackToRollupText: false,
+  includeDocumentMetadata: false,
+  includeWarnings: false,
+  pageTransitionMarkers: false,
+  appendUnreferencedTables: false
+};
+function clampHeadingLevel3(level) {
+  if (level === void 0 || !Number.isFinite(level)) return 2;
+  const n = Math.floor(level);
+  if (n < 1) return 1;
+  if (n > 6) return 6;
+  return n;
+}
+function sliceResult(result, blocks) {
+  return {
+    ...result,
+    blocks: [...blocks],
+    text: ""
+  };
+}
+function renderSlice(result, block, includeMarkdown) {
+  const r = sliceResult(result, [block]);
+  const text = convertStructuredToLlmText(r, SLICE_LLM_OPTS).trim();
+  const md = includeMarkdown ? convertStructuredToMarkdown(r, SLICE_MARKDOWN_OPTS).trim() : "";
+  return { text, md };
+}
+function joinChunkParts(parts) {
+  return parts.map((p) => p.trim()).filter((p) => p.length > 0).join("\n\n");
+}
+function safeBlocks(result) {
+  return Array.isArray(result.blocks) ? result.blocks : [];
+}
+function splitStructuredIntoChunks(result, options) {
+  const maxChars = Math.max(1, options?.maxChars ?? 4e3);
+  const overlapChars = Math.max(0, options?.overlapChars ?? 0);
+  const preferHeadings = options?.preferHeadings !== false;
+  const preserveTables = options?.preserveTables !== false;
+  const includeMarkdown = options?.includeMarkdown !== false;
+  const blocks = safeBlocks(result);
+  if (blocks.length === 0) {
+    const text = convertStructuredToLlmText(result, {
+      ...SLICE_LLM_OPTS,
+      fallbackToRollupText: true,
+      includeWarnings: false
+    }).trim();
+    const md = includeMarkdown ? convertStructuredToMarkdown(result, {
+      ...SLICE_MARKDOWN_OPTS,
+      includeMetadataHeader: false
+    }).trim() : void 0;
+    const chunkText = text.length > 0 ? text : typeof result.text === "string" ? result.text.trim() : "";
+    return [
+      {
+        index: 0,
+        text: chunkText,
+        markdown: md && md.length > 0 ? md : void 0,
+        headingPath: void 0,
+        pageIndex: void 0,
+        pageEndIndex: void 0
+      }
+    ];
+  }
+  const stack = [];
+  const units = [];
+  for (const block of blocks) {
+    if (block.type === "heading") {
+      const L = clampHeadingLevel3(block.level);
+      while (stack.length > 0 && stack[stack.length - 1].level >= L) {
+        stack.pop();
+      }
+      stack.push({ level: L, text: block.text.trim() });
+    }
+    const headingPath = stack.map((h) => h.text);
+    const { text, md } = renderSlice(result, block, includeMarkdown);
+    const pageIndex = block.pageIndex !== void 0 && Number.isFinite(block.pageIndex) ? Math.floor(block.pageIndex) : void 0;
+    units.push({
+      text,
+      md,
+      pageIndex,
+      isTable: block.type === "table",
+      isHeading: block.type === "heading",
+      headingPath
+    });
+  }
+  const chunks = [];
+  let current = [];
+  let pendingTextPrefix = "";
+  function projectedTextLength(next) {
+    const body = joinChunkParts(current.map((u) => u.text).concat(next.text));
+    const full = pendingTextPrefix ? `${pendingTextPrefix}${body.length > 0 ? "\n\n" + body : ""}` : body;
+    return full.length;
+  }
+  function flush() {
+    if (current.length === 0) return;
+    const body = joinChunkParts(current.map((u) => u.text));
+    const text = pendingTextPrefix ? `${pendingTextPrefix}${body.length > 0 ? "\n\n" + body : ""}`.trim() : body.trim();
+    const markdown = includeMarkdown && current.length > 0 ? joinChunkParts(current.map((u) => u.md)).trim() : void 0;
+    const pages = current.map((u) => u.pageIndex).filter((n) => n !== void 0);
+    const pageIndex = pages.length > 0 ? Math.min(...pages) : void 0;
+    const pageEndIndex = pages.length > 0 ? Math.max(...pages) : void 0;
+    const headingPath = current.length > 0 ? current[current.length - 1].headingPath : void 0;
+    if (text.length > 0 || markdown && markdown.length > 0) {
+      chunks.push({
+        index: chunks.length,
+        text,
+        markdown: markdown && markdown.length > 0 ? markdown : void 0,
+        headingPath: headingPath && headingPath.length > 0 ? [...headingPath] : void 0,
+        pageIndex,
+        pageEndIndex
+      });
+    }
+    pendingTextPrefix = overlapChars > 0 && text.length > 0 ? text.slice(Math.max(0, text.length - overlapChars)).trimStart() : "";
+    current = [];
+  }
+  for (let i = 0; i < units.length; i++) {
+    const unit = units[i];
+    if (preferHeadings && unit.isHeading && current.length > 0) {
+      flush();
+    }
+    if (preserveTables && unit.isTable && unit.text.length > maxChars) {
+      if (current.length > 0) flush();
+      current = [unit];
+      flush();
+      continue;
+    }
+    if (current.length > 0 && projectedTextLength(unit) > maxChars) {
+      flush();
+    }
+    current.push(unit);
+  }
+  flush();
+  if (chunks.length === 0) {
+    return [
+      {
+        index: 0,
+        text: typeof result.text === "string" ? result.text.trim() : "",
+        markdown: void 0,
+        headingPath: void 0,
+        pageIndex: void 0,
+        pageEndIndex: void 0
+      }
+    ];
+  }
+  return chunks.map((c, i) => ({ ...c, index: i }));
+}
+
+// src/render.ts
+function renderMarkdown(result, options) {
+  return convertStructuredToMarkdown(result, options);
+}
+function renderLlmText(result, options) {
+  return convertStructuredToLlmText(result, options);
+}
+function renderMarkdownSections(result, options) {
+  const chunks = splitStructuredIntoChunks(result, {
+    ...options,
+    includeMarkdown: true
+  });
+  return chunks.map((c) => ({
+    index: c.index,
+    markdown: (c.markdown ?? "").trim(),
+    headingPath: c.headingPath,
+    pageIndex: c.pageIndex,
+    pageEndIndex: c.pageEndIndex,
+    text: c.text.trim().length > 0 ? c.text.trim() : void 0
+  }));
+}
+
+export { convertStructuredToLlmText, convertStructuredToMarkdown, renderLlmText, renderMarkdown, renderMarkdownSections, splitStructuredIntoChunks, structuredDocumentToLlmText, structuredDocumentToMarkdown };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@dragon708/docmind-markdown",
+  "version": "1.0.0",
+  "description": "StructuredDocumentResult → Markdown and LLM-oriented plain text for DocMind.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "clean": "node -e \"try{require('fs').rmSync('dist',{recursive:true,force:true})}catch(e){}\""
+  },
+  "keywords": [
+    "docmind",
+    "markdown",
+    "structured-document",
+    "llm"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@dragon708/docmind-shared": "^1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.37",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.1"
+  }
+}