@json-to-office/core-docx 0.29.0 → 0.31.0

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/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/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';
@@ -16,6 +17,6 @@ export { examples, getExample, getExampleNames, loadJsonExample, } from './templ
 export { runExample } from './utils/exampleRunner';
 import './components/index';
 export type { ChartGenerationResult, } from './components/highcharts';
-export { createComponent, createVersion, createDocumentGenerator, validateComponentProps, validateDocument, cleanComponentProps, ComponentValidationError, UnknownPreservedComponentError, generatePluginDocumentSchema, exportPluginSchema, generateComponentSchemas, mergeSchemas, type CustomComponent, type ComponentVersion, type ComponentVersionMap, type RenderFunction, type RenderContext as ComponentRenderContext, type DocumentGenerator, type DocumentGeneratorOptions, type GenerateOptions, type GenerateFileOptions, type GenerationResult, type BufferGenerationResult, type FileGenerationResult, type ValidationResult, type ValidationError, type ExtractCustomComponentType, type CustomComponentUnion, type ExtendedComponentDefinition, type ExtendedReportComponent, type InferCustomComponents, } from './plugin/index';
+export { createComponent, createVersion, createDocumentGenerator, validateComponentProps, validateDocument, cleanComponentProps, ComponentValidationError, UnknownPreservedComponentError, generatePluginDocumentSchema, exportPluginSchema, generateComponentSchemas, mergeSchemas, type CustomComponent, type ComponentVersion, type ComponentVersionMap, type RenderFunction, type RenderContext as ComponentRenderContext, type DocumentGenerator, type DocumentGeneratorOptions, type GenerateOptions, type GenerateFileOptions, type GenerationResult, type BufferGenerationResult, type FileGenerationResult, type StandardDefinitionResult, type ValidationResult, type ValidationError, type ExtractCustomComponentType, type CustomComponentUnion, type ExtendedComponentDefinition, type ExtendedReportComponent, type InferCustomComponents, } from './plugin/index';
 export type { PluginComponent, PluginRenderFunction, PluginValidationError, PluginValidationResult, } from './types/plugin';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -4271,6 +4271,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 +4339,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 +4409,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
@@ -7229,6 +7267,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 +7356,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)
@@ -9001,70 +9055,104 @@ function createBuilderImpl(state) {
     }
     return new Set(list);
   }
