@cj-tech-master/excelts 9.5.4 → 9.5.5

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

@@ -0,0 +1,119 @@
+/**
+ * DOCX Module - Document Walker (Visitor Pattern)
+ *
+ * Unified traversal engine for the DocxDocument model. Provides a single,
+ * tested implementation of document tree walking that all consumers
+ * (renderers, validators, field engines, template engines, etc.) can use
+ * instead of each implementing their own recursive traversal.
+ *
+ * Design principles:
+ * - Visitor receives enter/leave callbacks for structural elements
+ * - Return "skip" to prune subtrees, "stop" to abort early
+ * - WalkPath provides full context (location, nesting depth, container)
+ * - Options control which parts of the document are visited
+ */
+import type { DocxDocument, BodyContent, Paragraph, Run, RunContent, Table, TableRow, TableCell, MathBlock, MathContent, StructuredDocumentTag, Hyperlink, InsertedRun, DeletedRun, MovedFromRun, MovedToRun, FloatingImage, BookmarkStart, CommentRangeStart, CommentRangeEnd, TextBox, TableOfContents, AltChunk, ChartContent, ChartExContent, CheckBox, DrawingShape, OpaqueDrawing } from "../types.js";
+/** Action returned by visitor callbacks to control traversal. */
+export type VisitAction = "continue" | "skip" | "stop";
+/** Location context passed to visitor callbacks. */
+export interface WalkPath {
+    /** Current section index (0-based). */
+    readonly section: number;
+    /** Nesting depth (0 = top-level body content). */
+    readonly depth: number;
+    /** Whether currently inside a header. */
+    readonly inHeader: boolean;
+    /** Whether currently inside a footer. */
+    readonly inFooter: boolean;
+    /** Whether currently inside a footnote. */
+    readonly inFootnote: boolean;
+    /** Whether currently inside an endnote. */
+    readonly inEndnote: boolean;
+    /** Whether currently inside a comment. */
+    readonly inComment: boolean;
+    /** Index within the parent container. */
+    readonly index: number;
+}
+/** Options controlling which parts of the document to walk. */
+export interface WalkOptions {
+    /** Walk header content. Default: true. */
+    readonly includeHeaders?: boolean;
+    /** Walk footer content. Default: true. */
+    readonly includeFooters?: boolean;
+    /** Walk footnote content. Default: true. */
+    readonly includeFootnotes?: boolean;
+    /** Walk endnote content. Default: true. */
+    readonly includeEndnotes?: boolean;
+    /** Walk comment content. Default: false. */
+    readonly includeComments?: boolean;
+}
+/**
+ * Visitor interface for document traversal.
+ * All methods are optional — implement only what you need.
+ */
+export interface DocxVisitor {
+    enterParagraph?(para: Paragraph, path: WalkPath): VisitAction | void;
+    leaveParagraph?(para: Paragraph, path: WalkPath): void;
+    enterTable?(table: Table, path: WalkPath): VisitAction | void;
+    leaveTable?(table: Table, path: WalkPath): void;
+    enterTableRow?(row: TableRow, path: WalkPath): VisitAction | void;
+    leaveTableRow?(row: TableRow, path: WalkPath): void;
+    enterTableCell?(cell: TableCell, path: WalkPath): VisitAction | void;
+    leaveTableCell?(cell: TableCell, path: WalkPath): void;
+    enterSdt?(sdt: StructuredDocumentTag, path: WalkPath): VisitAction | void;
+    leaveSdt?(sdt: StructuredDocumentTag, path: WalkPath): void;
+    enterMathBlock?(math: MathBlock, path: WalkPath): VisitAction | void;
+    leaveMathBlock?(math: MathBlock, path: WalkPath): void;
+    visitFloatingImage?(image: FloatingImage, path: WalkPath): void;
+    visitTextBox?(textBox: TextBox, path: WalkPath): VisitAction | void;
+    visitTableOfContents?(toc: TableOfContents, path: WalkPath): void;
+    visitAltChunk?(chunk: AltChunk, path: WalkPath): void;
+    visitChart?(chart: ChartContent, path: WalkPath): void;
+    visitChartEx?(chart: ChartExContent, path: WalkPath): void;
+    visitCheckBox?(checkBox: CheckBox, path: WalkPath): void;
+    visitDrawingShape?(shape: DrawingShape, path: WalkPath): void;
+    visitOpaqueDrawing?(drawing: OpaqueDrawing, path: WalkPath): void;
+    enterRun?(run: Run, path: WalkPath): VisitAction | void;
+    leaveRun?(run: Run, path: WalkPath): void;
+    enterHyperlink?(hyperlink: Hyperlink, path: WalkPath): VisitAction | void;
+    leaveHyperlink?(hyperlink: Hyperlink, path: WalkPath): void;
+    visitInsertedRun?(inserted: InsertedRun, path: WalkPath): VisitAction | void;
+    visitDeletedRun?(deleted: DeletedRun, path: WalkPath): void;
+    visitMovedFromRun?(moved: MovedFromRun, path: WalkPath): void;
+    visitMovedToRun?(moved: MovedToRun, path: WalkPath): VisitAction | void;
+    visitBookmarkStart?(bookmark: BookmarkStart, path: WalkPath): void;
+    visitBookmarkEnd?(id: number, path: WalkPath): void;
+    visitCommentRangeStart?(comment: CommentRangeStart, path: WalkPath): void;
+    visitCommentRangeEnd?(comment: CommentRangeEnd, path: WalkPath): void;
+    visitRunContent?(content: RunContent, run: Run, path: WalkPath): void;
+    visitMathContent?(content: MathContent, path: WalkPath): void;
+}
+/**
+ * Walk an entire DocxDocument, calling visitor methods for each element.
+ *
+ * @param doc - The document to walk.
+ * @param visitor - Visitor with callbacks for elements of interest.
+ * @param options - Controls which document parts to include.
+ */
+export declare function walkDocument(doc: DocxDocument, visitor: DocxVisitor, options?: WalkOptions): void;
+/**
+ * Walk a list of body content blocks (useful for walking sub-documents).
+ *
+ * @param blocks - Body content array to walk.
+ * @param visitor - Visitor with callbacks.
+ * @param basePath - Optional initial path context.
+ * @returns "stop" if traversal was aborted, "continue" otherwise.
+ */
+export declare function walkBlocks(blocks: readonly BodyContent[], visitor: DocxVisitor, basePath?: WalkPath): "stop" | "continue";
+/**
+ * Collect all paragraphs from a document (including nested in tables/SDTs).
+ */
+export declare function collectParagraphs(doc: DocxDocument, options?: WalkOptions): Paragraph[];
+/**
+ * Collect all runs from a document (including nested).
+ */
+export declare function collectRuns(doc: DocxDocument, options?: WalkOptions): Run[];
+/**
+ * Collect all tables from a document (including nested).
+ */
+export declare function collectTables(doc: DocxDocument, options?: WalkOptions): Table[];

