superdoc 2.2.0 → 2.3.0

package/dist/public/ui-react.es.js

@@ -0,0 +1,159 @@
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-fxF2Q8Ib.es.js";
+import { createContext, createElement, useCallback, useContext, useEffect, useRef, useState } from "react";
+var SuperDocUIContext = createContext(null);
+function disposeOwnedUi(ref) {
+	const ui = ref.current;
+	if (!ui) return;
+	ui.destroy();
+	ref.current = null;
+}
+function SuperDocUIProvider(props) {
+	const [ui, setUi] = useState(null);
+	const [host, setHost] = useState(null);
+	const ownedUiRef = useRef(null);
+	const setSuperDoc = useCallback((superdoc) => {
+		const hostUi = superdoc.ui;
+		disposeOwnedUi(ownedUiRef);
+		if (hostUi) setUi(hostUi);
+		else {
+			const created = createSuperDocUI({ superdoc });
+			ownedUiRef.current = created;
+			setUi(created);
+		}
+		setHost(superdoc);
+	}, []);
+	useEffect(() => () => disposeOwnedUi(ownedUiRef), []);
+	const value = {
+		ui,
+		host,
+		setSuperDoc
+	};
+	return createElement(SuperDocUIContext.Provider, { value }, props.children);
+}
+function useContextValue() {
+	const value = useContext(SuperDocUIContext);
+	if (!value) throw new Error("[superdoc/ui/react] hooks must be used within <SuperDocUIProvider>.");
+	return value;
+}
+function useSuperDocUI() {
+	return useContextValue().ui;
+}
+function useSuperDocHost() {
+	return useContextValue().host;
+}
+function useSetSuperDoc() {
+	return useContextValue().setSuperDoc;
+}
+function toSliceSource(source) {
+	const candidate = source;
+	if (typeof candidate.getSnapshot === "function" && typeof candidate.observe === "function") return source;
+	const raw = source;
+	return {
+		getSnapshot: () => raw.get(),
+		observe: (listener) => {
+			const unsubscribe = raw.subscribe(listener);
+			listener(raw.get());
+			return unsubscribe;
+		}
+	};
+}
+function useSuperDocSlice(pick, initial) {
+	const ui = useSuperDocUI();
+	const [value, setValue] = useState(() => ui ? toSliceSource(pick(ui)).getSnapshot() : initial);
+	useEffect(() => {
+		if (!ui) {
+			setValue(initial);
+			return;
+		}
+		const source = toSliceSource(pick(ui));
+		setValue(source.getSnapshot());
+		return source.observe(setValue);
+	}, [ui]);
+	return value;
+}
+var EMPTY_SELECTION = {
+	status: "pending",
+	empty: true,
+	target: null,
+	selectionTarget: null,
+	activeMarks: [],
+	activeCommentIds: [],
+	activeChangeIds: [],
+	quotedText: ""
+};
+function useSuperDocSelection() {
+	return useSuperDocSlice((ui) => ui.selection, EMPTY_SELECTION);
+}
+function useSuperDocComments() {
+	return useSuperDocSlice((ui) => ui.comments, {
+		status: "pending",
+		listStatus: "pending",
+		items: [],
+		total: 0,
+		activeIds: [],
+		activeId: null
+	});
+}
+function useSuperDocContentControls() {
+	return useSuperDocSlice((ui) => ui.contentControls, {
+		status: "pending",
+		items: [],
+		total: 0,
+		activeId: null,
+		activeIds: []
+	});
+}
+function useSuperDocTrackChanges() {
+	return useSuperDocSlice((ui) => ui.trackChanges, {
+		status: "pending",
+		items: [],
+		total: 0,
+		activeId: null,
+		authors: []
+	});
+}
+function useSuperDocToolbar() {
+	return useSuperDocSlice((ui) => ui.toolbar, {
+		context: null,
+		commands: {},
+		copyFormatActive: false
+	});
+}
+function useSuperDocCommand(id) {
+	return useSuperDocSlice((ui) => ({
+		getSnapshot: () => ui.commands.get(id).getState(),
+		observe: (cb) => ui.commands.get(id).observe(cb)
+	}), {
+		enabled: false,
+		active: false,
+		supported: false
+	});
+}
+function useSuperDocDocument() {
+	return useSuperDocSlice((ui) => ui.document, {
+		ready: false,
+		mode: null,
+		dirty: false
+	});
+}
+function useSuperDocFontOptions() {
+	return useSuperDocSlice((ui) => ({
+		getSnapshot: () => ui.fonts.getFamilyOptions(),
+		observe: (cb) => ui.fonts.observe((slice) => cb(slice.options))
+	}), []);
+}
+function useSuperDocFontSizeOptions() {
+	return useSuperDocSlice((ui) => ({
+		getSnapshot: () => ui.fonts.getSizeOptions(),
+		observe: (cb) => ui.fonts.observe((slice) => cb(slice.sizeOptions))
+	}), []);
+}
+function useSuperDocZoom() {
+	return useSuperDocSlice((ui) => ui.zoom, {
+		mode: null,
+		value: 100,
+		min: 10,
+		max: 100
+	});
+}
+export { SuperDocUIProvider, useSetSuperDoc, useSuperDocCommand, useSuperDocComments, useSuperDocContentControls, useSuperDocDocument, useSuperDocFontOptions, useSuperDocFontSizeOptions, useSuperDocHost, useSuperDocSelection, useSuperDocSlice, useSuperDocToolbar, useSuperDocTrackChanges, useSuperDocUI, useSuperDocZoom };

