@json-to-office/core-docx 0.30.0 → 0.32.0

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/toc/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,SAAS,EACT,eAAe,EAIhB,MAAM,MAAM,CAAC;AAEd,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,KAAK,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC;CACjB;AAyCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,sBAAsB,EACjC,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,aAAa,GACtB,CAAC,SAAS,GAAG,eAAe,CAAC,EAAE,CAyNjC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/toc/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,SAAS,EACT,eAAe,EAIhB,MAAM,MAAM,CAAC;AAEd,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,KAAK,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC;CACjB;AAyCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,sBAAsB,EACjC,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,aAAa,GACtB,CAAC,SAAS,GAAG,eAAe,CAAC,EAAE,CAgNjC"}

package/dist/core/cached-render.d.ts

@@ -6,6 +6,28 @@ import { Paragraph, Table, TableOfContents, Textbox } from 'docx';
 import { ComponentDefinition, RenderContext } from '../types';
 import { ThemeConfig } from '../styles';
 import { MemoryCache } from '../cache';
+/** Why a component type is never cached (see renderComponentWithCache). */
+export type ComponentBypassReason = 'dynamic-context' | 'bookmark-id' | 'revision-ids';
+export interface ComponentBypassStats {
+    /** Component type name. */
+    type: string;
+    /** Renders that skipped the cache by design. */
+    renders: number;
+    /** The (first observed) reason this type bypasses the cache. */
+    reason: ComponentBypassReason;
+}
+/**
+ * Get per-type "uncached by design" render counters.
+ */
+export declare function getComponentBypassStats(): ComponentBypassStats[];
+/**
+ * True when the serialized props/children reference a registered placeholder
+ * whose output can vary with the generation date. Components without one
+ * render identically across dates, so their cache keys must not embed the
+ * per-render timestamp — that's what made cross-render hits impossible for
+ * date-less documents (#156).
+ */
+export declare function usesDateSensitivePlaceholder(serialized: string): boolean;
 /**
  * Initialize the component cache
  */
@@ -32,9 +54,25 @@ export declare function warmComponentCache(components: Array<{
     context: RenderContext;
 }>): Promise<void>;
 /**
- * Get component cache statistics
+ * Get component cache statistics, extended with per-type "uncached by
+ * design" render counters (#156). The bypass counters exist even before the
+ * cache is initialized — a document full of bypassed types never triggers
+ * initialization, yet its renders are exactly what needs surfacing.
  */
-export declare function getComponentCacheStats(): import("@json-to-office/shared/cache").CacheStatistics | null;
+export declare function getComponentCacheStats(): {
+    bypassedComponents: ComponentBypassStats[];
+} | {
+    bypassedComponents: ComponentBypassStats[];
+    entries: number;
+    totalSize: number;
+    hitRate: number;
+    missRate: number;
+    totalHits: number;
+    totalMisses: number;
+    avgResponseTime: number;
+    evictions: number;
+    componentStats: Map<string, import("@json-to-office/shared/cache").ComponentStatistics>;
+} | null;
 /**
  * Export component cache for persistence
  */