package/dist/types/modules/word/crypto.d.ts

@@ -1,17 +1,22 @@
 /**
- * DOCX Module - Encryption & Digital Signatures (Subpath Export)
+ * DOCX Module - Encryption & Digital Signatures (Subpath Entry)
  *
- * Import separately to avoid pulling crypto code into the bundle
- * when only core document building is needed.
+ * Public API at `excelts/word/crypto`. Referenced by
+ * `package.json#exports["./word/crypto"]`. Import this subpath separately to
+ * keep encryption / CFB / signature / font obfuscation code out of bundles
+ * that only need core document building.
  *
  * @example
  * ```ts
- * import { isEncryptedDocx, decryptPackage } from "excelts/word/crypto";
+ * import { isEncryptedDocx, decryptDocx, encryptDocx } from "excelts/word/crypto";
  * import { extractSignatures } from "excelts/word/crypto";
  * ```
  */
-export { isEncryptedDocx, verifyPassword, decryptPackage, parseEncryptionInfoXml, deriveEncryptionKey, AGILE_BLOCK_KEYS } from "./encryption.js";
-export type { AgileEncryptionInfo } from "./encryption.js";
-export { hasDigitalSignatures, parseSignatureXml, extractSignatures, isWellFormedSignature } from "./digital-signatures.js";
-export type { DigitalSignatureInfo } from "./digital-signatures.js";
-export { deobfuscateFont, obfuscateFont, generateFontKey } from "./font-obfuscation.js";
+export { isEncryptedDocx, verifyPassword, decryptPackage, decryptDocx, encryptDocx, parseEncryptionInfoXml, deriveEncryptionKey, AGILE_BLOCK_KEYS } from "./security/encryption.js";
+export type { AgileEncryptionInfo, EncryptOptions } from "./security/encryption.js";
+export { DocxEncryptedError } from "./errors.js";
+export { readCfb, writeCfb } from "./security/cfb-reader.js";
+export type { CfbEntry } from "./security/cfb-reader.js";
+export { hasDigitalSignatures, parseSignatureXml, extractSignatures, isWellFormedSignature } from "./security/digital-signatures.js";
+export type { DigitalSignatureInfo } from "./security/digital-signatures.js";
+export { deobfuscateFont, obfuscateFont, generateFontKey } from "./font/font-obfuscation.js";