package/dist/public/ui.cjs

@@ -0,0 +1,5 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-CXCqHc2m.cjs");
+exports.BUILT_IN_COMMAND_IDS = require_create_super_doc_ui.BUILT_IN_COMMAND_IDS;
+exports.createSuperDocUI = require_create_super_doc_ui.createSuperDocUI;
+exports.shallowEqual = require_create_super_doc_ui.shallowEqual;

package/dist/public/ui.es.js

@@ -0,0 +1,2 @@
+import { n as shallowEqual, r as BUILT_IN_COMMAND_IDS, t as createSuperDocUI } from "../chunks/create-super-doc-ui-fxF2Q8Ib.es.js";
+export { BUILT_IN_COMMAND_IDS, createSuperDocUI, shallowEqual };

package/dist/shared/common/comments-types.d.ts

@@ -0,0 +1,102 @@
+export type Comment = {
+    commentId: string;
+    parentCommentId: string;
+    fileId: string;
+    fileType: string;
+    mentions: unknown[];
+    creatorId?: string | null;
+    creatorName: string;
+    creatorEmail?: string;
+    createdTime: number;
+    importedId: string;
+    importedAuthor: {
+        name: string;
+        email?: string;
+    };
+    isInternal: boolean;
+    commentText: string;
+    selection: {
+        documentId: string;
+        page: number;
+        selectionBounds: unknown;
+    };
+    trackedChange: boolean;
+    trackedChangeText: string | null;
+    trackedChangeType: 'trackInsert' | 'trackDelete' | 'both' | 'trackFormat';
+    trackedChangeDisplayType?: 'hyperlinkAdded' | 'hyperlinkModified' | null;
+    deletedText: string | null;
+    resolvedTime: number | null;
+    resolvedById: string | null;
+    resolvedByEmail: string | null;
+    resolvedByName: string | null;
+    commentJSON: CommentJSON;
+    origin?: 'word' | 'google-docs' | 'unknown';
+    threadingMethod?: 'commentsExtended' | 'range-based' | 'mixed';
+    threadingStyleOverride?: CommentThreadingStyle;
+    threadingParentCommentId?: string;
+    originalXmlStructure?: {
+        hasCommentsExtended: boolean;
+        hasCommentsExtensible: boolean;
+        hasCommentsIds: boolean;
+    };
+};
+export type CommentThreadingStyle = 'commentsExtended' | 'range-based';
+export type CommentThreadingProfile = {
+    defaultStyle: CommentThreadingStyle;
+    mixed?: boolean;
+    fileSet: {
+        hasCommentsExtended: boolean;
+        hasCommentsExtensible: boolean;
+        hasCommentsIds: boolean;
+    };
+};
+export type CommentContent = {
+    type: string;
+    marks: Array<{
+        type: string;
+        attrs: {
+            color: string;
+            fontFamily: string;
+            fontSize: string;
+            styleId: string | null;
+        };
+    }>;
+    text: string;
+};
+export type CommentJSON = {
+    type: string;
+    attrs: {
+        lineHeight: string | null;
+        textIndent: string | null;
+        paraId: string | null;
+        textId: string | null;
+        rsidR: string | null;
+        rsidRDefault: string | null;
+        rsidP: string | null;
+        rsidRPr: string | null;
+        rsidDel: string | null;
+        spacing: {
+            lineSpaceAfter: number;
+            lineSpaceBefore: number;
+            line: number;
+            lineRule: string | null;
+        };
+        extraAttrs: Record<string, unknown>;
+        marksAttrs: unknown[] | null;
+        indent: unknown;
+        borders: unknown;
+        class: string | null;
+        styleId: string | null;
+        sdBlockId: string | null;
+        attributes: unknown;
+        filename: string | null;
+        keepLines: boolean | null;
+        keepNext: boolean | null;
+        paragraphProperties: Record<string, unknown> | null;
+        dropcap: string | null;
+        pageBreakSource: string | null;
+        justify: unknown;
+        tabStops: unknown;
+    };
+    content: CommentContent[];
+};

