@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/types/modules/word/writer/streaming-writer.d.ts

@@ -0,0 +1,344 @@
+/**
+ * DOCX Module - Streaming Writer
+ *
+ * A DOCX generator that serializes body content incrementally and pushes it
+ * through a streaming compression pipeline. Uses the same streaming ZIP
+ * infrastructure as the Excel module:
+ *
+ * - `Zip` (StreamingZip) — streams ZIP entries to output
+ * - `ZipDeflate` — per-entry deflate compression
+ * - `StreamBuf` — event-driven pipe from XML to ZIP
+ * - `StringBuf` — efficient XML string builder with buffer reuse
+ *
+ * Data flow with sink (true end-to-end streaming):
+ * ```
+ * add(paragraph) → XML → StreamBuf → ZipDeflate → Zip
+ *                                                     ↓ (per-chunk callback)
+ *                                            await SinkAdapter.write(chunk)
+ *                                                     ↓
+ *                                           user-supplied WritableStream /
+ *                                           Node Writable / duck-typed sink
+ * ```
+ *
+ * Memory profile:
+ *   - Body model is never retained: each element is serialised and
+ *     compressed as it arrives, so peak per-element memory is
+ *     O(largest_single_element).
+ *   - When `options.sink` is provided, compressed bytes are pushed
+ *     into the sink as soon as they are produced (with backpressure
+ *     awaited via {@link SinkAdapter}). Total writer-side memory then
+ *     stays O(largest_part) regardless of final DOCX size.
+ *   - When `options.sink` is omitted, compressed bytes accumulate in
+ *     `_outputChunks` and `finalize()` returns the assembled
+ *     `Uint8Array`. Total memory is O(compressed_docx_size).
+ */
+import { type AnySink } from "../../stream/internal/sink-adapter.js";
+import type { WordSecurityPolicy } from "../security/policy.js";
+import type { AbstractNumbering, AppProperties, BodyContent, CommentDef, CoreProperties, CustomProperty, CustomXmlPart, DocDefaults, DocumentBackground, DocumentSettings, DocumentTheme, EmbeddedFont, EndnoteDef, FontDef, FooterDef, FootnoteDef, HeaderDef, ImageDef, NumberingInstance, OpaquePart, Paragraph, SectionProperties, StyleDef, Watermark } from "../types.js";
+/** Options for the streaming DOCX writer. */
+export interface StreamingDocxOptions {
+    /** Compression level (0-9). Default: 6. */
+    readonly compressionLevel?: number;
+    /** Progress callback interval: report after every N elements. Default: 1000. */
+    readonly chunkSize?: number;
+    /** Section properties for the final section. */
+    readonly sectionProperties?: SectionProperties;
+    /** Document styles. */
+    readonly styles?: readonly StyleDef[];
+    /** Document defaults. */
+    readonly docDefaults?: DocDefaults;
+    /** Abstract numbering definitions. */
+    readonly abstractNumberings?: readonly AbstractNumbering[];
+    /** Numbering instances. */
+    readonly numberingInstances?: readonly NumberingInstance[];
+    /** Headers. */
+    readonly headers?: ReadonlyMap<string, HeaderDef>;
+    /** Footers. */
+    readonly footers?: ReadonlyMap<string, FooterDef>;
+    /** Footnotes. */
+    readonly footnotes?: readonly FootnoteDef[];
+    /** Endnotes. */
+    readonly endnotes?: readonly EndnoteDef[];
+    /** Images. */
+    readonly images?: readonly ImageDef[];
+    /** Fonts. */
+    readonly fonts?: readonly FontDef[];
+    /** Document settings. */
+    readonly settings?: DocumentSettings;
+    /** Core properties. */
+    readonly coreProperties?: CoreProperties;
+    /** App properties. */
+    readonly appProperties?: AppProperties;
+    /** Comments. */
+    readonly comments?: readonly CommentDef[];
+    /** Background. */
+    readonly background?: DocumentBackground;
+    /** Custom properties. */
+    readonly customProperties?: readonly CustomProperty[];
+    /** Watermark. */
+    readonly watermark?: Watermark;
+    /** Theme. */
+    readonly theme?: DocumentTheme;
+    /** Custom XML parts (for SDT data binding). */
+    readonly customXmlParts?: readonly CustomXmlPart[];
+    /** Embedded font binaries (stored in word/fonts/). */
+    readonly embeddedFonts?: readonly EmbeddedFont[];
+    /** Opaque (unrecognized) parts preserved for round-trip fidelity. */
+    readonly opaqueParts?: readonly OpaquePart[];
+    /**
+     * How to handle image references whose binary is not in `images`.
+     *
+     * - `"throw"` (default): throw `DocxWriteError` from `add*` so the caller
+     *   notices the broken reference immediately.
+     * - `"warn"`: emit a `console.warn` and skip the rId. The output will be
+     *   missing this image's relationship — useful only for tooling that
+     *   knows it's intentionally producing a partial document.
+     *
+     * The previous behaviour (silent skip) is gone because it generated
+     * invalid DOCX files.
+     */
+    readonly missingImagePolicy?: "throw" | "warn";
+    /**
+     * Security policy. Currently used to surface `rawXmlPolicy` to the renderers
+     * (preserve / strip / reject) so opaque rawXml fields behave consistently
+     * with the buffered `packageDocx` writer.
+     */
+    readonly securityPolicy?: WordSecurityPolicy;
+    /**
+     * Output sink. When provided, compressed bytes flow through it as soon
+     * as the underlying ZIP pipeline produces them, with backpressure
+     * awaited via {@link SinkAdapter}. Total writer-side memory then
+     * stays O(largest_part) regardless of final DOCX size.
+     *
+     * Accepts:
+     *  - Web `WritableStream<Uint8Array>` (browser, Deno, modern Node)
+     *  - Node `Writable` (`fs.createWriteStream`, http response, …)
+     *  - Any duck-typed object exposing `write(chunk)` + `end()` plus
+     *    `once("drain"|"error"|"close"|"finish", …)` listeners
+     *
+     * When the sink is provided, {@link StreamingDocxWriter.finalize}
+     * resolves to a zero-length `Uint8Array` (the bytes have already
+     * been delivered to the sink — the empty return is a sentinel that
+     * keeps `finalize`'s return type stable across both modes). Use
+     * {@link StreamingDocxWriter.addAsync} (instead of
+     * {@link StreamingDocxWriter.add}) when you want each `add` call to
+     * await actual sink drain — that gives true end-to-end backpressure
+     * for tight production loops.
+     *
+     * When omitted, behaviour is unchanged: compressed bytes accumulate
+     * internally and `finalize()` returns the assembled `Uint8Array`.
+     */
+    readonly sink?: AnySink;
+}
+/** Progress callback for streaming writer. */
+export type StreamingProgressCallback = (info: {
+    /** Number of body elements written so far. */
+    elementsWritten: number;
+    /** Current phase: "body" | "finalizing". */
+    phase: string;
+}) => void;
+/**
+ * Streaming DOCX writer. Body elements are serialized to XML and compressed
+ * into the ZIP pipeline as they arrive, so the body **model** is not retained
+ * after each `add()`.
+ *
+ * When constructed with `options.sink`, compressed bytes are pushed into
+ * the sink as soon as the ZIP layer produces them, with backpressure
+ * awaited via {@link SinkAdapter}; in this mode peak memory is
+ * O(largest_part) and `finalize()` resolves to a zero-length
+ * `Uint8Array` (the bytes are already in the sink). Without a sink,
+ * compressed bytes accumulate in `_outputChunks` and `finalize()`
+ * returns the assembled `Uint8Array` (peak memory
+ * O(compressed_docx_size)).
+ *
+ * Use {@link addAsync} (instead of {@link add}) when driving the sink
+ * variant to obtain true end-to-end backpressure: each call awaits all
+ * pending sink writes before resolving.
+ */
+export declare class StreamingDocxWriter {
+    private readonly _options;
+    private _elementCount;
+    private _finalized;
+    private _onProgress?;
+    private readonly _xmlBuffer;
+    private _zip;
+    /** Compressed-byte accumulator used when no `sink` is supplied. */
+    private _outputChunks;
+    /** Sink-mode adapter (set when `options.sink` is provided). */
+    private _sinkAdapter?;
+    /**
+     * Promise chain serialising every sink write. The `Zip` callback fires
+     * synchronously, so we queue chunks via `.then(...)` and let
+     * `addAsync` / `finalize` await the chain.
+     */
+    private _pendingDrain;
+    private _documentStream;
+    private _documentZipFile;
+    private _headerWritten;
+    /**
+     * Whether the previously-written body element was a `<w:tbl>`. Tracked
+     * so we can insert a separator `<w:p>` between adjacent tables — Word
+     * rejects (and silently merges) two `<w:tbl>` blocks that share no
+     * paragraph between them per ECMA-376 §17.13.5.34.
+     */
+    private _prevWasTable;
+    /**
+     * First error reported by the underlying ZIP stream (compression failure,
+     * write-after-end, etc.). Stored synchronously by the `Zip` callback and
+     * surfaced from `finalize()` so callers receive a rejection instead of an
+     * indefinitely-pending promise.
+     */
+    private _streamError;
+    private _documentRels;
+    private _renderCtx;
+    /** Charts encountered in body content; rendered to `word/charts/chartN.xml` at finalize time. */
+    private readonly _bodyCharts;
+    /** ChartEx items encountered in body content. */
+    private readonly _bodyChartEx;
+    /**
+     * Per-chart sequence numbers fixed at registration time. Both classes
+     * use independent monotonic counters; the writer emits
+     * `word/charts/chart{n}.xml` for the regular chart family and
+     * `word/charts/chartEx{n}.xml` for the chartEx family.
+     *
+     * The previous scheme used `chartCount + chartExCount + 1` as the
+     * sequence number for both classes, which made the rId path encoded in
+     * documentRels disagree with the path used at finalize when the writer
+     * iterated the two arrays separately. The result was relationships
+     * pointing at non-existent chart parts.
+     */
+    private readonly _chartNum;
+    private _nextChartSeq;
+    private _nextChartExSeq;
+    /** Hyperlink object identities already registered (to keep one rId per object). */
+    private readonly _registeredHyperlinks;
+    /** Image rIds already registered to documentRels (avoid duplicates). */
+    private readonly _registeredImageRIds;
+    /** header map key → newly allocated rId. Populated by `_allocateHeaderFooterRIds`. */
+    private readonly _headerKeyToRid;
+    /** footer map key → newly allocated rId. */
+    private readonly _footerKeyToRid;
+    /** rId allocated for the auto-generated watermark header (if any). */
+    private _watermarkHeaderRid;
+    constructor(options?: StreamingDocxOptions);
+    /** Set a progress callback. */
+    onProgress(cb: StreamingProgressCallback): this;
+    /**
+     * Add a single body element. The element is immediately serialized to XML
+     * and pushed into the ZIP compression pipeline. After this call, the element
+     * can be garbage collected — it is not retained.
+     */
+    add(element: BodyContent): this;
+    /** Add multiple body elements at once. */
+    addMany(elements: readonly BodyContent[]): this;
+    /**
+     * Async variant of {@link add}. After serialising the element, awaits
+     * any pending writes to the configured `sink` so callers driving large
+     * input get true end-to-end backpressure rather than letting the
+     * sink-write queue grow unbounded inside the writer.
+     *
+     * Without `options.sink` this is equivalent to `add` (resolving
+     * synchronously after element serialisation).
+     *
+     * Throws if the sink reports an error: previous queued writes whose
+     * rejection was captured into `_streamError` surface here.
+     */
+    addAsync(element: BodyContent): Promise<this>;
+    /**
+     * Async variant of {@link addMany}. Awaits `addAsync` for each element
+     * so backpressure is honoured between every body element.
+     */
+    addManyAsync(elements: readonly BodyContent[]): Promise<this>;
+    /** Add a paragraph with simple text content. */
+    addText(content: string, properties?: Paragraph["properties"]): this;
+    /** Get the count of body elements written so far. */
+    get elementCount(): number;
+    /**
+     * Finalize the document.
+     *
+     * - Without `options.sink`: returns the assembled `Uint8Array`
+     *   containing the full DOCX file.
+     * - With `options.sink`: drains any pending sink writes, calls
+     *   `sink.end()`, and resolves to a zero-length `Uint8Array`. The
+     *   DOCX bytes have already been delivered to the sink — the empty
+     *   return is a sentinel signalling "writer is done; consumer keeps
+     *   the data".
+     */
+    finalize(): Promise<Uint8Array>;
+    /** Reset the writer for reuse. */
+    /**
+     * Reset the writer for reuse.
+     *
+     * Throws when the writer was constructed with an `options.sink`: a
+     * sink can only be `end()`ed once, so reusing the same writer would
+     * produce an undefined byte stream. Construct a new writer (with a
+     * new sink) for each document instead.
+     */
+    reset(): this;
+    private _initZip;
+    private _write;
+    private _writeDocumentHeader;
+    private _writeBodyElement;
+    /**
+     * Emit an empty `<w:p/>` to separate two adjacent tables. Required by
+     * ECMA-376 §17.13.5.34 — Word rejects packages where two `<w:tbl>`
+     * elements appear without a paragraph between them.
+     */
+    private _writeSeparatorParagraph;
+    /**
+     * Scan a single body element and register any chart / hyperlink / image
+     * references it introduces against the writer's accumulated state. This
+     * must run before the element is serialized so the render context already
+     * carries the relationships the renderer will look up.
+     */
+    private _registerElementReferences;
+    private _registerParagraphReferences;
+    private _registerChart;
+    private _registerChartEx;
+    private _registerHyperlink;
+    private _registerImageRId;
+    private _lookupImage;
+    private _writeDocumentFooter;
+    /**
+     * Allocate header/footer relationship IDs deterministically (in the same
+     * order auxiliary parts will be emitted). Called once during finalize so
+     * `_writeDocumentFooter` and `_addAuxiliaryParts` agree on which rId
+     * points at which header/footer XML part.
+     */
+    private _allocateHeaderFooterRIds;
+    private _rewireSectionRefs;
+    /**
+     * Synthesise section-property header references for every header part
+     * the caller registered. Recognised type keys (`default`/`first`/`even`)
+     * keep their semantics; any other key (round-tripped rId names from
+     * readDocx, custom strings) falls back to `"default"` so the header is
+     * actually referenced — without this fallback header parts can sit in
+     * the package as dangling content.
+     *
+     * If multiple keys map to the same logical type, only the first one is
+     * kept so we don't emit two `<w:headerReference w:type="default">`
+     * children (Word's behaviour with duplicates is implementation-defined).
+     */
+    private _synthesizeHeaderRefs;
+    private _synthesizeFooterRefs;
+    private _addAuxiliaryParts;
+    private _endStream;
+    private _assembleOutput;
+}
+/**
+ * Create a new streaming DOCX writer.
+ *
+ * @example
+ * ```ts
+ * const writer = createDocxStream({
+ *   styles: [{ type: "paragraph", styleId: "Normal", name: "Normal" }]
+ * });
+ *
+ * for (let i = 0; i < 100000; i++) {
+ *   writer.addText(`Paragraph ${i}`);
+ * }
+ *
+ * const buffer = await writer.finalize();
+ * ```
+ */
+export declare function createDocxStream(options?: StreamingDocxOptions): StreamingDocxWriter;

