@json-to-office/core-docx 0.38.1 → 1.1.0

package/dist/components/highcharts.d.ts

@@ -1,10 +1,14 @@
 /**
- * Highcharts Component
- * Standard component for generating charts using Highcharts Export Server
+ * The `highcharts` component: a chart drawn by an export server.
+ *
+ * Nothing here renders a document. A chart has no OOXML form of its own — it
+ * becomes a PNG and then an `image` — so what lives here is the request the
+ * export server needs, the theme palette that goes into it, and the image props
+ * the result desugars to.
  */
-import { Paragraph, Table } from 'docx';
-import { ComponentDefinition, RenderContext } from '../types';
 import { ThemeConfig } from '../styles';
+import type { HighchartsProps } from '@json-to-office/shared-docx';
+import type { HighchartsServiceConfig } from '@json-to-office/shared';
 export type { HighchartsProps } from '@json-to-office/shared-docx';
 /**
  * Chart generation result
@@ -15,7 +19,13 @@ export interface ChartGenerationResult {
     height: number;
 }
 /**
- * Render highcharts component
+ * Map a chart's props to the `image` props it desugars to.
+ *
+ * Shared by the render-time component and the DocxIR desugaring pass so the two
+ * cannot drift on the one decision that is not obvious: an explicit `width` or
+ * `height` on the component replaces the chart's own canvas size outright,
+ * rather than merging with it — stating one and inheriting the other would
+ * distort the chart.
  */
-export declare function renderHighchartsComponent(component: ComponentDefinition, theme: ThemeConfig, themeName: string, context?: RenderContext): Promise<(Paragraph | Table)[]>;
+export declare function renderChartToImageProps(props: HighchartsProps, theme: ThemeConfig, servicesConfig?: HighchartsServiceConfig): Promise<Record<string, unknown>>;
 //# sourceMappingURL=highcharts.d.ts.map