package/dist/shared/common/layout-constants.d.ts

@@ -0,0 +1,7 @@
+export declare const LIST_MARKER_GAP = 8;
+export declare const MIN_MARKER_GUTTER = 24;
+export declare const DEFAULT_LIST_INDENT_BASE_PX = 24;
+export declare const DEFAULT_LIST_INDENT_STEP_PX = 24;
+export declare const DEFAULT_LIST_HANGING_PX = 18;
+export declare const SPACE_SUFFIX_GAP_PX = 4;
+export declare const DEFAULT_TAB_INTERVAL_PX = 48;

package/dist/shared/common/list-marker-utils.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Shared utilities for list marker positioning and text start calculation.
+ *
+ * This module provides a unified implementation of list marker text positioning logic
+ * that is used consistently across the measuring and layout subsystems. The core
+ * function `resolveListTextStartPx` determines where paragraph text begins after
+ * accounting for list markers, tabs, and various justification modes.
+ *
+ * This module is extracted to ensure consistency across:
+ * - remeasure.ts (fast canvas-based remeasurement)
+ * - list-indent-utils.ts (layout bridge utilities)
+ * - measuring/dom/src/index.ts (full typography measurement)
+ */
+/**
+ * Minimal marker run formatting information for text measurement.
+ */
+export type MinimalMarkerRun = {
+    fontFamily?: string;
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    color?: string;
+    letterSpacing?: number;
+    vanish?: boolean;
+    allCaps?: boolean;
+    smallCaps?: boolean;
+};
+/**
+ * Tracked-change review metadata for a list marker glyph (Plan 5).
+ *
+ * Structurally mirrors the canonical `MarkerTrackedChange` in
+ * `@superdoc/contracts` (which reuses `TrackedChangeMeta`). It is re-declared
+ * here so `@superdoc/common` stays dependency-free; the painter accepts both
+ * shapes through one permissive view. Keep the two declarations in sync.
+ */
+export type MinimalMarkerTrackedChange = {
+    /** Primary tracked-change id, stamped as `data-track-change-id`. */
+    id: string;
+    /** Review kind driving base class + marker color/decoration. */
+    kind: 'insert' | 'delete' | 'format';
+    /** All affected ids for `data-track-change-ids`, when more than one. */
+    groupedIds?: readonly string[];
+    /** Raw structural change type (e.g. `paragraph-mark`, `list-properties`). */
+    type?: string;
+    /** Logical structural subtype. */
+    subtype?: string;
+    /** Structural target kind (e.g. `list-item`). */
+    targetKind?: string;
+    /** Semantic color category (e.g. `insertion`, `move-from`). */
+    semanticColorKey?: string;
+    /** Paint-ready semantic color. */
+    semanticColor?: string;
+    /** Per-author color. */
+    color?: string;
+    author?: string;
+    authorEmail?: string;
+    date?: string;
+    storyKey?: string;
+};
+/**
+ * Minimal marker information required for text start calculation.
+ *
+ * This type represents the essential properties needed from a marker object
+ * to calculate where text should start after the marker. It's designed to be
+ * compatible with various marker representations across different subsystems.
+ */
+export type MinimalMarker = {
+    /** Pre-measured width of the entire marker box in pixels */
+    markerBoxWidthPx?: number;
+    /** Pre-measured width of the marker glyph/text in pixels */
+    glyphWidthPx?: number;
+    /** Horizontal position where marker is drawn (used in firstLineIndentMode) */
+    markerX?: number;
+    /** Horizontal position where text should start (used in firstLineIndentMode) */
+    textStartX?: number;
+    /** Width of the gutter between marker and text (used for center/right justification) */
+    gutterWidthPx?: number;
+    /** Marker justification: 'left', 'center', or 'right' */
+    justification?: 'left' | 'center' | 'right';
+    /** What follows the marker: 'tab', 'space', or 'nothing' */
+    suffix?: 'tab' | 'space' | 'nothing';
+    /** The text content of the marker (for measurement if glyphWidthPx not available) */
+    markerText?: string;
+    /** Formatting information for the marker (for measurement if needed) */
+    run?: MinimalMarkerRun;
+    /**
+     * Optional tracked-change review metadata for the marker glyph (Plan 5).
+     * Carried through the `wordLayout.marker` legacy paint path so the painter
+     * can stamp marker review identity/styling. Absent for normal markers.
+     */
+    trackedChange?: MinimalMarkerTrackedChange;
+};
+/**
+ * Minimal word layout configuration for text start calculation.
+ *
+ * Contains the subset of word layout properties needed to determine text positioning.
+ */
+export type MinimalWordLayout = {
+    /** Whether this list uses first-line indent mode (input-rule created lists) */
+    firstLineIndentMode?: boolean;
+    /** Pre-calculated horizontal position where text should start */
+    textStartPx?: number;
+    /** Left indent in pixels from word-layout marker positioning */
+    indentLeftPx?: number;
+    /** Array of tab stop positions in pixels (for firstLineIndentMode) */
+    tabsPx?: number[];
+    /** Marker information */
+    marker?: MinimalMarker;
+};
+/**
+ * Function type for measuring marker text width.
+ *
+ * Different subsystems use different text measurement approaches:
+ * - remeasure.ts: Canvas-based measurement with getCtx()
+ * - measuring/dom: Canvas-based measurement with cached context
+ * - list-indent-utils: May not have access to canvas, provides markerWidth parameter
+ */
+export type MarkerTextMeasurer = (markerText: string, marker: MinimalMarker) => number;
+/**
+ * Resolved list prefix geometry for a single numbered or bulleted paragraph line.
+ *
+ * All coordinates are measured from the left edge of the paragraph content area.
+ */
+export type ResolvedListMarkerGeometry = {
+    /** Left edge where the visible marker glyph should be painted. */
+    markerStartPx: number;
+    /** Visible marker glyph width in pixels. */
+    markerTextWidthPx: number;
+    /** Horizontal position where paragraph text begins after marker + suffix. */
+    textStartPx: number;
+    /** Width contributed by the suffix separator (tab, space, or nothing). */
+    suffixWidthPx: number;
+};
+/**
+ * Resolves full marker geometry for a list prefix on a paragraph line.
+ *
+ * This is the canonical geometry source for marker start, suffix width, and
+ * paragraph text start. Measurement and painting should both use this helper
+ * so they stay aligned on numbered-list first lines.
+ *
+ * @param wordLayout - Word list layout metadata for the paragraph
+ * @param indentLeft - Paragraph left indent in pixels
+ * @param firstLine - Paragraph first-line indent in pixels
+ * @param hanging - Paragraph hanging indent in pixels
+ * @param measureMarkerText - Callback used when marker glyph width is not precomputed
+ * @returns Resolved list prefix geometry, or undefined when the paragraph has no marker
+ */
+export declare function resolveListMarkerGeometry(wordLayout: MinimalWordLayout | undefined, indentLeft: number, firstLine: number, hanging: number, measureMarkerText: MarkerTextMeasurer): ResolvedListMarkerGeometry | undefined;
+/**
+ * Convenience wrapper that returns only the text-start X coordinate from
+ * {@link resolveListMarkerGeometry}. Falls back to `wordLayout.textStartPx`
+ * for firstLineIndentMode paragraphs that have no marker.
+ *
+ * @param wordLayout - Word list layout metadata for the paragraph
+ * @param indentLeft - Paragraph left indent in pixels
+ * @param firstLine - Paragraph first-line indent in pixels
+ * @param hanging - Paragraph hanging indent in pixels
+ * @param measureMarkerText - Callback used when marker glyph width is not precomputed
+ * @returns Horizontal pixel position where text content should begin, or undefined if no marker present
+ */
+export declare function resolveListTextStartPx(wordLayout: MinimalWordLayout | undefined, indentLeft: number, firstLine: number, hanging: number, measureMarkerText: MarkerTextMeasurer): number | undefined;
+/**
+ * Type guard to check if a value is a valid MinimalWordLayout object.
+ *
+ * Validates that the object has the expected structure for MinimalWordLayout
+ * without unsafe type assertions. Shared across resolver and painter.
+ */
+export declare function isMinimalWordLayout(value: unknown): value is MinimalWordLayout;
+/**
+ * Compute the width of the tab separator between a list marker and its text content.
+ *
+ * Used for marker modes whose rendering contract differs from the shared geometry
+ * helper, such as right/center-justified markers and firstLineIndentMode paragraphs.
+ */
+export type MarkerIndent = {
+    anchorIndentPx: number;
+    firstLinePx: number;
+    hangingPx: number;
+};
+export declare function resolveMarkerIndent(indent: {
+    left?: number;
+    right?: number;
+    firstLine?: number;
+    hanging?: number;
+} | undefined, isRtl: boolean): MarkerIndent;
+export declare function computeTabWidth(currentPos: number, justification: string, tabs: number[] | undefined, hangingIndent: number | undefined, firstLineIndent: number | undefined, leftIndent: number): number;

