@json-to-office/shared 0.8.0 → 0.12.0

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { AddWarningFunction, GenerationWarning } from './types/warnings.js';
 export { DEFAULT_ERROR_CONFIG, ERROR_EMOJIS, ErrorFormatterConfig, calculatePosition, clearComponentNamesCache, createErrorConfig, createJsonParseError, extractStandardComponentNames, formatErrorMessage, formatErrorSummary, getLiteralValue, getObjectSchemaPropertyNames, getSchemaMetadata, groupErrorsByPath, isLiteralSchema, isObjectSchema, isUnionSchema, transformValueError, transformValueErrors } from './validation/unified/index.js';
 export { T as TransformedError, V as ValidationError, a as ValidationResult } from './types-BWFZ7OaO.js';
 export { ComponentValidationError, ComponentValidationResult, ComponentVersion, ComponentVersionMap, CustomComponent, DuplicateComponentError, PluginValidationOptions, PluginValidationResult, RenderContext, RenderFunction, createComponent, createVersion, getValidationSummary, isValidationSuccess, resolveComponentVersion, validateCustomComponentProps } from './plugin/index.js';
+import { F as FontRegistryEntry, a as FontRuntimeOpts, R as ResolvedFontSource, b as ResolvedFont } from './types-CL0Hbw6x.js';
+export { c as FontFamilyNameSchema, d as FontRegistryDefinition, e as FontRegistryEntrySchema, f as FontRegistrySchema, g as FontSource, h as FontSourceSchema, S as SAFE_FONTS, i as SafeFontName, j as isSafeFont } from './types-CL0Hbw6x.js';
 export { ParsedSemver, compareSemver, isValidSemver, latestVersion, parseSemver } from './utils/semver.js';
 import '@sinclair/typebox';
 import '@sinclair/typebox/value';
@@ -10,14 +12,451 @@ import '@sinclair/typebox/value';
 /**
  * Service configuration types for external integrations (e.g. Highcharts export server)
  */
+type HighchartsHeaders = Record<string, string>;
+type HighchartsHeadersResolver = (body: unknown) => HighchartsHeaders | Promise<HighchartsHeaders>;
 interface HighchartsServiceConfig {
     serverUrl?: string;
-    headers?: Record<string, string>;
+    headers?: HighchartsHeaders | HighchartsHeadersResolver;
 }
 interface ServicesConfig {
     highcharts?: HighchartsServiceConfig;
 }
 