package/dist/core/cached-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cached-render.d.ts","sourceRoot":"","sources":["../../src/core/cached-render.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,WAAW,EAIZ,MAAM,UAAU,CAAC;AAoBlB;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CA4BlE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,GAAG,IAAI,CAEtD;AAED;;GAEG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAIzD;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,mBAAmB,EAC9B,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,WAAW,UAAQ,GAClB,OAAO,CAAC,CAAC,SAAS,GAAG,KAAK,GAAG,eAAe,GAAG,OAAO,CAAC,EAAE,CAAC,CAyG5D;AAKD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,KAAK,CAAC;IAChB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;CACxB,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;GAEG;AACH,wBAAgB,sBAAsB,kEAMrC;AAED;;GAEG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,GAAG,CACvD,MAAM,EACN,OAAO,CACR,GAAG,IAAI,CAAC,CAgBR;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GACzB,OAAO,CAAC,IAAI,CAAC,CAQf"}
+{"version":3,"file":"cached-render.d.ts","sourceRoot":"","sources":["../../src/core/cached-render.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,WAAW,EAIZ,MAAM,UAAU,CAAC;AAWlB,2EAA2E;AAC3E,MAAM,MAAM,qBAAqB,GAC7B,iBAAiB,GACjB,aAAa,GACb,cAAc,CAAC;AAEnB,MAAM,WAAW,oBAAoB;IACnC,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,MAAM,EAAE,qBAAqB,CAAC;CAC/B;AAwBD;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,EAAE,CAMhE;AAUD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CASxE;AAYD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CA4BlE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,GAAG,IAAI,CAEtD;AAED;;GAEG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKzD;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,mBAAmB,EAC9B,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,WAAW,UAAQ,GAClB,OAAO,CAAC,CAAC,SAAS,GAAG,KAAK,GAAG,eAAe,GAAG,OAAO,CAAC,EAAE,CAAC,CAuH5D;AAKD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,KAAK,CAAC;IAChB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;CACxB,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB;;;;;;;;;;;;;SAOrC;AAED;;GAEG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,GAAG,CACvD,MAAM,EACN,OAAO,CACR,GAAG,IAAI,CAAC,CAgBR;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GACzB,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/core/layout.d.ts

@@ -38,8 +38,6 @@ export interface SectionLayout {
     isUserSection: boolean;
     /** True if this layout chunk belongs to a user-defined Section (all chunks of that section) */
     belongsToUserSection: boolean;
-    /** The heading level of the section title (e.g., 1 for Heading1) - used by TOCs to exclude section title from section-scoped TOCs */
-    sectionTitleLevel?: number;
     /** Page configuration override for this section */
     pageOverride?: {
         size?: 'A4' | 'A3' | 'LETTER' | 'LEGAL' | {

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

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

package/dist/core/prerasterizeVisuals.d.ts

@@ -23,6 +23,22 @@ export interface PrerasterizeOptions {
     /** Max concurrent per-visual fallback rasterizations (default 4). */
     concurrency?: number;
 }
+/** Cumulative pre-pass counters for cache observability (#156). */
+export interface VisualPrepassStats {
+    /** Documents that entered the pre-pass with at least one visual. */
+    documents: number;
+    /** Enabled visuals collected across those documents. */
+    collected: number;
+    /** Unique rasterization units after dedupe (identical content+dpi). */
+    unique: number;
+}
+/**
+ * Get cumulative per-document pre-pass counters. `collected - unique` is the
+ * work the dedupe saved — the `visual` cache benefit the component cache
+ * stats can never show, since `visual` bypasses that cache by design.
+ */
+export declare function getVisualPrepassStats(): VisualPrepassStats;
+export declare function resetVisualPrepassStats(): void;
 /**
  * Collect the props of every enabled `visual` component reachable from
  * `root`. The walk is generic — every array element and object value is

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

@@ -1 +1 @@
-{"version":3,"file":"prerasterizeVisuals.d.ts","sourceRoot":"","sources":["../../src/core/prerasterizeVisuals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAIL,KAAK,iBAAiB,EAEtB,KAAK,6BAA6B,EACnC,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAkB/D,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AASD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,EAAE,CA4B/D;AAsDD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,OAAO,EACb,aAAa,EAAE,iBAAiB,GAAG,SAAS,EAC5C,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC,CAmJrD"}
+{"version":3,"file":"prerasterizeVisuals.d.ts","sourceRoot":"","sources":["../../src/core/prerasterizeVisuals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAIL,KAAK,iBAAiB,EAEtB,KAAK,6BAA6B,EACnC,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAkB/D,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;CAChB;AAQD;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,kBAAkB,CAE1D;AAED,wBAAgB,uBAAuB,IAAI,IAAI,CAI9C;AASD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,EAAE,CA4B/D;AAsDD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,OAAO,EACb,aAAa,EAAE,iBAAiB,GAAG,SAAS,EAC5C,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC,CAuJrD"}

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

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/core/render.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,KAAK,EACL,eAAe,EAEf,eAAe,EAKf,OAAO,EACR,MAAM,MAAM,CAAC;AAcd,OAAO,EACL,mBAAmB,EACnB,aAAa,EAed,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAIxC,OAAO,EAEL,iBAAiB,EAElB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAKrD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AA+B7D,UAAU,qBAAqB;IAC7B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA8DD;;GAEG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,iBAAiB,EAC5B,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,QAAQ,CAAC,CAYnB;AAkZD;;GAEG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,cAAc,CAAC,EAAE,MAAM,EACvB,aAAa,CAAC,EAAE,OAAO,EACvB,WAAW,UAAQ,GAClB,OAAO,CAAC,eAAe,CAAC,CAiH1B;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,mBAAmB,EAC9B,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,CAAC,SAAS,GAAG,KAAK,GAAG,eAAe,GAAG,OAAO,CAAC,EAAE,CAAC,CAmC5D"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/core/render.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,KAAK,EACL,eAAe,EAEf,eAAe,EAKf,OAAO,EACR,MAAM,MAAM,CAAC;AAcd,OAAO,EACL,mBAAmB,EACnB,aAAa,EAed,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAIxC,OAAO,EAEL,iBAAiB,EAElB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAKrD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AA+B7D,UAAU,qBAAqB;IAC7B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA8DD;;GAEG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,iBAAiB,EAC5B,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,QAAQ,CAAC,CAYnB;AAkZD;;GAEG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,cAAc,CAAC,EAAE,MAAM,EACvB,aAAa,CAAC,EAAE,OAAO,EACvB,WAAW,UAAQ,GAClB,OAAO,CAAC,eAAe,CAAC,CA+G1B;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,mBAAmB,EAC9B,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,CAAC,SAAS,GAAG,KAAK,GAAG,eAAe,GAAG,OAAO,CAAC,EAAE,CAAC,CAmC5D"}

package/dist/core/structure.d.ts

@@ -25,8 +25,6 @@ export interface DocumentMetadata {
     date: Date;
 }
 export interface ProcessedSection {
-    title?: string;
-    level?: number;
     components: ComponentDefinition[];
     header?: ComponentDefinition[] | 'linkToPrevious';
     footer?: ComponentDefinition[] | 'linkToPrevious';

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

@@ -1 +1 @@
-{"version":3,"file":"structure.d.ts","sourceRoot":"","sources":["../../src/core/structure.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,yBAAyB,EACzB,aAAa,EAGd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAQxC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,MAAM,CAAC,EAAE,mBAAmB,EAAE,GAAG,gBAAgB,CAAC;IAClD,MAAM,CAAC,EAAE,mBAAmB,EAAE,GAAG,gBAAgB,CAAC;IAClD,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,sDAAsD;IACtD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mDAAmD;IACnD,IAAI,CAAC,EAAE;QACL,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,QAAQ,GAAG,OAAO,GAAG;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QAC5E,OAAO,CAAC,EAAE;YACR,GAAG,CAAC,EAAE,MAAM,CAAC;YACb,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,KAAK,CAAC,EAAE,MAAM,CAAC;YACf,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,MAAM,CAAC,EAAE,MAAM,CAAC;SACjB,CAAC;KACH,CAAC;CACH;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,yBAAyB,EACnC,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,IAAI,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAgE5B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,EAClB,cAAc,OAAa,GAC1B,gBAAgB,CAWlB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,mBAAmB,EAAE,EACjC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAoE7B;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,mBAAmB,EAAE,EACjC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAmDhC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,GAChB,aAAa,CA0Bf"}
+{"version":3,"file":"structure.d.ts","sourceRoot":"","sources":["../../src/core/structure.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,yBAAyB,EACzB,aAAa,EAGd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAKxC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,MAAM,CAAC,EAAE,mBAAmB,EAAE,GAAG,gBAAgB,CAAC;IAClD,MAAM,CAAC,EAAE,mBAAmB,EAAE,GAAG,gBAAgB,CAAC;IAClD,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,sDAAsD;IACtD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mDAAmD;IACnD,IAAI,CAAC,EAAE;QACL,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,QAAQ,GAAG,OAAO,GAAG;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QAC5E,OAAO,CAAC,EAAE;YACR,GAAG,CAAC,EAAE,MAAM,CAAC;YACb,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,KAAK,CAAC,EAAE,MAAM,CAAC;YACf,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,MAAM,CAAC,EAAE,MAAM,CAAC;SACjB,CAAC;KACH,CAAC;CACH;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,yBAAyB,EACnC,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,IAAI,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAgE5B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,EAClB,cAAc,OAAa,GAC1B,gBAAgB,CAWlB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,mBAAmB,EAAE,EACjC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAwC7B;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,mBAAmB,EAAE,EACjC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAyBhC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,GAChB,aAAa,CA0Bf"}

package/dist/index.d.ts

@@ -2,7 +2,8 @@ export declare function getCoreVersion(): string;
 export { generateDocument, generateFromConfig, generateDocumentFromJson, generateDocumentFromFile, generateBufferFromJson, generateBufferFromFile, generateAndSaveFromJson, generateAndSaveFromFile, validateJsonSchema, isReportComponentDefinition, saveDocument, generateAndSave, DocumentGenerator as CoreDocumentGenerator, } from './core/generator';
 export { flattenVisuals, type FlattenVisualsOptions, } from './core/flattenVisuals';
 export { MemoryCache, CacheKeyGenerator, DEFAULT_CACHE_CONFIG, getCacheConfigFromEnv, mergeConfigs, ComponentCacheAnalytics, type CacheConfiguration, type CachedComponent, type CacheStatistics, type CacheKeyOptions, type CacheEvents, type CacheAnalyticsReport, type ComponentPerformanceMetrics, type ComponentCacheTrends, type CacheOptimizationRecommendation, type TimeSeriesPoint, } from './cache/index';
-export { initializeComponentCache, getComponentCache, clearComponentCache, getComponentCacheStats, warmComponentCache, } from './core/cached-render';
+export { initializeComponentCache, getComponentCache, clearComponentCache, getComponentCacheStats, getComponentBypassStats, warmComponentCache, type ComponentBypassReason, type ComponentBypassStats, } from './core/cached-render';
+export { getVisualPrepassStats, resetVisualPrepassStats, type VisualPrepassStats, } from './core/prerasterizeVisuals';
 export { isReportComponent, isSectionComponent, isHeadingComponent, isParagraphComponent, isColumnsComponent, isImageComponent, isStatisticComponent, isTableComponent, isListComponent, isHighchartsComponent, isVisualComponent, } from './types/index';
 export type { ImageContent, StatisticContent, TableData, SectionProperties, ColumnSettings, PageSizeOptions, PageMarginOptions, PageNumberOptions, PageBorderOptions, RenderContext, } from './types/index';
 export * from './utils/formatters';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAGD,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,2BAA2B,EAC3B,YAAY,EACZ,eAAe,EACf,iBAAiB,IAAI,qBAAqB,GAC3C,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,EACZ,uBAAuB,EAEvB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,EACzB,KAAK,+BAA+B,EACpC,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAEL,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAGvB,YAAY,EAEV,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,GACd,MAAM,eAAe,CAAC;AAGvB,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EACL,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,MAAM,EACN,YAAY,EACZ,cAAc,EACd,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,QAAQ,EACR,UAAU,EACV,eAAe,EACf,eAAe,GAChB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGnD,OAAO,oBAAoB,CAAC;AAG5B,YAAY,EAEV,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AAMjC,OAAO,EAEL,eAAe,EACf,aAAa,EACb,uBAAuB,EAGvB,sBAAsB,EACtB,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,EACxB,8BAA8B,EAG9B,4BAA4B,EAC5B,kBAAkB,EAClB,wBAAwB,EACxB,YAAY,EAGZ,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,aAAa,IAAI,sBAAsB,EAC5C,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EACrB,KAAK,eAAe,EAGpB,KAAK,0BAA0B,EAC/B,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,GAC3B,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -2257,39 +2257,15 @@ async function extractSections(components, context) {
         context
       );
       const shouldPageBreak = component.props?.pageBreak !== false;
-      if (component.props?.title) {
-        const headingLevel = Math.min(
-          Math.max(component.props.level || 1, 1),
-          6
-        );
-        sectionComponents.unshift(
-          resolveComponentDefaults(
-            {
-              name: "heading",
-              props: {
-                text: component.props.title,
-                level: headingLevel,
-                pageBreak: shouldPageBreak,
-                // Apply zero-spacing to prevent unwanted initial line
-                spacing: {
-                  before: 0,
-                  after: 0
-                }
-              }
-            },
-            context.fullTheme
-          )
-        );
-      }
       sections.push({
-        title: component.props?.title,
-        level: component.props?.level,
         components: sectionComponents,
         header: component.props?.header,
         footer: component.props?.footer,
         isExplicitSection: true,
-        // Store pageBreak for titleless sections to be handled at layout level
-        pageBreak: !component.props?.title ? shouldPageBreak : void 0,
+        // Page break is handled at layout level (sections render no title of
+        // their own — a visible title is an explicit heading child; the
+        // authoring label lives in props.meta.title and is never rendered)
+        pageBreak: shouldPageBreak,
         // Preserve page configuration override if present
         page: component.props?.page
       });
@@ -2314,29 +2290,6 @@ async function flattenComponents(components, context) {
         children: await flattenComponents(component.children, context)
       });
     } else if (isSectionComponent(component) && component.children) {
-      if (component.props?.title) {
-        const headingLevel = Math.min(
-          Math.max(component.props.level || 1, 1),
-          6
-        );
-        flattened.push(
-          resolveComponentDefaults(
-            {
-              name: "heading",
-              props: {
-                text: component.props.title,
-                level: headingLevel,
-                // Apply zero-spacing to prevent unwanted initial line
-                spacing: {
-                  before: 0,
-                  after: 0
-                }
-              }
-            },
-            context.fullTheme
-          )
-        );
-      }
       flattened.push(...await flattenComponents(component.children, context));
     } else {
       flattened.push(component);
@@ -2399,7 +2352,6 @@ function applyLayout(sections, theme, themeName) {
         footer: section.footer,
         isUserSection: isSourceUserSection,
         belongsToUserSection: isSourceUserSection,
-        sectionTitleLevel: section.level,
         pageOverride: section.page
       });
       continue;
@@ -2434,8 +2386,6 @@ function applyLayout(sections, theme, themeName) {
         // at the start of column content.
         isUserSection: isSourceUserSection && j === 0,
         belongsToUserSection: isSourceUserSection,
-        // Pass section title level for TOC scoping
-        sectionTitleLevel: section.level,
         // Pass page override for this section
         pageOverride: section.page
       });
@@ -4271,6 +4221,33 @@ function componentHasRevision(component) {
 import { createHash as createHash3 } from "crypto";
 var componentCache = null;
 var cacheKeyGen = null;
+var bypassStats = /* @__PURE__ */ new Map();
+function recordBypass(type, reason) {
+  const entry = bypassStats.get(type);
+  if (entry) {
+    entry.renders++;
+  } else {
+    bypassStats.set(type, { renders: 1, reason });
+  }
+}
+function getComponentBypassStats() {
+  return Array.from(bypassStats.entries()).map(([type, s]) => ({
+    type,
+    renders: s.renders,
+    reason: s.reason
+  }));
+}
+var DATE_INDEPENDENT_PLACEHOLDERS = /* @__PURE__ */ new Set(["PAGE", "TOTAL_PAGES"]);
+function usesDateSensitivePlaceholder(serialized) {
+  const placeholderRegex = /\{([^}{]+)\}/g;
+  let match;
+  while ((match = placeholderRegex.exec(serialized)) !== null) {
+    const name = match[1].toUpperCase();
+    if (DATE_INDEPENDENT_PLACEHOLDERS.has(name)) continue;
+    if (PlaceholderRegistry.has(name)) return true;
+  }
+  return false;
+}
 function createThemeHash(theme) {
   const themeString = JSON.stringify(theme);
   return createHash3("sha256").update(themeString).digest("hex").substring(0, 8);
@@ -4312,24 +4289,34 @@ async function clearComponentCache() {
   if (componentCache) {
     await componentCache.clear();
   }
+  bypassStats.clear();
 }
 async function renderComponentWithCache(component, theme, themeName, context, bypassCache = false) {
-  const forceBypassForType = component.name === "toc" || component.name === "section" || component.name === "visual" || component.name === "heading" || // Both explicit lists and markdown-list paragraphs register numbering in
-  // the current document scope. Cached paragraphs can otherwise reference
-  // definitions that only existed in a previous render.
-  component.name === "list" || component.name === "paragraph" || "id" in component || componentHasRevision(component);
+  const bypassReason = componentHasRevision(
+    component
+  ) ? "revision-ids" : "id" in component ? "bookmark-id" : component.name === "toc" || component.name === "section" || component.name === "visual" || component.name === "heading" || // Both explicit lists and markdown-list paragraphs register
+  // numbering in the current document scope. Cached paragraphs can
+  // otherwise reference definitions that only existed in a previous
+  // render.
+  component.name === "list" || component.name === "paragraph" ? "dynamic-context" : null;
   if (!componentCache) {
     initializeComponentCache();
   }
-  if (!componentCache || bypassCache || forceBypassForType || !componentCache.getConfig().enabled) {
+  if (bypassReason !== null) {
+    recordBypass(component.name, bypassReason);
+    return renderComponent(component, theme, themeName, context);
+  }
+  if (!componentCache || bypassCache || !componentCache.getConfig().enabled) {
     return renderComponent(component, theme, themeName, context);
   }
   const componentProps = JSON.stringify(component.props || {});
   const themeHash = createThemeHash(theme);
   const contextKey = context?.section ? `${context.section.currentLayout}:${context.section.columnCount}` : "no-section";
-  const generationDateKey = getGenerationDate().toISOString();
   const baseDirKey = getBaseDir() ?? "";
   const childrenKey = "children" in component && component.children ? `:children:${JSON.stringify(component.children)}` : "";
+  const generationDateKey = usesDateSensitivePlaceholder(
+    componentProps + childrenKey
+  ) ? getGenerationDate().toISOString() : "no-date";
   const cacheKey = `component:${component.name}:${themeHash}:${contextKey}:${generationDateKey}:${baseDirKey}:${componentProps}${childrenKey}`;
   const cached = await componentCache.get(cacheKey);
   if (cached) {
@@ -4372,10 +4359,11 @@ async function warmComponentCache(components) {
   await Promise.all(warmingPromises);
 }
 function getComponentCacheStats() {
+  const bypassedComponents = getComponentBypassStats();
   if (!componentCache) {
-    return null;
+    return bypassedComponents.length > 0 ? { bypassedComponents } : null;
   }
-  return componentCache.getStats();
+  return { ...componentCache.getStats(), bypassedComponents };
 }
 
 // src/core/content.ts
@@ -6808,8 +6796,6 @@ function renderTocComponent(component, theme, context) {
     );
   }
   const stylesWithLevels = [];
-  const sectionTitleLevel = context?.section?.sectionTitleLevel;
-  const startLevel = effectiveScope === "section" && sectionTitleLevel ? sectionTitleLevel : 0;
   if (componentProps.styles && componentProps.styles.length > 0) {
     for (const styleMapping of componentProps.styles) {
       const styleId = styleMapping.styleId;
@@ -6820,7 +6806,7 @@ function renderTocComponent(component, theme, context) {
       );
     }
   }
-  const effectiveDepthStart = effectiveScope === "section" && sectionTitleLevel ? Math.max(depthStart, startLevel + 1) : depthStart;
+  const effectiveDepthStart = depthStart;
   const effectiveDepthEnd = depthEnd;
   const tocOptions = {
     hyperlink: true,
@@ -7229,6 +7215,19 @@ function createLimiter(max) {
 var DEFAULT_FALLBACK_CONCURRENCY = 4;
 var BATCH_TIMEOUT_BASE_MS = 3e4;
 var BATCH_TIMEOUT_PER_SLIDE_MS = 1e4;
+var prepassStats = {
+  documents: 0,
+  collected: 0,
+  unique: 0
+};
+function getVisualPrepassStats() {
+  return { ...prepassStats };
+}
+function resetVisualPrepassStats() {
+  prepassStats.documents = 0;
+  prepassStats.collected = 0;
+  prepassStats.unique = 0;
+}
 function collectVisualProps(root) {
   const found = [];
   const seen = /* @__PURE__ */ new WeakSet();
@@ -7305,6 +7304,9 @@ async function prerasterizeVisuals(root, serviceConfig, options = {}) {
     }
   }
   if (targets.size === 0) return map;
+  prepassStats.documents++;
+  prepassStats.collected += visuals.length;
+  prepassStats.unique += targets.size;
   const unique = [...targets.values()];
   const limit = createLimiter(
     Math.max(1, options.concurrency ?? DEFAULT_FALLBACK_CONCURRENCY)
@@ -7705,9 +7707,7 @@ async function renderSection(section, theme, themeName, context, sectionOrdinal,
       currentLayout: section.layoutType,
       columnCount: section.properties.column?.count || 1,
       // Always pass the same bookmark ID for all layout chunks of the same section
-      sectionBookmarkId,
-      // Pass section title level for TOC scoping (excludes section title from its own TOC)
-      sectionTitleLevel: section.sectionTitleLevel
+      sectionBookmarkId
     }
   };
   if (sectionBookmarkId && isFirstLayoutOfUserSection && sharedLinkId !== void 0) {
@@ -9297,11 +9297,13 @@ export {
   generatePluginDocumentSchema,
   generateWarningsDocument,
   export_getCacheConfigFromEnv as getCacheConfigFromEnv,
+  getComponentBypassStats,
   getComponentCache,
   getComponentCacheStats,
   getCoreVersion,
   getExample,
   getExampleNames,
+  getVisualPrepassStats,
   hasNodeBuiltins,
   initializeComponentCache,
   isColumnsComponent,
@@ -9325,6 +9327,7 @@ export {
   minimalTheme,
   modernTheme,
   parseTextWithDecorators,
+  resetVisualPrepassStats,
   runExample,
   saveDocument,
   themes,