package/dist/types/modules/word/document-io.d.ts

@@ -1,43 +1,49 @@
 /**
  * DOCX Module - Document IO
  *
- * IO operations that depend on docx-packager and docx-reader.
- * Separated from document.ts so that builder helpers can be imported
- * without pulling in archive/xml/writer code.
+ * IO operations: package/unpackage to bytes, base64, Flat OPC,
+ * plus the public Patch and Template APIs that combine read/patch/write.
  */
-import type { DocxDocument, Paragraph, Table, ImageDef } from "./types.js";
+import { type PatchOperation } from "./patcher.js";
+import type { TemplateOptions } from "./template/template-engine.js";
+import type { DocxDocument } from "./types.js";
+export type { PatchContent, PatchOperation } from "./patcher.js";
 /** Package a DocxDocument model to DOCX bytes. */
 export declare function toBuffer(doc: DocxDocument, compressionLevel?: number): Promise<Uint8Array>;
 /** Package a DocxDocument model to base64 string. */
 export declare function toBase64(doc: DocxDocument, compressionLevel?: number): Promise<string>;
-/** Type of content to patch into a placeholder. */
-export type PatchContent = {
-    readonly type: "text";
-    readonly text: string;
-} | {
-    readonly type: "paragraph";
-    readonly children: readonly Paragraph[];
-} | {
-    readonly type: "table";
-    readonly table: Table;
-} | {
-    readonly type: "image";
-    readonly image: ImageDef;
-    readonly width: number;
-    readonly height: number;
-};
-/** A single patch operation mapping a placeholder to replacement content. */
-export interface PatchOperation {
-    /** Placeholder string to find (e.g. "{{name}}"). */
-    readonly placeholder: string;
-    /** Content to replace the placeholder with. */
-    readonly content: PatchContent;
-}
 /** Options for patchDocument. */
 export interface PatchOptions {
     /** Compression level (0-9). Default: 6. */
     readonly compressionLevel?: number;
 }
+/** A compiled template that can be reused for multiple patch operations. */
+export interface CompiledTemplate {
+    /** The parsed document model (internal use only). */
+    readonly _doc: DocxDocument;
+}
+/**
+ * Compile a DOCX template for reuse with multiple data sets.
+ *
+ * Parsing the ZIP and XML is expensive. If you need to patch the same template
+ * multiple times with different data, compile it once and reuse.
+ *
+ * @param buffer - The source DOCX template file as a Uint8Array.
+ * @returns A compiled template handle.
+ */
+export declare function compileTemplate(buffer: Uint8Array): Promise<CompiledTemplate>;
+/**
+ * Apply patches to a pre-compiled template.
+ *
+ * Much faster than `patchDocument` when applying to the same template repeatedly,
+ * since ZIP/XML parsing is skipped.
+ *
+ * @param template - A compiled template from `compileTemplate`.
+ * @param patches - Array of patch operations to apply.
+ * @param options - Optional compression settings.
+ * @returns New DOCX file as a Uint8Array.
+ */
+export declare function patchTemplate(template: CompiledTemplate, patches: readonly PatchOperation[], options?: PatchOptions): Promise<Uint8Array>;
 /**
  * Read an existing DOCX file, replace placeholders with content, and produce a new DOCX.
  *
@@ -56,3 +62,29 @@ export interface PatchOptions {
  * @returns New DOCX file as a Uint8Array.
  */
 export declare function patchDocument(buffer: Uint8Array, patches: readonly PatchOperation[], options?: PatchOptions): Promise<Uint8Array>;