package/dist/components/highcharts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"highcharts.d.ts","sourceRoot":"","sources":["../../src/components/highcharts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AACxC,OAAO,EACL,mBAAmB,EACnB,aAAa,EAEd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAYxC,YAAY,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AA6GD;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,mBAAmB,EAC9B,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,CAAC,SAAS,GAAG,KAAK,CAAC,EAAE,CAAC,CA+BhC"}
+{"version":3,"file":"highcharts.d.ts","sourceRoot":"","sources":["../../src/components/highcharts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAMxC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAItE,YAAY,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AA6GD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,WAAW,EAClB,cAAc,CAAC,EAAE,uBAAuB,GACvC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAalC"}

package/dist/components/index.d.ts

@@ -1,18 +1,12 @@
 /**
- * Standard and Custom Components
- * This folder contains all components that extend the document generator
+ * Components with behaviour of their own.
+ *
+ * Not a renderer registry: the DocxIR compiler knows every standard component
+ * by name. What is left here is the two components that need an external
+ * service before they can become anything — a `visual` and a `highcharts`, both
+ * of which desugar to an image — and the bundled custom component.
  */
-export { renderHeadingComponent } from './heading';
-export { renderParagraphComponent } from './paragraph';
-export { renderListComponent } from './list';
-export { renderImageComponent } from './image';
-export { renderTextBoxComponent } from './text-box';
-export { renderTableComponent } from './table';
-export { renderSectionComponent } from './section';
-export { renderColumnsComponent } from './columns';
-export { renderStatisticComponent } from './statistic';
-export { renderTocComponent } from './toc';
-export { renderHighchartsComponent } from './highcharts';
-export { renderVisualComponent } from './visual';
+export { buildVisualPresentation, defaultVisualWidthPx, effectiveVisualServerUrl, rasterizeVisualSlide, visualRasterKey, visualToImageOptions, visualToImageProps, type ImageOptions, } from './visual';
+export { renderChartToImageProps, type ChartGenerationResult, type HighchartsProps, } from './highcharts';
 export { textSpaceAfterComponent } from './text-space-after';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,YAAY,GAClB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/components/visual.d.ts

@@ -1,42 +1,88 @@
 /**
- * Visual Component
+ * The `visual` component: a free-canvas graphic authored as a single pptx
+ * slide.
  *
- * Renders a free-canvas graphic authored as a single pptx slide and embeds it
- * as a rasterized PNG. The slide is rendered to an image by an injected
- * rasterization service (`services.pptx`) — exactly the way the `highcharts`
- * component offloads chart rendering to an export server — then desugars to a
- * plain `image`.
+ * Nothing here renders a document. A visual has no OOXML form of its own — an
+ * injected rasterization service (`services.pptx`) draws the slide into a PNG
+ * and it becomes a plain `image`, exactly as a `highcharts` becomes one. What
+ * lives here is the presentation that gets sent, the identity that keys the
+ * batch, and the image props the result desugars to.
  */
-import { Paragraph, Table } from 'docx';
-import { ComponentDefinition, RenderContext } from '../types';
-import { ThemeConfig } from '../styles';
-import { type ImageOptions } from '../core/content';
-import type { VisualProps } from '@json-to-office/shared-docx';
-import { type PptxServiceConfig, type PptxRasterizeResult, type RasterizeFontFace } from '@json-to-office/shared';
+import type { VisualRasterProps } from '@json-to-office/shared-docx';
+import type { PptxServiceConfig, PptxRasterizeResult, RasterizeFontFace } from '@json-to-office/shared';
 export declare const DEFAULT_RASTERIZE_SERVER_URL = "http://localhost:7802";
 /**
  * Build a single-slide pptx presentation component definition from visual props.
  * The shape mirrors a normal `.pptx.json` document so the pptx engine renders
  * it unchanged. Exported for reuse by the `flattenVisuals` transform.
  */
-export declare function buildVisualPresentation(props: VisualProps): Record<string, unknown>;
+export declare function buildVisualPresentation(props: VisualRasterProps): Record<string, unknown>;
+/**
+ * Where an image sits on the page, and how big it is.
+ *
+ * The authoring surface of the `image` component a visual desugars into, so
+ * this is the shape a visual's placement props have to land in.
+ */
+export interface ImageOptions {
+    caption?: string;
+    width?: number | string;
+    height?: number | string;
+    widthRelativeTo?: 'content' | 'page';
+    heightRelativeTo?: 'content' | 'page';
+    alignment?: 'left' | 'center' | 'right';
+    spacing?: {
+        before?: number;
+        after?: number;
+    };
+    floating?: {
+        horizontalPosition?: {
+            relative?: 'character' | 'column' | 'margin' | 'page' | 'text';
+            align?: 'left' | 'center' | 'right' | 'inside' | 'outside';
+            offset?: number | string;
+        };
+        verticalPosition?: {
+            relative?: 'margin' | 'page' | 'paragraph' | 'line' | 'text';
+            align?: 'top' | 'center' | 'bottom' | 'inside' | 'outside';
+            offset?: number | string;
+        };
+        wrap?: {
+            type: 'none' | 'square' | 'topAndBottom' | 'around' | 'tight' | 'through';
+            side?: 'bothSides' | 'left' | 'right' | 'largest';
+            margins?: {
+                top?: number | string;
+                bottom?: number | string;
+                left?: number | string;
+                right?: number | string;
+            };
+        };
+        allowOverlap?: boolean;
+        behindDocument?: boolean;
+        lockAnchor?: boolean;
+        layoutInCell?: boolean;
+        zIndex?: number;
+        rotation?: number;
+        visibility?: 'hidden' | 'inherit';
+    };
+    keepNext?: boolean;
+    keepLines?: boolean;
+}
 /**
  * Default rendered width (px) for a visual: its physical canvas inches, so a
  * 6×4 canvas prints 6×4 unless `width` overrides.
  */
-export declare function defaultVisualWidthPx(props: VisualProps): number;
+export declare function defaultVisualWidthPx(props: VisualRasterProps): number;
 /**
  * Shared image-placement options derived from a visual's props. Used by BOTH
- * the render-time createImage call and the flatten transform so the two
- * desugaring paths can't drift (width default, alignment default, caption,
- * spacing, floating, keepNext/keepLines all live here once).
+ * desugaring paths — the generation pre-pass and the offline flatten transform
+ * — so the two cannot drift: width default, alignment default, caption,
+ * spacing, floating and the keep flags all live here once.
  */
-export declare function visualToImageOptions(props: VisualProps): ImageOptions;
+export declare function visualToImageOptions(props: VisualRasterProps): ImageOptions;
 /**
  * Map visual props to the `image` props they desugar to (used by the
  * `flattenVisuals` transform to produce a portable, service-free document).
  */
-export declare function visualToImageProps(props: VisualProps, base64DataUri: string): Record<string, unknown>;
+export declare function visualToImageProps(props: VisualRasterProps, base64DataUri: string): Record<string, unknown>;
 /**
  * Identity of one visual rasterization: content + resolution + (for HTTP
  * services) the target server. Keys the per-document pre-rasterization map
@@ -61,7 +107,7 @@ export declare function visualRasterKey(presentation: unknown, dpi: number, serv
  * actually do or the same visual could rasterize against two different
  * services depending on cache luck.
  */
-export declare function effectiveVisualServerUrl(props: VisualProps, serviceConfig: PptxServiceConfig | undefined): string | undefined;
+export declare function effectiveVisualServerUrl(props: VisualRasterProps, serviceConfig: PptxServiceConfig | undefined): string | undefined;
 /**
  * Rasterize a single-slide presentation to a PNG via the configured service.
  * An in-process `render` callback takes precedence over an HTTP `serverUrl`.
@@ -75,8 +121,4 @@ export declare function rasterizeVisualSlide(presentation: Record<string, unknow
  * what it was before fonts existed.
  */
 fonts?: readonly RasterizeFontFace[]): Promise<PptxRasterizeResult>;