+/** Scan an arbitrary doc tree (DOCX or PPTX) for every font family referenced. */
+declare function collectFontNames(doc: unknown): Set<string>;
+/** Scan a DOCX document tree for every font family name referenced. */
+declare const collectFontNamesFromDocx: typeof collectFontNames;
+/** Scan a PPTX presentation tree for every font family name referenced. */
+declare const collectFontNamesFromPptx: typeof collectFontNames;
+
+/**
+ * Validate that every font name referenced in a document is either
+ * in SAFE_FONTS or present in the document's fontRegistry / runtime overrides.
+ *
+ * Used at generate-start; emits warnings for unresolved names so pipelines
+ * can surface them via their existing warning channels.
+ */
+
+/**
+ * Warning codes for font resolution + rendering.
+ *
+ * - `FONT_UNRESOLVED`         — family not in SAFE_FONTS and not registered.
+ * - `FONT_MODE_SUBSTITUTED`   — non-safe families rewritten to safe equivalents.
+ * - `FONT_MODE_CUSTOM`        — export mode "custom" — refs kept as-is.
+ */
+type FontIssueCode = 'FONT_UNRESOLVED' | 'FONT_MODE_SUBSTITUTED' | 'FONT_MODE_CUSTOM';
+interface FontResolutionIssue {
+    code: FontIssueCode;
+    family: string;
+    message: string;
+}
+interface FontValidationResult {
+    /** Names that resolved via SAFE_FONTS or the registry. */
+    resolved: string[];
+    /** Names with no resolution path. */
+    unresolved: string[];
+    /** One warning per unresolved name. */
+    warnings: FontResolutionIssue[];
+}
+interface FontValidationInput {
+    /** Font names referenced in the document (from collectFontNamesFromDocx / FromPptx). */
+    referencedNames: Iterable<string>;
+    /** Runtime-registered entries (e.g. from FontRuntimeOpts.extraEntries). */
+    registeredEntries?: FontRegistryEntry[];
+}
+/**
+ * Validate referenced font names against SAFE_FONTS + runtime-registered entries.
+ * Does not perform network fetches — this runs purely off schema + opts content.
+ */
+declare function validateFontReferences(input: FontValidationInput): FontValidationResult;
+
+/**
+ * Map a (family, weight, italic) tuple to the pair of
+ * `(familyName, { bold, italic })` the renderer should actually use.
+ *
+ * OOXML runs can only carry a bold/italic toggle, not a numeric weight.
+ * For weights outside the RIBBI quad (400/700 × roman/italic), Word
+ * resolves intermediate weights via **separate sub-family faces** whose
+ * internal family name is the canonical Google-Fonts-style subfamily,
+ * e.g. `Inter Light`, `Inter ExtraBold Italic`. Rewriting the run's
+ * `family` to that synthetic name lets Word pick the right face when the
+ * recipient has the full family installed, and lets the LibreOffice
+ * preview resolve the matching staged TTF by its internal name.
+ *
+ * No embedding involved — this is purely a name transform applied at
+ * render time. Safe fonts and unrecognised weights fall back to the
+ * bold-only heuristic (`weight >= 600 → bold`).
+ */
+/** Human-readable labels for the canonical font-weight numbers. */
+declare const WEIGHT_LABELS: Record<number, string>;
+interface SynthesizedFamily {
+    /** The family name to emit in `rFonts`/`fontFace`. */
+    family: string;
+    /** Whether to also set the run's bold toggle. */
+    bold: boolean;
+    /** Whether to also set the run's italic toggle. */
+    italic: boolean;
+    /**
+     * `true` when the input `weight` was not one of the canonical
+     * 100/200/.../900 labels. The canonical family name is returned with
+     * a `weight >= 600 → bold` fallback, but the run will not match a
+     * dedicated sub-family face — callers should surface this so authors
+     * know the weight was effectively rounded to Regular or Bold.
+     */
+    nonCanonicalWeight: boolean;
+}
+/**
+ * Translate `(family, weight, italic)` into the rendering-time family name
+ * plus the bold/italic toggles to emit on the run.
+ *
+ * - RIBBI (weights 400 + 700, roman + italic) stays on the canonical family
+ *   name and uses native bold/italic toggles.
+ * - Other canonical weights become `"<Family> <Weight>"` (e.g.
+ *   `"Inter Light"`) with bold/italic toggles cleared; any italic flag is
+ *   folded into the name (`"Inter Light Italic"`).
+ * - Non-canonical weights (floating or out-of-range) fall back to
+ *   `bold = weight >= 600` and leave the family name untouched.
+ */
+declare function synthesizeFamilyName(family: string, weight: number | undefined, italic: boolean): SynthesizedFamily;
+
+/**
+ * Rewrite a TTF/OTF's `name` table so `nameID` 1 / 4 / 6 / 16 carry the
+ * supplied synthetic family name. Used by the preview-side font stagers
+ * so that running-text references like `"Inter Light"` resolve to the
+ * correct face when the stager registers it with Core Text / fontconfig
+ * / GDI (all of which index by the font's internal `name` table rather
+ * than the filename).
+ *
+ * The transform rebuilds the whole font: new `name` table bytes, new
+ * table directory with shifted offsets, recomputed per-table checksums,
+ * and the magic `head.checkSumAdjustment` recomputed against the whole
+ * output buffer. Nothing else is touched.
+ *
+ * OTF (CFF-flavoured) and TTF (glyf-flavoured) share the sfnt outer
+ * structure, so the same code handles both.
+ */
+/**
+ * Return a copy of `input` whose name table has `nameID` 1/4/6/16 rewritten
+ * to `newFamily`. Returns the original buffer unchanged if the font has no
+ * `name` table or the sfnt header is invalid.
+ */
+declare function rewriteFontFamilyName(input: Buffer, newFamily: string): Buffer;
+
+/**
+ * FontRegistry — merges catalog + document registry + runtime entries
+ * and materializes referenced fonts into ResolvedFont records.
+ *
+ * Resolution rules, per referenced name:
+ * 1. Registry match (by family or id, case-insensitive). Runtime entries win
+ *    on collision with document entries. Materialize each source.
+ * 2. SAFE_FONTS membership → empty sources.
+ * 3. Otherwise → empty sources with FONT_UNRESOLVED warning.
+ */
+
+/**
+ * Minimal interface the registry needs from a disk cache. The concrete
+ * implementation ships in `./cache/disk-cache` but is Node-only (uses fs/crypto).
+ * Callers on Node inject an instance; browser callers pass nothing.
+ */
+interface FontDiskCacheLike$1 {
+    get(key: string): Promise<Buffer | undefined>;
+    set(key: string, value: Buffer): Promise<void>;
+}
+/**
+ * Minimal interface for a file-loader. Same reasoning as FontDiskCacheLike:
+ * concrete impl is Node-only, callers inject when on Node.
+ */
+type FontFileLoader = (input: {
+    path: string;
+    weight?: number;
+    italic?: boolean;
+    baseDir?: string;
+}) => Promise<ResolvedFontSource>;
+/**
+ * Minimal interface for the variable-font fetcher. `subset-font` (the
+ * harfbuzz-wasm wrapper we use for axis pinning) reaches for `fs` at
+ * init time, which crashes in the browser. Injection keeps that import
+ * behind the Node-only subpath; browser bundles never pull it in, and
+ * browser callers simply won't see `kind: 'variable'` fonts resolved
+ * (the registry warns and skips instead).
+ */
+type FontVariableLoader = (input: {
+    url: string;
+    weight: number;
+    italic: boolean;
+    axes?: Record<string, number>;
+    fetchTimeoutMs?: number;
+    memoryCache?: {
+        get(key: string): Buffer | undefined;
+        set(key: string, value: Buffer): void;
+    };
+    diskCache?: {
+        get(key: string): Promise<Buffer | undefined>;
+        set(key: string, value: Buffer): Promise<void>;
+    };
+}) => Promise<{
+    source?: ResolvedFontSource;
+    warnings?: string[];
+}>;
+interface FontRegistryInput {
+    /** Runtime options — entries come from opts.extraEntries. */
+    opts?: FontRuntimeOpts;
+    /** Optional disk cache (Node only). Pass an instance of FontDiskCache. */
+    diskCache?: FontDiskCacheLike$1;
+    /**
+     * Optional `kind: "file"` loader (Node only). Inject `loadFileFontSource`
+     * from `@json-to-office/shared/fonts/sources/file-loader` on Node. Browser
+     * callers pass nothing; `kind: "file"` sources then warn and skip.
+     */
+    fileLoader?: FontFileLoader;
+    /**
+     * Optional `kind: "variable"` loader (Node only). Inject
+     * `fetchVariableFontSource` from `@json-to-office/shared/fonts/node` on
+     * Node. Browser callers pass nothing; `kind: "variable"` sources then
+     * warn and skip. Keeping this injected avoids dragging subset-font (and
+     * its `fs.promises.readFile` bootstrap) into client bundles.
+     */
+    variableLoader?: FontVariableLoader;
+}
+declare class FontRegistry {
+    private readonly index;
+    private readonly cache;
+    private readonly opts;
+    private readonly memoryCache;
+    private readonly diskCache;
+    private readonly fileLoader;
+    private readonly variableLoader;
+    constructor(input?: FontRegistryInput);
+    private addEntry;
+    /** Resolve every referenced name in one pass. Order preserved. */
+    resolveMany(names: Iterable<string>): Promise<ResolvedFont[]>;
+    resolve(name: string): Promise<ResolvedFont>;
+    private materializeEntry;
+    private materializeSource;
+}
+
+/**
+ * Font format detection from magic bytes.
+ * Source: OpenType spec + WOFF1/WOFF2 W3C specs.
+ */
+
+declare function detectFontFormat(buf: Buffer): ResolvedFontSource['format'];
+
+/**
+ * Curated list of popular Google Fonts for picker autocomplete.
+ *
+ * Not exhaustive — the full Google Fonts library has ~1500 families.
+ * This is ~30 names known to cover most real-world use cases.
+ */
+interface PopularGoogleFont {
+    family: string;
+    category: 'sans' | 'serif' | 'mono' | 'display' | 'handwriting';
+    /** Weights available on Google Fonts for this family. */
+    weights: number[];
+    /** Whether italic variants exist. */
+    hasItalic: boolean;
+}
+declare const POPULAR_GOOGLE_FONTS: readonly PopularGoogleFont[];
+
+/**
+ * Per-family upstream overrides for popular Google Fonts whose
+ * redistribution on fonts.google.com has known defects we can't fix via
+ * metadata patching alone.
+ *
+ * When `autoGoogleFontEntries` hits a family present in this table, it
+ * builds override sources instead of issuing `kind: "google"` CSS requests.
+ * Each entry is either:
+ *
+ *   - `{ kind: "url", url, weight, italic? }` — a direct HTTPS TTF/OTF.
+ *     Use when a clean per-weight static exists on a stable CDN.
+ *
+ *   - `{ kind: "variable", url, weight, italic? }` — points at a variable
+ *     TTF with an `fvar` table. The registry downloads the variable font
+ *     once and harfbuzz-pins the `wght` axis to the specified weight,
+ *     producing a clean static TTF. Use when the upstream ships a variable
+ *     font but no per-weight statics on a CDN (rsms/inter is the
+ *     canonical example — variable font on jsDelivr, per-weight statics
+ *     only in GitHub release zips).
+ *
+ * Pick `variable` over `url` when both are available: the instancer
+ * produces per-weight glyph outlines that diverge correctly at every
+ * axis value. Google's static redistributions collapse adjacent weights
+ * onto the same instance — Inter Thin and ExtraLight both source at
+ * ~wght=250 in Google's pipeline, so their static TTFs have 98% identical
+ * glyph outlines. Instancing the upstream variable font at exactly wght=100
+ * vs wght=200 gives properly distinct geometry.
+ *
+ * Validate new entries with a HEAD request before adding — the fetchers
+ * reject non-TTF responses, but a failed override silently falls back to
+ * the Google path, defeating the purpose.
+ */
+/** One upstream variant source. Type matches the FontSource schema so we
+ *  can pass the entry directly into `FontRegistry`'s materialize pipeline. */
+type UpstreamVariant = {
+    kind: 'url';
+    url: string;
+    weight: number;
+    italic?: boolean;
+} | {
+    kind: 'variable';
+    url: string;
+    weight: number;
+    italic?: boolean;
+    /** Extra axis pins merged on top of the derived `wght` pin. */
+    axes?: Record<string, number>;
+};
+interface UpstreamOverride {
+    /** Human-readable for logs/diagnostics only. */
+    reason: string;
+    variants: UpstreamVariant[];
+}
+declare const UPSTREAM_OVERRIDES: Record<string, UpstreamOverride>;
+/** Case-insensitive lookup. Returns undefined when the family has no override. */
+declare function getUpstreamOverride(family: string): UpstreamOverride | undefined;
+
+/**
+ * In-process LRU cache for resolved font buffers.
+ * Scoped to a single process — do not share across requests on a server.
+ */
+interface MemoryCacheOptions {
+    /** Approximate soft cap in bytes. LRU-evict when exceeded. */
+    maxBytes?: number;
+}
+declare class FontMemoryCache {
+    private readonly store;
+    private bytes;
+    private readonly maxBytes;
+    constructor(opts?: MemoryCacheOptions);
+    get(key: string): Buffer | undefined;
+    set(key: string, value: Buffer): void;
+    size(): number;
+}
+
+/**
+ * Google Fonts fetcher.
+ *
+ * Hits the CSS API v2 with an older User-Agent that returns TTF (default UA
+ * gets WOFF2, which Office cannot embed as-is). Parses the `src: url(...)` line
+ * and downloads the binary.
+ *
+ * Uses memory + optional disk cache keyed by `${family}|${weight}|${italic}`.
+ */
+
+interface FontDiskCacheLike {
+    get(key: string): Promise<Buffer | undefined>;
+    set(key: string, value: Buffer): Promise<void>;
+}
+interface GoogleFetchOptions {
+    family: string;
+    weights: number[];
+    italics?: boolean;
+    memoryCache?: FontMemoryCache;
+    diskCache?: FontDiskCacheLike;
+    fetchTimeoutMs?: number;
+    /** Override for tests. */
+    fetcher?: typeof fetch;
+}
+interface GoogleFetchResult {
+    sources: ResolvedFontSource[];
+    warnings: string[];
+}
+declare function fetchGoogleFontSources(opts: GoogleFetchOptions): Promise<GoogleFetchResult>;
+
+/**
+ * Font family substitution: rewrite every non-safe family reference in
+ * the doc tree + theme to a SAFE_FONTS equivalent. Used by the
+ * `'substitute'` export mode (`FontRuntimeOpts.mode`) so that non-safe
+ * fonts (Playfair Display, Inter, …) ship as Georgia/Calibri and the
+ * document renders identically on every recipient machine — no embed
+ * bytes, no Word-for-Mac intermediate-weight surprises.
+ *
+ * The walker mirrors the shape used by `collectFontNamesFromDocx/Pptx`
+ * so the two stay in sync: whatever `collect` scans, `rewrite` will
+ * rewrite. Future component-schema additions that introduce new font
+ * keys go in `FONT_NAME_KEYS` / `THEME_FONT_KEYS` once, both sides pick
+ * them up.
+ */
+
+/** One swap recorded during a rewrite. */
+interface FontSubstitution {
+    from: string;
+    to: string;
+}
+interface ApplyFontSubstitutionResult<T> {
+    doc: T;
+    substitutions: FontSubstitution[];
+}
+/**
+ * Walk a doc tree + swap every non-safe family reference per `mapping`.
+ * Returns a new tree (structural clone) plus the list of `(from, to)`
+ * swaps made, deduped by source name.
+ *
+ * Families already in SAFE_FONTS are never rewritten (even if a mapping
+ * entry targets them as a key — safe fonts don't need substitution).
+ * Families with no mapping entry are left untouched — callers should
+ * feed the result of `buildDefaultSubstitutionMap` to ensure every
+ * non-safe reference gets a fallback.
+ */
+declare function applyFontSubstitution<T>(doc: T, mapping: Record<string, string>): ApplyFontSubstitutionResult<T>;
+/**
+ * Pick the safe-font fallback for a single non-safe family. Precedence:
+ *   1. Explicit override in `EXPLICIT_OVERRIDES`.
+ *   2. Category lookup in `POPULAR_GOOGLE_FONTS`.
+ *   3. Final default (`Calibri`).
+ *
+ * Exposed for the playground dialog so it can pre-populate the per-family
+ * picker with the same defaults the CLI would apply.
+ */
+declare function defaultSubstituteFor(family: string): string;
+/**
+ * Build a substitution map for every non-safe family in `referencedNames`.
+ * Safe fonts are omitted from the result since they don't need swapping.
+ * Caller can override individual entries before passing to
+ * `applyFontSubstitution`.
+ */
+declare function buildDefaultSubstitutionMap(referencedNames: Iterable<string>): Record<string, string>;
+
+/**
+ * Cache-key suffix used to scope generator outputs by export mode. When
+ * `fonts.mode === 'substitute'` the doc tree is rewritten pre-render, so
+ * a substitute-mode buffer and a custom-mode buffer for the same base
+ * theme must not collide in the byte cache. Keep this as a single
+ * helper so a typo in one caller can't silently alias one mode onto the
+ * other's cache slot.
+ */
+declare function scopedThemeName(baseThemeName: string, fontMode: string | undefined): string;
+
+interface ApplyExportModeInput<D, T> {
+    doc: D;
+    theme: T;
+    fonts?: FontRuntimeOpts;
+}
+interface ApplyExportModeWarning {
+    code: 'FONT_MODE_CUSTOM' | 'FONT_MODE_SUBSTITUTED';
+    message: string;
+}
+interface ApplyExportModeResult<D, T> {
+    doc: D;
+    theme: T;
+    warnings: ApplyExportModeWarning[];
+}
+/**
+ * Inspect `fonts.mode` and apply the pre-resolution rewrite for the
+ * requested mode.
+ *
+ * - `'custom'` (default) — no rewrite. Font references stay as authored;
+ *   recipients need the font installed or Word falls back. The
+ *   LibreOffice preview stager registers resolved bytes so preview
+ *   fidelity matches the recipient-side experience when the font is
+ *   installed.
+ * - `'substitute'` — rewrite every non-safe family in doc + theme to its
+ *   mapped safe equivalent. Fills in defaults via
+ *   `buildDefaultSubstitutionMap` for any non-safe reference not present
+ *   in `fonts.substitution`. Emits one `FONT_MODE_SUBSTITUTED` warning
+ *   listing every swap.
+ */
+declare function applyExportMode<D, T>(input: ApplyExportModeInput<D, T>): ApplyExportModeResult<D, T>;
+
 /**
  * Deep Merge Utilities
  * Generic deep-merge helpers used by both docx and pptx
@@ -31,4 +470,4 @@ interface ServicesConfig {
  */
 declare function mergeWithDefaults<T>(userConfig: T, themeDefaults: Partial<T>): T;
 
-export { type HighchartsServiceConfig, type ServicesConfig, mergeWithDefaults };
+export { type FontIssueCode, FontRegistry, FontRegistryEntry, type FontRegistryInput, type FontResolutionIssue, FontRuntimeOpts, type FontSubstitution, type FontValidationInput, type FontValidationResult, type HighchartsHeaders, type HighchartsHeadersResolver, type HighchartsServiceConfig, POPULAR_GOOGLE_FONTS, type PopularGoogleFont, ResolvedFont, ResolvedFontSource, type ServicesConfig, type SynthesizedFamily, UPSTREAM_OVERRIDES, type UpstreamOverride, type UpstreamVariant, WEIGHT_LABELS, applyExportMode, applyFontSubstitution, buildDefaultSubstitutionMap, collectFontNamesFromDocx, collectFontNamesFromPptx, defaultSubstituteFor, detectFontFormat, fetchGoogleFontSources, getUpstreamOverride, mergeWithDefaults, rewriteFontFamilyName, scopedThemeName, synthesizeFamilyName, validateFontReferences };