package/dist/shared/common/list-numbering/index.d.ts

@@ -0,0 +1,16 @@
+type NumberingHandler = (path: number[], lvlText: string, customFormat?: string) => string | null;
+export interface GenerateOrderedListIndexOptions {
+    listLevel: number[];
+    lvlText: string | null | undefined;
+    listNumberingType?: string;
+    customFormat?: string;
+}
+export declare const generateOrderedListIndex: ({ listLevel, lvlText, listNumberingType, customFormat, }: GenerateOrderedListIndexOptions) => string | null;
+export declare const intToJapaneseCounting: (num: number) => string;
+export declare const normalizeLvlTextChar: (lvlText?: string) => string | undefined;
+export declare const listNumberingHelpers: {
+    generateOrderedListIndex: ({ listLevel, lvlText, listNumberingType, customFormat, }: GenerateOrderedListIndexOptions) => string | null;
+    intToJapaneseCounting: (num: number) => string;
+    normalizeLvlTextChar: (lvlText?: string) => string | undefined;
+};
+export type { NumberingHandler };

package/dist/shared/font-system/src/activation.d.ts

@@ -0,0 +1,64 @@
+/** Selection of which bundled families are active, by logical Word family name. */
+export interface BundledFontSelection {
+    /** Active families. When set (non-empty), ONLY these logical families resolve/advertise. */
+    include?: readonly string[];
+    /** Inactive families. When set, every bundled family EXCEPT these is active. */
+    exclude?: readonly string[];
+}
+/** Inputs that decide bundled activation for a document. */
+export interface BundledActivationInput extends BundledFontSelection {
+    /** Whether the consumer wired the bundled pack (config presence or the CDN build). */
+    packConfigured: boolean;
+}
+/** A resolved activation: the packConfigured flag, a per-logical-family predicate, and a signature. */
+export interface BundledActivation {
+    /** True when the bundled pack is wired for this document (config presence or the CDN build). */
+    readonly packConfigured: boolean;
+    /** Whether bundled substitution / advertising is active for this LOGICAL family (any case). */
+    isActive(logicalFamily: string): boolean;
+    /**
+     * Deterministic identity of this activation. `''` when FULLY active (packConfigured with no
+     * include/exclude) so default / full-pack documents keep sharing the measure cache and match the
+     * global resolver; any narrower activation (no pack, or curated) gets a distinct, non-empty
+     * signature the resolver folds into its own {@link FontResolver.signature} (the measure-cache key)
+     * - so a no-pack or curated document never reuses a full-pack document's cached measures.
+     */
+    readonly signature: string;
+}
+/**
+ * Fully-active activation: every bundled family, signature `''`. The resolver's default, so the
+ * module-level resolver and any `createFontResolver()` with no activation keep the prior global
+ * substitution behavior (and share the measure cache).
+ */
+export declare const FULLY_ACTIVE_BUNDLED: BundledActivation;
+/**
+ * No-pack activation: no bundled family is active. The conservative baseline default for the STATIC
+ * toolbar surfaces (the headless `DEFAULT_FONT_FAMILY_OPTIONS` / Vue `TOOLBAR_FONTS` consts, which
+ * have no runtime config to read).
+ */
+export declare const BASELINE_BUNDLED: BundledActivation;
+/**
+ * Build a {@link BundledActivation} from config-presence plus optional include/exclude.
+ *
+ * `include` is the stronger intent and WINS if both are passed (they are not meant to be combined).
+ * An include/exclude list with no usable entries is ignored rather than emptying the toolbar - "no
+ * bundled fonts" is expressed by not configuring the pack, not by `include: []`.
+ */
+export declare function createBundledActivation(input: BundledActivationInput): BundledActivation;
+/** Structural slice of a `fonts` config the activation needs - keeps this free of the editor type. */
+export interface FontAssetConfigLike {
+    resolveAssetUrl?: unknown;
+    assetBaseUrl?: unknown;
+    bundled?: BundledFontSelection;
+}
+/**
+ * Derive a document's {@link BundledActivation} from its `fonts` config. The pack counts as
+ * configured when the consumer set `resolveAssetUrl` (e.g. `superdocFonts`) or `assetBaseUrl`, or
+ * when a host marked it present page-globally ({@link isBundledPackPresent}). Selection comes from
+ * `fonts.bundled` (set via `createSuperDocFonts`).
+ *
+ * This is the lower-level primitive; runtime documents that may carry hand-written `fonts.bundled`
+ * derive activation through `deriveBundledActivationForConfig` (in font-offerings), which sanitizes
+ * unknown curation names against the known family set first.
+ */
+export declare function deriveBundledActivation(config: FontAssetConfigLike | null | undefined): BundledActivation;