+/**
+ * Read a DOCX buffer, fill template placeholders with data, and produce a new DOCX.
+ *
+ * This is a convenience wrapper combining readDocx + fillTemplate + packageDocx.
+ *
+ * @param buffer - The source DOCX template file as a Uint8Array.
+ * @param data - Data object to fill into the template placeholders.
+ * @param options - Template and compression options.
+ * @returns New DOCX file as a Uint8Array.
+ */
+export declare function fillTemplateFromBuffer(buffer: Uint8Array, data: Record<string, unknown>, options?: TemplateOptions & {
+    readonly compressionLevel?: number;
+}): Promise<Uint8Array>;
+/**
+ * Package a DocxDocument model into Flat OPC XML format.
+ *
+ * This packages the document to a ZIP, then re-reads the entries to wrap
+ * them as Flat OPC XML. While this involves a ZIP round-trip, it ensures
+ * the Flat OPC output is byte-identical to what `packageDocx` would produce
+ * (same XML serialization, same relationships, same content types).
+ *
+ * @param doc - The document model.
+ * @param compressionLevel - Optional compression level (0 = no compression, faster for Flat OPC).
+ * @returns The Flat OPC XML string.
+ */
+export declare function toFlatOpcFromDoc(doc: DocxDocument, compressionLevel?: number): Promise<string>;

package/dist/types/modules/word/errors.d.ts

@@ -4,7 +4,6 @@
  * All DOCX-related errors extend DocxError.
  */
 import { BaseError, type BaseErrorOptions } from "../../utils/errors.js";
-export { AbortError, createAbortError, isAbortError, throwIfAborted, createLinkedAbortController, toError, suppressUnhandledRejection, errorToJSON, getErrorChain, getRootCause, type BaseErrorOptions } from "../../utils/errors.js";
 /**
  * Base class for all DOCX-related errors.
  */
@@ -47,3 +46,47 @@ export declare class DocxUnsupportedFeatureError extends DocxError {
     name: string;
     constructor(feature: string);
 }
+/**
+ * Error thrown when a DOCX file is encrypted (CFB format) and no password
+ * was provided. Pass `{ password }` in the second argument of `readDocx()`
+ * to decrypt automatically, or call `decryptDocx()` from "excelts/word/crypto"
+ * directly if you need lower-level access to the decrypted ZIP bytes.
+ */
+export declare class DocxEncryptedError extends DocxError {
+    name: string;
+    constructor();
+}
+/**
+ * Error thrown when an encrypted DOCX cannot be decrypted with the provided
+ * password (wrong password) or when the encryption metadata is malformed.
+ */
+export declare class DocxDecryptionError extends DocxError {
+    name: string;
+}
+/**
+ * Error thrown when an input package exceeds a declared resource limit (e.g.
+ * total package size, single part size, number of parts). Used to defend
+ * against ZIP bombs and runaway memory usage.
+ */
+export declare class DocxLimitExceededError extends DocxParseError {
+    name: string;
+    /** Limit category that was exceeded. */
+    readonly limit: "packageSize" | "partSize" | "partCount";
+    /** Configured maximum. */
+    readonly maximum: number;
+    /** Actual measured value (or the value that would have been reached). */
+    readonly actual: number;
+    constructor(limit: "packageSize" | "partSize" | "partCount", maximum: number, actual: number, detail?: string);
+}
+/**
+ * Error thrown when the active `WordSecurityPolicy.rawXmlPolicy` is `"reject"`
+ * and the writer encounters opaque/preserved rawXml that would otherwise have
+ * been emitted verbatim. Callers can either drop the offending model field
+ * before serialisation or relax the policy to `"strip"` / `"preserve"`.
+ */
+export declare class DocxRawXmlPolicyError extends DocxWriteError {
+    name: string;
+    /** Short label identifying the offending writer site. */
+    readonly site: string;
+    constructor(site: string);
+}

