@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/types/modules/word/convert/docx-to-semantic.d.ts

@@ -0,0 +1,39 @@
+/**
+ * DOCX → Semantic Document Converter
+ *
+ * Transforms a DocxDocument into a format-agnostic SemanticDocument.
+ * This is the bridge between OOXML-specific types and the universal IR
+ * that HTML/Markdown/other renderers can consume.
+ *
+ * Handles:
+ * - Heading detection (via style name or outlineLevel)
+ * - Inline formatting resolution
+ * - Hyperlink extraction
+ * - Image registration into ConversionContext
+ * - Table structure with merge (colSpan/rowSpan)
+ * - List/numbering detection (basic)
+ * - Footnote/endnote reference and content
+ * - Math content (text fallback)
+ */
+import type { DocxDocument } from "../types.js";
+import type { ConversionContext, SemanticDocument } from "./conversion-ir.js";
+/** Options for the semantic conversion. */
+export interface DocxToSemanticOptions {
+    /** Include footnotes in the output. Default: true. */
+    readonly includeFootnotes?: boolean;
+    /** Include endnotes in the output. Default: true. */
+    readonly includeEndnotes?: boolean;
+    /** Extract images and register as assets. Default: true. */
+    readonly extractImages?: boolean;
+}
+/**
+ * Convert a DocxDocument to a SemanticDocument (format-agnostic IR).
+ *
+ * @param doc - The parsed DOCX document.
+ * @param options - Conversion options.
+ * @returns The semantic document with warnings and assets.
+ */
+export declare function docxToSemantic(doc: DocxDocument, options?: DocxToSemanticOptions): {
+    document: SemanticDocument;
+    context: ConversionContext;
+};

package/dist/types/modules/word/convert/flat-opc.d.ts

@@ -0,0 +1,44 @@
+/**
+ * DOCX Module - Flat OPC Format Support
+ *
+ * Implements reading and writing of Flat OPC (Office Open XML Package) format,
+ * which represents an entire DOCX package as a single XML file.
+ * This is useful for debugging, XML transformations, and enterprise integration scenarios.
+ *
+ * Flat OPC uses the `pkg:` namespace to wrap all package parts in a single XML document.
+ * Each part is represented as a `<pkg:part>` element with its content either as XML or base64.
+ *
+ * References:
+ * - [MS-OFFCRYPTO] §2.1.5 (pkgStart namespace)
+ * - ECMA-376 Part 2 (OPC) Annex C (non-normative)
+ */
+/** A part extracted from Flat OPC XML. */
+export interface FlatOpcPart {
+    /** Part name (e.g. "/word/document.xml"). */
+    readonly name: string;
+    /** Content type of the part. */
+    readonly contentType: string;
+    /** Raw data (decoded from base64 for binary, or UTF-8 encoded XML). */
+    readonly data: Uint8Array;
+}
+/**
+ * Parse a Flat OPC XML document into individual package parts.
+ * Returns a Map keyed by part path (without leading slash) to binary data,
+ * compatible with the archive entry format used by `readDocx`.
+ *
+ * @param xmlContent - The Flat OPC XML string or UTF-8 bytes.
+ * @returns A map of part paths to their binary content.
+ */
+export declare function parseFlatOpc(xmlContent: string | Uint8Array): Map<string, Uint8Array>;
+/**
+ * Check if content appears to be a Flat OPC XML document.
+ */
+export declare function isFlatOpc(content: string | Uint8Array): boolean;
+/**
+ * Convert a ZIP archive's entries (as a map of path → data) to Flat OPC XML string.
+ *
+ * @param entries - Map of part paths to their binary content.
+ * @param contentTypes - Map of part paths to content types (from [Content_Types].xml).
+ * @returns The Flat OPC XML string.
+ */
+export declare function toFlatOpc(entries: Map<string, Uint8Array>, contentTypes?: Map<string, string>): string;

package/dist/types/modules/word/convert/html/html-import.d.ts