-/**
- * Render visual component
- */
-export declare function renderVisualComponent(component: ComponentDefinition, theme: ThemeConfig, themeName?: string, context?: RenderContext): Promise<(Paragraph | Table)[]>;
 //# sourceMappingURL=visual.d.ts.map

package/dist/components/visual.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"visual.d.ts","sourceRoot":"","sources":["../../src/components/visual.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AACxC,OAAO,EACL,mBAAmB,EACnB,aAAa,EAEd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAKjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACvB,MAAM,wBAAwB,CAAC;AAEhC,eAAO,MAAM,4BAA4B,0BAA0B,CAAC;AAIpE;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,WAAW,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBzB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAWrE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,MAAM,GACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,OAAO,EACrB,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAIR;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,iBAAiB,GAAG,SAAS,GAC3C,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,aAAa,EAAE,iBAAiB,GAAG,SAAS,EAC5C,OAAO,EAAE,MAAM,GAAG,SAAS;AAC3B;;;;GAIG;AACH,KAAK,CAAC,EAAE,SAAS,iBAAiB,EAAE,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAuD9B;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,mBAAmB,EAC9B,KAAK,EAAE,WAAW,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,CAAC,SAAS,GAAG,KAAK,CAAC,EAAE,CAAC,CAmDhC"}
+{"version":3,"file":"visual.d.ts","sourceRoot":"","sources":["../../src/components/visual.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAEhC,eAAO,MAAM,4BAA4B,0BAA0B,CAAC;AAIpE;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IACrC,gBAAgB,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IACxC,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,kBAAkB,CAAC,EAAE;YACnB,QAAQ,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;YAC/D,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;YAC3D,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;SAC1B,CAAC;QACF,gBAAgB,CAAC,EAAE;YACjB,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;YAC7D,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;YAC3D,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;SAC1B,CAAC;QACF,IAAI,CAAC,EAAE;YAEL,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,cAAc,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;YAC1E,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;YAClD,OAAO,CAAC,EAAE;gBACR,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;gBACtB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;gBACzB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;gBACvB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;aACzB,CAAC;SACH,CAAC;QACF,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;KACnC,CAAC;IAEF,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CAW3E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,iBAAiB,EACxB,aAAa,EAAE,MAAM,GACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,OAAO,EACrB,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAIR;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,iBAAiB,EACxB,aAAa,EAAE,iBAAiB,GAAG,SAAS,GAC3C,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,aAAa,EAAE,iBAAiB,GAAG,SAAS,EAC5C,OAAO,EAAE,MAAM,GAAG,SAAS;AAC3B;;;;GAIG;AACH,KAAK,CAAC,EAAE,SAAS,iBAAiB,EAAE,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAuD9B"}

package/dist/core/collectTocHeadings.d.ts

@@ -40,7 +40,21 @@
  * come later in the document) and each list's item counters.
  */
 import type { SectionLayout } from './layout';