-  async function generate(document, options) {
-    try {
-      const preserveSet = resolvePreserveSet(options);
-      const rootIn = document;
-      const internalDocument = rootIn.props === void 0 ? { ...rootIn, props: {} } : rootIn;
-      const vOpts = {
-        ...state.validation,
-        ...options?.validation
-      };
-      if (vOpts.enabled !== false) {
-        const result = validateDocument(
-          internalDocument,
-          state.components,
-          { allowUnknownFields: vOpts.allowUnknownFields }
+  async function expandDocument(document, options) {
+    const preserveSet = resolvePreserveSet(options);
+    const rootIn = document;
+    const internalDocument = rootIn.props === void 0 ? { ...rootIn, props: {} } : rootIn;
+    const vOpts = {
+      ...state.validation,
+      ...options?.validation
+    };
+    if (vOpts.enabled !== false) {
+      const result = validateDocument(
+        internalDocument,
+        state.components,
+        { allowUnknownFields: vOpts.allowUnknownFields }
+      );
+      if (!result.valid) {
+        throw new ComponentValidationError2(
+          (result.errors ?? []).map((e) => ({
+            path: e.path ?? "",
+            message: e.message
+          })),
+          internalDocument
         );
-        if (!result.valid) {
-          throw new ComponentValidationError2(
-            (result.errors ?? []).map((e) => ({
-              path: e.path ?? "",
-              message: e.message
-            })),
-            internalDocument
-          );
-        }
       }
-      const validateEmitted = vOpts.enabled === false ? void 0 : (emitted, componentLabel) => {
-        const result = validateDocument(
-          { ...internalDocument, children: emitted },
-          state.components,
-          { allowUnknownFields: vOpts.allowUnknownFields }
+    }
+    const validateEmitted = vOpts.enabled === false ? void 0 : (emitted, componentLabel) => {
+      const result = validateDocument(
+        { ...internalDocument, children: emitted },
+        state.components,
+        { allowUnknownFields: vOpts.allowUnknownFields }
+      );
+      if (!result.valid) {
+        throw new ComponentValidationError2(
+          (result.errors ?? []).map((e) => ({
+            path: e.path ?? "",
+            message: `custom component '${componentLabel}' emitted invalid output \u2014 ${e.message}`
+          })),
+          emitted
         );
-        if (!result.valid) {
-          throw new ComponentValidationError2(
-            (result.errors ?? []).map((e) => ({
-              path: e.path ?? "",
-              message: `custom component '${componentLabel}' emitted invalid output \u2014 ${e.message}`
-            })),
-            emitted
-          );
-        }
+      }
+    };
+    const warnings = [];
+    const {
+      document: modedRoot,
+      theme: modedTheme,
+      themeName
+    } = resolveThemeContext(internalDocument, {
+      customThemes: state.customThemes,
+      fonts: state.fonts,
+      warnings,
+      resolveNamedTheme: resolveDocumentTheme
+    });
+    const processed = await processDocumentComponents(
+      modedRoot.children || [],
+      preserveSet,
+      warnings,
+      modedTheme,
+      validateEmitted
+    );
+    const processedDocument = {
+      ...modedRoot,
+      children: processed.standard
+    };
+    const [modedDoc] = normalizeDocument(processedDocument);
+    return {
+      modedRoot,
+      modedTheme,
+      themeName,
+      processed,
+      modedDoc,
+      warnings,
+      preserveSet
+    };
+  }
+  async function expandStandardDefinition(document, options) {
+    try {
+      const { modedDoc, warnings } = await expandDocument(document, options);
+      return {
+        standardDefinition: modedDoc,
+        warnings: warnings.length > 0 ? warnings : null
       };
-      const warnings = [];
+    } catch (error) {
+      if (state.debug) {
+        console.error("Document expansion error:", error);
+      }
+      throw error;
+    }
+  }
+  async function generate(document, options) {
+    try {
       const {
-        document: modedRoot,
-        theme: modedTheme,
-        themeName
-      } = resolveThemeContext(internalDocument, {
-        customThemes: state.customThemes,
-        fonts: state.fonts,
-        warnings,
-        resolveNamedTheme: resolveDocumentTheme
-      });
-      const processed = await processDocumentComponents(
-        modedRoot.children || [],
-        preserveSet,
-        warnings,
+        modedRoot,
         modedTheme,
-        validateEmitted
-      );
-      const processedDocument = {
-        ...modedRoot,
-        children: processed.standard
-      };
-      const [modedDoc] = normalizeDocument(processedDocument);
+        themeName,
+        processed,
+        modedDoc,
+        warnings,
+        preserveSet
+      } = await expandDocument(document, options);
       await resolveDocumentFonts(modedDoc, modedTheme, state.fonts, warnings);
       const packageOptions = {
         deterministic: options?.deterministic ?? state.deterministic,
@@ -9191,6 +9279,7 @@ function createBuilderImpl(state) {
     generate,
     generateBuffer,
     generateFile,
+    expandStandardDefinition,
     getComponentNames,
     validate,
     generateSchema,
@@ -9262,11 +9351,13 @@ export {
   generatePluginDocumentSchema,
   generateWarningsDocument,
   export_getCacheConfigFromEnv as getCacheConfigFromEnv,
+  getComponentBypassStats,
   getComponentCache,
   getComponentCacheStats,
   getCoreVersion,
   getExample,
   getExampleNames,
+  getVisualPrepassStats,
   hasNodeBuiltins,
   initializeComponentCache,
   isColumnsComponent,
@@ -9290,6 +9381,7 @@ export {
   minimalTheme,
   modernTheme,
   parseTextWithDecorators,
+  resetVisualPrepassStats,
   runExample,
   saveDocument,
   themes,