package/dist/types/modules/word/excel.d.ts

@@ -0,0 +1,14 @@
+/**
+ * DOCX Module - Excel Bridge (Subpath Entry)
+ *
+ * Re-exports the Excel bridge API at `excelts/word/excel`. This file is
+ * referenced by `package.json#exports["./word/excel"]`; it forwards to the
+ * implementation under `./bridge/excel-bridge`.
+ *
+ * @example
+ * ```ts
+ * import { excelToDocx } from "excelts/word/excel";
+ * ```
+ */
+export { excelToDocx, extractTablesToExcel, renderWordChartSvg, buildWordChartExXml, wordChartToChartModel, generateChartEmbeddedXlsx } from "./bridge/excel-bridge.js";
+export type { ExcelToDocxOptions, WordChartExOptions } from "./bridge/excel-bridge.js";

package/dist/types/modules/word/font/font-embed.d.ts

@@ -0,0 +1,112 @@
+/**
+ * DOCX Module - Embedded Font Writer
+ *
+ * Provides the ability to embed font files into DOCX documents.
+ * Supports TTF, OTF, and WOFF fonts with optional ODTTF obfuscation
+ * as required by the OOXML specification for embedded fonts.
+ *
+ * ECMA-376 Part 1, §17.8.3 describes how fonts are embedded:
+ * - Fonts are stored in word/fonts/ directory
+ * - Each embedded font has a relationship in fontTable.xml
+ * - Obfuscation uses a GUID-based XOR scheme (ODTTF format)
+ *
+ * Supports font subsetting to reduce file size by only including
+ * glyphs that are actually used in the document.
+ */
+import type { DocxDocument, FontDef, EmbeddedFont } from "../types.js";
+/** Font embedding style (which variants to embed). */
+export type FontEmbedStyle = "regular" | "bold" | "italic" | "boldItalic";
+/** Options for embedding a font. */
+export interface EmbedFontOptions {
+    /** Font family name as it will appear in the document. */
+    readonly name: string;
+    /** The raw font file data (TTF/OTF/WOFF). */
+    readonly data: Uint8Array;
+    /** Which style variant this is. Default: "regular". */
+    readonly style?: FontEmbedStyle;
+    /** Whether to apply ODTTF obfuscation. Default: true. */
+    readonly obfuscate?: boolean;
+    /** Font family classification. */
+    readonly family?: "roman" | "swiss" | "modern" | "script" | "decorative" | "auto";
+    /** Font pitch. */
+    readonly pitch?: "default" | "fixed" | "variable";
+    /** Panose-1 classification (10-byte hex string). */
+    readonly panose1?: string;
+    /** Character set (0 = ANSI). */
+    readonly charset?: number;
+    /**
+     * Characters used in the document for subsetting.
+     * When provided, the embedded font will only contain glyphs for these characters,
+     * significantly reducing file size. Pass all unique characters from the document
+     * that use this font.
+     */
+    readonly usedCharacters?: string;
+}
+/** Result of embedding a font. */
+export interface EmbedFontResult {
+    /** The font definition to add to `doc.fonts`. */
+    readonly fontDef: FontDef;
+    /** The embedded font entry to add to `doc.embeddedFonts`. */
+    readonly embeddedFont: EmbeddedFont;
+}
+/**
+ * Subset a TrueType/OpenType font to include only the specified characters.
+ *
+ * This performs a minimal subset by:
+ * 1. Parsing the cmap table to find glyph IDs for requested characters
+ * 2. Building a new glyf/loca table with only needed glyphs (+ composite dependencies)
+ * 3. Rebuilding the font with minimal tables
+ *
+ * For CFF (PostScript-outline) fonts, subsetting is more complex and we fall back
+ * to embedding the full font.
+ *
+ * @param fontData - Raw TTF/OTF font bytes
+ * @param characters - String of characters to keep
+ * @returns Subsetted font bytes, or original if subsetting fails/not applicable
+ */
+export declare function subsetFont(fontData: Uint8Array, characters: string): Uint8Array;
+/**
+ * Prepare a font for embedding into a DOCX document.
+ *
+ * Returns both the FontDef (for the font table) and the EmbeddedFont
+ * (for the embedded binary). The caller should add these to the document model.
+ *
+ * @param options - Font embedding options.
+ * @returns The font definition and embedded font data.
+ *
+ * @example
+ * ```ts
+ * const result = embedFont({
+ *   name: "CustomFont",
+ *   data: fontFileBytes,
+ *   style: "regular",
+ *   obfuscate: true
+ * });
+ *
+ * // Add to document
+ * const doc = {
+ *   ...existingDoc,
+ *   fonts: [...(existingDoc.fonts ?? []), result.fontDef],
+ *   embeddedFonts: [...(existingDoc.embeddedFonts ?? []), result.embeddedFont]
+ * };
+ * ```
+ */
+export declare function embedFont(options: EmbedFontOptions): EmbedFontResult;
+/**
+ * Embed multiple font variants (regular, bold, italic, boldItalic) for a font family.
+ *
+ * @param name - Font family name.
+ * @param variants - Map of style to font data.
+ * @param options - Shared options for all variants.
+ * @returns Array of embed results.
+ */
+export declare function embedFontFamily(name: string, variants: Partial<Record<FontEmbedStyle, Uint8Array>>, options?: Omit<EmbedFontOptions, "name" | "data" | "style">): EmbedFontResult[];
+/**
+ * Add embedded fonts to an existing document model.
+ * Merges new fonts with existing font definitions.
+ *
+ * @param doc - The existing document.
+ * @param results - Embed results from `embedFont` or `embedFontFamily`.
+ * @returns A new document with embedded fonts added.
+ */
+export declare function addEmbeddedFonts(doc: DocxDocument, results: readonly EmbedFontResult[]): DocxDocument;