-import type { NumberedItemInfo } from '../utils/numberedItemsRegistry';
+/**
+ * A cross-reference target: a numbered heading or list item.
+ *
+ * Resolved by the outline pre-pass and read back while text is compiled, which
+ * is why a `[@id]` can point at something further down the document.
+ */
+export interface NumberedItemInfo {
+    kind: 'heading' | 'list-item';
+    /** Rendered text of the target, for a `:none` (text) reference. */
+    text: string;
+    /** Full multilevel number ("2.1.3"), absent when the target is unnumbered. */
+    full?: string;
+    /** The target's own level counter ("3"), absent when unnumbered. */
+    own?: string;
+}
 export interface TocHeadingEntry {
     /** Rendered text, with markdown decorators stripped as `createHeading` does. */
     title: string;

package/dist/core/collectTocHeadings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collectTocHeadings.d.ts","sourceRoot":"","sources":["../../src/core/collectTocHeadings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAQ9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAKvE,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,0EAA0E;IAC1E,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC9C;AAOD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMxD;AA8CD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,aAAa,EAAE,GACjC,eAAe,CAoLjB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,aAAa,EAAE,GACjC,eAAe,EAAE,CAEnB"}
+{"version":3,"file":"collectTocHeadings.d.ts","sourceRoot":"","sources":["../../src/core/collectTocHeadings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAQ9C;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,GAAG,WAAW,CAAC;IAC9B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAKD,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,0EAA0E;IAC1E,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC9C;AAOD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMxD;AA8CD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,aAAa,EAAE,GACjC,eAAe,CAkLjB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,aAAa,EAAE,GACjC,eAAe,EAAE,CAEnB"}

package/dist/core/componentTransform.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Walk a document tree and replace components.
+ *
+ * The docx model holds child components in more places than `children`: a
+ * section's `header` and `footer`, and a table's `columns[].header.content` and
+ * `columns[].cells[].content`. Any transform that misses one of those quietly
+ * leaves part of the document behind, which is exactly the kind of bug that
+ * only shows up in the one template that puts a chart in a table cell.
+ *
+ * So the walk lives here, once, and transforms supply only the decision about
+ * what to replace.
+ */
+/**
+ * Decide what one component becomes.
+ *
+ * Return a replacement node to substitute it — the walk does not descend into
+ * a replacement — or `undefined` to leave the node alone and keep walking.
+ */
+export type ComponentReplacer = (node: Record<string, unknown>) => Promise<Record<string, unknown> | undefined>;
+/** Return a deep copy of `doc` with `replace` applied to every component. */
+export declare function transformComponents<T>(doc: T, replace: ComponentReplacer): Promise<T>;
+/**
+ * Carry a node's identity and visibility onto its replacement.
+ *
+ * A desugared node is still the component the author wrote: an `id` other
+ * things link to, and an `enabled` flag something downstream may act on, both
+ * have to survive the substitution.
+ */
+export declare function withNodeIdentity(original: Record<string, unknown>, replacement: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=componentTransform.d.ts.map

package/dist/core/componentTransform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"componentTransform.d.ts","sourceRoot":"","sources":["../../src/core/componentTransform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;AAElD,6EAA6E;AAC7E,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,GAAG,EAAE,CAAC,EACN,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAkFD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB"}

package/dist/core/desugarExternals.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Turn components that need an external service into plain `image` components,
+ * before anything else looks at the document.
+ *
+ * A `visual` is a nested presentation rendered by LibreOffice; a `highcharts`
+ * is a chart rendered by an export server. Both end up as a PNG in the package,
+ * and neither has an OOXML form of its own — so rather than teaching the
+ * compiler about services, they are desugared here and the compiler only ever
+ * sees an image.
+ *
+ * That keeps compilation a pure function of the document. Everything that can
+ * fail, block on a network call or depend on a machine's LibreOffice happens in
+ * this pass; what comes out is a document that builds anywhere.
+ */
+import { type RasterizeFontFace, type ServicesConfig } from '@json-to-office/shared';
+import type { ThemeConfig } from '../styles';
+export interface DesugarExternalsOptions {
+    theme: ThemeConfig;
+    services?: ServicesConfig;
+    /** Directory relative asset paths inside a visual resolve against. */
+    baseDir?: string;
+    /** Font faces staged for each visual's LibreOffice render. */
+    visualFonts?: readonly RasterizeFontFace[];
+}
+/**
+ * Replace every `visual` and `highcharts` in `document` with its image.
+ *
+ * Visuals are rasterized in one batch first: the document walk is sequential,
+ * and without the batch each visual would cost its own service round trip and
+ * its own LibreOffice launch — about twenty-five of each for the bundled
+ * templates. The batch is only an accelerator, though: anything it misses, or a
+ * batch that fails outright, falls back to rasterizing that visual on its own.
+ */
+export declare function desugarExternals<T>(document: T, options: DesugarExternalsOptions): Promise<T>;
+//# sourceMappingURL=desugarExternals.d.ts.map

package/dist/core/desugarExternals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desugarExternals.d.ts","sourceRoot":"","sources":["../../src/core/desugarExternals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAOhC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAY7C,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,CAAC,CAAC,CA4CZ"}

package/dist/core/flattenVisuals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flattenVisuals.d.ts","sourceRoot":"","sources":["../../src/core/flattenVisuals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACvB,MAAM,wBAAwB,CAAC;AAYhC,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtC;AAUD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,CAAC,GAAG,OAAO,EAC9C,GAAG,EAAE,CAAC,EACN,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,CAAC,CAAC,CA+CZ"}
+{"version":3,"file":"flattenVisuals.d.ts","sourceRoot":"","sources":["../../src/core/flattenVisuals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACvB,MAAM,wBAAwB,CAAC;AAiBhC,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtC;AAUD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,CAAC,GAAG,OAAO,EAC9C,GAAG,EAAE,CAAC,EACN,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAyDZ"}

package/dist/core/generateFromIr.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The IR-based DOCX generation path.
+ *
+ * Normalisation, theme resolution, font resolution, desugaring of the
+ * service-backed components, structure and layout — and then, instead of
+ * building renderer objects directly, it compiles to DocxIR, checks the
+ * selected backend can express what the document needs, and hands the IR to an
+ * adapter.
+ *
+ * The shape is deliberate: everything asynchronous or fallible happens before
+ * compilation, so compiling is a pure function of the document plus the
+ * resources already in hand. Two compilations of the same document give the
+ * same IR, which is what makes the IR comparable, cacheable and snapshottable.
+ */
+/// <reference types="node" />
+import type { GenerationWarning, ServicesConfig } from '@json-to-office/shared';
+import type { FontRuntimeOpts } from '@json-to-office/shared';
+import { compileDocument, type UnsupportedComponent } from '../ir/compiler';
+import type { DocxIR } from '../ir/types';
+import type { DocxRendererId } from '../renderers/types';
+import type { ThemeConfig } from '../styles';
+import type { ReportComponentDefinition } from '../types';
+import { type GenerationThemeContext } from './generationContext';
+export interface IrDocxGenerationOptions {
+    customThemes?: Record<string, ThemeConfig>;
+    services?: ServicesConfig;
+    fonts?: FontRuntimeOpts;
+    warnings?: GenerationWarning[];
+    baseDir?: string;
+    deterministic?: boolean;
+    generatedAt?: string | Date;
+    /** Backend to render with. Defaults to `docxjs`. */
+    renderer?: DocxRendererId;
+    /**
+     * A prologue already run by the caller.
+     *
+     * The plugin path has to resolve the theme before it expands custom
+     * components — a component's `render` is handed the resolved theme — and
+     * normalises the tree that expansion produced. Passing that result in means
+     * the prologue runs once rather than twice, which matters because the
+     * export-mode pre-pass inside it rewrites the document.
+     */
+    context?: GenerationThemeContext;
+}
+export interface IrDocxGenerationResult {
+    buffer: Buffer;
+    warnings: GenerationWarning[];
+}
+/**
+ * Thrown when the compiler meets something it does not lower yet.
+ *
+ * Silently dropping it would be worse than failing: the document would look
+ * complete and not be. This disappears as the compiler covers the surface.
+ */
+export declare class UncompiledComponentError extends Error {
+    readonly code = "UNCOMPILED_COMPONENT";
+    readonly components: readonly UnsupportedComponent[];
+    constructor(components: readonly UnsupportedComponent[]);
+}
+export interface CompiledDocx {
+    ir: DocxIR;
+    theme: ThemeConfig;
+    warnings: GenerationWarning[];
+    required: ReturnType<typeof compileDocument>['required'];
+    unsupported: UnsupportedComponent[];
+}
+/**
+ * Compile a report definition to DocxIR without rendering it.
+ *
+ * Scoped rather than plain: a relative image path resolves against the
+ * document's own directory, and leaf utilities report warnings into the
+ * caller's collector, both through async-local state that has to be entered
+ * before the walk begins.
+ */
+export declare function compileDocumentToIr(document: ReportComponentDefinition, options?: IrDocxGenerationOptions, collector?: GenerationWarning[]): Promise<CompiledDocx>;
+/** Generate a `.docx` buffer through DocxIR and the selected renderer. */
+export declare function generateBufferViaIr(document: ReportComponentDefinition, options?: IrDocxGenerationOptions): Promise<IrDocxGenerationResult>;
+//# sourceMappingURL=generateFromIr.d.ts.map

package/dist/core/generateFromIr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateFromIr.d.ts","sourceRoot":"","sources":["../../src/core/generateFromIr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAO9D,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAE1D,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,qBAAqB,CAAC;AAK7B,MAAM,WAAW,uBAAuB;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3C,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,SAAgB,IAAI,0BAA0B;IAC9C,SAAgB,UAAU,EAAE,SAAS,oBAAoB,EAAE,CAAC;gBAEhD,UAAU,EAAE,SAAS,oBAAoB,EAAE;CAiBxD;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,QAAQ,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,UAAU,CAAC,CAAC;IACzD,WAAW,EAAE,oBAAoB,EAAE,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,yBAAyB,EACnC,OAAO,GAAE,uBAA4B,EACrC,SAAS,CAAC,EAAE,iBAAiB,EAAE,GAC9B,OAAO,CAAC,YAAY,CAAC,CAOvB;AA2FD,0EAA0E;AAC1E,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,yBAAyB,EACnC,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAcjC"}

package/dist/core/generationContext.d.ts

@@ -3,7 +3,7 @@
  *
  * Both entry points — `generateBufferFromJson` (core) and
  * `createDocumentGenerator` (plugin) — must resolve the same theme, apply the
- * same in-document overrides, and derive the same cache key before the
+ * same in-document overrides, and apply the same export mode before the
  * structure → layout → render engine runs. Keeping two copies of that meant
  * `props.themeOverrides` reached only one of them (#133); this module is the
  * single definition so the next root-level prop cannot diverge (#132).
@@ -35,7 +35,7 @@ export interface GenerationThemeContext {
     /** The document after the export-mode pre-pass rewrote font references. */
     document: ReportComponentDefinition;
     theme: ThemeConfig;
-    /** Cache key: base theme name + override digest + export-mode scope. */
+    /** Base theme name, retained for built-in fallback lookups. */
     themeName: string;
 }
 export declare function resolveThemeContext(documentIn: ReportComponentDefinition, options?: ThemeContextOptions): GenerationThemeContext;

package/dist/core/generationContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generationContext.d.ts","sourceRoot":"","sources":["../../src/core/generationContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAKhC,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAA;KAAE,CAAC;IAC9C,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC/B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,CAClB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,iBAAiB,EAAE,GAAG,SAAS,EACzC,QAAQ,EAAE,OAAO,KACd,WAAW,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,QAAQ,EAAE,yBAAyB,CAAC;IACpC,KAAK,EAAE,WAAW,CAAC;IACnB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;CACnB;AAoBD,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,yBAAyB,EACrC,OAAO,GAAE,mBAAwB,GAChC,sBAAsB,CAkExB"}
+{"version":3,"file":"generationContext.d.ts","sourceRoot":"","sources":["../../src/core/generationContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAKhC,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAA;KAAE,CAAC;IAC9C,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC/B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,CAClB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,iBAAiB,EAAE,GAAG,SAAS,EACzC,QAAQ,EAAE,OAAO,KACd,WAAW,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,QAAQ,EAAE,yBAAyB,CAAC;IACpC,KAAK,EAAE,WAAW,CAAC;IACnB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;CACnB;AAoBD,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,yBAAyB,EACrC,OAAO,GAAE,mBAAwB,GAChC,sBAAsB,CA6DxB"}

package/dist/core/generator.d.ts

@@ -1,12 +1,21 @@
 /**
- * Document Generator
- * Main orchestration functions that compose the document generation pipeline
+ * Document generation entry points.
+ *
+ * Every path here compiles the authoring tree to DocxIR and hands it to a
+ * renderer adapter; nothing in this module knows which backend that is. The
+ * default is `docxjs`, which reproduces the output this pipeline has always
+ * produced — see `src/__tests__/corpus-ir-parity.test.ts`.
+ *
+ * The surface is buffer- and file-oriented. No entry point returns or accepts a
+ * renderer-native object: the whole point of the IR is that the backend is an
+ * implementation detail, and handing a caller a docx.js `Document` would make
+ * it part of the contract again.
  */
 /// <reference types="node" />
-import { Document } from 'docx';
 import { ComponentDefinition, ReportProps, ReportComponentDefinition } from '../types';
 import { ThemeConfig } from '../styles';
 import type { ServicesConfig, FontRuntimeOpts } from '@json-to-office/shared';
+import type { DocxRendererId } from '../renderers/types';
 import { DocumentValidationResult } from '@json-to-office/shared-docx';
 import type { GenerationWarning } from '@json-to-office/shared';
 export interface JsonGenerationOptions {
@@ -47,78 +56,78 @@ export interface JsonGenerationOptions {
      * it falls back to `process.cwd()` (#142).
      */
     baseDir?: string;
+    /**
+     * Backend to render with. Defaults to `docxjs`.
+     *
+     * The default reproduces byte-for-byte what this pipeline has always
+     * produced; anything else is opt-in and may not.
+     */
+    renderer?: DocxRendererId;
+}
+/** A generated package, with whatever the pipeline had to say about it. */
+export interface DocxGenerationResult {
+    buffer: Buffer;
+    warnings: GenerationWarning[];
 }
 /**
  * Type guard to check if input is a report component definition
  */
 export declare function isReportComponentDefinition(definition: unknown): definition is ReportComponentDefinition;
 /**
- * Generate a Word document from a report component definition
- * This is the main entry point for document generation
+ * Generate a `.docx` buffer from a report definition, with its warnings.
+ *
+ * Validation runs first unless the caller opts out: the same validator the
+ * playground uses, so an object or a buffer is held to the same standard as a
+ * pasted document and malformed props are surfaced rather than dropped into an
+ * incomplete file.
  */
-export declare function generateDocument(document: ReportComponentDefinition, options?: JsonGenerationOptions): Promise<Document>;
+export declare function generateBufferWithWarnings(jsonConfig: string | ComponentDefinition | ReportComponentDefinition, options?: JsonGenerationOptions): Promise<DocxGenerationResult>;
 /**
- * Generate document from report props and components
- * Convenience function that constructs the report component
+ * Generate a `.docx` buffer from a report definition built out of props and
+ * children — the same document as passing `{ name: 'docx', props, children }`.
  */
-export declare function generateFromConfig(props: ReportProps, components: ComponentDefinition[], options?: JsonGenerationOptions): Promise<Document>;
-/**
- * Generate a Word document from JSON report definition
- * Handles parsing, validation, and conversion to internal components
- */
-export declare function generateDocumentFromJson(jsonConfig: string | ComponentDefinition | ReportComponentDefinition, options?: JsonGenerationOptions): Promise<Document>;
+export declare function generateBufferFromConfig(props: ReportProps, components: ComponentDefinition[], options?: JsonGenerationOptions): Promise<Buffer>;
 /**
  * Validate JSON schema without generating document
  */
 export declare function validateJsonSchema(jsonConfig: string | object): DocumentValidationResult;
 /**
- * Generate document buffer from JSON (commonly used for API responses)
+ * Generate a `.docx` buffer from a report definition.
  */
-export declare function generateBufferFromJson(jsonConfig: string | ReportComponentDefinition, options?: JsonGenerationOptions): Promise<Buffer>;
+export declare function generateBufferFromJson(jsonConfig: string | ComponentDefinition | ReportComponentDefinition, options?: JsonGenerationOptions): Promise<Buffer>;
 /**
- * Generate and save document from JSON in one operation
+ * Generate and save a `.docx` file from a report definition.
  */
-export declare function generateAndSaveFromJson(jsonConfig: string | ReportComponentDefinition, filename: string, options?: JsonGenerationOptions): Promise<void>;
+export declare function generateAndSaveFromJson(jsonConfig: string | ComponentDefinition | ReportComponentDefinition, filename: string, options?: JsonGenerationOptions): Promise<void>;
 /**
- * Generate document from JSON file
- */
-export declare function generateDocumentFromFile(filePath: string, options?: JsonGenerationOptions): Promise<Document>;
-/**
- * Generate document buffer from JSON file
+ * Generate a `.docx` buffer from a JSON file.
+ *
+ * The document's own directory is the natural base for its relative assets, so
+ * it becomes the default `baseDir` unless the caller says otherwise.
  */
 export declare function generateBufferFromFile(filePath: string, options?: JsonGenerationOptions): Promise<Buffer>;
 /**
- * Generate and save document from JSON file in one operation
+ * Generate and save a `.docx` file from a JSON file.
  */
 export declare function generateAndSaveFromFile(inputFilePath: string, outputFilePath: string, options?: JsonGenerationOptions): Promise<void>;
-/**
- * Save a document to file
- */
-export declare function saveDocument(document: Document, filename: string, options?: JsonGenerationOptions): Promise<void>;
-/**
- * Generate and save document in one operation
- */
-export declare function generateAndSave(document: ReportComponentDefinition, filename: string, options?: JsonGenerationOptions): Promise<void>;
 /**
  * Compose multiple transform functions
  * Utility for creating custom pipelines
  */
 export declare function pipe<T>(...fns: Array<(_arg: T) => T>): (_arg: T) => T;
 /**
- * Export the main API
+ * The main API surface.
+ *
+ * Buffer- and file-oriented only: no member returns a renderer-native object.
  */
 export declare const DocumentGenerator: {
-    generate: typeof generateDocument;
-    generateFromConfig: typeof generateFromConfig;
-    generateFromJson: typeof generateDocumentFromJson;
-    generateFromFile: typeof generateDocumentFromFile;
     generateBufferFromJson: typeof generateBufferFromJson;
+    generateBufferWithWarnings: typeof generateBufferWithWarnings;
+    generateBufferFromConfig: typeof generateBufferFromConfig;
     generateBufferFromFile: typeof generateBufferFromFile;
     generateAndSaveFromJson: typeof generateAndSaveFromJson;
     generateAndSaveFromFile: typeof generateAndSaveFromFile;
     validateJsonSchema: typeof validateJsonSchema;
-    save: typeof saveDocument;
-    generateAndSave: typeof generateAndSave;
     isReportComponentDefinition: typeof isReportComponentDefinition;
 };
 //# sourceMappingURL=generator.d.ts.map

package/dist/core/generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/core/generator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/core/generator.ts"],"names":[],"mappings":"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"}