docx-kit 0.0.0 → 0.1.0

package/dist/index.d.ts

@@ -1,5 +1,1032 @@
-//#region src/index.d.ts
-declare const msg = "hello world";
-declare function greet(): string;
+import { EChartsOption } from "echarts";
+
+//#region src/types/utility.d.ts
+/** Hexadecimal CSS color string, e.g. `"#ff0000"`. */
+type HexColor = `#${string}`;
+/**
+ * A literal union type that still allows arbitrary string values.
+ * Useful for autocomplete-friendly APIs with extensible values.
+ *
+ * @template T — The literal subtype (e.g. `'Arial' | 'Calibri'`)
+ * @template U — The base type, defaults to `string`
+ */
+type LiteralUnion<T extends U, U = string> = T | (U & {});
+/**
+ * A value that might be synchronous or wrapped in a Promise.
+ *
+ * @template T — The inner value type
+ */
+type MaybePromise<T> = Promise<T> | T;
+/**
+ * CSS-like length value.
+ *
+ * Supports bare numbers, and explicit unit strings:
+ * `%`, `cm`, `in`, `mm`, `pt`, `px`.
+ *
+ * Bare-number conventions vary by context:
+ * - `fontSize` → interpreted as `pt`
+ * - spacing / indent → interpreted as `pt`
+ * - image size → interpreted as `px`
+ */
+type UnitValue = `${number}%` | `${number}cm` | `${number}in` | `${number}mm` | `${number}pt` | `${number}px` | number;
 //#endregion