@@ -0,0 +1,50 @@
+/**
+ * DOCX Module - HTML to DOCX Converter
+ *
+ * Converts an HTML string into DOCX document body content (paragraphs, tables, etc.).
+ * Handles common HTML elements: p, h1-h6, strong, em, a, ul, ol, li, table, img, br, span.
+ *
+ * This is NOT a full HTML rendering engine — it covers the structural elements
+ * that map cleanly to WordprocessingML concepts.
+ *
+ * @example
+ * ```ts
+ * import { htmlToDocxBody } from "excelts/word/html";
+ * import { Document, toBuffer } from "excelts/word";
+ *
+ * const body = htmlToDocxBody("<h1>Hello</h1><p>World</p>");
+ * const h = Document.create();
+ * for (const block of body) {
+ *   Document.addBodyContent(h, block);
+ * }
+ * const buffer = await toBuffer(Document.build(h));
+ * ```
+ */
+import type { BodyContent } from "../../types.js";
+/** Options for HTML to DOCX conversion. */
+export interface HtmlImportOptions {
+    /** Default font size in half-points (default: 24 = 12pt). */
+    readonly defaultFontSize?: number;
+    /** Default font family. */
+    readonly defaultFont?: string;
+    /** Map of CSS class names to inline style strings. Matched classes are merged with element styles. */
+    readonly classStyles?: Record<string, string>;
+}
+/**
+ * Convert an HTML string into an array of DOCX body content blocks.
+ *
+ * Supported elements:
+ * - Block: p, div, h1-h6, blockquote, pre, hr
+ * - List: ul, ol, li
+ * - Table: table, thead, tbody, tr, th, td (colspan, rowspan, border styles)
+ * - Inline: strong/b, em/i, u, s/strike/del, a, br, span, sub, sup, code
+ * - Images: img (base64 data URLs as InlineImageContent, http(s) as placeholder)
+ * - Page break: div with style="page-break-before: always" or class="page-break"
+ * - CSS inline styles: font-family, font-size, color, background-color, font-weight,
+ *   font-style, text-decoration, text-align
+ *
+ * @param html - The HTML string to convert.
+ * @param options - Optional conversion settings.
+ * @returns Array of BodyContent blocks.
+ */
+export declare function htmlToDocxBody(html: string, options?: HtmlImportOptions): BodyContent[];

package/dist/{browser/modules/word → types/modules/word/convert/html}/html-renderer.d.ts

@@ -5,7 +5,7 @@
  * Supports paragraphs, runs with formatting, tables, lists, images, hyperlinks,
  * headings, comments, footnotes/endnotes, and more.
  */