package/dist/types/modules/word/font/hyphenation.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Hyphenation Engine
+ *
+ * Implements Liang's hyphenation algorithm (as used in TeX) for automatic
+ * word hyphenation without external dependencies.
+ *
+ * Features:
+ * - Pattern-based hyphenation (Liang algorithm)
+ * - Built-in patterns for English (US)
+ * - Pluggable pattern sets for other languages
+ * - Min-prefix / min-suffix constraints
+ * - Exception dictionary support
+ *
+ * @stability experimental
+ */
+/** Hyphenation options. */
+export interface HyphenationOptions {
+    /** Minimum characters before the first hyphenation point. Default: 2. */
+    readonly minLeft?: number;
+    /** Minimum characters after the last hyphenation point. Default: 2. */
+    readonly minRight?: number;
+    /** Custom hyphen character. Default: "\u00AD" (soft hyphen). */
+    readonly hyphenChar?: string;
+}
+/** Hyphenation pattern set for a language. */
+export interface HyphenationPatterns {
+    /** Language identifier (e.g., "en-us"). */
+    readonly language: string;
+    /** Patterns in Liang format (e.g., ".ach4" means level 4 between 'c' and 'h' at word start). */
+    readonly patterns: readonly string[];
+    /** Exception words with explicit hyphenation (e.g., "as-so-ciate"). */
+    readonly exceptions?: readonly string[];
+}
+/**
+ * Create a hyphenator function for a given language/pattern set.
+ *
+ * @param patterns - The hyphenation patterns to use.
+ * @param options - Hyphenation constraints.
+ * @returns A function that takes a word and returns an array of hyphenation points (indices).
+ */
+export declare function createHyphenator(patterns: HyphenationPatterns, options?: HyphenationOptions): (word: string) => number[];
+/**
+ * Hyphenate a word by inserting soft hyphens at valid break points.
+ *
+ * @param word - The word to hyphenate.
+ * @param hyphenator - A hyphenator function (from createHyphenator).
+ * @param hyphenChar - The hyphen character to insert. Default: "\u00AD".
+ * @returns The word with soft hyphens inserted.
+ */
+export declare function hyphenateWord(word: string, hyphenator: (w: string) => number[], hyphenChar?: string): string;
+/**
+ * Hyphenate all words in a text string.
+ *
+ * @param text - The text to hyphenate.
+ * @param hyphenator - A hyphenator function.
+ * @param hyphenChar - The hyphen character to insert.
+ * @returns The text with soft hyphens inserted.
+ */
+export declare function hyphenateText(text: string, hyphenator: (w: string) => number[], hyphenChar?: string): string;
+/**
+ * English (US) hyphenation patterns — comprehensive TeX US English patterns.
+ * Based on Liang's dissertation patterns (hyph-en-us) providing full coverage
+ * for standard English word hyphenation.
+ */
+export declare const ENGLISH_US_PATTERNS: HyphenationPatterns;