package/dist/shared/font-system/src/bundled-manifest.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Manifest of the bundled reviewed fallback pack: pure data, no binary
+ * imports. The provider ({@link ./bundled}) turns each entry into a `url(...)` face
+ * against a runtime base URL, so font bytes are emitted/served as SEPARATE assets and
+ * never inlined into the JS bundle. Adding reviewed fallback rows extends the pack without changing
+ * the resolver -> registry -> gate -> report flow.
+ *
+ * The `family` is the physical substitute name (must match the resolver's targets); the
+ * `file` is the asset filename under `../assets/`. Family display names with spaces map
+ * to space-free file prefixes (e.g. "Liberation Sans" -> `LiberationSans-*.woff2`).
+ */
+/** License identifier or expression for provenance and diagnostics. */
+export type BundledLicense = 'OFL-1.1' | 'Apache-2.0' | 'AGPL-3.0-only WITH PS-or-PDF-font-exception-20170817' | 'GPL-2.0-only WITH Font-exception-2.0' | 'LicenseRef-GUST-Font-License-1.0';
+/** One shippable face of a bundled family: its style axis + the asset filename. */
+export interface BundledFaceFile {
+    weight: 'normal' | 'bold';
+    style: 'normal' | 'italic';
+    /** Asset filename under the pack's `assets/` dir, e.g. `Carlito-Regular.woff2`. */
+    file: string;
+}
+/** A bundled substitute family modeled as its faces. */
+export interface BundledFamilyManifest {
+    /** Physical family name (the substitute), e.g. "Carlito", "Liberation Sans". */
+    family: string;
+    license: BundledLicense;
+    faces: readonly BundledFaceFile[];
+}
+/**
+ * The verified bundled substitutes. Adding a row extends the pack without
+ * touching the provider, registry, gate, or report.
+ */
+export declare const BUNDLED_MANIFEST: readonly BundledFamilyManifest[];

package/dist/shared/font-system/src/bundled.d.ts

@@ -0,0 +1,41 @@
+import type { FontRegistry } from './registry.js';
+import type { FontAssetUrlResolver } from './types.js';
+export type { BundledLicense, BundledFaceFile, BundledFamilyManifest } from './bundled-manifest.js';
+export type { FontAssetUrlContext, FontAssetUrlResolver } from './types.js';
+export { BUNDLED_MANIFEST } from './bundled-manifest.js';
+/**
+ * Last-resort base URL the bundled `.woff2` are served from. Used only when neither a
+ * `resolveAssetUrl` nor an `assetBaseUrl` is configured and no build target set a default.
+ * A dev / simple-self-host fallback, NOT the product deploy assumption.
+ */
+export declare const DEFAULT_BUNDLED_FONT_BASE = "/fonts/";
+/** Override the default asset base (e.g. a host that serves the pack from a fixed path). */
+export declare function setBundledFontAssetBase(base: string): void;
+/** The current default asset base (script-relative on CDN, else {@link DEFAULT_BUNDLED_FONT_BASE}). */
+export declare function getBundledFontAssetBase(): string;
+/** Mark the bundled pack as served page-globally (for hosts that serve it without per-instance config). */
+export declare function markBundledPackPresent(): void;
+/** Whether the bundled pack is served page-globally (see {@link markBundledPackPresent}). */
+export declare function isBundledPackPresent(): boolean;
+/** Reset the page-global pack-present flag. Test-only; not part of the public surface. */
+export declare function __resetBundledPackPresent(): void;
+export interface InstallBundledOptions {
+    /** Highest-precedence per-face URL resolver (consumer `fonts.resolveAssetUrl`). */
+    resolveAssetUrl?: FontAssetUrlResolver;
+    /** Base URL the `.woff2` are served from (consumer `fonts.assetBaseUrl`). */
+    assetBaseUrl?: string;
+}
+/**
+ * Register the bundled substitute pack into a registry, once, as URL-sourced faces.
+ *
+ * The pack is one font PROVIDER - it registers `url(...)` faces through the same
+ * `registry.register` path as customer/embedded fonts, never importing font binaries
+ * into shared runtime, so the bytes are emitted as separate assets and never inlined.
+ *
+ * URL resolution precedence (per face): `resolveAssetUrl` -> `assetBaseUrl` -> the module
+ * default base (script-relative on CDN, else `/fonts/`). Loading stays lazy at the binary
+ * level: a `.woff2` is fetched only when the load gate awaits the family a document
+ * declares. Idempotent per registry. Physical family names MUST match the resolver's
+ * substitute targets.
+ */
+export declare function installBundledSubstitutes(registry: FontRegistry, options?: InstallBundledOptions): void;

package/dist/shared/font-system/src/document-font-options.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Document-scoped font options for the toolbar: one option per logical family a loaded document
+ * actually uses. Distinct from the static {@link ./font-offerings} (the bundled choices): this is
+ * runtime and document-scoped because it needs the document's registry and resolver.
+ *
+ * Fallback diagnostics are intentionally not part of this surface. The toolbar lists document fonts as
+ * plain picker rows; internal fallback/reporting details stay in SuperDoc's runtime font report.
+ */
+import { type BundledActivation } from './activation.js';
+import { type UsedFace } from './report.js';
+import type { FontRegistry } from './registry.js';
+import type { FontResolver } from './resolver.js';
+/**
+ * One document font for the toolbar: the logical name (the dropdown label and the value stored and
+ * exported) and the family to render its preview in.
+ */
+export interface DocumentFontOption {
+    /** The Word-facing logical family: the dropdown label and the value stored + exported (e.g. "Aptos"). */
+    logicalFamily: string;
+    /**
+     * The physical family to render the dropdown PREVIEW in (Calibri previews as Carlito; a document-
+     * provided font previews as itself). The regular face is used as the representative when present.
+     */
+    previewFamily: string;
+}
+/**
+ * The document-specific font options for the toolbar: one per LOGICAL family the document renders,
+ * deduped, each with the family that actually paints its preview. Resolved FACE-aware (via
+ * {@link buildFaceReport}) so an embedded / customer font the document supplies is detected even when
+ * no bundled clone exists.
+ */
+export declare function buildDocumentFontOptions(usedFaces: Iterable<UsedFace>, registry: FontRegistry, resolver?: FontResolver): DocumentFontOption[];
+/**
+ * Final, dropdown-ready font family option. `label` and `value` are the logical family; `previewFamily`
+ * is only for rendering the row preview.
+ */
+export interface FontFamilyOption {
+    /** Display text: the Word-facing logical family (e.g. "Calibri"). */
+    label: string;
+    /** Value to apply with the font-family command. */
+    value: string;
+    /** Physical family used to render the option preview. */
+    previewFamily: string;
+}
+/**
+ * Compose the final font-family picker list from the built-in toolbar choices plus the active
+ * document's fonts. The built-in choices are gated on the document's bundled-font {@link
+ * BundledActivation} (baseline when no pack is configured, the curated rich set when it is); pass it
+ * from the editor so the picker advertises only what this document will render. Document fonts are
+ * always listed - they come from the loaded document itself. Sorted alphabetically, deduped by
+ * logical family.
+ */
+export declare function buildFontFamilyOptions(documentOptions: ReadonlyArray<DocumentFontOption>, activation?: BundledActivation): FontFamilyOption[];