Authoring Custom Plugins for `@m2d/core`

import type { IPlugin, Root, EmptyNode } from "@m2d/core";
import type * as docx from "docx";

export interface IPlugin<T extends Node = EmptyNode> {
  /** Modifies or enriches the AST before rendering begins */
  preprocess?: (
    tree: Root,
    docxProps: IDocxProps,
    sectionProps?: ISectionProps,
  ) => void | Promise<void>;

  /** Handles block-level elements (paragraphs, tables, callouts) */
  block?: (
    docxModule: typeof docx,
    node: ExtendedRootContent<T>,
    paraProps: MutableParaOptions,
    blockChildrenProcessor: BlockNodeChildrenProcessor,
    inlineChildrenProcessor: InlineChildrenProcessor,
  ) => (docx.Paragraph | docx.Table)[];

  /** Handles phrasing/inline-level elements (runs, badges, links) */
  inline?: (
    docxModule: typeof docx,
    node: ExtendedPhrasingContent<T>,
    runProps: docx.IRunOptions,
    inlineChildrenProcessor: InlineChildrenProcessor,
  ) => docx.IRun[];

  /** Final cleanup or cache flushing after document packaging */
  postprocess?: (sections: docx.ISectionOptions[]) => void | Promise<void>;
}

flowchart TD
    A["Input Markdown AST (Root)"] --> B["preprocess(tree, docxProps, sectionProps)"]
    B --> C["Section Parsing & Hierarchy Resolution"]
    C --> D{"AST Node Classification"}
    D -->|"Block Node"| E["plugin.block(docx, node, paraProps, ...)"]
    D -->|"Phrasing / Inline Node"| F["plugin.inline(docx, node, runProps, ...)"]
    E --> G["Word Document Assembly"]
    F --> G
    G --> H["postprocess(sections)"]
    H --> I["Packer: Blob / Buffer / Uint8Array"]