package/dist/types/modules/word/writer/string-buf.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-export of the shared {@link StringBuf} from `@utils/string-buf`.
+ *
+ * Kept as a thin alias so existing relative imports (`./string-buf`) within
+ * the word writer continue to work without churn.
+ */
+export { StringBuf } from "../../../utils/string-buf.js";
+export type { StringBufOptions } from "../../../utils/string-buf.js";

package/dist/types/modules/word/{writers → writer}/table-writer.d.ts

@@ -6,5 +6,6 @@
  */
 import type { XmlSink } from "../../xml/types.js";
 import type { Table } from "../types.js";
+import type { RenderHelpers } from "./render-context.js";
 /** Render a w:tbl element. */
-export declare function renderTable(xml: XmlSink, table: Table): void;
+export declare function renderTable(xml: XmlSink, table: Table, helpers?: RenderHelpers): void;

package/dist/types/modules/xml/types.d.ts

@@ -214,6 +214,28 @@ export interface SaxOptions {
  * Accepts strings or Uint8Array chunks.
  * Compatible with Node.js Writable, browser WritableStream wrappers,
  * and the project's own StreamBuf.
+ *
+ * **Backpressure caveat**: `write()` returns `void`. The XmlStreamWriter
+ * cannot signal or wait for backpressure on the target — it pushes
+ * chunks synchronously as the caller invokes `openNode`/`writeText`/etc.
+ *
+ * If the target is a slow sink (HTTP response, fs stream, etc), the
+ * caller is responsible for ensuring chunks are consumed at a rate
+ * matching production. Two safe patterns:
+ *
+ *   1. Wrap the target so `write()` buffers into a bounded queue and
+ *      pause your XML production loop when the queue is full.
+ *   2. Use a small in-memory buffer as the `WritableTarget`, then ship
+ *      the assembled bytes to the slow sink with proper backpressure
+ *      (e.g. via `pipeline()`).
+ *
+ * `XmlStreamWriter` is used internally by excelts's xlsx writer. The xlsx
+ * writer wraps it in a backpressure-aware zip pipeline that awaits drain
+ * BETWEEN zip entries — so memory grows at most by one entry's worth of
+ * uncompressed XML before the producer is parked. Within a single very
+ * large worksheet entry the synchronous push pattern still applies; that
+ * is the practical bound on how much a slow user sink can buffer behind
+ * the xlsx writer.
  */
 export interface WritableTarget {
     write(chunk: string | Uint8Array): void;

package/dist/types/utils/crypto.browser.d.ts

@@ -19,7 +19,9 @@ export declare function sha256(input: Uint8Array): Uint8Array;
 export declare function md5(input: Uint8Array): Uint8Array;
 /**
  * RC4 stream cipher.
- * @deprecated Only used for reading legacy encrypted PDFs.
+ *
+ * Required by ISO 32000 for reading PDFs encrypted with the RC4 algorithm
+ * (PDF 1.4 standard handler V=1/V=2).
  */
 export declare function rc4(key: Uint8Array, data: Uint8Array): Uint8Array;
 /**

package/dist/types/utils/crypto.d.ts

@@ -67,7 +67,10 @@ export declare function aesCbcEncryptRaw(plaintext: Uint8Array, key: Uint8Array,
 export declare function aesEcbEncrypt(block: Uint8Array, key: Uint8Array): Uint8Array;
 /**
  * RC4 stream cipher.
- * @deprecated Only used for reading legacy encrypted PDFs.
+ *
+ * Required by ISO 32000 for reading PDFs encrypted with the RC4 algorithm
+ * (PDF 1.4 standard handler V=1/V=2). Modern Node `crypto` no longer
+ * exposes RC4, so this is a pure-JS implementation.
  */
 export declare function rc4(key: Uint8Array, data: Uint8Array): Uint8Array;
 /**

package/dist/types/utils/font-metrics.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Standard Font Metrics — shared between Word layout and PDF rendering.
+ *
+ * Provides width data for the 14 standard PDF fonts (Helvetica, Times, Courier families).
+ * Used for text measurement without requiring actual font files.
+ *
+ * Character widths are specified in 1/1000 of a text unit. To get the actual width
+ * of a character at a given font size:
+ *   width_in_points = (charWidth / 1000) * fontSize
+ *
+ * @see PDF Reference 1.7, Appendix D - Standard Type 1 Fonts
+ * @see Adobe Font Metrics files (AFM) for canonical widths
+ */
+/**
+ * Get the width of a character in a given font.
+ * @param charCode - Unicode code point (or char code)
+ * @param fontName - PDF standard font name
+ * @returns Width in thousandths of a unit
+ */
+export declare function getCharWidth(charCode: number, fontName: string): number;
+/**
+ * Measure the width of a text string in the given font and size.
+ * @param text - The string to measure
+ * @param fontName - PDF standard font name
+ * @param fontSize - Font size in points
+ * @returns Width in points
+ */
+export declare function measureTextWidth(text: string, fontName: string, fontSize: number): number;
+/**
+ * Get the font ascent for a given font and size.
+ * @param fontName - PDF standard font name
+ * @param fontSize - Font size in points
+ * @returns Ascent in points (positive, distance above baseline)
+ */
+export declare function getFontAscent(fontName: string, fontSize: number): number;
+/**
+ * Get the font descent for a given font and size.
+ * @param fontName - PDF standard font name
+ * @param fontSize - Font size in points
+ * @returns Descent in points (positive value representing distance below baseline)
+ */
+export declare function getFontDescent(fontName: string, fontSize: number): number;
+/**
+ * Get the total line height (ascent - descent) for a font.
+ * @param fontName - PDF standard font name
+ * @param fontSize - Font size in points
+ * @returns Line height in points
+ */
+export declare function getLineHeight(fontName: string, fontSize: number): number;
+/**
+ * Check if a font name is a known standard PDF font.
+ */
+export declare function isStandardFont(fontName: string): boolean;
+/**
+ * Get all supported standard font names.
+ */
+export declare function getStandardFontNames(): string[];
+/**
+ * Map common font names (like "Arial", "Calibri") to closest standard font.
+ * Returns the input unchanged if it's already a standard font name.
+ * Falls back to "Helvetica" for unknown fonts.
+ */
+export declare function mapToStandardFont(fontName: string): string;

package/dist/types/utils/string-buf.d.ts

@@ -0,0 +1,42 @@
+/**
+ * StringBuf - Cross-Platform String Buffer
+ *
+ * Efficient string builder that accumulates UTF-8 encoded bytes into a single
+ * `Uint8Array`. Designed for hot paths that build large XML / text payloads
+ * (XLSX worksheet writers, streaming DOCX writer) where naïve `string +=`
+ * concatenation triggers O(n²) re-allocations.
+ *
+ * Works identically in Node.js and Browser environments — uses only
+ * `TextEncoder` and `Uint8Array`.
+ */
+interface StringBufOptions {
+    /** Initial capacity in bytes (default: 16384). */
+    size?: number;
+    /**
+     * Encoding label, accepted for API symmetry. Only UTF-8 is supported by
+     * `TextEncoder`, so this option is ignored.
+     */
+    encoding?: string;
+}
+/**
+ * Efficient string builder backed by a growable `Uint8Array`.
+ */
+declare class StringBuf {
+    private _buf;
+    private _inPos;
+    private _buffer;
+    constructor(options?: StringBufOptions);
+    get length(): number;
+    get capacity(): number;
+    get buffer(): Uint8Array;
+    /** Return a snapshot of the bytes written so far. Cached until next mutation. */
+    toBuffer(): Uint8Array;
+    reset(position?: number): void;
+    private _grow;
+    /** Append a string, encoded as UTF-8. */
+    addText(text: string): void;
+    /** Append the contents of another StringBuf without re-encoding. */
+    addStringBuf(inBuf: StringBuf): void;
+}
+export { StringBuf };
+export type { StringBufOptions };

package/dist/types/utils/theme-colors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * OOXML Theme Color Resolution — shared between Excel and Word modules.
+ *
+ * Provides utilities for resolving theme color references with tint/shade
+ * transformations per the ECMA-376 color model.
+ */
+/** Standard OOXML theme color names (scheme keys in theme1.xml). */
+export type OoxmlThemeColorName = "dk1" | "lt1" | "dk2" | "lt2" | "accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "hlink" | "folHlink";
+/**
+ * Map from OOXML property attribute values to theme scheme keys.
+ *
+ * Word/Excel run/paragraph/cell properties use long-form names ("dark1",
+ * "light1", "hyperlink") while the theme XML stores short-form keys
+ * ("dk1", "lt1", "hlink"). This map normalises both forms.
+ */
+export declare const THEME_COLOR_ATTRIBUTE_MAP: Record<string, OoxmlThemeColorName>;
+/**
+ * Apply a tint (lighten toward white) to a hex color.
+ *
+ * OOXML tint formula: `newComponent = component + (255 - component) * tint`
+ * where tint ∈ [0, 1]. tint=0 → original, tint=1 → white.
+ *
+ * @param hex - 6-character hex color string (no "#" prefix).
+ * @param tint - Tint value in range [0, 1].
+ * @returns Tinted 6-character hex color string.
+ */
+export declare function applyTint(hex: string, tint: number): string;
+/**
+ * Apply a shade (darken toward black) to a hex color.
+ *
+ * OOXML shade formula: `newComponent = component * shade`
+ * where shade ∈ [0, 1]. shade=1 → original, shade=0 → black.
+ *
+ * @param hex - 6-character hex color string (no "#" prefix).
+ * @param shade - Shade value in range [0, 1].
+ * @returns Shaded 6-character hex color string.
+ */
+export declare function applyShade(hex: string, shade: number): string;
+/**
+ * Resolve a theme color reference to a hex color string.
+ *
+ * Looks up the theme color by attribute name (normalising long-form names
+ * like "dark1" to scheme keys like "dk1"), then applies optional tint or
+ * shade transformation.
+ *
+ * @param themeColorName - The theme color attribute value (e.g. "accent1", "dark1", "dk1").
+ * @param colors - The theme color scheme (scheme key → 6-char hex mapping).
+ * @param tint - Optional tint value in [0, 1]. Values > 1 are treated as
+ *               raw bytes (0-255) and normalised by dividing by 255.
+ * @param shade - Optional shade value in [0, 1]. Values > 1 are treated as
+ *                raw bytes (0-255) and normalised by dividing by 255.
+ * @returns Resolved 6-character hex color string, or undefined if the theme
+ *          color name cannot be found in the provided scheme.
+ */
+export declare function resolveOoxmlThemeColor(themeColorName: string, colors: Readonly<Record<string, string>>, tint?: number, shade?: number): string | undefined;