package/dist/types/modules/word/font/text-shaping.d.ts

@@ -0,0 +1,58 @@
+/**
+ * OpenType Text Shaping Engine
+ *
+ * Provides basic text shaping for complex scripts without external dependencies.
+ * Covers Arabic joining, BiDi reordering, and basic Indic/Thai features.
+ *
+ * This is not a full HarfBuzz replacement — it handles the most common shaping
+ * requirements for document layout and rendering:
+ * - Arabic contextual joining (Initial/Medial/Final/Isolated forms)
+ * - Unicode Bidirectional Algorithm (UAX #9) simplified implementation
+ * - Basic Indic vowel reordering (Devanagari, Bengali, Tamil, etc.)
+ * - Thai/Lao mark positioning hints
+ *
+ * @stability experimental
+ */
+/** Script classification for a text run. */
+export type ScriptType = "latin" | "arabic" | "hebrew" | "devanagari" | "bengali" | "tamil" | "thai" | "lao" | "cjk" | "hangul" | "other";
+/** BiDi direction for a text segment. */
+export type BiDiDirection = "ltr" | "rtl";
+/** A shaped glyph cluster — the output of shaping. */
+export interface ShapedCluster {
+    /** The original characters in this cluster. */
+    readonly chars: string;
+    /** The visual form (after joining/reordering). */
+    readonly visual: string;
+    /** Advance width multiplier (1.0 = normal, 0 = zero-width). */
+    readonly advanceMultiplier: number;
+    /** Script classification. */
+    readonly script: ScriptType;
+    /** BiDi direction. */
+    readonly direction: BiDiDirection;
+}
+/** Shaping options. */
+export interface ShapingOptions {
+    /** Base paragraph direction. Default: "ltr". */
+    readonly direction?: BiDiDirection;
+    /** Enable Arabic joining. Default: true. */
+    readonly arabicJoining?: boolean;
+    /** Enable BiDi reordering. Default: true. */
+    readonly bidiReorder?: boolean;
+}
+/**
+ * Shape a text string for complex script rendering.
+ * Returns an array of shaped clusters in visual order.
+ *
+ * @param text - The input text in logical order.
+ * @param options - Shaping options.
+ * @returns Array of shaped clusters.
+ */
+export declare function shapeText(text: string, options?: ShapingOptions): ShapedCluster[];
+/**
+ * Detect the dominant script of a text string.
+ */
+export declare function detectScript(text: string): ScriptType;
+/**
+ * Determine the BiDi direction of a text based on its first strong character.
+ */
+export declare function detectDirection(text: string): BiDiDirection;

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

@@ -1,13 +1,14 @@
 /**
- * DOCX Module - HTML Renderer (Subpath Export)
+ * DOCX Module - HTML Converters (Subpath Entry)
  *
- * Import separately to avoid pulling html-renderer into the bundle
- * when only core document building is needed.
+ * Re-exports the HTML converter API at `excelts/word/html`. This file is
+ * referenced by `package.json#exports["./word/html"]`; it forwards to the
+ * implementation under `./convert/html`.
  *
  * @example
  * ```ts
- * import { renderToHtml } from "excelts/word/html";
+ * import { renderToHtml, htmlToDocxBody } from "excelts/word/html";
  * ```
  */
-export { renderToHtml } from "./html-renderer.js";
-export type { HtmlRenderOptions, HtmlRenderResult } from "./html-renderer.js";
+export { renderToHtml, htmlToDocxBody } from "./convert/html/html.js";
+export type { HtmlRenderOptions, HtmlRenderResult, HtmlImportOptions } from "./convert/html/html.js";