-import type { DocxDocument } from "./types.js";
+import type { DocxDocument, Chart, ChartExContent } from "../../types.js";
 /** Options for HTML rendering. */
 export interface HtmlRenderOptions {
     /** Include CSS inline in a <style> tag. Default: true. */
@@ -18,10 +18,23 @@ export interface HtmlRenderOptions {
     readonly imageMode?: "dataUrl" | "filename" | "none";
     /** Convert comments to HTML. Default: false. */
     readonly includeComments?: boolean;
+    /** Render revision marks (insertions/deletions) as <ins>/<del>. Default: false. */
+    readonly includeRevisions?: boolean;
     /** Render footnotes/endnotes as anchored references. Default: true. */
     readonly includeNotes?: boolean;
     /** Custom CSS class prefix (default: "docx-"). */
     readonly classPrefix?: string;
+    /**
+     * Style map: Word style name → HTML tag/class mapping.
+     * Values use the format "tag.className" (e.g. "h1.doc-heading", "blockquote.quote").
+     * If only a tag is provided (no dot), no class is added.
+     * If only a class is provided (starts with "."), the default tag is used with that class.
+     */
+    readonly styleMap?: ReadonlyMap<string, string> | Record<string, string>;
+    /** Optional chart renderer callback. When provided, charts are rendered as inline SVG. */
+    readonly chartRenderer?: (chart: Chart) => string;
+    /** Optional ChartEx renderer callback. When provided, chartEx blocks are rendered as inline SVG. */
+    readonly chartExRenderer?: (chartEx: ChartExContent) => string;
 }
 /** The result of HTML rendering. */
 export interface HtmlRenderResult {

package/dist/types/modules/word/convert/html/html.d.ts

@@ -0,0 +1,15 @@
+/**
+ * DOCX Module - HTML Converters (Subpath Export)
+ *
+ * Import separately to avoid pulling converter code into the bundle
+ * when only core document building is needed.
+ *
+ * @example
+ * ```ts
+ * import { renderToHtml, htmlToDocxBody } from "excelts/word/html";
+ * ```
+ */
+export { renderToHtml } from "./html-renderer.js";
+export type { HtmlRenderOptions, HtmlRenderResult } from "./html-renderer.js";
+export { htmlToDocxBody } from "./html-import.js";
+export type { HtmlImportOptions } from "./html-import.js";

package/dist/types/modules/word/convert/markdown/markdown-import.d.ts

@@ -0,0 +1,68 @@
+/**
+ * DOCX Module - Markdown to DOCX Converter
+ *
+ * Converts a GFM (GitHub Flavored Markdown) string into DOCX document body content.
+ * Handles common Markdown elements: headings, paragraphs, bold, italic, strikethrough,
+ * code, links, images, lists, tables, blockquotes, horizontal rules, and fenced code blocks.
+ *
+ * @example
+ * ```ts
+ * import { markdownToDocx } from "excelts/word/markdown";
+ * import { Document, toBuffer } from "excelts/word";
+ *
+ * const doc = markdownToDocx("# Hello\n\nWorld **bold**");
+ * const buffer = await toBuffer(doc);
+ * ```
+ *
+ * @stability experimental
+ */
+import type { BodyContent, DocxDocument } from "../../types.js";
+/** Options for Markdown to DOCX conversion. */
+export interface MarkdownImportOptions {
+    /** Default font family for body text. */
+    readonly defaultFont?: string;
+    /** Default font size in half-points (default: 24 = 12pt). */
+    readonly defaultFontSize?: number;
+    /** Code font family (default: "Courier New"). */
+    readonly codeFont?: string;
+    /** Code font size in half-points (default: 20 = 10pt). */
+    readonly codeFontSize?: number;
+    /** Custom image resolver — given a URL, return image data or undefined to skip. */
+    readonly resolveImage?: (url: string, alt: string) => MarkdownImageData | undefined | Promise<MarkdownImageData | undefined>;
+}
+/** Resolved image data for embedding. */
+export interface MarkdownImageData {
+    readonly data: Uint8Array;
+    readonly mediaType: "png" | "jpeg" | "gif" | "bmp" | "tiff" | "svg" | "webp";
+    readonly width?: number;
+    readonly height?: number;
+}
+/**
+ * Convert a Markdown string into a complete DocxDocument.
+ *
+ * @param markdown - The GFM Markdown string.
+ * @param options - Optional conversion settings.
+ * @returns A DocxDocument ready to be packaged.
+ */
+export declare function markdownToDocx(markdown: string, options?: MarkdownImportOptions): DocxDocument;
+/**
+ * Convert a Markdown string into an array of DOCX body content blocks.
+ *
+ * **Caveat — body content is not self-contained.**
+ *   - **Lists** (bullet / numbered / task) reference numbering ids that
+ *     live in document-level `abstractNumberings` + `numberingInstances`,
+ *     which this helper does NOT return.
+ *   - **Block quotes** reference the named `Quote` style.
+ *   - **Code blocks** reference the named code styles.
+ *
+ * Splicing markdown that uses any of these constructs into a document that
+ * lacks the matching numbering / styles yields invalid OOXML. Either keep
+ * the input flat (paragraphs + headings + inline formatting) before
+ * splicing, or use the higher-level {@link markdownToDocx} which returns a
+ * complete `DocxDocument` with the supporting definitions populated.
+ *
+ * @param markdown - The GFM Markdown string.
+ * @param options - Optional conversion settings.
+ * @returns Array of BodyContent blocks (no numbering / styles attached).
+ */
+export declare function markdownToDocxBody(markdown: string, options?: MarkdownImportOptions): BodyContent[];

package/dist/types/modules/word/convert/markdown/markdown-renderer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * DOCX Module - Markdown Renderer
+ *
+ * Converts a DocxDocument model to a GFM-compatible Markdown string.
+ * Supports headings, inline formatting, tables, lists, images, hyperlinks,
+ * footnotes, code spans, horizontal rules, and more.
+ */
+import type { DocxDocument } from "../../types.js";
+/** Options for Markdown rendering. */
+export interface MarkdownRenderOptions {
+    /** Include images as ![alt](filename). Default: true. */
+    readonly includeImages?: boolean;
+    /** Include footnotes as [^N]. Default: true. */
+    readonly includeNotes?: boolean;
+    /** Heading style: "atx" (# style) or "setext" (underline style). Default: "atx". */
+    readonly headingStyle?: "atx" | "setext";
+}
+/**
+ * Convert a DocxDocument to a GFM-compatible Markdown string.
+ *
+ * @param doc - The document model to convert.
+ * @param options - Optional rendering settings.
+ * @returns Markdown string.
+ */
+export declare function renderToMarkdown(doc: DocxDocument, options?: MarkdownRenderOptions): string;

package/dist/types/modules/word/convert/markdown/markdown.d.ts

@@ -0,0 +1,15 @@
+/**
+ * DOCX Module - Markdown Converters (Subpath Export)
+ *
+ * Import separately to avoid pulling renderer code into the bundle
+ * when only core document building is needed.
+ *
+ * @example
+ * ```ts
+ * import { renderToMarkdown, markdownToDocx, markdownToDocxBody } from "excelts/word/markdown";
+ * ```
+ */
+export { renderToMarkdown } from "./markdown-renderer.js";
+export type { MarkdownRenderOptions } from "./markdown-renderer.js";
+export { markdownToDocx, markdownToDocxBody } from "./markdown-import.js";
+export type { MarkdownImportOptions, MarkdownImageData } from "./markdown-import.js";

package/dist/types/modules/word/convert/odt/odt.d.ts

@@ -0,0 +1,41 @@
+/**
+ * DOCX Module - OpenDocument Text (ODT) Format Support
+ *
+ * Implements reading and writing of ODT (OpenDocument Text) files.
+ * ODT files are ZIP archives containing XML content in ODF namespaces.
+ *
+ * Main archive structure:
+ * - content.xml — document body and automatic styles
+ * - styles.xml — named styles, page layout, master pages
+ * - meta.xml — document metadata
+ * - META-INF/manifest.xml — manifest of all archive entries
+ * - Pictures/ — embedded images
+ *
+ * @stability experimental
+ */
+import type { DocxDocument } from "../../types.js";
+/**
+ * Read an ODT file and convert to DocxDocument model.
+ *
+ * Extracts the ZIP archive, parses content.xml, styles.xml, and meta.xml,
+ * and produces a unified DocxDocument representation.
+ *
+ * @param buffer - The ODT file as a Uint8Array.
+ * @returns A DocxDocument representing the ODT content.
+ * @throws {DocxParseError} If the ODT file is malformed or missing required parts.
+ *
+ * @stability experimental
+ */
+export declare function readOdt(buffer: Uint8Array): Promise<DocxDocument>;
+/**
+ * Convert a DocxDocument to ODT (OpenDocument Text) format.
+ *
+ * Generates the ZIP archive structure with content.xml, styles.xml,
+ * meta.xml, and META-INF/manifest.xml.
+ *
+ * @param doc - The DocxDocument to convert.
+ * @returns A Uint8Array containing the ODT ZIP archive.
+ *
+ * @stability experimental
+ */
+export declare function writeOdt(doc: DocxDocument): Promise<Uint8Array>;

package/dist/types/modules/word/{color-utils.d.ts → core/color-utils.d.ts}

@@ -4,8 +4,15 @@
  * Resolves OOXML theme colors with tint/shade transformations.
  * Extracted to a standalone file so that html-renderer and document.ts
  * can both import it without creating circular heavy dependencies.
+ *
+ * Core tint/shade/resolve logic lives in @utils/theme-colors; this module
+ * re-exports and adapts it for Word's ColorSpec / DocumentTheme types.
  */
-import type { DocumentTheme, ColorSpec, HexColor } from "./types.js";
+import { applyTint, applyShade, THEME_COLOR_ATTRIBUTE_MAP } from "../../../utils/theme-colors.js";
+import type { OoxmlThemeColorName } from "../../../utils/theme-colors.js";
+import type { DocumentTheme, ColorSpec, HexColor } from "../types.js";
+export { applyTint, applyShade, THEME_COLOR_ATTRIBUTE_MAP };
+export type { OoxmlThemeColorName };
 /**
  * Resolve a ColorSpec to an actual hex RGB color using the document theme.
  *

package/dist/types/modules/word/core/internal-utils.d.ts

@@ -0,0 +1,90 @@
+/**
+ * DOCX Module - Internal Utilities (unified shared helpers)
+ *
+ * This is the single source of truth for cross-cutting low-level utilities
+ * used throughout the word module. Consolidates previously duplicated
+ * implementations of base64, UUID, UTF-16LE encoding, and XML helpers.
+ */
+/**
+ * Shared `TextEncoder` instance for UTF-8 encoding. Reusing this avoids the
+ * cost of constructing a fresh encoder on every call site (each `new
+ * TextEncoder()` allocates a small native object).
+ */
+export declare const utf8Encoder: TextEncoder;
+/**
+ * Shared `TextDecoder` instance for UTF-8 decoding. Stateless — safe to share
+ * across modules. Use this instead of `new TextDecoder("utf-8")`.
+ */
+export declare const utf8Decoder: TextDecoder;
+/**
+ * Encode a byte array to base64. Uses native Node `Buffer` if available;
+ * otherwise falls back to chunked `btoa()` for browser environments.
+ *
+ * The chunked approach avoids the O(n²) string concatenation cost that naïve
+ * `String.fromCharCode(...data)` implementations exhibit on large buffers.
+ */
+export declare function bytesToBase64(data: Uint8Array): string;
+/**
+ * Decode a base64 string to a byte array. Uses native Node `Buffer` if available.
+ */
+export declare function base64ToBytes(s: string): Uint8Array;
+/**
+ * Generate a GUID in braced format: "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}".
+ * Used by font obfuscation (w:fontKey) and building blocks.
+ */
+export declare function generateGuid(): string;
+/**
+ * Encode a string as UTF-16LE bytes.
+ * Required by ECMA-376 password hashing and OLE operations.
+ */
+export declare function stringToUtf16LE(str: string): Uint8Array;
+/**
+ * Generate cryptographically secure random bytes.
+ * Throws `DocxError` if `crypto.getRandomValues` is unavailable on the host.
+ */
+export declare function randomBytes(length: number): Uint8Array;
+/**
+ * Make all properties of T mutable (remove readonly).
+ * Used in mutation APIs (acceptAllRevisions, replaceText, etc.) that operate
+ * on document models in-place. Preferred over `as any` casts.
+ */
+export type Mutable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+/**
+ * Deep mutable version — recursively removes readonly from nested objects.
+ */
+export type DeepMutable<T> = {
+    -readonly [P in keyof T]: T[P] extends ReadonlyArray<infer U> ? Array<DeepMutable<U>> : T[P] extends ReadonlyMap<infer K, infer V> ? Map<K, DeepMutable<V>> : T[P] extends object ? DeepMutable<T[P]> : T[P];
+};
+/**
+ * Validate and normalize a URL for use in a hyperlink. Returns a safe URL
+ * string, or `undefined` if the input is unsafe.
+ *
+ * Rules:
+ * - Empty/whitespace input → `undefined`.
+ * - Fragment-only (`#anchor`) and protocol-relative (`//host`) URLs → kept.
+ * - Relative URLs without a scheme → kept (no host injection possible since
+ *   they resolve against the document base).
+ * - URLs with a scheme are accepted only if the scheme is in
+ *   {@link SAFE_URL_SCHEMES}.
+ * - Surrounding whitespace and control characters that browsers historically
+ *   strip when parsing URLs are removed before scheme detection so attackers
+ *   can't bypass the check with `"  java\tscript:..."`.
+ */
+export declare function sanitizeUrl(url: string | undefined | null): string | undefined;
+/**
+ * Strip path-traversal segments and other unsafe characters from a
+ * caller-supplied media file name so it can be used as a leaf entry
+ * inside an OPC ZIP package without enabling zipslip.
+ *
+ * The previous behaviour was to forward `image.fileName` /
+ * `font.fileName` straight into `archive.add`, which let a hostile DOCX
+ * round-tripped through `readDocx` write entries like
+ * `word/media/../../etc/passwd.png` into the output package — a real
+ * attack vector when the file is later unpacked by a third-party tool.
+ *
+ * Returns a single safe leaf name. Falls back to `fallback` (default
+ * `"file.bin"`) when the cleaned name would be empty.
+ */
+export declare function sanitizeMediaFileName(raw: string | undefined, fallback?: string): string;

package/dist/types/modules/word/core/mapper.d.ts

@@ -0,0 +1,44 @@
+/**
+ * DOCX Module - Immutable Document Mapper
+ *
+ * Provides `mapDocument()` and the `DocxTransformer` interface for rebuilding
+ * a document tree with transformations applied to specific node types.
+ *
+ * Unlike the read-only `walkDocument()` (in walker.ts), this mapper produces
+ * a new document without mutating the input.
+ */
+import type { BodyContent, DocxDocument, Paragraph, Run, RunContent, StructuredDocumentTag, Table } from "../types.js";
+import type { WalkPath } from "./walker.js";
+/**
+ * Transformer interface for immutable document tree rebuilding.
+ * Return the node to keep/replace it, or null to remove it.
+ * For flatMapBodyContent, return an array to expand one node into multiple.
+ */
+export interface DocxTransformer {
+    transformParagraph?(para: Paragraph, path: WalkPath): Paragraph | null;
+    transformRun?(run: Run, path: WalkPath): Run | null;
+    transformTable?(table: Table, path: WalkPath): Table | null;
+    transformSdt?(sdt: StructuredDocumentTag, path: WalkPath): StructuredDocumentTag | null;
+    transformRunContent?(content: RunContent, run: Run, path: WalkPath): RunContent | null;
+    /** Transform a body content item. Return null to remove, a single item to replace, or an array to expand. */
+    transformBodyContent?(content: BodyContent, path: WalkPath): BodyContent | BodyContent[] | null;
+}
+/** Options controlling which parts of the document to map. */
+export interface MapOptions {
+    readonly includeHeaders?: boolean;
+    readonly includeFooters?: boolean;
+    readonly includeFootnotes?: boolean;
+    readonly includeEndnotes?: boolean;
+    readonly includeComments?: boolean;
+}
+/**
+ * Immutable document tree transformation.
+ * Rebuilds the document tree, allowing callers to replace or filter nodes.
+ * Never mutates the input document.
+ *
+ * @param doc - The document to transform.
+ * @param transformer - Callbacks to transform each node type.
+ * @param options - Controls which document parts to include.
+ * @returns A new DocxDocument with transformations applied.
+ */
+export declare function mapDocument(doc: DocxDocument, transformer: DocxTransformer, options?: MapOptions): DocxDocument;

package/dist/types/modules/word/core/opc-paths.d.ts

@@ -0,0 +1,33 @@
+/**
+ * OPC Path Utilities
+ *
+ * Small helpers for working with Open Packaging Conventions part paths.
+ * These are used throughout the reader/writer when resolving the location of
+ * a relationships file or extracting an extension to choose a content type.
+ */
+/**
+ * Get the `.rels` part path for a given part path.
+ *
+ * Per OPC convention, the relationships for `dir/name.ext` live at
+ * `dir/_rels/name.ext.rels`; for a top-level `name.ext` they live at
+ * `_rels/name.ext.rels`.
+ */
+export declare function getPartRelsPath(partPath: string): string;
+/**
+ * Extract the file name (last path segment) from a part path.
+ *
+ * @example
+ * getFileName("word/media/image1.png")  // "image1.png"
+ * getFileName("standalone.xml")         // "standalone.xml"
+ */
+export declare function getFileName(partPath: string): string;
+/**
+ * Extract the lower-cased file extension (without the dot) from a part path
+ * or file name. Returns an empty string when there is no extension.
+ *
+ * @example
+ * getFileExt("image1.PNG")        // "png"
+ * getFileExt("word/media/x.tiff") // "tiff"
+ * getFileExt("noext")             // ""
+ */
+export declare function getFileExt(partPath: string): string;

package/dist/types/modules/word/core/text-utils.d.ts

@@ -0,0 +1,38 @@
+/**
+ * DOCX Module - Text Utilities & Type Guards
+ *
+ * Single source of truth for type guards and text extraction helpers
+ * used across the word module. Eliminates duplicated implementations
+ * of `isRun`, `extractParagraphText`, `extractMathText`, etc.
+ */
+import type { Paragraph, ParagraphChild, Run, MathContent, Hyperlink } from "../types.js";
+/**
+ * Check if a paragraph child is a Run.
+ *
+ * A Run is the only ParagraphChild without a `type` discriminator field.
+ * All other paragraph children (Hyperlink, InsertedRun, DeletedRun, MovedFromRun,
+ * MovedToRun, BookmarkStart/End, CommentRangeStart/End) have an explicit `type`
+ * string. Therefore, a child is a Run iff it has a `content` array AND no `type`
+ * field — this is more robust than checking `content` alone (since some typed
+ * children also have `content`-like properties).
+ */
+export declare function isRun(child: ParagraphChild): child is Run;
+/** Check if a paragraph child is a Hyperlink. */
+export declare function isHyperlink(child: ParagraphChild): child is Hyperlink;
+/**
+ * Extract plain text from a single run's content array.
+ */
+export declare function extractRunText(run: Run): string;
+/**
+ * Extract concatenated plain text from a paragraph's children (runs + hyperlinks).
+ * This recursively handles hyperlinks and tracked changes.
+ */
+export declare function extractParagraphText(para: Paragraph): string;
+/**
+ * Extract text from a single paragraph child (run, hyperlink, or tracked change).
+ */
+export declare function extractChildText(child: ParagraphChild): string;
+/**
+ * Extract plain text representation from math content elements.
+ */
+export declare function extractMathText(content: readonly MathContent[]): string;