@superdoc-dev/fonts 0.1.0 → 0.1.1

package/README.md

@@ -40,6 +40,27 @@ That is the whole setup. No copying files into `public/`, no `assetBaseUrl`. The
 written as `new URL('../assets/<file>', import.meta.url)`, which Vite, Webpack 5, Next, Nuxt,
 esbuild, and Parcel all detect, emit, and rewrite to the final hashed path.
 
+### CDN / `<script>` tag (no bundler)
+
+For a plain HTML page, load the browser build and use the `SuperDocFonts` global. It exposes the
+same API, and the faces resolve relative to the script, so there is no bundler and no path config:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/superdoc/dist/superdoc.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@superdoc-dev/fonts/dist/superdoc-fonts.min.js"></script>
+<script>
+  new SuperDoc({
+    selector: '#editor',
+    document: 'contract.docx',
+    fonts: SuperDocFonts.superdocFonts, // or SuperDocFonts.createSuperDocFonts({ exclude: [...] })
+  });
+</script>
+```
+
+The `superdoc` CDN build ships no fonts and shows the baseline until you add this script. Self-hosting
+works too: keep the package's `dist/` and `assets/` in their relative layout, since the faces resolve
+to `../assets/` next to `superdoc-fonts.min.js`.
+
 ### Choosing which fonts
 
 `superdocFonts` enables every reviewed family. To narrow the set, use `createSuperDocFonts` and name

package/dist/bundled-families.d.ts

@@ -6,4 +6,10 @@
  * bundled face, including category fallbacks like Verdana). A name outside this set is a typo or an
  * unbundled font, so createSuperDocFonts rejects it instead of silently dropping the intended fonts.
  */
-export declare const BUNDLED_FAMILY_NAMES: readonly string[];
+export declare const BUNDLED_FAMILY_NAMES: readonly ["Arial", "Arial Black", "Arial MT", "Arial Narrow", "Baskerville Old Face", "Bookman Old Style", "Brush Script MT", "Calibri", "Calibri Light", "Cambria", "Century", "Century Gothic", "Century Schoolbook", "Comic Sans MS", "Consolas", "Cooper Black", "Courier", "Courier New", "Garamond", "Georgia", "Gill Sans MT Condensed", "Helvetica", "ITC Bookman", "Lucida Console", "Segoe UI", "Tahoma", "Times", "Times New Roman", "Trebuchet MS", "Verdana"];
+/**
+ * Union of the Word family names the bundled pack can curate, for autocomplete on
+ * createSuperDocFonts({ include / exclude }). Those options also accept any string (case- and
+ * quote-insensitive, validated at runtime), so a list built from dynamic config still type-checks.
+ */
+export type BundledFontFamilyName = (typeof BUNDLED_FAMILY_NAMES)[number];

package/dist/bundled-files.d.ts

@@ -0,0 +1,8 @@
+/**
+ * GENERATED by scripts/generate-asset-urls.mjs - do not edit by hand.
+ *
+ * The flat list of bundled .woff2 filenames, with NO `import.meta.url` (unlike asset-urls.ts).
+ * The browser/IIFE entry (cdn-entry.ts) imports this to validate face files and to resolve them
+ * relative to its own <script>, since import.meta.url is not available in an IIFE bundle.
+ */
+export declare const BUNDLED_FONT_FILES: readonly string[];

package/dist/bundled-files.js

@@ -0,0 +1,74 @@
+/**
+ * GENERATED by scripts/generate-asset-urls.mjs - do not edit by hand.
+ *
+ * The flat list of bundled .woff2 filenames, with NO `import.meta.url` (unlike asset-urls.ts).
+ * The browser/IIFE entry (cdn-entry.ts) imports this to validate face files and to resolve them
+ * relative to its own <script>, since import.meta.url is not available in an IIFE bundle.
+ */
+export const BUNDLED_FONT_FILES = Object.freeze([
+    'ArchivoBlack-Regular.woff2',
+    'BacasimeAntique-Regular.woff2',
+    'C059-BdIta.woff2',
+    'C059-Bold.woff2',
+    'C059-Italic.woff2',
+    'C059-Roman.woff2',
+    'Caladea-Bold.woff2',
+    'Caladea-BoldItalic.woff2',
+    'Caladea-Italic.woff2',
+    'Caladea-Regular.woff2',
+    'Caprasimo-Regular.woff2',
+    'Cardo-Bold.woff2',
+    'Cardo-Italic.woff2',
+    'Cardo-Regular.woff2',
+    'Carlito-Bold.woff2',
+    'Carlito-BoldItalic.woff2',
+    'Carlito-Italic.woff2',
+    'Carlito-Regular.woff2',
+    'ComicRelief-Bold.woff2',
+    'ComicRelief-Regular.woff2',
+    'Gelasio-Bold.woff2',
+    'Gelasio-BoldItalic.woff2',
+    'Gelasio-Italic.woff2',
+    'Gelasio-Regular.woff2',
+    'InconsolataSemiExpanded-Bold.woff2',
+    'InconsolataSemiExpanded-Regular.woff2',
+    'LiberationMono-Bold.woff2',
+    'LiberationMono-BoldItalic.woff2',
+    'LiberationMono-Italic.woff2',
+    'LiberationMono-Regular.woff2',
+    'LiberationSans-Bold.woff2',
+    'LiberationSans-BoldItalic.woff2',
+    'LiberationSans-Italic.woff2',
+    'LiberationSans-Regular.woff2',
+    'LiberationSansNarrow-Bold.woff2',
+    'LiberationSansNarrow-BoldItalic.woff2',
+    'LiberationSansNarrow-Italic.woff2',
+    'LiberationSansNarrow-Regular.woff2',
+    'LiberationSerif-Bold.woff2',
+    'LiberationSerif-BoldItalic.woff2',
+    'LiberationSerif-Italic.woff2',
+    'LiberationSerif-Regular.woff2',
+    'NotoSans-Bold.woff2',
+    'NotoSans-BoldItalic.woff2',
+    'NotoSans-Italic.woff2',
+    'NotoSans-Regular.woff2',
+    'NotoSansMono-Bold.woff2',
+    'NotoSansMono-Regular.woff2',
+    'OreganoItalic-Regular.woff2',
+    'PTSans-Bold.woff2',
+    'PTSans-BoldItalic.woff2',
+    'PTSans-Italic.woff2',
+    'PTSans-Regular.woff2',
+    'PTSansNarrow-Bold.woff2',
+    'PTSansNarrow-Regular.woff2',
+    'Selawik-Bold.woff2',
+    'Selawik-Regular.woff2',
+    'TeXGyreBonum-Bold.woff2',
+    'TeXGyreBonum-BoldItalic.woff2',
+    'TeXGyreBonum-Italic.woff2',
+    'TeXGyreBonum-Regular.woff2',
+    'URWGothic-Book.woff2',
+    'URWGothic-BookOblique.woff2',
+    'URWGothic-Demi.woff2',
+    'URWGothic-DemiOblique.woff2',
+]);

package/dist/cdn-entry.d.ts

@@ -0,0 +1,27 @@
+import { type BundledFontAssetContext, type SuperDocFontsConfig, type SuperDocFontsOptions } from './curation.js';
+/**
+ * Resolve a bundled face filename to a URL relative to THIS script. Throws on an unknown file
+ * (a version mismatch between `@superdoc-dev/fonts` and `superdoc`) and on a missing script URL,
+ * matching the bundler entry's fail-loud-not-silent contract.
+ *
+ * @beta
+ */
+export declare function resolveBundledFontAssetUrl(context: BundledFontAssetContext): string;
+/**
+ * Drop-in value for SuperDoc's `fonts` config: `new SuperDoc({ fonts: SuperDocFonts.superdocFonts })`.
+ *
+ * @beta
+ */
+export declare const superdocFonts: SuperDocFontsConfig;
+/**
+ * Build a curated `fonts` config: the bundled pack narrowed to the families you choose. Same API
+ * and validation as the bundler entry's `createSuperDocFonts`; only the resolver differs.
+ *
+ *     new SuperDoc({ fonts: SuperDocFonts.createSuperDocFonts({ exclude: ['Cooper Black'] }) });
+ *
+ * @beta
+ */
+export declare function createSuperDocFonts(options?: SuperDocFontsOptions): SuperDocFontsConfig;
+export type { BundledFontAssetContext, SuperDocFontsConfig, SuperDocFontsOptions };
+export { BUNDLED_FAMILY_NAMES } from './bundled-families.js';
+export type { BundledFontFamilyName } from './bundled-families.js';

package/dist/cdn-entry.js

@@ -0,0 +1,67 @@
+/**
+ * Browser / `<script>` (IIFE) entry for `@superdoc-dev/fonts`, built to
+ * `dist/superdoc-fonts.min.js` and exposed as the `SuperDocFonts` global.
+ *
+ * Unlike the bundler entry ({@link "./index"}), it resolves the `.woff2` relative to its OWN
+ * `<script>` (`document.currentScript`) instead of `import.meta.url`, so a plain CDN / self-host
+ * `<script>` tag works with no bundler:
+ *
+ *     <script src="https://cdn.jsdelivr.net/npm/superdoc/dist/superdoc.min.js"></script>
+ *     <script src="https://cdn.jsdelivr.net/npm/@superdoc-dev/fonts/dist/superdoc-fonts.min.js"></script>
+ *     <script>
+ *       new SuperDoc({ selector: '#editor', document: 'contract.docx', fonts: SuperDocFonts.superdocFonts });
+ *     </script>
+ *
+ * The faces ship in the package's `assets/` dir and this bundle in `dist/`, so a face resolves to
+ * `../assets/<file>` relative to the script. On a public CDN (jsDelivr / unpkg) the whole package
+ * is served, so that resolves with no setup; self-hosting requires the `dist/` and `assets/` dirs
+ * to keep their relative layout.
+ *
+ * @beta
+ */
+import { BUNDLED_FONT_FILES } from './bundled-files.js';
+import { resolveCuration, } from './curation.js';
+// Capture the executing <script> src at load. `document.currentScript` is valid while this
+// top-level IIFE runs and null later (e.g. in async callbacks), so it MUST be read here, at module
+// eval, not inside the resolver. Duck-typed (no `instanceof HTMLScriptElement`) so the module also
+// evaluates under a non-DOM test environment where that constructor is absent.
+const currentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const SCRIPT_SRC = currentScript?.src ?? '';
+const KNOWN_FILES = new Set(BUNDLED_FONT_FILES);
+/**
+ * Resolve a bundled face filename to a URL relative to THIS script. Throws on an unknown file
+ * (a version mismatch between `@superdoc-dev/fonts` and `superdoc`) and on a missing script URL,
+ * matching the bundler entry's fail-loud-not-silent contract.
+ *
+ * @beta
+ */
+export function resolveBundledFontAssetUrl(context) {
+    if (!KNOWN_FILES.has(context.file)) {
+        throw new Error(`[@superdoc-dev/fonts] no bundled asset for "${context.file}". This pack ships ` +
+            `${BUNDLED_FONT_FILES.length} faces; the file is unknown, so @superdoc-dev/fonts and ` +
+            `superdoc are likely version-mismatched. Align their versions.`);
+    }
+    if (!SCRIPT_SRC) {
+        throw new Error('[@superdoc-dev/fonts] could not determine the script URL to resolve bundled fonts from. ' +
+            'Load superdoc-fonts.min.js with a normal <script src="..."> tag.');
+    }
+    return new URL(`../assets/${context.file}`, SCRIPT_SRC).href;
+}
+/**
+ * Drop-in value for SuperDoc's `fonts` config: `new SuperDoc({ fonts: SuperDocFonts.superdocFonts })`.
+ *
+ * @beta
+ */
+export const superdocFonts = { resolveAssetUrl: resolveBundledFontAssetUrl };
+/**
+ * Build a curated `fonts` config: the bundled pack narrowed to the families you choose. Same API
+ * and validation as the bundler entry's `createSuperDocFonts`; only the resolver differs.
+ *
+ *     new SuperDoc({ fonts: SuperDocFonts.createSuperDocFonts({ exclude: ['Cooper Black'] }) });
+ *
+ * @beta
+ */
+export function createSuperDocFonts(options = {}) {
+    return { resolveAssetUrl: resolveBundledFontAssetUrl, ...resolveCuration(options) };
+}
+export { BUNDLED_FAMILY_NAMES } from './bundled-families.js';

package/dist/curation.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Resolver-independent curation + validation shared by the two entries: the bundler entry
+ * (`index.ts`, asset URLs via `import.meta.url`) and the browser/IIFE entry (`cdn-entry.ts`, URLs
+ * relative to its own `<script>`). Each entry supplies only its own asset-URL resolver; the
+ * `include` / `exclude` validation lives here once so the two entries can never drift.
+ *
+ * @beta
+ */
+import { type BundledFontFamilyName } from './bundled-families.js';
+/**
+ * Minimal structural shape of SuperDoc's bundled-font asset context. Kept LOCAL so this package
+ * has no dependency on `@superdoc/font-system`; only `file` is read. Assignable to SuperDoc's
+ * `FontAssetUrlResolver` by structural typing.
+ *
+ * @beta
+ */
+export interface BundledFontAssetContext {
+    /** Asset filename, e.g. `Carlito-Regular.woff2`. */
+    file: string;
+    family?: string;
+    weight?: string;
+    style?: 'normal' | 'italic';
+    source?: string;
+}
+/** Per-face asset-URL resolver: maps a bundled face filename to a URL the browser can fetch. */
+export type BundledFontAssetResolver = (context: BundledFontAssetContext) => string;
+/**
+ * Choose which bundled families SuperDoc advertises and renders, by LOGICAL Word family name
+ * (`"Calibri"`, never the physical `"Carlito"`).
+ *
+ * @beta
+ */
+export interface SuperDocFontsOptions {
+    /**
+     * Allow-list: ONLY these logical families are active, e.g. `['Calibri', 'Cambria']`. Autocompletes
+     * the bundled names, but also accepts any string (case- and quote-insensitive, validated at
+     * runtime), so a list built from dynamic config still type-checks.
+     */
+    include?: readonly (BundledFontFamilyName | (string & {}))[];
+    /** Block-list: every bundled family EXCEPT these, e.g. `['Cooper Black', 'Brush Script MT']`. */
+    exclude?: readonly (BundledFontFamilyName | (string & {}))[];
+}
+/**
+ * The `fonts` config the entries return: the bundled-asset resolver plus the curation.
+ * Structurally assignable to SuperDoc's `fonts` option.
+ *
+ * @beta
+ */
+export interface SuperDocFontsConfig {
+    resolveAssetUrl: BundledFontAssetResolver;
+    bundled?: {
+        include?: string[];
+        exclude?: string[];
+    };
+}
+/**
+ * Validate the curation options and return the `{ bundled? }` slice (no resolver). Each entry
+ * spreads this into its own `{ resolveAssetUrl, ...resolveCuration(options) }`.
+ */
+export declare function resolveCuration(options?: SuperDocFontsOptions): {
+    bundled?: {
+        include?: string[];
+        exclude?: string[];
+    };
+};

package/dist/curation.js

@@ -0,0 +1,102 @@
+/**
+ * Resolver-independent curation + validation shared by the two entries: the bundler entry
+ * (`index.ts`, asset URLs via `import.meta.url`) and the browser/IIFE entry (`cdn-entry.ts`, URLs
+ * relative to its own `<script>`). Each entry supplies only its own asset-URL resolver; the
+ * `include` / `exclude` validation lives here once so the two entries can never drift.
+ *
+ * @beta
+ */
+import { BUNDLED_FAMILY_NAMES } from './bundled-families.js';
+/**
+ * Validate the curation options and return the `{ bundled? }` slice (no resolver). Each entry
+ * spreads this into its own `{ resolveAssetUrl, ...resolveCuration(options) }`.
+ */
+export function resolveCuration(options = {}) {
+    const include = normalizeNameList(options.include, 'include');
+    const exclude = normalizeNameList(options.exclude, 'exclude');
+    // include and exclude are mutually exclusive intents; accepting both silently would hide which one
+    // wins. Reject at the API boundary (this runs in the consumer's setup code, so it fails fast and
+    // clearly) rather than picking one arbitrarily.
+    if (include && exclude) {
+        throw new Error('[@superdoc-dev/fonts] createSuperDocFonts: pass `include` OR `exclude`, not both. ' +
+            '`include` is an allow-list (only those families resolve and appear in the toolbar); ' +
+            '`exclude` keeps everything but the named families.');
+    }
+    // Reject names SuperDoc does not bundle. This runs in the consumer's setup code, so it fails fast
+    // and clearly - especially for `include`, where a typo would otherwise silently hide the fonts the
+    // consumer meant to keep. (Raw `fonts.bundled` set directly stays lenient and only warns.)
+    if (include)
+        assertKnownFamilies(include, 'include');
+    if (exclude)
+        assertKnownFamilies(exclude, 'exclude');
+    if (include)
+        return { bundled: { include } };
+    if (exclude)
+        return { bundled: { exclude } };
+    return {};
+}
+/** Validate and clean a curation list: an array of non-empty strings, or omitted. Throws on misuse. */
+function normalizeNameList(value, field) {
+    if (value == null)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error(`[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` must be an array of Word font names.`);
+    }
+    const names = value.map((name) => (typeof name === 'string' ? name.trim() : '')).filter(Boolean);
+    if (names.length !== value.length) {
+        throw new Error(`[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` must contain only non-empty font name strings ` +
+            `(e.g. ["Calibri", "Cambria"]).`);
+    }
+    return names.length ? names : undefined;
+}
+/** Normalize a family name for matching: trim, strip surrounding quotes, lowercase. */
+function normalizeKey(name) {
+    return name
+        .trim()
+        .replace(/^["']|["']$/g, '')
+        .toLowerCase();
+}
+const KNOWN_FAMILY_KEYS = new Set(BUNDLED_FAMILY_NAMES.map(normalizeKey));
+/** Bounded Levenshtein distance between two short strings, for a "did you mean" hint on a typo. */
+function editDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (Math.abs(m - n) > 2)
+        return 3;
+    let prev = Array.from({ length: n + 1 }, (_, i) => i);
+    for (let i = 1; i <= m; i += 1) {
+        const curr = [i];
+        for (let j = 1; j <= n; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        prev = curr;
+    }
+    return prev[n];
+}
+/** The closest bundled family within edit distance 2, or null - so a typo gets a concrete suggestion. */
+function closestKnownFamily(name) {
+    const key = normalizeKey(name);
+    let best = null;
+    let bestDist = 3;
+    for (const family of BUNDLED_FAMILY_NAMES) {
+        const dist = editDistance(key, normalizeKey(family));
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = family;
+        }
+    }
+    return best;
+}
+/** Throw on any curation name SuperDoc does not bundle, with a suggestion and the full valid list. */
+function assertKnownFamilies(names, field) {
+    const unknown = names.filter((name) => !KNOWN_FAMILY_KEYS.has(normalizeKey(name)));
+    if (unknown.length === 0)
+        return;
+    const hints = unknown.map((name) => {
+        const suggestion = closestKnownFamily(name);
+        return suggestion ? `"${name}" (did you mean "${suggestion}"?)` : `"${name}"`;
+    });
+    throw new Error(`[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` names a font SuperDoc does not bundle: ${hints.join(', ')}. ` +
+        `Curate by Word family name. Bundled families: ${BUNDLED_FAMILY_NAMES.join(', ')}.`);
+}

package/dist/index.d.ts

@@ -7,9 +7,13 @@
  * `new URL('../assets/<file>', import.meta.url)`, which Vite, Webpack 5, Next, Nuxt, esbuild, and
  * Parcel detect, emit, and rewrite to the final hashed path.
  *
+ * For a plain `<script>` / CDN page (no bundler), load `dist/superdoc-fonts.min.js` instead and use
+ * the `SuperDocFonts` global - same API, faces resolved relative to the script. See `cdn-entry.ts`.
+ *
  * @beta This package is in preview; its surface may change before 1.0.
  */
-import { BUNDLED_FONT_ASSET_URLS } from './asset-urls';
+import { BUNDLED_FONT_ASSET_URLS } from './asset-urls.js';
+import { type BundledFontAssetContext, type SuperDocFontsConfig, type SuperDocFontsOptions } from './curation.js';
 /**
  * The full filename -> bundler-emitted URL map for every bundled face. Most consumers use
  * {@link superdocFonts} or {@link resolveBundledFontAssetUrl} instead of reading this directly.
@@ -17,21 +21,15 @@ import { BUNDLED_FONT_ASSET_URLS } from './asset-urls';
  * @beta
  */
 export { BUNDLED_FONT_ASSET_URLS };
+export type { BundledFontAssetContext, SuperDocFontsConfig, SuperDocFontsOptions };
 /**
- * Minimal structural shape of SuperDoc's bundled-font asset context. Kept LOCAL so this
- * package has no dependency on `@superdoc/font-system`; only `file` is read. Assignable to
- * SuperDoc's `FontAssetUrlResolver` by structural typing.
+ * The curatable Word family names (and their union type), for building `include` / `exclude` lists
+ * with autocomplete. Re-exported from the generated source.
  *
  * @beta
  */
-export interface BundledFontAssetContext {
-    /** Asset filename, e.g. `Carlito-Regular.woff2`. */
-    file: string;
-    family?: string;
-    weight?: string;
-    style?: 'normal' | 'italic';
-    source?: string;
-}
+export { BUNDLED_FAMILY_NAMES } from './bundled-families.js';
+export type { BundledFontFamilyName } from './bundled-families.js';
 /**
  * Resolve a bundled substitute face filename to a bundler-emitted URL.
  *
@@ -53,34 +51,7 @@ export declare function resolveBundledFontAssetUrl(context: BundledFontAssetCont
  *
  * @beta
  */
-export declare const superdocFonts: {
-    resolveAssetUrl: (context: BundledFontAssetContext) => string;
-};
-/**
- * Choose which bundled families SuperDoc advertises and renders, by LOGICAL Word family name
- * (`"Calibri"`, never the physical `"Carlito"`).
- *
- * @beta
- */
-export interface SuperDocFontsOptions {
-    /** Allow-list: ONLY these logical families are active, e.g. `['Calibri', 'Cambria']`. */
-    include?: string[];
-    /** Block-list: every bundled family EXCEPT these, e.g. `['Cooper Black', 'Brush Script MT']`. */
-    exclude?: string[];
-}
-/**
- * The `fonts` config {@link createSuperDocFonts} returns: the bundled-asset resolver plus the
- * curation. Structurally assignable to SuperDoc's `fonts` option.
- *
- * @beta
- */
-export interface SuperDocFontsConfig {
-    resolveAssetUrl: (context: BundledFontAssetContext) => string;
-    bundled?: {
-        include?: string[];
-        exclude?: string[];
-    };
-}
+export declare const superdocFonts: SuperDocFontsConfig;
 /**
  * Build a curated `fonts` config: the bundled pack, narrowed to the families you choose.
  *

package/dist/index.js

@@ -7,10 +7,13 @@
  * `new URL('../assets/<file>', import.meta.url)`, which Vite, Webpack 5, Next, Nuxt, esbuild, and
  * Parcel detect, emit, and rewrite to the final hashed path.
  *
+ * For a plain `<script>` / CDN page (no bundler), load `dist/superdoc-fonts.min.js` instead and use
+ * the `SuperDocFonts` global - same API, faces resolved relative to the script. See `cdn-entry.ts`.
+ *
  * @beta This package is in preview; its surface may change before 1.0.
  */
-import { BUNDLED_FONT_ASSET_URLS } from './asset-urls';
-import { BUNDLED_FAMILY_NAMES } from './bundled-families';
+import { BUNDLED_FONT_ASSET_URLS } from './asset-urls.js';
+import { resolveCuration, } from './curation.js';
 /**
  * The full filename -> bundler-emitted URL map for every bundled face. Most consumers use
  * {@link superdocFonts} or {@link resolveBundledFontAssetUrl} instead of reading this directly.
@@ -18,6 +21,13 @@ import { BUNDLED_FAMILY_NAMES } from './bundled-families';
  * @beta
  */
 export { BUNDLED_FONT_ASSET_URLS };
+/**
+ * The curatable Word family names (and their union type), for building `include` / `exclude` lists
+ * with autocomplete. Re-exported from the generated source.
+ *
+ * @beta
+ */
+export { BUNDLED_FAMILY_NAMES } from './bundled-families.js';
 /**
  * Resolve a bundled substitute face filename to a bundler-emitted URL.
  *
@@ -67,92 +77,5 @@ export const superdocFonts = {
  * @beta
  */
 export function createSuperDocFonts(options = {}) {
-    const include = normalizeNameList(options.include, 'include');
-    const exclude = normalizeNameList(options.exclude, 'exclude');
-    // include and exclude are mutually exclusive intents; accepting both silently would hide which one
-    // wins. Reject at the API boundary (this runs in the consumer's setup code, so it fails fast and
-    // clearly) rather than picking one arbitrarily.
-    if (include && exclude) {
-        throw new Error('[@superdoc-dev/fonts] createSuperDocFonts: pass `include` OR `exclude`, not both. ' +
-            '`include` is an allow-list (only those families resolve and appear in the toolbar); ' +
-            '`exclude` keeps everything but the named families.');
-    }
-    // Reject names SuperDoc does not bundle. This runs in the consumer's setup code, so it fails fast
-    // and clearly - especially for `include`, where a typo would otherwise silently hide the fonts the
-    // consumer meant to keep. (Raw `fonts.bundled` set directly stays lenient and only warns.)
-    if (include)
-        assertKnownFamilies(include, 'include');
-    if (exclude)
-        assertKnownFamilies(exclude, 'exclude');
-    const config = { resolveAssetUrl: resolveBundledFontAssetUrl };
-    if (include)
-        config.bundled = { include };
-    else if (exclude)
-        config.bundled = { exclude };
-    return config;
-}
-/** Validate and clean a curation list: an array of non-empty strings, or omitted. Throws on misuse. */
-function normalizeNameList(value, field) {
-    if (value == null)
-        return undefined;
-    if (!Array.isArray(value)) {
-        throw new Error(`[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` must be an array of Word font names.`);
-    }
-    const names = value.map((name) => (typeof name === 'string' ? name.trim() : '')).filter(Boolean);
-    if (names.length !== value.length) {
-        throw new Error(`[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` must contain only non-empty font name strings ` +
-            `(e.g. ["Calibri", "Cambria"]).`);
-    }
-    return names.length ? names : undefined;
-}
-/** Normalize a family name for matching: trim, strip surrounding quotes, lowercase. */
-function normalizeKey(name) {
-    return name
-        .trim()
-        .replace(/^["']|["']$/g, '')
-        .toLowerCase();
-}
-const KNOWN_FAMILY_KEYS = new Set(BUNDLED_FAMILY_NAMES.map(normalizeKey));
-/** Bounded Levenshtein distance between two short strings, for a "did you mean" hint on a typo. */
-function editDistance(a, b) {
-    const m = a.length;
-    const n = b.length;
-    if (Math.abs(m - n) > 2)
-        return 3;
-    let prev = Array.from({ length: n + 1 }, (_, i) => i);
-    for (let i = 1; i <= m; i += 1) {
-        const curr = [i];
-        for (let j = 1; j <= n; j += 1) {
-            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
-        }
-        prev = curr;
-    }
-    return prev[n];
-}
-/** The closest bundled family within edit distance 2, or null - so a typo gets a concrete suggestion. */
-function closestKnownFamily(name) {
-    const key = normalizeKey(name);
-    let best = null;
-    let bestDist = 3;
-    for (const family of BUNDLED_FAMILY_NAMES) {
-        const dist = editDistance(key, normalizeKey(family));
-        if (dist < bestDist) {
-            bestDist = dist;
-            best = family;
-        }
-    }
-    return best;
-}
-/** Throw on any curation name SuperDoc does not bundle, with a suggestion and the full valid list. */
-function assertKnownFamilies(names, field) {
-    const unknown = names.filter((name) => !KNOWN_FAMILY_KEYS.has(normalizeKey(name)));
-    if (unknown.length === 0)
-        return;
-    const hints = unknown.map((name) => {
-        const suggestion = closestKnownFamily(name);
-        return suggestion ? `"${name}" (did you mean "${suggestion}"?)` : `"${name}"`;
-    });
-    throw new Error(`[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` names a font SuperDoc does not bundle: ${hints.join(', ')}. ` +
-        `Curate by Word family name. Bundled families: ${BUNDLED_FAMILY_NAMES.join(', ')}.`);
+    return { resolveAssetUrl: resolveBundledFontAssetUrl, ...resolveCuration(options) };
 }

package/dist/superdoc-fonts.min.js

@@ -0,0 +1,3 @@
+var SuperDocFonts=(function(f){Object.defineProperty(f,Symbol.toStringTag,{value:"Module"});const d=Object.freeze(["ArchivoBlack-Regular.woff2","BacasimeAntique-Regular.woff2","C059-BdIta.woff2","C059-Bold.woff2","C059-Italic.woff2","C059-Roman.woff2","Caladea-Bold.woff2","Caladea-BoldItalic.woff2","Caladea-Italic.woff2","Caladea-Regular.woff2","Caprasimo-Regular.woff2","Cardo-Bold.woff2","Cardo-Italic.woff2","Cardo-Regular.woff2","Carlito-Bold.woff2","Carlito-BoldItalic.woff2","Carlito-Italic.woff2","Carlito-Regular.woff2","ComicRelief-Bold.woff2","ComicRelief-Regular.woff2","Gelasio-Bold.woff2","Gelasio-BoldItalic.woff2","Gelasio-Italic.woff2","Gelasio-Regular.woff2","InconsolataSemiExpanded-Bold.woff2","InconsolataSemiExpanded-Regular.woff2","LiberationMono-Bold.woff2","LiberationMono-BoldItalic.woff2","LiberationMono-Italic.woff2","LiberationMono-Regular.woff2","LiberationSans-Bold.woff2","LiberationSans-BoldItalic.woff2","LiberationSans-Italic.woff2","LiberationSans-Regular.woff2","LiberationSansNarrow-Bold.woff2","LiberationSansNarrow-BoldItalic.woff2","LiberationSansNarrow-Italic.woff2","LiberationSansNarrow-Regular.woff2","LiberationSerif-Bold.woff2","LiberationSerif-BoldItalic.woff2","LiberationSerif-Italic.woff2","LiberationSerif-Regular.woff2","NotoSans-Bold.woff2","NotoSans-BoldItalic.woff2","NotoSans-Italic.woff2","NotoSans-Regular.woff2","NotoSansMono-Bold.woff2","NotoSansMono-Regular.woff2","OreganoItalic-Regular.woff2","PTSans-Bold.woff2","PTSans-BoldItalic.woff2","PTSans-Italic.woff2","PTSans-Regular.woff2","PTSansNarrow-Bold.woff2","PTSansNarrow-Regular.woff2","Selawik-Bold.woff2","Selawik-Regular.woff2","TeXGyreBonum-Bold.woff2","TeXGyreBonum-BoldItalic.woff2","TeXGyreBonum-Italic.woff2","TeXGyreBonum-Regular.woff2","URWGothic-Book.woff2","URWGothic-BookOblique.woff2","URWGothic-Demi.woff2","URWGothic-DemiOblique.woff2"]),s=Object.freeze(["Arial","Arial Black","Arial MT","Arial Narrow","Baskerville Old Face","Bookman Old Style","Brush Script MT","Calibri","Calibri Light","Cambria","Century","Century Gothic","Century Schoolbook","Comic Sans MS","Consolas","Cooper Black","Courier","Courier New","Garamond","Georgia","Gill Sans MT Condensed","Helvetica","ITC Bookman","Lucida Console","Segoe UI","Tahoma","Times","Times New Roman","Trebuchet MS","Verdana"]);function B(o={}){const r=w(o.include,"include"),e=w(o.exclude,"exclude");if(r&&e)throw new Error("[@superdoc-dev/fonts] createSuperDocFonts: pass `include` OR `exclude`, not both. `include` is an allow-list (only those families resolve and appear in the toolbar); `exclude` keeps everything but the named families.");return r&&m(r,"include"),e&&m(e,"exclude"),r?{bundled:{include:r}}:e?{bundled:{exclude:e}}:{}}function w(o,r){if(o==null)return;if(!Array.isArray(o))throw new Error(`[@superdoc-dev/fonts] createSuperDocFonts: \`${r}\` must be an array of Word font names.`);const e=o.map(a=>typeof a=="string"?a.trim():"").filter(Boolean);if(e.length!==o.length)throw new Error(`[@superdoc-dev/fonts] createSuperDocFonts: \`${r}\` must contain only non-empty font name strings (e.g. ["Calibri", "Cambria"]).`);return e.length?e:void 0}function c(o){return o.trim().replace(/^["']|["']$/g,"").toLowerCase()}var g=new Set(s.map(c));function h(o,r){const e=o.length,a=r.length;if(Math.abs(e-a)>2)return 3;let n=Array.from({length:a+1},(t,l)=>l);for(let t=1;t<=e;t+=1){const l=[t];for(let i=1;i<=a;i+=1){const R=o[t-1]===r[i-1]?0:1;l[i]=Math.min(l[i-1]+1,n[i]+1,n[i-1]+R)}n=l}return n[a]}function b(o){const r=c(o);let e=null,a=3;for(const n of s){const t=h(r,c(n));t<a&&(a=t,e=n)}return e}function m(o,r){const e=o.filter(n=>!g.has(c(n)));if(e.length===0)return;const a=e.map(n=>{const t=b(n);return t?`"${n}" (did you mean "${t}"?)`:`"${n}"`});throw new Error(`[@superdoc-dev/fonts] createSuperDocFonts: \`${r}\` names a font SuperDoc does not bundle: ${a.join(", ")}. Curate by Word family name. Bundled families: ${s.join(", ")}.`)}var S=(typeof document<"u"?document.currentScript:null)?.src??"",C=new Set(d);function u(o){if(!C.has(o.file))throw new Error(`[@superdoc-dev/fonts] no bundled asset for "${o.file}". This pack ships ${d.length} faces; the file is unknown, so @superdoc-dev/fonts and superdoc are likely version-mismatched. Align their versions.`);if(!S)throw new Error('[@superdoc-dev/fonts] could not determine the script URL to resolve bundled fonts from. Load superdoc-fonts.min.js with a normal <script src="..."> tag.');return new URL(`../assets/${o.file}`,S).href}const p={resolveAssetUrl:u};function I(o={}){return{resolveAssetUrl:u,...B(o)}}return f.BUNDLED_FAMILY_NAMES=s,f.createSuperDocFonts=I,f.resolveBundledFontAssetUrl=u,f.superdocFonts=p,f})({});
+
+//# sourceMappingURL=superdoc-fonts.min.js.map

package/dist/superdoc-fonts.min.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"superdoc-fonts.min.js","names":["BUNDLED_FONT_FILES: readonly string[]","KNOWN_FAMILY_KEYS: ReadonlySet<string>","best: string | null","SCRIPT_SRC: string","KNOWN_FILES: ReadonlySet<string>","superdocFonts: SuperDocFontsConfig"],"sources":["../src/bundled-files.ts","../src/bundled-families.ts","../src/curation.ts","../src/cdn-entry.ts"],"sourcesContent":["/**\n * GENERATED by scripts/generate-asset-urls.mjs - do not edit by hand.\n *\n * The flat list of bundled .woff2 filenames, with NO `import.meta.url` (unlike asset-urls.ts).\n * The browser/IIFE entry (cdn-entry.ts) imports this to validate face files and to resolve them\n * relative to its own <script>, since import.meta.url is not available in an IIFE bundle.\n */\nexport const BUNDLED_FONT_FILES: readonly string[] = Object.freeze([\n  'ArchivoBlack-Regular.woff2',\n  'BacasimeAntique-Regular.woff2',\n  'C059-BdIta.woff2',\n  'C059-Bold.woff2',\n  'C059-Italic.woff2',\n  'C059-Roman.woff2',\n  'Caladea-Bold.woff2',\n  'Caladea-BoldItalic.woff2',\n  'Caladea-Italic.woff2',\n  'Caladea-Regular.woff2',\n  'Caprasimo-Regular.woff2',\n  'Cardo-Bold.woff2',\n  'Cardo-Italic.woff2',\n  'Cardo-Regular.woff2',\n  'Carlito-Bold.woff2',\n  'Carlito-BoldItalic.woff2',\n  'Carlito-Italic.woff2',\n  'Carlito-Regular.woff2',\n  'ComicRelief-Bold.woff2',\n  'ComicRelief-Regular.woff2',\n  'Gelasio-Bold.woff2',\n  'Gelasio-BoldItalic.woff2',\n  'Gelasio-Italic.woff2',\n  'Gelasio-Regular.woff2',\n  'InconsolataSemiExpanded-Bold.woff2',\n  'InconsolataSemiExpanded-Regular.woff2',\n  'LiberationMono-Bold.woff2',\n  'LiberationMono-BoldItalic.woff2',\n  'LiberationMono-Italic.woff2',\n  'LiberationMono-Regular.woff2',\n  'LiberationSans-Bold.woff2',\n  'LiberationSans-BoldItalic.woff2',\n  'LiberationSans-Italic.woff2',\n  'LiberationSans-Regular.woff2',\n  'LiberationSansNarrow-Bold.woff2',\n  'LiberationSansNarrow-BoldItalic.woff2',\n  'LiberationSansNarrow-Italic.woff2',\n  'LiberationSansNarrow-Regular.woff2',\n  'LiberationSerif-Bold.woff2',\n  'LiberationSerif-BoldItalic.woff2',\n  'LiberationSerif-Italic.woff2',\n  'LiberationSerif-Regular.woff2',\n  'NotoSans-Bold.woff2',\n  'NotoSans-BoldItalic.woff2',\n  'NotoSans-Italic.woff2',\n  'NotoSans-Regular.woff2',\n  'NotoSansMono-Bold.woff2',\n  'NotoSansMono-Regular.woff2',\n  'OreganoItalic-Regular.woff2',\n  'PTSans-Bold.woff2',\n  'PTSans-BoldItalic.woff2',\n  'PTSans-Italic.woff2',\n  'PTSans-Regular.woff2',\n  'PTSansNarrow-Bold.woff2',\n  'PTSansNarrow-Regular.woff2',\n  'Selawik-Bold.woff2',\n  'Selawik-Regular.woff2',\n  'TeXGyreBonum-Bold.woff2',\n  'TeXGyreBonum-BoldItalic.woff2',\n  'TeXGyreBonum-Italic.woff2',\n  'TeXGyreBonum-Regular.woff2',\n  'URWGothic-Book.woff2',\n  'URWGothic-BookOblique.woff2',\n  'URWGothic-Demi.woff2',\n  'URWGothic-DemiOblique.woff2',\n]);\n","/**\n * GENERATED by scripts/generate-bundled-families.ts - do not edit by hand.\n *\n * The Word family names a document can curate via createSuperDocFonts({ include / exclude }), mirrored\n * from @superdoc/font-system's runtime curation set (every logical family the resolver substitutes to a\n * bundled face, including category fallbacks like Verdana). A name outside this set is a typo or an\n * unbundled font, so createSuperDocFonts rejects it instead of silently dropping the intended fonts.\n */\nexport const BUNDLED_FAMILY_NAMES = Object.freeze([\n  'Arial',\n  'Arial Black',\n  'Arial MT',\n  'Arial Narrow',\n  'Baskerville Old Face',\n  'Bookman Old Style',\n  'Brush Script MT',\n  'Calibri',\n  'Calibri Light',\n  'Cambria',\n  'Century',\n  'Century Gothic',\n  'Century Schoolbook',\n  'Comic Sans MS',\n  'Consolas',\n  'Cooper Black',\n  'Courier',\n  'Courier New',\n  'Garamond',\n  'Georgia',\n  'Gill Sans MT Condensed',\n  'Helvetica',\n  'ITC Bookman',\n  'Lucida Console',\n  'Segoe UI',\n  'Tahoma',\n  'Times',\n  'Times New Roman',\n  'Trebuchet MS',\n  'Verdana',\n] as const);\n\n/**\n * Union of the Word family names the bundled pack can curate, for autocomplete on\n * createSuperDocFonts({ include / exclude }). Those options also accept any string (case- and\n * quote-insensitive, validated at runtime), so a list built from dynamic config still type-checks.\n */\nexport type BundledFontFamilyName = (typeof BUNDLED_FAMILY_NAMES)[number];\n","/**\n * Resolver-independent curation + validation shared by the two entries: the bundler entry\n * (`index.ts`, asset URLs via `import.meta.url`) and the browser/IIFE entry (`cdn-entry.ts`, URLs\n * relative to its own `<script>`). Each entry supplies only its own asset-URL resolver; the\n * `include` / `exclude` validation lives here once so the two entries can never drift.\n *\n * @beta\n */\nimport { BUNDLED_FAMILY_NAMES, type BundledFontFamilyName } from './bundled-families.js';\n\n/**\n * Minimal structural shape of SuperDoc's bundled-font asset context. Kept LOCAL so this package\n * has no dependency on `@superdoc/font-system`; only `file` is read. Assignable to SuperDoc's\n * `FontAssetUrlResolver` by structural typing.\n *\n * @beta\n */\nexport interface BundledFontAssetContext {\n  /** Asset filename, e.g. `Carlito-Regular.woff2`. */\n  file: string;\n  family?: string;\n  weight?: string;\n  style?: 'normal' | 'italic';\n  source?: string;\n}\n\n/** Per-face asset-URL resolver: maps a bundled face filename to a URL the browser can fetch. */\nexport type BundledFontAssetResolver = (context: BundledFontAssetContext) => string;\n\n/**\n * Choose which bundled families SuperDoc advertises and renders, by LOGICAL Word family name\n * (`\"Calibri\"`, never the physical `\"Carlito\"`).\n *\n * @beta\n */\nexport interface SuperDocFontsOptions {\n  /**\n   * Allow-list: ONLY these logical families are active, e.g. `['Calibri', 'Cambria']`. Autocompletes\n   * the bundled names, but also accepts any string (case- and quote-insensitive, validated at\n   * runtime), so a list built from dynamic config still type-checks.\n   */\n  include?: readonly (BundledFontFamilyName | (string & {}))[];\n  /** Block-list: every bundled family EXCEPT these, e.g. `['Cooper Black', 'Brush Script MT']`. */\n  exclude?: readonly (BundledFontFamilyName | (string & {}))[];\n}\n\n/**\n * The `fonts` config the entries return: the bundled-asset resolver plus the curation.\n * Structurally assignable to SuperDoc's `fonts` option.\n *\n * @beta\n */\nexport interface SuperDocFontsConfig {\n  resolveAssetUrl: BundledFontAssetResolver;\n  bundled?: { include?: string[]; exclude?: string[] };\n}\n\n/**\n * Validate the curation options and return the `{ bundled? }` slice (no resolver). Each entry\n * spreads this into its own `{ resolveAssetUrl, ...resolveCuration(options) }`.\n */\nexport function resolveCuration(options: SuperDocFontsOptions = {}): {\n  bundled?: { include?: string[]; exclude?: string[] };\n} {\n  const include = normalizeNameList(options.include, 'include');\n  const exclude = normalizeNameList(options.exclude, 'exclude');\n  // include and exclude are mutually exclusive intents; accepting both silently would hide which one\n  // wins. Reject at the API boundary (this runs in the consumer's setup code, so it fails fast and\n  // clearly) rather than picking one arbitrarily.\n  if (include && exclude) {\n    throw new Error(\n      '[@superdoc-dev/fonts] createSuperDocFonts: pass `include` OR `exclude`, not both. ' +\n        '`include` is an allow-list (only those families resolve and appear in the toolbar); ' +\n        '`exclude` keeps everything but the named families.',\n    );\n  }\n  // Reject names SuperDoc does not bundle. This runs in the consumer's setup code, so it fails fast\n  // and clearly - especially for `include`, where a typo would otherwise silently hide the fonts the\n  // consumer meant to keep. (Raw `fonts.bundled` set directly stays lenient and only warns.)\n  if (include) assertKnownFamilies(include, 'include');\n  if (exclude) assertKnownFamilies(exclude, 'exclude');\n  if (include) return { bundled: { include } };\n  if (exclude) return { bundled: { exclude } };\n  return {};\n}\n\n/** Validate and clean a curation list: an array of non-empty strings, or omitted. Throws on misuse. */\nfunction normalizeNameList(value: readonly string[] | undefined, field: 'include' | 'exclude'): string[] | undefined {\n  if (value == null) return undefined;\n  if (!Array.isArray(value)) {\n    throw new Error(`[@superdoc-dev/fonts] createSuperDocFonts: \\`${field}\\` must be an array of Word font names.`);\n  }\n  const names = value.map((name) => (typeof name === 'string' ? name.trim() : '')).filter(Boolean);\n  if (names.length !== value.length) {\n    throw new Error(\n      `[@superdoc-dev/fonts] createSuperDocFonts: \\`${field}\\` must contain only non-empty font name strings ` +\n        `(e.g. [\"Calibri\", \"Cambria\"]).`,\n    );\n  }\n  return names.length ? names : undefined;\n}\n\n/** Normalize a family name for matching: trim, strip surrounding quotes, lowercase. */\nfunction normalizeKey(name: string): string {\n  return name\n    .trim()\n    .replace(/^[\"']|[\"']$/g, '')\n    .toLowerCase();\n}\n\nconst KNOWN_FAMILY_KEYS: ReadonlySet<string> = new Set(BUNDLED_FAMILY_NAMES.map(normalizeKey));\n\n/** Bounded Levenshtein distance between two short strings, for a \"did you mean\" hint on a typo. */\nfunction editDistance(a: string, b: string): number {\n  const m = a.length;\n  const n = b.length;\n  if (Math.abs(m - n) > 2) return 3;\n  let prev = Array.from({ length: n + 1 }, (_, i) => i);\n  for (let i = 1; i <= m; i += 1) {\n    const curr = [i];\n    for (let j = 1; j <= n; j += 1) {\n      const cost = a[i - 1] === b[j - 1] ? 0 : 1;\n      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);\n    }\n    prev = curr;\n  }\n  return prev[n];\n}\n\n/** The closest bundled family within edit distance 2, or null - so a typo gets a concrete suggestion. */\nfunction closestKnownFamily(name: string): string | null {\n  const key = normalizeKey(name);\n  let best: string | null = null;\n  let bestDist = 3;\n  for (const family of BUNDLED_FAMILY_NAMES) {\n    const dist = editDistance(key, normalizeKey(family));\n    if (dist < bestDist) {\n      bestDist = dist;\n      best = family;\n    }\n  }\n  return best;\n}\n\n/** Throw on any curation name SuperDoc does not bundle, with a suggestion and the full valid list. */\nfunction assertKnownFamilies(names: readonly string[], field: 'include' | 'exclude'): void {\n  const unknown = names.filter((name) => !KNOWN_FAMILY_KEYS.has(normalizeKey(name)));\n  if (unknown.length === 0) return;\n  const hints = unknown.map((name) => {\n    const suggestion = closestKnownFamily(name);\n    return suggestion ? `\"${name}\" (did you mean \"${suggestion}\"?)` : `\"${name}\"`;\n  });\n  throw new Error(\n    `[@superdoc-dev/fonts] createSuperDocFonts: \\`${field}\\` names a font SuperDoc does not bundle: ${hints.join(', ')}. ` +\n      `Curate by Word family name. Bundled families: ${BUNDLED_FAMILY_NAMES.join(', ')}.`,\n  );\n}\n","/**\n * Browser / `<script>` (IIFE) entry for `@superdoc-dev/fonts`, built to\n * `dist/superdoc-fonts.min.js` and exposed as the `SuperDocFonts` global.\n *\n * Unlike the bundler entry ({@link \"./index\"}), it resolves the `.woff2` relative to its OWN\n * `<script>` (`document.currentScript`) instead of `import.meta.url`, so a plain CDN / self-host\n * `<script>` tag works with no bundler:\n *\n *     <script src=\"https://cdn.jsdelivr.net/npm/superdoc/dist/superdoc.min.js\"></script>\n *     <script src=\"https://cdn.jsdelivr.net/npm/@superdoc-dev/fonts/dist/superdoc-fonts.min.js\"></script>\n *     <script>\n *       new SuperDoc({ selector: '#editor', document: 'contract.docx', fonts: SuperDocFonts.superdocFonts });\n *     </script>\n *\n * The faces ship in the package's `assets/` dir and this bundle in `dist/`, so a face resolves to\n * `../assets/<file>` relative to the script. On a public CDN (jsDelivr / unpkg) the whole package\n * is served, so that resolves with no setup; self-hosting requires the `dist/` and `assets/` dirs\n * to keep their relative layout.\n *\n * @beta\n */\nimport { BUNDLED_FONT_FILES } from './bundled-files.js';\nimport {\n  resolveCuration,\n  type BundledFontAssetContext,\n  type SuperDocFontsConfig,\n  type SuperDocFontsOptions,\n} from './curation.js';\n\n// Capture the executing <script> src at load. `document.currentScript` is valid while this\n// top-level IIFE runs and null later (e.g. in async callbacks), so it MUST be read here, at module\n// eval, not inside the resolver. Duck-typed (no `instanceof HTMLScriptElement`) so the module also\n// evaluates under a non-DOM test environment where that constructor is absent.\nconst currentScript = typeof document !== 'undefined' ? (document.currentScript as { src?: string } | null) : null;\nconst SCRIPT_SRC: string = currentScript?.src ?? '';\n\nconst KNOWN_FILES: ReadonlySet<string> = new Set(BUNDLED_FONT_FILES);\n\n/**\n * Resolve a bundled face filename to a URL relative to THIS script. Throws on an unknown file\n * (a version mismatch between `@superdoc-dev/fonts` and `superdoc`) and on a missing script URL,\n * matching the bundler entry's fail-loud-not-silent contract.\n *\n * @beta\n */\nexport function resolveBundledFontAssetUrl(context: BundledFontAssetContext): string {\n  if (!KNOWN_FILES.has(context.file)) {\n    throw new Error(\n      `[@superdoc-dev/fonts] no bundled asset for \"${context.file}\". This pack ships ` +\n        `${BUNDLED_FONT_FILES.length} faces; the file is unknown, so @superdoc-dev/fonts and ` +\n        `superdoc are likely version-mismatched. Align their versions.`,\n    );\n  }\n  if (!SCRIPT_SRC) {\n    throw new Error(\n      '[@superdoc-dev/fonts] could not determine the script URL to resolve bundled fonts from. ' +\n        'Load superdoc-fonts.min.js with a normal <script src=\"...\"> tag.',\n    );\n  }\n  return new URL(`../assets/${context.file}`, SCRIPT_SRC).href;\n}\n\n/**\n * Drop-in value for SuperDoc's `fonts` config: `new SuperDoc({ fonts: SuperDocFonts.superdocFonts })`.\n *\n * @beta\n */\nexport const superdocFonts: SuperDocFontsConfig = { resolveAssetUrl: resolveBundledFontAssetUrl };\n\n/**\n * Build a curated `fonts` config: the bundled pack narrowed to the families you choose. Same API\n * and validation as the bundler entry's `createSuperDocFonts`; only the resolver differs.\n *\n *     new SuperDoc({ fonts: SuperDocFonts.createSuperDocFonts({ exclude: ['Cooper Black'] }) });\n *\n * @beta\n */\nexport function createSuperDocFonts(options: SuperDocFontsOptions = {}): SuperDocFontsConfig {\n  return { resolveAssetUrl: resolveBundledFontAssetUrl, ...resolveCuration(options) };\n}\n\nexport type { BundledFontAssetContext, SuperDocFontsConfig, SuperDocFontsOptions };\nexport { BUNDLED_FAMILY_NAMES } from './bundled-families.js';\nexport type { BundledFontFamilyName } from './bundled-families.js';\n"],"mappings":"4FAOA,MAAaA,EAAwC,OAAO,OAAO,CACjE,6BACA,gCACA,mBACA,kBACA,oBACA,mBACA,qBACA,2BACA,uBACA,wBACA,0BACA,mBACA,qBACA,sBACA,qBACA,2BACA,uBACA,wBACA,yBACA,4BACA,qBACA,2BACA,uBACA,wBACA,qCACA,wCACA,4BACA,kCACA,8BACA,+BACA,4BACA,kCACA,8BACA,+BACA,kCACA,wCACA,oCACA,qCACA,6BACA,mCACA,+BACA,gCACA,sBACA,4BACA,wBACA,yBACA,0BACA,6BACA,8BACA,oBACA,0BACA,sBACA,uBACA,0BACA,6BACA,qBACA,wBACA,0BACA,gCACA,4BACA,6BACA,uBACA,8BACA,uBACA,8BACD,ECjEY,EAAuB,OAAO,OAAO,CAChD,QACA,cACA,WACA,eACA,uBACA,oBACA,kBACA,UACA,gBACA,UACA,UACA,iBACA,qBACA,gBACA,WACA,eACA,UACA,cACA,WACA,UACA,yBACA,YACA,cACA,iBACA,WACA,SACA,QACA,kBACA,eACA,UACD,ECsBD,SAAgB,EAAgB,EAAgC,CAAA,EAE9D,CACA,MAAM,EAAU,EAAkB,EAAQ,QAAS,SAAA,EAC7C,EAAU,EAAkB,EAAQ,QAAS,SAAA,EAInD,GAAI,GAAW,EACb,MAAM,IAAI,MACR,0NAAA,EAUJ,OAFI,GAAS,EAAoB,EAAS,SAAA,EACtC,GAAS,EAAoB,EAAS,SAAA,EACtC,EAAgB,CAAE,QAAS,CAAE,QAAA,CAAA,CAAS,EACtC,EAAgB,CAAE,QAAS,CAAE,QAAA,CAAA,CAAS,EACnC,CAAA,EAIT,SAAS,EAAkB,EAAsC,EAAoD,CACnH,GAAI,GAAS,KAAM,OACnB,GAAI,CAAC,MAAM,QAAQ,CAAA,EACjB,MAAM,IAAI,MAAM,gDAAgD,CAAA,yCAAM,EAExE,MAAM,EAAQ,EAAM,IAAK,GAAU,OAAO,GAAS,SAAW,EAAK,KAAA,EAAS,EAAA,EAAK,OAAO,OAAA,EACxF,GAAI,EAAM,SAAW,EAAM,OACzB,MAAM,IAAI,MACR,gDAAgD,CAAA,iFAAM,EAI1D,OAAO,EAAM,OAAS,EAAQ,OAIhC,SAAS,EAAa,EAAsB,CAC1C,OAAO,EACJ,KAAA,EACA,QAAQ,eAAgB,EAAA,EACxB,YAAA,EAGL,IAAMC,EAAyC,IAAI,IAAI,EAAqB,IAAI,CAAA,CAAa,EAG7F,SAAS,EAAa,EAAW,EAAmB,CAClD,MAAM,EAAI,EAAE,OACN,EAAI,EAAE,OACZ,GAAI,KAAK,IAAI,EAAI,CAAA,EAAK,EAAG,MAAO,GAChC,IAAI,EAAO,MAAM,KAAK,CAAE,OAAQ,EAAI,CAAA,EAAG,CAAG,EAAG,IAAM,CAAA,EACnD,QAAS,EAAI,EAAG,GAAK,EAAG,GAAK,EAAG,CAC9B,MAAM,EAAO,CAAC,CAAA,EACd,QAAS,EAAI,EAAG,GAAK,EAAG,GAAK,EAAG,CAC9B,MAAM,EAAO,EAAE,EAAI,CAAA,IAAO,EAAE,EAAI,CAAA,EAAK,EAAI,EACzC,EAAK,CAAA,EAAK,KAAK,IAAI,EAAK,EAAI,CAAA,EAAK,EAAG,EAAK,CAAA,EAAK,EAAG,EAAK,EAAI,CAAA,EAAK,CAAA,EAEjE,EAAO,EAET,OAAO,EAAK,CAAA,EAId,SAAS,EAAmB,EAA6B,CACvD,MAAM,EAAM,EAAa,CAAA,EACzB,IAAIC,EAAsB,KACtB,EAAW,EACf,UAAW,KAAU,EAAsB,CACzC,MAAM,EAAO,EAAa,EAAK,EAAa,CAAA,CAAO,EAC/C,EAAO,IACT,EAAW,EACX,EAAO,GAGX,OAAO,EAIT,SAAS,EAAoB,EAA0B,EAAoC,CACzF,MAAM,EAAU,EAAM,OAAQ,GAAS,CAAC,EAAkB,IAAI,EAAa,CAAA,CAAK,CAAC,EACjF,GAAI,EAAQ,SAAW,EAAG,OAC1B,MAAM,EAAQ,EAAQ,IAAK,GAAS,CAClC,MAAM,EAAa,EAAmB,CAAA,EACtC,OAAO,EAAa,IAAI,CAAA,oBAAwB,CAAA,MAAkB,IAAI,CAAA,MAExE,MAAM,IAAI,MACR,gDAAgD,CAAA,6CAAkD,EAAM,KAAK,IAAA,CAAK,mDAC/D,EAAqB,KAAK,IAAA,CAAK,GAAC,ECxHvF,IAAMC,GADgB,OAAO,SAAa,IAAe,SAAS,cAA4C,OACpE,KAAO,GAE3CC,EAAmC,IAAI,IAAI,CAAA,EASjD,SAAgB,EAA2B,EAA0C,CACnF,GAAI,CAAC,EAAY,IAAI,EAAQ,IAAA,EAC3B,MAAM,IAAI,MACR,+CAA+C,EAAQ,IAAA,sBAClD,EAAmB,MAAA,uHAAO,EAInC,GAAI,CAAC,EACH,MAAM,IAAI,MACR,0JAAA,EAIJ,OAAO,IAAI,IAAI,aAAa,EAAQ,IAAA,GAAQ,CAAA,EAAY,KAQ1D,MAAaC,EAAqC,CAAE,gBAAiB,CAAA,EAUrE,SAAgB,EAAoB,EAAgC,CAAA,EAAyB,CAC3F,MAAO,CAAE,gBAAiB,EAA4B,GAAG,EAAgB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/fonts",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Optional bundled metric-compatible font substitutes for SuperDoc, shipped as bundler-resolvable assets.",
   "type": "module",
   "license": "SEE LICENSE IN assets/LICENSES.md",
@@ -25,17 +25,18 @@
     "assets"
   ],
   "sideEffects": false,
+  "devDependencies": {
+    "@types/node": "22.19.2",
+    "typescript": "^5.9.2",
+    "vite": "^7.2.7"
+  },
   "scripts": {
     "sync": "node scripts/sync-assets.mjs",
     "generate": "node scripts/generate-asset-urls.mjs && pnpm exec tsx scripts/generate-bundled-families.ts",
     "check:families": "pnpm exec tsx scripts/check-bundled-families.ts",
-    "build": "node scripts/sync-assets.mjs && node scripts/generate-asset-urls.mjs && tsc --project tsconfig.json",
-    "prepare": "node scripts/sync-assets.mjs && node scripts/generate-asset-urls.mjs && tsc --project tsconfig.json",
+    "build:cdn": "vite build",
+    "build": "node scripts/sync-assets.mjs && node scripts/generate-asset-urls.mjs && tsc --project tsconfig.json && vite build",
     "typecheck": "tsc --noEmit",
     "test": "vitest"
-  },
-  "devDependencies": {
-    "@types/node": "catalog:",
-    "typescript": "catalog:"
   }
-}
+}

package/src/bundled-families.ts

@@ -6,7 +6,7 @@
  * bundled face, including category fallbacks like Verdana). A name outside this set is a typo or an
  * unbundled font, so createSuperDocFonts rejects it instead of silently dropping the intended fonts.
  */
-export const BUNDLED_FAMILY_NAMES: readonly string[] = Object.freeze([
+export const BUNDLED_FAMILY_NAMES = Object.freeze([
   'Arial',
   'Arial Black',
   'Arial MT',
@@ -37,4 +37,11 @@ export const BUNDLED_FAMILY_NAMES: readonly string[] = Object.freeze([
   'Times New Roman',
   'Trebuchet MS',
   'Verdana',
-]);
+] as const);
+
+/**
+ * Union of the Word family names the bundled pack can curate, for autocomplete on
+ * createSuperDocFonts({ include / exclude }). Those options also accept any string (case- and
+ * quote-insensitive, validated at runtime), so a list built from dynamic config still type-checks.
+ */
+export type BundledFontFamilyName = (typeof BUNDLED_FAMILY_NAMES)[number];

package/src/bundled-files.ts

@@ -0,0 +1,74 @@
+/**
+ * GENERATED by scripts/generate-asset-urls.mjs - do not edit by hand.
+ *
+ * The flat list of bundled .woff2 filenames, with NO `import.meta.url` (unlike asset-urls.ts).
+ * The browser/IIFE entry (cdn-entry.ts) imports this to validate face files and to resolve them
+ * relative to its own <script>, since import.meta.url is not available in an IIFE bundle.
+ */
+export const BUNDLED_FONT_FILES: readonly string[] = Object.freeze([
+  'ArchivoBlack-Regular.woff2',
+  'BacasimeAntique-Regular.woff2',
+  'C059-BdIta.woff2',
+  'C059-Bold.woff2',
+  'C059-Italic.woff2',
+  'C059-Roman.woff2',
+  'Caladea-Bold.woff2',
+  'Caladea-BoldItalic.woff2',
+  'Caladea-Italic.woff2',
+  'Caladea-Regular.woff2',
+  'Caprasimo-Regular.woff2',
+  'Cardo-Bold.woff2',
+  'Cardo-Italic.woff2',
+  'Cardo-Regular.woff2',
+  'Carlito-Bold.woff2',
+  'Carlito-BoldItalic.woff2',
+  'Carlito-Italic.woff2',
+  'Carlito-Regular.woff2',
+  'ComicRelief-Bold.woff2',
+  'ComicRelief-Regular.woff2',
+  'Gelasio-Bold.woff2',
+  'Gelasio-BoldItalic.woff2',
+  'Gelasio-Italic.woff2',
+  'Gelasio-Regular.woff2',
+  'InconsolataSemiExpanded-Bold.woff2',
+  'InconsolataSemiExpanded-Regular.woff2',
+  'LiberationMono-Bold.woff2',
+  'LiberationMono-BoldItalic.woff2',
+  'LiberationMono-Italic.woff2',
+  'LiberationMono-Regular.woff2',
+  'LiberationSans-Bold.woff2',
+  'LiberationSans-BoldItalic.woff2',
+  'LiberationSans-Italic.woff2',
+  'LiberationSans-Regular.woff2',
+  'LiberationSansNarrow-Bold.woff2',
+  'LiberationSansNarrow-BoldItalic.woff2',
+  'LiberationSansNarrow-Italic.woff2',
+  'LiberationSansNarrow-Regular.woff2',
+  'LiberationSerif-Bold.woff2',
+  'LiberationSerif-BoldItalic.woff2',
+  'LiberationSerif-Italic.woff2',
+  'LiberationSerif-Regular.woff2',
+  'NotoSans-Bold.woff2',
+  'NotoSans-BoldItalic.woff2',
+  'NotoSans-Italic.woff2',
+  'NotoSans-Regular.woff2',
+  'NotoSansMono-Bold.woff2',
+  'NotoSansMono-Regular.woff2',
+  'OreganoItalic-Regular.woff2',
+  'PTSans-Bold.woff2',
+  'PTSans-BoldItalic.woff2',
+  'PTSans-Italic.woff2',
+  'PTSans-Regular.woff2',
+  'PTSansNarrow-Bold.woff2',
+  'PTSansNarrow-Regular.woff2',
+  'Selawik-Bold.woff2',
+  'Selawik-Regular.woff2',
+  'TeXGyreBonum-Bold.woff2',
+  'TeXGyreBonum-BoldItalic.woff2',
+  'TeXGyreBonum-Italic.woff2',
+  'TeXGyreBonum-Regular.woff2',
+  'URWGothic-Book.woff2',
+  'URWGothic-BookOblique.woff2',
+  'URWGothic-Demi.woff2',
+  'URWGothic-DemiOblique.woff2',
+]);

package/src/cdn-entry.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// cdn-entry resolves faces relative to its own <script> (document.currentScript), captured at module
+// eval. The fonts test env is `node` (no document), so we stub a minimal document.currentScript and
+// re-import the module per case to re-run that capture, mirroring what the browser sees.
+const SCRIPT = 'https://cdn.jsdelivr.net/npm/@superdoc-dev/fonts@0.1.0/dist/superdoc-fonts.min.js';
+const ASSET_BASE = 'https://cdn.jsdelivr.net/npm/@superdoc-dev/fonts@0.1.0/assets/';
+
+describe('cdn-entry (browser/IIFE): script-relative resolver', () => {
+  beforeEach(() => {
+    vi.stubGlobal('document', { currentScript: { src: SCRIPT } });
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.resetModules();
+  });
+
+  it('resolves a known face to ../assets/<file> relative to the script', async () => {
+    const { resolveBundledFontAssetUrl, superdocFonts } = await import('./cdn-entry');
+    expect(resolveBundledFontAssetUrl({ file: 'Carlito-Regular.woff2' })).toBe(`${ASSET_BASE}Carlito-Regular.woff2`);
+    // superdocFonts wires the same resolver.
+    expect(superdocFonts.resolveAssetUrl({ file: 'Carlito-Regular.woff2' })).toBe(`${ASSET_BASE}Carlito-Regular.woff2`);
+  });
+
+  it('throws on an unknown face so a version mismatch surfaces', async () => {
+    const { resolveBundledFontAssetUrl } = await import('./cdn-entry');
+    expect(() => resolveBundledFontAssetUrl({ file: 'NotAFont.woff2' })).toThrow(/no bundled asset/);
+  });
+
+  it('createSuperDocFonts shares the bundler entry validation', async () => {
+    const { createSuperDocFonts } = await import('./cdn-entry');
+    expect(createSuperDocFonts({ exclude: ['Cooper Black'] }).bundled).toEqual({ exclude: ['Cooper Black'] });
+    expect(createSuperDocFonts().bundled).toBeUndefined();
+    expect(() => createSuperDocFonts({ include: ['Calbri'] })).toThrow(/did you mean "Calibri"\?/);
+  });
+
+  it('throws a clear error when no script URL can be determined', async () => {
+    vi.stubGlobal('document', { currentScript: null });
+    vi.resetModules();
+    const { resolveBundledFontAssetUrl } = await import('./cdn-entry');
+    // Known file, so it passes the file check and reaches the missing-script-URL guard.
+    expect(() => resolveBundledFontAssetUrl({ file: 'Carlito-Regular.woff2' })).toThrow(
+      /could not determine the script URL/,
+    );
+  });
+});

package/src/cdn-entry.ts

@@ -0,0 +1,84 @@
+/**
+ * Browser / `<script>` (IIFE) entry for `@superdoc-dev/fonts`, built to
+ * `dist/superdoc-fonts.min.js` and exposed as the `SuperDocFonts` global.
+ *
+ * Unlike the bundler entry ({@link "./index"}), it resolves the `.woff2` relative to its OWN
+ * `<script>` (`document.currentScript`) instead of `import.meta.url`, so a plain CDN / self-host
+ * `<script>` tag works with no bundler:
+ *
+ *     <script src="https://cdn.jsdelivr.net/npm/superdoc/dist/superdoc.min.js"></script>
+ *     <script src="https://cdn.jsdelivr.net/npm/@superdoc-dev/fonts/dist/superdoc-fonts.min.js"></script>
+ *     <script>
+ *       new SuperDoc({ selector: '#editor', document: 'contract.docx', fonts: SuperDocFonts.superdocFonts });
+ *     </script>
+ *
+ * The faces ship in the package's `assets/` dir and this bundle in `dist/`, so a face resolves to
+ * `../assets/<file>` relative to the script. On a public CDN (jsDelivr / unpkg) the whole package
+ * is served, so that resolves with no setup; self-hosting requires the `dist/` and `assets/` dirs
+ * to keep their relative layout.
+ *
+ * @beta
+ */
+import { BUNDLED_FONT_FILES } from './bundled-files.js';
+import {
+  resolveCuration,
+  type BundledFontAssetContext,
+  type SuperDocFontsConfig,
+  type SuperDocFontsOptions,
+} from './curation.js';
+
+// Capture the executing <script> src at load. `document.currentScript` is valid while this
+// top-level IIFE runs and null later (e.g. in async callbacks), so it MUST be read here, at module
+// eval, not inside the resolver. Duck-typed (no `instanceof HTMLScriptElement`) so the module also
+// evaluates under a non-DOM test environment where that constructor is absent.
+const currentScript = typeof document !== 'undefined' ? (document.currentScript as { src?: string } | null) : null;
+const SCRIPT_SRC: string = currentScript?.src ?? '';
+
+const KNOWN_FILES: ReadonlySet<string> = new Set(BUNDLED_FONT_FILES);
+
+/**
+ * Resolve a bundled face filename to a URL relative to THIS script. Throws on an unknown file
+ * (a version mismatch between `@superdoc-dev/fonts` and `superdoc`) and on a missing script URL,
+ * matching the bundler entry's fail-loud-not-silent contract.
+ *
+ * @beta
+ */
+export function resolveBundledFontAssetUrl(context: BundledFontAssetContext): string {
+  if (!KNOWN_FILES.has(context.file)) {
+    throw new Error(
+      `[@superdoc-dev/fonts] no bundled asset for "${context.file}". This pack ships ` +
+        `${BUNDLED_FONT_FILES.length} faces; the file is unknown, so @superdoc-dev/fonts and ` +
+        `superdoc are likely version-mismatched. Align their versions.`,
+    );
+  }
+  if (!SCRIPT_SRC) {
+    throw new Error(
+      '[@superdoc-dev/fonts] could not determine the script URL to resolve bundled fonts from. ' +
+        'Load superdoc-fonts.min.js with a normal <script src="..."> tag.',
+    );
+  }
+  return new URL(`../assets/${context.file}`, SCRIPT_SRC).href;
+}
+
+/**
+ * Drop-in value for SuperDoc's `fonts` config: `new SuperDoc({ fonts: SuperDocFonts.superdocFonts })`.
+ *
+ * @beta
+ */
+export const superdocFonts: SuperDocFontsConfig = { resolveAssetUrl: resolveBundledFontAssetUrl };
+
+/**
+ * Build a curated `fonts` config: the bundled pack narrowed to the families you choose. Same API
+ * and validation as the bundler entry's `createSuperDocFonts`; only the resolver differs.
+ *
+ *     new SuperDoc({ fonts: SuperDocFonts.createSuperDocFonts({ exclude: ['Cooper Black'] }) });
+ *
+ * @beta
+ */
+export function createSuperDocFonts(options: SuperDocFontsOptions = {}): SuperDocFontsConfig {
+  return { resolveAssetUrl: resolveBundledFontAssetUrl, ...resolveCuration(options) };
+}
+
+export type { BundledFontAssetContext, SuperDocFontsConfig, SuperDocFontsOptions };
+export { BUNDLED_FAMILY_NAMES } from './bundled-families.js';
+export type { BundledFontFamilyName } from './bundled-families.js';

package/src/curation.ts

@@ -0,0 +1,157 @@
+/**
+ * Resolver-independent curation + validation shared by the two entries: the bundler entry
+ * (`index.ts`, asset URLs via `import.meta.url`) and the browser/IIFE entry (`cdn-entry.ts`, URLs
+ * relative to its own `<script>`). Each entry supplies only its own asset-URL resolver; the
+ * `include` / `exclude` validation lives here once so the two entries can never drift.
+ *
+ * @beta
+ */
+import { BUNDLED_FAMILY_NAMES, type BundledFontFamilyName } from './bundled-families.js';
+
+/**
+ * Minimal structural shape of SuperDoc's bundled-font asset context. Kept LOCAL so this package
+ * has no dependency on `@superdoc/font-system`; only `file` is read. Assignable to SuperDoc's
+ * `FontAssetUrlResolver` by structural typing.
+ *
+ * @beta
+ */
+export interface BundledFontAssetContext {
+  /** Asset filename, e.g. `Carlito-Regular.woff2`. */
+  file: string;
+  family?: string;
+  weight?: string;
+  style?: 'normal' | 'italic';
+  source?: string;
+}
+
+/** Per-face asset-URL resolver: maps a bundled face filename to a URL the browser can fetch. */
+export type BundledFontAssetResolver = (context: BundledFontAssetContext) => string;
+
+/**
+ * Choose which bundled families SuperDoc advertises and renders, by LOGICAL Word family name
+ * (`"Calibri"`, never the physical `"Carlito"`).
+ *
+ * @beta
+ */
+export interface SuperDocFontsOptions {
+  /**
+   * Allow-list: ONLY these logical families are active, e.g. `['Calibri', 'Cambria']`. Autocompletes
+   * the bundled names, but also accepts any string (case- and quote-insensitive, validated at
+   * runtime), so a list built from dynamic config still type-checks.
+   */
+  include?: readonly (BundledFontFamilyName | (string & {}))[];
+  /** Block-list: every bundled family EXCEPT these, e.g. `['Cooper Black', 'Brush Script MT']`. */
+  exclude?: readonly (BundledFontFamilyName | (string & {}))[];
+}
+
+/**
+ * The `fonts` config the entries return: the bundled-asset resolver plus the curation.
+ * Structurally assignable to SuperDoc's `fonts` option.
+ *
+ * @beta
+ */
+export interface SuperDocFontsConfig {
+  resolveAssetUrl: BundledFontAssetResolver;
+  bundled?: { include?: string[]; exclude?: string[] };
+}
+
+/**
+ * Validate the curation options and return the `{ bundled? }` slice (no resolver). Each entry
+ * spreads this into its own `{ resolveAssetUrl, ...resolveCuration(options) }`.
+ */
+export function resolveCuration(options: SuperDocFontsOptions = {}): {
+  bundled?: { include?: string[]; exclude?: string[] };
+} {
+  const include = normalizeNameList(options.include, 'include');
+  const exclude = normalizeNameList(options.exclude, 'exclude');
+  // include and exclude are mutually exclusive intents; accepting both silently would hide which one
+  // wins. Reject at the API boundary (this runs in the consumer's setup code, so it fails fast and
+  // clearly) rather than picking one arbitrarily.
+  if (include && exclude) {
+    throw new Error(
+      '[@superdoc-dev/fonts] createSuperDocFonts: pass `include` OR `exclude`, not both. ' +
+        '`include` is an allow-list (only those families resolve and appear in the toolbar); ' +
+        '`exclude` keeps everything but the named families.',
+    );
+  }
+  // Reject names SuperDoc does not bundle. This runs in the consumer's setup code, so it fails fast
+  // and clearly - especially for `include`, where a typo would otherwise silently hide the fonts the
+  // consumer meant to keep. (Raw `fonts.bundled` set directly stays lenient and only warns.)
+  if (include) assertKnownFamilies(include, 'include');
+  if (exclude) assertKnownFamilies(exclude, 'exclude');
+  if (include) return { bundled: { include } };
+  if (exclude) return { bundled: { exclude } };
+  return {};
+}
+
+/** Validate and clean a curation list: an array of non-empty strings, or omitted. Throws on misuse. */
+function normalizeNameList(value: readonly string[] | undefined, field: 'include' | 'exclude'): string[] | undefined {
+  if (value == null) return undefined;
+  if (!Array.isArray(value)) {
+    throw new Error(`[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` must be an array of Word font names.`);
+  }
+  const names = value.map((name) => (typeof name === 'string' ? name.trim() : '')).filter(Boolean);
+  if (names.length !== value.length) {
+    throw new Error(
+      `[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` must contain only non-empty font name strings ` +
+        `(e.g. ["Calibri", "Cambria"]).`,
+    );
+  }
+  return names.length ? names : undefined;
+}
+
+/** Normalize a family name for matching: trim, strip surrounding quotes, lowercase. */
+function normalizeKey(name: string): string {
+  return name
+    .trim()
+    .replace(/^["']|["']$/g, '')
+    .toLowerCase();
+}
+
+const KNOWN_FAMILY_KEYS: ReadonlySet<string> = new Set(BUNDLED_FAMILY_NAMES.map(normalizeKey));
+
+/** Bounded Levenshtein distance between two short strings, for a "did you mean" hint on a typo. */
+function editDistance(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (Math.abs(m - n) > 2) return 3;
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  for (let i = 1; i <= m; i += 1) {
+    const curr = [i];
+    for (let j = 1; j <= n; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev = curr;
+  }
+  return prev[n];
+}
+
+/** The closest bundled family within edit distance 2, or null - so a typo gets a concrete suggestion. */
+function closestKnownFamily(name: string): string | null {
+  const key = normalizeKey(name);
+  let best: string | null = null;
+  let bestDist = 3;
+  for (const family of BUNDLED_FAMILY_NAMES) {
+    const dist = editDistance(key, normalizeKey(family));
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = family;
+    }
+  }
+  return best;
+}
+
+/** Throw on any curation name SuperDoc does not bundle, with a suggestion and the full valid list. */
+function assertKnownFamilies(names: readonly string[], field: 'include' | 'exclude'): void {
+  const unknown = names.filter((name) => !KNOWN_FAMILY_KEYS.has(normalizeKey(name)));
+  if (unknown.length === 0) return;
+  const hints = unknown.map((name) => {
+    const suggestion = closestKnownFamily(name);
+    return suggestion ? `"${name}" (did you mean "${suggestion}"?)` : `"${name}"`;
+  });
+  throw new Error(
+    `[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` names a font SuperDoc does not bundle: ${hints.join(', ')}. ` +
+      `Curate by Word family name. Bundled families: ${BUNDLED_FAMILY_NAMES.join(', ')}.`,
+  );
+}

package/src/index.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from 'vitest';
-import { BUNDLED_FONT_ASSET_URLS, createSuperDocFonts, resolveBundledFontAssetUrl, superdocFonts } from './index';
+import {
+  BUNDLED_FAMILY_NAMES,
+  BUNDLED_FONT_ASSET_URLS,
+  createSuperDocFonts,
+  resolveBundledFontAssetUrl,
+  superdocFonts,
+} from './index';
 
 describe('superdocFonts / resolveBundledFontAssetUrl', () => {
   it('superdocFonts is a ready-made resolveAssetUrl config', () => {
@@ -70,3 +76,12 @@ describe('createSuperDocFonts', () => {
     expect(() => createSuperDocFonts({ include: ['  calibri  ', '"Cambria"'] })).not.toThrow();
   });
 });
+
+describe('BUNDLED_FAMILY_NAMES', () => {
+  it('is exported as a non-empty list of curatable Word family names', () => {
+    expect(BUNDLED_FAMILY_NAMES.length).toBeGreaterThan(0);
+    expect(BUNDLED_FAMILY_NAMES).toContain('Calibri');
+    // Every advertised name is accepted by the curation API (the list and the validator agree).
+    expect(() => createSuperDocFonts({ include: [...BUNDLED_FAMILY_NAMES] })).not.toThrow();
+  });
+});

package/src/index.ts

@@ -7,10 +7,18 @@
  * `new URL('../assets/<file>', import.meta.url)`, which Vite, Webpack 5, Next, Nuxt, esbuild, and
  * Parcel detect, emit, and rewrite to the final hashed path.
  *
+ * For a plain `<script>` / CDN page (no bundler), load `dist/superdoc-fonts.min.js` instead and use
+ * the `SuperDocFonts` global - same API, faces resolved relative to the script. See `cdn-entry.ts`.
+ *
  * @beta This package is in preview; its surface may change before 1.0.
  */
-import { BUNDLED_FONT_ASSET_URLS } from './asset-urls';
-import { BUNDLED_FAMILY_NAMES } from './bundled-families';
+import { BUNDLED_FONT_ASSET_URLS } from './asset-urls.js';
+import {
+  resolveCuration,
+  type BundledFontAssetContext,
+  type SuperDocFontsConfig,
+  type SuperDocFontsOptions,
+} from './curation.js';
 
 /**
  * The full filename -> bundler-emitted URL map for every bundled face. Most consumers use
@@ -20,21 +28,16 @@ import { BUNDLED_FAMILY_NAMES } from './bundled-families';
  */
 export { BUNDLED_FONT_ASSET_URLS };
 
+export type { BundledFontAssetContext, SuperDocFontsConfig, SuperDocFontsOptions };
+
 /**
- * Minimal structural shape of SuperDoc's bundled-font asset context. Kept LOCAL so this
- * package has no dependency on `@superdoc/font-system`; only `file` is read. Assignable to
- * SuperDoc's `FontAssetUrlResolver` by structural typing.
+ * The curatable Word family names (and their union type), for building `include` / `exclude` lists
+ * with autocomplete. Re-exported from the generated source.
  *
  * @beta
  */
-export interface BundledFontAssetContext {
-  /** Asset filename, e.g. `Carlito-Regular.woff2`. */
-  file: string;
-  family?: string;
-  weight?: string;
-  style?: 'normal' | 'italic';
-  source?: string;
-}
+export { BUNDLED_FAMILY_NAMES } from './bundled-families.js';
+export type { BundledFontFamilyName } from './bundled-families.js';
 
 /**
  * Resolve a bundled substitute face filename to a bundler-emitted URL.
@@ -68,34 +71,10 @@ export function resolveBundledFontAssetUrl(context: BundledFontAssetContext): st
  *
  * @beta
  */
-export const superdocFonts: { resolveAssetUrl: (context: BundledFontAssetContext) => string } = {
+export const superdocFonts: SuperDocFontsConfig = {
   resolveAssetUrl: resolveBundledFontAssetUrl,
 };
 
-/**
- * Choose which bundled families SuperDoc advertises and renders, by LOGICAL Word family name
- * (`"Calibri"`, never the physical `"Carlito"`).
- *
- * @beta
- */
-export interface SuperDocFontsOptions {
-  /** Allow-list: ONLY these logical families are active, e.g. `['Calibri', 'Cambria']`. */
-  include?: string[];
-  /** Block-list: every bundled family EXCEPT these, e.g. `['Cooper Black', 'Brush Script MT']`. */
-  exclude?: string[];
-}
-
-/**
- * The `fonts` config {@link createSuperDocFonts} returns: the bundled-asset resolver plus the
- * curation. Structurally assignable to SuperDoc's `fonts` option.
- *
- * @beta
- */
-export interface SuperDocFontsConfig {
-  resolveAssetUrl: (context: BundledFontAssetContext) => string;
-  bundled?: { include?: string[]; exclude?: string[] };
-}
-
 /**
  * Build a curated `fonts` config: the bundled pack, narrowed to the families you choose.
  *
@@ -113,97 +92,5 @@ export interface SuperDocFontsConfig {
  * @beta
  */
 export function createSuperDocFonts(options: SuperDocFontsOptions = {}): SuperDocFontsConfig {
-  const include = normalizeNameList(options.include, 'include');
-  const exclude = normalizeNameList(options.exclude, 'exclude');
-  // include and exclude are mutually exclusive intents; accepting both silently would hide which one
-  // wins. Reject at the API boundary (this runs in the consumer's setup code, so it fails fast and
-  // clearly) rather than picking one arbitrarily.
-  if (include && exclude) {
-    throw new Error(
-      '[@superdoc-dev/fonts] createSuperDocFonts: pass `include` OR `exclude`, not both. ' +
-        '`include` is an allow-list (only those families resolve and appear in the toolbar); ' +
-        '`exclude` keeps everything but the named families.',
-    );
-  }
-  // Reject names SuperDoc does not bundle. This runs in the consumer's setup code, so it fails fast
-  // and clearly - especially for `include`, where a typo would otherwise silently hide the fonts the
-  // consumer meant to keep. (Raw `fonts.bundled` set directly stays lenient and only warns.)
-  if (include) assertKnownFamilies(include, 'include');
-  if (exclude) assertKnownFamilies(exclude, 'exclude');
-  const config: SuperDocFontsConfig = { resolveAssetUrl: resolveBundledFontAssetUrl };
-  if (include) config.bundled = { include };
-  else if (exclude) config.bundled = { exclude };
-  return config;
-}
-
-/** Validate and clean a curation list: an array of non-empty strings, or omitted. Throws on misuse. */
-function normalizeNameList(value: string[] | undefined, field: 'include' | 'exclude'): string[] | undefined {
-  if (value == null) return undefined;
-  if (!Array.isArray(value)) {
-    throw new Error(`[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` must be an array of Word font names.`);
-  }
-  const names = value.map((name) => (typeof name === 'string' ? name.trim() : '')).filter(Boolean);
-  if (names.length !== value.length) {
-    throw new Error(
-      `[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` must contain only non-empty font name strings ` +
-        `(e.g. ["Calibri", "Cambria"]).`,
-    );
-  }
-  return names.length ? names : undefined;
-}
-
-/** Normalize a family name for matching: trim, strip surrounding quotes, lowercase. */
-function normalizeKey(name: string): string {
-  return name
-    .trim()
-    .replace(/^["']|["']$/g, '')
-    .toLowerCase();
-}
-
-const KNOWN_FAMILY_KEYS: ReadonlySet<string> = new Set(BUNDLED_FAMILY_NAMES.map(normalizeKey));
-
-/** Bounded Levenshtein distance between two short strings, for a "did you mean" hint on a typo. */
-function editDistance(a: string, b: string): number {
-  const m = a.length;
-  const n = b.length;
-  if (Math.abs(m - n) > 2) return 3;
-  let prev = Array.from({ length: n + 1 }, (_, i) => i);
-  for (let i = 1; i <= m; i += 1) {
-    const curr = [i];
-    for (let j = 1; j <= n; j += 1) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
-    }
-    prev = curr;
-  }
-  return prev[n];
-}
-
-/** The closest bundled family within edit distance 2, or null - so a typo gets a concrete suggestion. */
-function closestKnownFamily(name: string): string | null {
-  const key = normalizeKey(name);
-  let best: string | null = null;
-  let bestDist = 3;
-  for (const family of BUNDLED_FAMILY_NAMES) {
-    const dist = editDistance(key, normalizeKey(family));
-    if (dist < bestDist) {
-      bestDist = dist;
-      best = family;
-    }
-  }
-  return best;
-}
-
-/** Throw on any curation name SuperDoc does not bundle, with a suggestion and the full valid list. */
-function assertKnownFamilies(names: readonly string[], field: 'include' | 'exclude'): void {
-  const unknown = names.filter((name) => !KNOWN_FAMILY_KEYS.has(normalizeKey(name)));
-  if (unknown.length === 0) return;
-  const hints = unknown.map((name) => {
-    const suggestion = closestKnownFamily(name);
-    return suggestion ? `"${name}" (did you mean "${suggestion}"?)` : `"${name}"`;
-  });
-  throw new Error(
-    `[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` names a font SuperDoc does not bundle: ${hints.join(', ')}. ` +
-      `Curate by Word family name. Bundled families: ${BUNDLED_FAMILY_NAMES.join(', ')}.`,
-  );
+  return { resolveAssetUrl: resolveBundledFontAssetUrl, ...resolveCuration(options) };
 }