-export { greet, msg };
+//#region src/types/style.d.ts
+/**
+ * A single border side descriptor.
+ *
+ * Follows the CSS `border` shorthand convention (style, width, color).
+ */
+interface BorderRule {
+  /** Border color (e.g. `"#333"` or named color). */
+  color?: string | HexColor;
+  /** Line style. */
+  style?: BorderStyle;
+  /** Line width (bare number treated as pt). */
+  width?: UnitValue;
+}
+/** Available border line styles. */
+type BorderStyle = 'dashed' | 'dotted' | 'double' | 'none' | 'single';
+/**
+ * CSS-like style descriptor for a run, paragraph, cell, or table.
+ *
+ * Keys mirror familiar CSS property names. Unknown properties that don't
+ * map to Word XML are silently ignored.
+ */
+interface DocxStyleRule {
+  /** Force text to uppercase (small caps-like). */
+  allCaps?: boolean;
+  /** Background / shading color. */
+  backgroundColor?: string | HexColor;
+  /** Shorthand border for all four sides. */
+  border?: BorderRule;
+  /** Bottom border override. */
+  borderBottom?: BorderRule;
+  /** Left border override. */
+  borderLeft?: BorderRule;
+  /** Right border override. */
+  borderRight?: BorderRule;
+  /** Top border override. */
+  borderTop?: BorderRule;
+  /** Text / foreground color. */
+  color?: string | HexColor;
+  /**
+   * Direct passthrough to the underlying `docx` library constructor options.
+   * Use for properties not yet covered by the CSS-like mapping.
+   */
+  docx?: Record<string, unknown>;
+  /** Font family name. */
+  fontFamily?: LiteralUnion<'Arial' | 'Calibri' | 'Times New Roman'>;
+  /** Font size (bare number = pt). */
+  fontSize?: UnitValue;
+  /** Italic toggle. */
+  fontStyle?: 'italic' | 'normal';
+  /** Font weight: keyword `"bold"` / `"normal"` or numeric 100–900. */
+  fontWeight?: FontWeight;
+  /** Element height. */
+  height?: UnitValue;
+  /** Character spacing. */
+  letterSpacing?: UnitValue;
+  /** Line height multiplier or explicit unit value. */
+  lineHeight?: number | UnitValue;
+  /** Bottom margin. */
+  marginBottom?: UnitValue;
+  /** Left margin. */
+  marginLeft?: UnitValue;
+  /** Right margin. */
+  marginRight?: UnitValue;
+  /** Top margin. */
+  marginTop?: UnitValue;
+  /** Strikethrough toggle. */
+  strike?: boolean;
+  /** Horizontal text alignment. */
+  textAlign?: TextAlign;
+  /** First-line indent. */
+  textIndent?: UnitValue;
+  /** Underline style. */
+  underline?: 'double' | 'single' | boolean;
+  /** Vertical alignment (mostly for table cells). */
+  verticalAlign?: VerticalAlign;
+  /** Element width. */
+  width?: UnitValue;
+  /**
+   * CSS-like margin shorthand.
+   *
+   * Supports 1-value, 2-value, and 4-value string syntax
+   * (e.g. `"10pt"`, `"10pt 20pt"`, `"10pt 20pt 30pt 40pt"`).
+   */
+  margin?: `${string} ${string}` | `${string} ${string} ${string} ${string}` | UnitValue;
+  /**
+   * CSS-like padding shorthand (same syntax as margin).
+   */
+  padding?: `${string} ${string}` | `${string} ${string} ${string} ${string}` | UnitValue;
+}
+/**
+ * Font weight: keyword `"bold"` / `"normal"`, or numeric 100–900
+ * following the CSS `font-weight` spec.
+ */
+type FontWeight = 'bold' | 'normal' | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+/**
+ * A map of class name → style rule.
+ *
+ * Used to define reusable named styles referenced via `className` on nodes.
+ *
+ * @example
+ * ```ts
+ * const styles = defineStyles({
+ *   red:  { color: '#ff0000' },
+ *   big:  { fontSize: 20 },
+ * })
+ * ```
+ */
+type StyleSheet = Record<string, DocxStyleRule>;
+/** Horizontal text alignment. */
+type TextAlign = 'center' | 'justify' | 'left' | 'right';
+/** Vertical alignment (for table cells). */
+type VerticalAlign = 'bottom' | 'middle' | 'top';
+/**
+ * Define a type-safe stylesheet.
+ *
+ * `fontSize` defaults to pt when passed as a bare number.
+ *
+ * @param styles - — The stylesheet object
+ * @returns The same stylesheet with `const` type inference
+ *
+ * @example
+ * ```ts
+ * const styles = defineStyles({
+ *   title: { fontSize: 28, fontWeight: 'bold' },
+ *   body:  { fontSize: 12, lineHeight: 1.5 },
+ * })
+ * ```
+ */
+declare function defineStyles<const T extends StyleSheet>(styles: T): T;
+//#endregion
+//#region src/dsl/nodes.d.ts
+/**
+ * Common properties shared by all nodes.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface BaseNode<TStyles extends StyleSheet = StyleSheet> {
+  /**
+   * CSS-like class name(s) referencing stylesheet entries.
+   *
+   * Can be a single string, an array, or a space-separated string.
+   */
+  className?: string | ClassName<TStyles> | ClassName<TStyles>[];
+  /** Optional unique identifier (for templating / references). */
+  id?: string;
+  /** Inline style override for this specific node. */
+  style?: DocxStyleRule;
+}
+/**
+ * Union of all top-level content node types.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+type BlockNode<TStyles extends StyleSheet = StyleSheet> = HeadingNode<TStyles> | ImageNode<TStyles> | PageBreakNode | ParagraphNode<TStyles> | PluginNode<string, unknown, TStyles> | TableNode<Record<string, unknown>, TStyles>;
+/**
+ * Extract valid class name keys from a stylesheet type.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+type ClassName<TStyles extends StyleSheet> = Extract<keyof TStyles, string>;
+/**
+ * A heading node (h1–h6).
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface HeadingNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Heading level (1 = largest, 6 = smallest). */
+  level: 1 | 2 | 3 | 4 | 5 | 6;
+  /** Heading text content. */
+  text: string;
+  type: 'heading';
+}
+/**
+ * An image node.
+ *
+ * Supports raw bytes (`Uint8Array`, `ArrayBuffer`, `Blob`) or a file path string.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface ImageNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Image data as bytes, blob, or file path. */
+  data: string | ArrayBuffer | Blob | Uint8Array;
+  type: 'image';
+  /** Alt text for accessibility. */
+  alt?: string;
+  /** Display height. */
+  height?: UnitValue;
+  /** Image format hint. Auto-detected if omitted. */
+  imageType?: 'bmp' | 'gif' | 'jpeg' | 'jpg' | 'png';
+  /** Display width. */
+  width?: UnitValue;
+  /**
+   * Floating layout configuration.
+   *
+   * - `true` enables default floating
+   * - Object allows wrap mode and position offsets
+   */
+  floating?: boolean | {
+    /** Text wrap mode. */wrap?: 'square' | 'tight' | 'topAndBottom'; /** Horizontal offset. */
+    x?: UnitValue; /** Vertical offset. */
+    y?: UnitValue;
+  };
+}
+/**
+ * Union of inline content node types (appear inside paragraphs).
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+type InlineNode<TStyles extends StyleSheet = StyleSheet> = ImageNode<TStyles> | TextNode<TStyles>;
+/**
+ * A forced page break.
+ */
+interface PageBreakNode {
+  type: 'pageBreak';
+}
+/**
+ * A paragraph containing text and/or inline children.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface ParagraphNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  type: 'paragraph';
+  /** Inline children (text runs, inline images, etc.). */
+  children?: InlineNode<TStyles>[];
+  /** Plain-text content (used when `children` is not provided). */
+  text?: string;
+}
+/**
+ * A plugin-invocation node.
+ *
+ * Plugins extend the DSL with arbitrary content types.
+ *
+ * @template TName — Plugin name (string literal)
+ * @template TOptions — Plugin-specific options shape
+ * @template TStyles — The user's stylesheet type
+ */
+interface PluginNode<TName extends string = string, TOptions = unknown, TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Registered plugin name. */
+  name: TName;
+  /** Plugin-specific options. */
+  options: TOptions;
+  type: 'plugin';
+}
+/**
+ * A column definition for a table.
+ *
+ * @template TData — The row data type
+ */
+interface TableColumn<TData extends Record<string, unknown> = Record<string, unknown>> {
+  /** Key in the data object this column maps to. */
+  key: Extract<keyof TData, string>;
+  /** Column header text. */
+  title: string;
+  /** Cell text alignment. */
+  align?: 'center' | 'left' | 'right';
+  /** Column width. Supports percentage strings (e.g. `"30%"`). */
+  width?: UnitValue;
+  /**
+   * Custom cell renderer.
+   *
+   * Receives the raw value, full row data, and row index.
+   * Returns a string or inline nodes.
+   */
+  render?: (value: TData[keyof TData], row: TData, index: number) => string | InlineNode[];
+}
+/**
+ * A table node with column definitions and data rows.
+ *
+ * @template TData — The row data type
+ * @template TStyles — The user's stylesheet type
+ */
+interface TableNode<TData extends Record<string, unknown> = Record<string, unknown>, TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Column definitions. */
+  columns: TableColumn<TData>[];
+  /** Row data objects. */
+  data: TData[];
+  type: 'table';
+  /** Show table borders. */
+  bordered?: boolean;
+  /** Default cell style for data rows. */
+  cellStyle?: DocxStyleRule;
+  /** Show header row (default: `true`). */
+  header?: boolean;
+  /** Style for header cells. */
+  headerCellStyle?: DocxStyleRule;
+  /** Alternate row shading. */
+  striped?: boolean;
+}
+/**
+ * A text run node (inline content).
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface TextNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Text content. */
+  text: string;
+  type: 'text';
+}
+//#endregion
+//#region src/types/document.d.ts
+/**
+ * Top-level configuration passed to `createDocx()`.
+ *
+ * Covers page setup, stylesheet, theme tokens, element defaults,
+ * and document metadata.
+ *
+ * @template TStyles — The user's stylesheet type (inferred from `styles`).
+ */
+interface DocxKitConfig<TStyles extends StyleSheet = StyleSheet> {
+  /** Page dimensions and margins. */
+  page?: PageConfig;
+  /** Named style classes (class → style rule map). */
+  styles?: TStyles;
+  /** Semantic design tokens for theming. */
+  theme?: DocxTheme;
+  /** Default styles applied as base for each element type. */
+  defaults?: {
+    /** Default table cell style. */cell?: DocxStyleRule; /** Default paragraph style. */
+    paragraph?: DocxStyleRule; /** Default table style. */
+    table?: DocxStyleRule; /** Default text run style. */
+    text?: DocxStyleRule;
+  };
+  /** OOXML core properties (appear in File → Info). */
+  metadata?: {
+    /** Document author. */creator?: string; /** Document description / summary. */
+    description?: string; /** Keywords / tags. */
+    keywords?: string[]; /** Last editor. */
+    lastModifiedBy?: string; /** Document subject. */
+    subject?: string; /** Document title. */
+    title?: string;
+  };
+}
+/**
+ * Theme tokens that can be referenced in styles.
+ *
+ * Allows defining a single source of truth for colors, fonts,
+ * font sizes, and spacing values.
+ */
+interface DocxTheme {
+  /** Color palette (name → hex). */
+  colors?: Record<string, string>;
+  /** Font family tokens (name → font family). */
+  fontFamily?: Record<string, string>;
+  /** Font size tokens (name → value). */
+  fontSize?: Record<string, UnitValue>;
+  /** Spacing tokens (name → value). */
+  spacing?: Record<string, UnitValue>;
+}
+/** Page orientation. */
+type Orientation = 'landscape' | 'portrait';
+/**
+ * Page configuration (size, orientation, margin).
+ */
+interface PageConfig {
+  /** Page orientation (`"portrait"` default). */
+  orientation?: Orientation;
+  /** Page size: preset name or explicit dimensions. */
+  size?: PageSize | {
+    height: UnitValue;
+    width: UnitValue;
+  };
+  /**
+   * Page margin.
+   *
+   * Supports 1-value, 2-value, and 4-value shorthand
+   * (e.g. `"20mm"`, `"20mm 15mm"`, `"20mm 15mm 25mm 15mm"`).
+   */
+  margin?: `${string} ${string}` | `${string} ${string} ${string} ${string}` | UnitValue;
+}
+/** Available page size presets. */
+type PageSize = 'A3' | 'A4' | 'Legal' | 'Letter';
+//#endregion
+//#region src/types/plugin.d.ts
+/**
+ * A docx-kit plugin.
+ *
+ * Plugins have a unique `name`, an optional `setup` hook,
+ * and a required `render` function that receives user options
+ * and a rendering context.
+ *
+ * @template TName — The plugin name (string literal type)
+ * @template TOptions — The shape of the user-provided options
+ */
+interface DocxPlugin<TName extends string = string, TOptions = unknown> {
+  /** Unique plugin name, used as the node discriminator. */
+  name: TName;
+  /** One-time setup called when the plugin is registered. */
+  setup?: () => MaybePromise<void>;
+  /**
+   * Render plugin content into one or more `docx` objects
+   * (Paragraph, Table, etc.).
+   *
+   * @param options - — User-provided plugin options
+   * @param context - — Rendering context with helper utilities
+   */
+  render: (options: TOptions, context: PluginRenderContext) => MaybePromise<unknown>;
+}
+/**
+ * Type-level map of plugin name → options type.
+ *
+ * Constructed via `Builder.use()` chaining.
+ */
+type PluginRegistry = Record<string, unknown>;
+/**
+ * Rendering context passed to a plugin's `render()` function.
+ *
+ * Provides access to the document config, image utilities,
+ * and the ability to compile child nodes.
+ */
+interface PluginRenderContext {
+  /** The full document config. */
+  config: DocxKitConfig;
+  /** Compile a child node (useful for nesting). */
+  compileNode: (node: BlockNode) => Promise<unknown>;
+  /** Utility helpers. */
+  utils: {
+    image: {
+      /** Convert a Blob to raw image bytes. */fromBlob: (blob: Blob) => Promise<Uint8Array>;
+      /**
+       * Decode a base64 data-URL to raw image bytes.
+       * Works in both browser and Node.js environments.
+       */
+      fromDataUrl: (dataUrl: string) => MaybePromise<Uint8Array>;
+    };
+  };
+}
+/**
+ * Define a type-safe plugin with full inference.
+ *
+ * @param plugin - — The plugin definition object
+ * @returns The same plugin with `const` type inference
+ *
+ * @example
+ * ```ts
+ * const myPlugin = definePlugin<'badge', { text: string }>({
+ *   name: 'badge',
+ *   render: async (opts, ctx) => {
+ *     // ... render logic
+ *     return new Paragraph({ text: opts.text })
+ *   },
+ * })
+ * ```
+ */
+declare function definePlugin<const TName extends string, TOptions>(plugin: DocxPlugin<TName, TOptions>): DocxPlugin<TName, TOptions>;
+//#endregion
+//#region src/builder/DocxBuilder.d.ts
+/**
+ * Fluent document builder.
+ *
+ * Use `createDocx()` to instantiate, then chain `.h1()`, `.p()`, `.table()`,
+ * etc. to build content. Call `.save()`, `.toBlob()`, `.toBuffer()`, or
+ * `.toBase64()` to export the document.
+ *
+ * @template TStyles — Inferred stylesheet type from `config.styles`
+ * @template TPlugins — Accumulated plugin registry (built via `.use()`)
+ */
+declare class DocxBuilder<TStyles extends StyleSheet = StyleSheet, TPlugins extends PluginRegistry = Record<never, never>> {
+  private readonly config;
+  private readonly nodes;
+  private readonly pendingSetups;
+  private readonly pluginMap;
+  constructor(config?: DocxKitConfig<TStyles>);
+  /**
+   * Add a raw DSL node to the document.
+   *
+   * @param node - — Any block-level node
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.add({ type: 'heading', level: 2, text: 'Section' })
+   * doc.add({ type: 'pageBreak' })
+   * ```
+   */
+  add(node: BlockNode<TStyles>): this;
+  /**
+   * Add a level-1 heading.
+   *
+   * @param text - — Heading text
+   * @param options - — Optional style overrides (className, id, style)
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.h1('Introduction', { className: 'title' })
+   * ```
+   */
+  h1(text: string, options?: Omit<Partial<HeadingNode<TStyles>>, 'level' | 'text' | 'type'>): this;
+  /**
+   * Add a level-2 heading.
+   *
+   * @param text - — Heading text
+   * @param options - — Optional style overrides
+   * @returns The builder (for chaining)
+   */
+  h2(text: string, options?: Omit<Partial<HeadingNode<TStyles>>, 'level' | 'text' | 'type'>): this;
+  /**
+   * Add a level-3 heading.
+   *
+   * @param text - — Heading text
+   * @param options - — Optional style overrides
+   * @returns The builder (for chaining)
+   */
+  h3(text: string, options?: Omit<Partial<HeadingNode<TStyles>>, 'level' | 'text' | 'type'>): this;
+  /**
+   * Add a level-4 heading.
+   *
+   * @param text - — Heading text
+   * @param options - — Optional style overrides
+   * @returns The builder (for chaining)
+   */
+  h4(text: string, options?: Omit<Partial<HeadingNode<TStyles>>, 'level' | 'text' | 'type'>): this;
+  /**
+   * Add a level-5 heading.
+   *
+   * @param text - — Heading text
+   * @param options - — Optional style overrides
+   * @returns The builder (for chaining)
+   */
+  h5(text: string, options?: Omit<Partial<HeadingNode<TStyles>>, 'level' | 'text' | 'type'>): this;
+  /**
+   * Add a level-6 heading.
+   *
+   * @param text - — Heading text
+   * @param options - — Optional style overrides
+   * @returns The builder (for chaining)
+   */
+  h6(text: string, options?: Omit<Partial<HeadingNode<TStyles>>, 'level' | 'text' | 'type'>): this;
+  /**
+   * Add an image node.
+   *
+   * @param options - — Image node options (data, width, height, etc.)
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.image({ data: imageBytes, width: 400, height: 300 })
+   * ```
+   */
+  image(options: Omit<ImageNode<TStyles>, 'type'>): this;
+  /**
+   * Add a paragraph.
+   *
+   * @param text - — Paragraph text content
+   * @param options - — Optional style overrides (className, id, style)
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.p('Hello world', { className: 'body', style: { textAlign: 'center' } })
+   * ```
+   */
+  p(text: string, options?: Omit<Partial<ParagraphNode<TStyles>>, 'text' | 'type'>): this;
+  /**
+   * Add a forced page break.
+   *
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.h1('Chapter 1').pageBreak().h1('Chapter 2')
+   * ```
+   */
+  pageBreak(): this;
+  /**
+   * Invoke a registered plugin.
+   *
+   * @param name - — Plugin name (must match a previously registered plugin)
+   * @param options - — Plugin-specific options
+   * @param style - — Optional inline style for the plugin's container
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.use(qrcodePlugin()).plugin('qrcode', { text: 'https://example.com' })
+   * ```
+   */
+  plugin<TName extends string & keyof TPlugins>(name: TName, options: TPlugins[TName], style?: DocxStyleRule): this;
+  /**
+   * Save the document to a file (Node.js only).
+   *
+   * **⚠️ Not available in browser environments.**
+   * Use {@link toBlob} and trigger a download instead.
+   *
+   * @param filename - — Output file path (e.g. `"report.docx"`)
+   *
+   * @example
+   * ```ts
+   * await doc.save('output.docx')
+   * ```
+   */
+  save(filename: string): Promise<void>;
+  /**
+   * Add a table.
+   *
+   * @param options - — Table node options (columns, data, style, etc.)
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.table({
+   *   columns: [
+   *     { key: 'name', title: 'Name' },
+   *     { key: 'value', title: 'Value', align: 'right' },
+   *   ],
+   *   data: [{ name: 'Revenue', value: '$1.2M' }],
+   *   headerCellStyle: { fontWeight: 'bold' },
+   * })
+   * ```
+   */
+  table<TData extends Record<string, unknown>>(options: Omit<TableNode<TData, TStyles>, 'type'>): this;
+  /**
+   * Export the document as a base64-encoded string.
+   *
+   * @returns Base64-encoded .docx data
+   *
+   * @example
+   * ```ts
+   * const b64 = await doc.toBase64()
+   * // Send b64 over HTTP or store in a database
+   * ```
+   */
+  toBase64(): Promise<string>;
+  /**
+   * Export the document as a `Blob` (browser-friendly).
+   *
+   * @returns A `Blob` containing the .docx binary
+   *
+   * @example
+   * ```ts
+   * const blob = await doc.toBlob()
+   * const url = URL.createObjectURL(blob)
+   * ```
+   */
+  toBlob(): Promise<Blob>;
+  /**
+   * Export the document as a `Uint8Array` (alias for {@link toUint8Array}).
+   *
+   * **Note:** Despite the name, this returns a standard `Uint8Array`,
+   * not a Node.js `Buffer`. Prefer using {@link toUint8Array} for clarity.
+   *
+   * @returns Raw .docx bytes
+   *
+   * @example
+   * ```ts
+   * const bytes = await doc.toBuffer()
+   * fs.writeFileSync('output.docx', bytes)
+   * ```
+   */
+  toBuffer(): Promise<Uint8Array>;
+  /**
+   * Compile and return the internal `docx` {@link Document} instance.
+   *
+   * Useful if you need to further manipulate the document with the
+   * raw `docx` library before packaging.
+   *
+   * @returns A `docx` `Document` object
+   */
+  toDocument(): Promise<import("docx").Document>;
+  /**
+   * Serialize the builder state to a JSON-friendly object.
+   *
+   * Useful for debugging, serialization, or AI-driven document generation.
+   *
+   * @returns The config + content node array as a plain object
+   */
+  toJSON(): {
+    content: BlockNode<TStyles>[];
+    page?: PageConfig;
+    styles?: TStyles | undefined;
+    theme?: DocxTheme;
+    defaults?: {
+      cell?: DocxStyleRule;
+      paragraph?: DocxStyleRule;
+      table?: DocxStyleRule;
+      text?: DocxStyleRule;
+    };
+    metadata?: {
+      creator?: string;
+      description?: string;
+      keywords?: string[];
+      lastModifiedBy?: string;
+      subject?: string;
+      title?: string;
+    };
+  };
+  /**
+   * Export the document as a `Uint8Array` (browser & Node.js).
+   *
+   * This is the preferred cross-platform export method.
+   *
+   * @returns Raw .docx bytes
+   *
+   * @example
+   * ```ts
+   * const bytes = await doc.toUint8Array()
+   * // In Node.js: import { writeFileSync } from 'node:fs'
+   * // In browser: trigger a download
+   * ```
+   */
+  toUint8Array(): Promise<Uint8Array>;
+  /**
+   * Register a plugin.
+   *
+   * The plugin's name and options type are accumulated into the builder's
+   * type-level plugin registry, enabling type-safe `.plugin()` calls.
+   *
+   * @param plugin - — The plugin definition returned by `definePlugin()`
+   * @returns The builder with the plugin type merged into `TPlugins`
+   *
+   * @example
+   * ```ts
+   * const doc = createDocx()
+   *   .use(qrcodePlugin())
+   *   .plugin('qrcode', { text: 'https://example.com' })
+   * ```
+   */
+  use<TName extends string, TOptions>(plugin: DocxPlugin<TName, TOptions>): DocxBuilder<TStyles, Record<TName, TOptions> & TPlugins>;
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error handling types and classes for docx-kit.
+ *
+ * @module errors
+ */
+/**
+ * Well-known error codes used throughout the library.
+ *
+ * Consumers can match against these codes for structured error handling.
+ */
+declare const ERROR_CODES: {
+  /** Document export failed. */readonly EXPORT_FAILED: "EXPORT_FAILED"; /** Image data is empty, corrupt, or unsupported. */
+  readonly IMAGE_INVALID_DATA: "IMAGE_INVALID_DATA"; /** A plugin node referenced an unregistered plugin. */
+  readonly PLUGIN_NOT_REGISTERED: "PLUGIN_NOT_REGISTERED"; /** A plugin's `render()` method threw an error. */
+  readonly PLUGIN_RENDER_FAILED: "PLUGIN_RENDER_FAILED"; /** A `className` referenced a stylesheet key that doesn't exist. */
+  readonly STYLE_UNKNOWN_CLASS: "STYLE_UNKNOWN_CLASS"; /** Table was created with no columns. */
+  readonly TABLE_INVALID_COLUMNS: "TABLE_INVALID_COLUMNS"; /** Encountered a node type that has no registered compiler. */
+  readonly UNKNOWN_NODE_TYPE: "UNKNOWN_NODE_TYPE";
+};
+/** Union type of all known error codes. */
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * Structured error class for docx-kit.
+ *
+ * Carries a machine-readable `code`, a human-readable `message`,
+ * and optionally the underlying `cause`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await doc.save('output.docx')
+ * } catch (err) {
+ *   if (err instanceof DocxKitError && err.code === ERROR_CODES.EXPORT_FAILED) {
+ *     console.error('Export failed:', err.message)
+ *   }
+ * }
+ * ```
+ */
+declare class DocxKitError extends Error {
+  /** The underlying error that caused this failure (if any). */
+  readonly cause: unknown;
+  /** Machine-readable error code. */
+  readonly code: string | ErrorCode;
+  /**
+   * @param code - — Known error code from {@link ERROR_CODES}
+   * @param message - — Human-readable description
+   * @param cause - — Optional underlying error
+   */
+  constructor(code: string | ErrorCode, message: string, cause?: unknown);
+}
+//#endregion
+//#region src/plugins/qrcode/index.d.ts
+/**
+ * QR Code plugin — embeds a QR code image in the document.
+ *
+ * Uses the `qrcode` package (peer dependency) to generate
+ * a QR code PNG and renders it as an inline `ImageRun`.
+ *
+ * @module plugins/qrcode
+ *
+ * @example
+ * ```ts
+ * const doc = createDocx()
+ *   .use(qrcodePlugin())
+ *   .h1('Scan Me')
+ *   .plugin('qrcode', { text: 'https://example.com', caption: 'Visit us' })
+ *   .save('qrcode.docx')
+ * ```
+ */
+/**
+ * Options for the QRCode plugin.
+ */
+interface QRCodePluginOptions {
+  /** The text / URL to encode. */
+  text: string;
+  /** Optional caption text displayed below the QR code. */
+  caption?: string;
+  /**
+   * QR error correction level.
+   *
+   * - `"L"` — ~7% recovery
+   * - `"M"` — ~15% recovery
+   * - `"Q"` — ~25% recovery
+   * - `"H"` — ~30% recovery
+   *
+   * @default "M"
+   */
+  errorCorrectionLevel?: 'H' | 'L' | 'M' | 'Q';
+  /** QR code margin (in modules). @default 1 */
+  margin?: number;
+  /** QR code image size in pixels. @default 128 */
+  size?: number;
+}
+/**
+ * Create a QRCode plugin instance.
+ *
+ * The plugin dynamically imports the `qrcode` package at render time,
+ * keeping it an optional peer dependency of docx-kit core.
+ *
+ * @returns A configured DocxPlugin for `'qrcode'`
+ *
+ * @example
+ * ```ts
+ * import { createDocx, qrcodePlugin } from 'docx-kit'
+ *
+ * const doc = createDocx()
+ *   .use(qrcodePlugin())
+ *   .plugin('qrcode', {
+ *     text: 'https://example.com',
+ *     size: 256,
+ *     errorCorrectionLevel: 'H',
+ *     caption: 'Scan to visit',
+ *   })
+ * ```
+ */
+declare function qrcodePlugin(): DocxPlugin<"qrcode", QRCodePluginOptions>;
+//#endregion
+//#region src/utils/dataUrl.d.ts
+/**
+ * Cross-platform base64 data-URL decoder.
+ *
+ * Auto-detects the runtime environment and uses the appropriate
+ * implementation:
+ * - **Node.js**: `Buffer.from(base64, 'base64')`
+ * - **Browser**: `atob(base64)` + manual byte population
+ *
+ * This is the internal shared version used by the compiler and
+ * built-in plugins. For platform-specific direct access, import
+ * from `'docx-kit/node'` or `'docx-kit/browser'`.
+ *
+ * @module utils/dataUrl
+ */
+/**
+ * Decode a base64 data-URL to raw bytes (works in both browser & Node.js).
+ *
+ * Strips the `"data:*;base64,"` prefix and decodes using the appropriate
+ * runtime API.
+ *
+ * @param dataUrl - — A base64 data-URI string (e.g. `"data:image/png;base64,iVBO..."`)
+ * @returns Raw bytes as `Uint8Array`
+ *
+ * @example
+ * ```ts
+ * import { dataUrlToUint8Array } from 'docx-kit'
+ *
+ * const bytes = await dataUrlToUint8Array('data:image/png;base64,iVBORw...')
+ * ```
+ */
+declare function dataUrlToUint8Array(dataUrl: string): Promise<Uint8Array>;
+//#endregion
+//#region src/plugins/echarts/index.d.ts
+/**
+ * Options for the ECharts plugin.
+ */
+interface EChartsPluginOptions {
+  /** Full ECharts option object (series, axes, title, etc.). */
+  option: EChartsOption;
+  /** Optional caption text displayed below the chart. */
+  caption?: string;
+  /** Chart height in pixels. @default 360 */
+  height?: number;
+  /** Output image format. @default "png" */
+  imageType?: 'png' | 'svg';
+  /** ECharts rendering engine. @default "canvas" */
+  renderer?: 'canvas' | 'svg';
+  /** Chart width in pixels. @default 640 */
+  width?: number;
+}
+/**
+ * Create an ECharts plugin instance.
+ *
+ * The plugin renders charts using the browser DOM. In Node.js
+ * environments, it throws an error prompting the user to provide
+ * a server-side canvas implementation.
+ *
+ * @returns A configured DocxPlugin for `'echarts'`
+ *
+ * @example
+ * ```ts
+ * import { createDocx, echartsPlugin } from 'docx-kit'
+ *
+ * const doc = createDocx()
+ *   .use(echartsPlugin())
+ *   .plugin('echarts', {
+ *     option: {
+ *       title: { text: 'Revenue' },
+ *       xAxis: { type: 'category', data: ['Q1', 'Q2', 'Q3', 'Q4'] },
+ *       yAxis: { type: 'value' },
+ *       series: [{ data: [820, 932, 901, 1347], type: 'line' }],
+ *     },
+ *     caption: 'Quarterly revenue trend',
+ *   })
+ * ```
+ */
+declare function echartsPlugin(): DocxPlugin<"echarts", EChartsPluginOptions>;
+//#endregion
+//#region src/builder/createDocx.d.ts
+/**
+ * JSON schema for `renderDocx()`.
+ *
+ * The schema is deliberately simple — a flat config object plus an
+ * ordered array of block nodes. This makes it easy to generate from
+ * AI / LLMs or store as JSON.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface DocxSchema<TStyles extends StyleSheet = StyleSheet> {
+  /** Ordered array of block nodes. */
+  content: BlockNode<TStyles>[];
+  /** Optional page configuration. */
+  page?: DocxKitConfig<TStyles>['page'];
+  /** Named stylesheet entries. */
+  styles?: TStyles;
+}
+/**
+ * Create a new DocxBuilder with optional configuration.
+ *
+ * This is the primary entry point for the fluent builder API.
+ * Chain `.h1()`, `.p()`, `.table()`, etc. and call `.save()`
+ * or `.toBlob()` to export.
+ *
+ * @param config - — Document configuration (page, styles, metadata, theme, defaults)
+ * @returns A new `DocxBuilder` instance
+ *
+ * @example
+ * ```ts
+ * const styles = defineStyles({
+ *   title: { fontSize: 28, fontWeight: 'bold' },
+ *   body:  { fontSize: 12, lineHeight: 1.5 },
+ * })
+ *
+ * const doc = createDocx({
+ *   styles,
+ *   page: { size: 'A4', margin: '20mm' },
+ *   metadata: { title: 'Report', creator: 'docx-kit' },
+ * })
+ *
+ * await doc
+ *   .h1('Annual Report', { className: 'title' })
+ *   .p('Lorem ipsum...', { className: 'body' })
+ *   .save('report.docx')
+ * ```
+ */
+declare function createDocx<const TStyles extends StyleSheet = StyleSheet>(config?: DocxKitConfig<TStyles>): DocxBuilder<TStyles, Record<never, never>>;
+/**
+ * Render a document from a JSON schema (AI-friendly / serializable DSL).
+ *
+ * Unlike `createDocx()`, this accepts a single JSON-serializable object
+ * with `content` (node array), optional `styles`, and optional `page` config.
+ * Ideal for AI-driven document generation or API integrations.
+ *
+ * @param schema - — The `DocxSchema` object
+ * @returns A `DocxBuilder` instance (ready to export)
+ *
+ * @example
+ * ```ts
+ * const blob = await renderDocx({
+ *   page: { size: 'A4', margin: '20mm' },
+ *   styles: {
+ *     h1: { fontSize: 24, fontWeight: 'bold' },
+ *     p:  { fontSize: 12 },
+ *   },
+ *   content: [
+ *     { type: 'heading',  level: 1, text: 'Report', className: 'h1' },
+ *     { type: 'paragraph', text: 'This is a report generated via JSON DSL.', className: 'p' },
+ *     { type: 'pageBreak' },
+ *     {
+ *       type: 'table',
+ *       columns: [{ key: 'name', title: 'Name' }, { key: 'value', title: 'Value' }],
+ *       data: [{ name: 'Revenue', value: '$1.2M' }],
+ *     },
+ *   ],
+ * }).toBlob()
+ * ```
+ */
+declare function renderDocx<const TStyles extends StyleSheet = StyleSheet>(schema: DocxSchema<TStyles>): DocxBuilder<TStyles>;
+//#endregion
+export { type BaseNode, type BlockNode, type BorderRule, type BorderStyle, type ClassName, DocxBuilder, type DocxKitConfig, DocxKitError, type DocxPlugin, type DocxSchema, type DocxStyleRule, type DocxTheme, type EChartsPluginOptions, ERROR_CODES, type ErrorCode, type FontWeight, type HeadingNode, type ImageNode, type InlineNode, type Orientation, type PageBreakNode, type PageConfig, type PageSize, type ParagraphNode, type PluginNode, type PluginRegistry, type PluginRenderContext, type QRCodePluginOptions, type StyleSheet, type TableColumn, type TableNode, type TextAlign, type TextNode, type VerticalAlign, createDocx, dataUrlToUint8Array, definePlugin, defineStyles, echartsPlugin, qrcodePlugin, renderDocx };