@mermanjs/web-render 0.9.3 → 0.10.0-alpha.2

package/dist/public-types.d.ts

@@ -1,19 +1,23 @@
-import type { AsciiCapability, BindingStatusCodeName, DiagramFamilyCapability, DiagramType, LintBindingOptions, LintRuleCatalogResponse, LintRuleCategory, LintRuleSeverity, LintRuleTag, RuntimeCapabilities } from "./public-catalog.js";
+import type { AsciiCapability, BindingStatusCodeName, DiagramFamilyCapability, DiagramType, LintBindingOptions, LintRuleCatalogResponse, LintRuleCategory, LintRuleSeverity, LintRuleTag, RuntimeCapabilities, ThemeName } from "./public-catalog.js";
 import type { HostTextDirection, HostTextMeasurementOperation, HostTextMeasurementPhase, HostTextWhiteSpace, HostTextWrapMode } from "./generated/text-measurement-abi.js";
 import type { EditorRenamePolicy } from "./generated/editor-rename-policy.js";
-import type { ResourceOverrideId, ResourceLimitId, ResourceOptions, ResourceProfile } from "./generated/resource-contract.js";
+import type { BINDING_OPTIONS_SCHEMA_VERSION, ResourceOverrideId, ResourceLimitId, ResourceOptions, ResourceProfile } from "./generated/resource-contract.js";
 export type { HostTextDirection, HostTextMeasurementOperation, HostTextMeasurementPhase, HostTextMeasurementResultKind, HostTextWhiteSpace, HostTextWrapMode, } from "./generated/text-measurement-abi.js";
 export type { ResourceOptions } from "./generated/resource-contract.js";
 export interface ParseOptions {
     suppress_errors?: boolean;
 }
 export interface LayoutOptions {
+    /** Explicit whole-column packing, currently supported by Kanban only. */
+    adaptation?: "none" | "fit-width";
     container_width?: number;
     container_height?: number;
     screen_available_width?: number;
 }
 export interface RenderEnvironmentOptions {
-    text_measurement?: "deterministic";
+    /** Require the renderer's native portability admission; pipeline selection alone is not strict. */
+    theme_portability?: "best-effort" | "require-portable";
+    text_measurement?: "deterministic" | null;
     math_renderer?: "none" | "ratex";
 }
 /**
@@ -38,33 +42,66 @@ export interface RuntimeCatalog {
     registry: RuntimeRegistryContract;
     resources: RuntimeResourceContract;
 }
-export interface PresentationCatalog {
+export interface ThemeCatalog {
     schema_version: 1;
-    theme_presets: PresentationThemePresetCatalogEntry[];
-    profiles: PresentationProfileCatalogEntry[];
-}
-export interface PresentationThemePresetCatalogEntry {
+    structured_spec_available: boolean;
+    supported_output_ids: string[];
+    presets: ThemePresetCatalogEntry[];
+    known_capability_ids: string[];
+    known_text_capability_ids: string[];
+    known_font_container_ids: string[];
+    known_font_source_ids: string[];
+    known_semantic_target_ids: string[];
+    known_variant_ids: string[];
+    resource_limits: ThemeResourceLimitCatalogEntry[];
+}
+export interface ThemePresetCatalogEntry {
     id: string;
+    display_name: string;
     appearance: string;
-    fully_available: boolean;
-    missing_capability_ids: string[];
-}
-export interface PresentationProfileCatalogEntry {
+    maturity: string;
+    available: boolean;
+    availability_reason_ids: string[];
+    /** Ordered color swatches for discovery, not a rendered palette or support claim. */
+    preview_colors: string[];
+    /** Curated design scope, independent of technical support or qualification. */
+    family_designs: ThemePresetFamilyDesign[];
+    /** Curated visual guidance; recommendations require an explicit host/user decision. */
+    application_notes: ThemePresetApplicationNote[];
+    qualified_cells: ThemePresetQualifiedCell[];
+    license_expression: string;
+    required_attribution: string | null;
+    export_kind: "design" | "complete_spec";
+}
+/** Missing families and unknown treatments are unreviewed; preserve unknown IDs. */
+export interface ThemePresetFamilyDesign {
+    family_id: string;
+    /** Open string: dedicated, base_only, or unreviewed. None grants portability. */
+    treatment: string;
+}
+/** Open discovery guidance for a family; presence grants no support or qualification. */
+export interface ThemePresetApplicationNote {
     id: string;
-    fully_available: boolean;
-    missing_capability_ids: string[];
-    aspects: PresentationAspectCatalogEntry[];
-}
-export interface PresentationAspectCatalogEntry {
+    family_id: string;
+    message: string;
+    /** Suggested Mermaid site configuration. Never applied by preset selection itself. */
+    recommended_config: Record<string, unknown> | null;
+}
+/** Scoped metadata backed by catalog qualification, not an unconditional portability claim. */
+export interface ThemePresetQualifiedCell {
+    family_id: string;
+    output_id: string;
+    /** Scenario and resource conditions. Unknown profiles do not grant usable support. */
+    profile_id: string;
+    /** Open target admission ID; for example `portable` or `host_dependent`. */
+    admission_status: string;
+}
+export interface ThemeResourceLimitCatalogEntry {
     id: string;
-    applicability: PresentationAspectApplicability;
-    required_capability_id: string | null;
-    available: boolean;
-    missing_capability_ids: string[];
-}
-export interface PresentationAspectApplicability {
-    kind: string;
-    family_id: string | null;
+    phase: string;
+    description: string;
+    effective_value: number | null;
+    hard_cap: boolean;
 }
 export interface RuntimePayloadSchema {
     [key: string]: unknown;
@@ -149,27 +186,500 @@ export interface RuntimeResourceProfile {
 export interface SvgOptions {
     diagram_id?: string;
     pipeline?: "parity" | "readable" | "resvg-safe";
-    scoped_css?: string;
-    css_override_policy?: "preserve" | "strip-existing-important";
     root_background_color?: string;
     drop_native_duplicate_fallbacks?: boolean;
     viewbox_padding?: number;
     viewBoxPadding?: number;
 }
-export type PresentationThemeAppearance = "light" | "dark";
-export interface PresentationThemeOptions {
-    preset?: string;
-    appearance?: PresentationThemeAppearance;
-    font_family?: string;
-    font_size?: string;
-    roles?: Record<string, string>;
-    series_palette?: string[];
+/** A named preset, direct specification, or shareable recipe. Select exactly one form. */
+export type DiagramThemeSelection = ({
+    kind?: never;
+    schema_version?: never;
+    design?: never;
+    complete_spec?: never;
+} & ({
+    preset: string;
+    spec?: never;
+} | {
+    preset?: never;
+    spec: DiagramThemeSpec;
+})) | ThemeRecipeV1;
+/** A literal or an exact document-local token reference; dots have no traversal meaning. */
+export type ThemeValueV1<T> = T | ThemeReferenceV1;
+export interface ThemeReferenceV1 {
+    ref: string;
+}
+/** An editable design. Only clearable style fields accept explicit null. */
+export interface ThemeDesignV1 {
+    tokens?: Record<string, ThemeDesignTokenV1>;
+    styles?: Record<string, ThemeDesignStyleV1>;
+    rules?: ThemeDesignRuleV1[];
+    palettes?: Record<string, ThemeValueV1<ThemeValueV1<string>[]>>;
+    canvas?: ThemeDesignCanvasV1;
+    typography?: ThemeDesignTypographyV1;
+    mermaid?: MermaidThemeCompatibility;
+    assets?: ThemeAssetsSpec;
+    requirements?: ThemeRequirementsSpec;
+}
+export type ThemeDesignTokenV1 = {
+    label?: string;
+    description?: string;
+    group?: string;
+} & ({
+    type: "color";
+    value: ThemeValueV1<string>;
+} | {
+    type: "number";
+    value: ThemeValueV1<number>;
+} | {
+    type: "string";
+    value: ThemeValueV1<string>;
+} | {
+    type: "length";
+    value: ThemeValueV1<ThemeLength>;
+} | {
+    type: "insets";
+    value: ThemeValueV1<ThemeInsets>;
+} | {
+    type: "line-height";
+    value: ThemeValueV1<ThemeLineHeight>;
+} | {
+    type: "font-stack";
+    value: ThemeValueV1<string[]>;
+} | {
+    type: "palette";
+    value: ThemeValueV1<ThemeValueV1<string>[]>;
+} | {
+    type: "paint";
+    value: ThemeValueV1<ThemeDesignPaintV1>;
+} | {
+    type: "stroke";
+    value: ThemeValueV1<ThemeDesignStrokeV1>;
+} | {
+    type: "text-style";
+    value: ThemeValueV1<ThemeDesignTextStyleV1>;
+} | {
+    type: "effect";
+    value: ThemeValueV1<ThemeDesignEffectV1>;
+});
+export interface ThemeDesignRuleV1 {
+    target: string;
+    family?: string;
+    variant?: string;
+    ordinal?: ThemeRuleEntry["ordinal"];
+    style: ThemeDesignStyleV1;
+}
+export interface ThemeDesignStyleV1 {
+    fill?: ThemePatch<ThemeValueV1<ThemeDesignPaintV1>>;
+    opacity?: ThemePatch<ThemeValueV1<number>>;
+    fill_opacity?: ThemePatch<ThemeValueV1<number>>;
+    stroke?: ThemeValueV1<ThemeDesignStrokeV1>;
+    radius?: ThemePatch<ThemeValueV1<ThemeLength>>;
+    padding?: ThemePatch<ThemeValueV1<ThemeInsets>>;
+    typography?: ThemeValueV1<ThemeDesignTextStyleV1>;
+    effect?: ThemePatch<ThemeValueV1<ThemeDesignEffectV1>>;
+}
+export interface ThemeDesignStrokeV1 {
+    paint?: ThemePatch<ThemeValueV1<ThemeDesignPaintV1>>;
+    width?: ThemePatch<ThemeValueV1<ThemeLength>>;
+    dasharray?: ThemePatch<ThemeValueV1<number>[]>;
+    linecap?: ThemePatch<ThemeValueV1<"butt" | "round" | "square">>;
+    linejoin?: ThemePatch<ThemeValueV1<"miter" | "round" | "bevel">>;
+    opacity?: ThemePatch<ThemeValueV1<number>>;
+}
+export interface ThemeDesignTextStyleV1 {
+    font_stack?: ThemePatch<ThemeValueV1<string[]>>;
+    font_size_px?: ThemePatch<ThemeValueV1<ThemeLength>>;
+    font_weight?: ThemePatch<ThemeValueV1<number>>;
+    font_style?: ThemePatch<ThemeValueV1<"normal" | "italic" | "oblique">>;
+    line_height?: ThemePatch<ThemeValueV1<ThemeLineHeight>>;
+    letter_spacing_px?: ThemePatch<ThemeValueV1<ThemeLength>>;
+    word_spacing_px?: ThemePatch<ThemeValueV1<ThemeLength>>;
+    transform?: ThemePatch<ThemeValueV1<"none" | "uppercase" | "lowercase" | "capitalize">>;
+    decoration?: ThemePatch<ThemeValueV1<"none" | "underline" | "overline" | "line-through">>;
+    text_align?: ThemePatch<ThemeValueV1<"start" | "center" | "end">>;
+    white_space?: ThemePatch<ThemeValueV1<"normal" | "pre" | "no-wrap" | "pre-wrap" | "pre-line">>;
+    wrap?: ThemePatch<ThemeValueV1<"normal" | "break-word" | "anywhere">>;
+}
+export interface ThemeDesignTypographyV1 {
+    default?: ThemeValueV1<ThemeDesignTextStyleV1>;
+    families?: Record<string, ThemeValueV1<ThemeDesignTextStyleV1>>;
+}
+export type ThemeDesignPaintV1 = string | {
+    kind: "transparent";
+} | {
+    kind: "solid";
+    color: ThemeValueV1<string>;
+} | {
+    kind: "linear-gradient";
+    angle_degrees: ThemeValueV1<number>;
+    stops: ThemeDesignGradientStopV1[];
+    repetition?: ThemeLinearGradientRepetition;
+} | {
+    kind: "radial-gradient";
+    center_x: ThemeValueV1<ThemeLength>;
+    center_y: ThemeValueV1<ThemeLength>;
+    radius: ThemeValueV1<ThemeLength>;
+    stops: ThemeDesignGradientStopV1[];
+    repetition?: ThemeRadialGradientRepetition;
+} | {
+    /** Acceptance preserves the request; it does not establish pattern renderer support. */
+    kind: "pattern";
+    pattern: "dots" | "grid" | "stripes";
+    cell_width: ThemeValueV1<ThemeLength>;
+    cell_height: ThemeValueV1<ThemeLength>;
+    foreground: ThemeValueV1<string>;
+    background?: ThemeValueV1<string>;
+    angle_degrees?: ThemeValueV1<number>;
+};
+export interface ThemeDesignGradientStopV1 {
+    offset: ThemeValueV1<number>;
+    color: ThemeValueV1<string>;
+    opacity?: ThemeValueV1<number>;
+}
+export interface ThemeDesignCanvasV1 {
+    base?: ThemeValueV1<ThemeDesignPaintV1>;
+    layers?: ThemeDesignCanvasLayerV1[];
+    bleed?: ThemeValueV1<ThemeInsets>;
+}
+export interface ThemeDesignCanvasLayerV1 {
+    paint: ThemeValueV1<ThemeDesignPaintV1>;
+    opacity?: ThemeValueV1<number>;
+    blend_mode?: ThemeCanvasLayer["blend_mode"];
+    offset_x?: ThemeValueV1<ThemeLength>;
+    offset_y?: ThemeValueV1<ThemeLength>;
+}
+export type ThemeShadowCompositionV1 = "independent" | "cascade";
+export type ThemeDesignEffectV1 = {
+    kind: "shadow-stack";
+    composition: ThemeShadowCompositionV1;
+    color_space?: "linear-rgb" | "srgb";
+    shadows: ThemeDesignShadowV1[];
+} | {
+    kind: "graph";
+    color_space?: "linear-rgb" | "srgb";
+    primitives: ThemeEffectPrimitive[];
+};
+export interface ThemeDesignShadowV1 {
+    offset_x: ThemeValueV1<ThemeLength>;
+    offset_y: ThemeValueV1<ThemeLength>;
+    /** Gaussian standard deviation in pixels; zero produces a hard shadow. */
+    std_deviation: ThemeValueV1<ThemeLength>;
+    color: ThemeValueV1<string>;
+    opacity?: ThemeValueV1<number>;
+}
+export interface MaterializedThemeWireV1 {
+    schema_version: 1;
+    authoring_schema_version: 1;
+    expansion_version: 1;
+    spec_schema_version: 1;
+    spec: DiagramThemeSpec;
+    /** Declared authoring references and consumer constraints; this is not a winning-rule trace. */
+    references?: ThemeDesignReferenceUse[];
+}
+export interface ThemeDesignValueDomain {
+    value_type: ThemeDesignTokenV1["type"];
+    choices?: string[];
+    units?: string[];
+    min?: number;
+    max?: number;
+}
+export interface ThemeDesignReferenceUse {
+    token: string;
+    /** JSON Pointer to the authored consumer. */
+    path: string;
+    domain: ThemeDesignValueDomain;
+}
+export interface ThemeDesignInspection {
+    references: ThemeDesignReferenceUse[];
+}
+export type ThemeSupportOutputId = "standalone-svg" | "browser-svg" | "png" | "jpeg" | "pdf" | "ascii" | (string & {});
+declare const themeSupportUnknownSubjectKind: unique symbol;
+/**
+ * A subject kind not understood by this Web contract revision.
+ *
+ * The brand prevents an incomplete known subject such as `{ kind: "rule" }` from falling through
+ * to the forward-compatible branch. Values decoded from a newer runtime can retain their unknown
+ * kind, while authored known subjects remain checked against their exact required fields.
+ */
+export type ThemeSupportUnknownSubjectKindV1 = string & {
+    readonly [themeSupportUnknownSubjectKind]: "unknown-theme-support-subject";
+};
+export type ThemeSupportUnknownSubjectV1 = {
+    kind: ThemeSupportUnknownSubjectKindV1;
+} & Record<string, unknown>;
+export type ThemeSupportSubjectV1 = {
+    kind: "rule";
+    target: string;
+    facet: string;
+} | {
+    kind: "ordinal-palette";
+    target: string;
+} | {
+    kind: "base-typography";
+    property: string;
+} | ThemeSupportUnknownSubjectV1;
+export interface ThemeSupportQueryV1 {
+    schema_version: 1;
+    family: string;
+    output: ThemeSupportOutputId;
+    subject: ThemeSupportSubjectV1;
+}
+export type ThemeSupportState = "unconditional" | "conditional" | "not-applicable" | "unsupported" | "unverified";
+export interface ThemeCapabilityDescriptorV1 {
+    schema_version: 1;
+    claim_revision: number;
+    query: ThemeSupportQueryV1;
+    state: ThemeSupportState;
+    reason_ids: string[];
+}
+export type ThemeCapabilityDescriptor = ThemeCapabilityDescriptorV1;
+/**
+ * A versioned theme document that can be saved as JSON and passed directly as options.theme.
+ * A recipe describes authored styles; it does not certify every family or output target.
+ */
+export type ThemeRecipeV1 = {
+    schema_version: 1;
+    preset?: never;
+    spec?: never;
+} & ({
+    kind: "design";
+    design: ThemeDesignV1;
+    complete_spec?: never;
+} | {
+    kind: "complete_spec";
+    complete_spec: DiagramThemeSpec;
+    design?: never;
+});
+export interface DiagramThemeSpec {
+    mermaid?: MermaidThemeCompatibility;
+    typography?: ThemeTypographySpec;
+    styles?: ThemeStyleEntry[];
+    canvas?: ThemeCanvasSpec;
+    effects?: ThemeEffectEntry[];
+    requirements?: ThemeRequirementsSpec;
+    assets?: ThemeAssetsSpec;
+}
+export interface MermaidThemeCompatibility {
+    theme?: ThemeName;
+    dark_mode?: boolean;
+    variables?: Record<string, string | number | boolean>;
+}
+export interface ThemeTypographySpec {
+    default?: ThemeTextStyle;
+    families?: Record<string, ThemeTextStyle>;
+}
+export interface ThemeTextStyle {
+    font_stack?: string[];
+    font_size_px?: number;
+    font_weight?: number;
+    font_style?: "normal" | "italic" | "oblique";
+    line_height?: ThemeLineHeight;
+    letter_spacing_px?: number;
+    word_spacing_px?: number;
+    transform?: "none" | "uppercase" | "lowercase" | "capitalize";
+    decoration?: "none" | "underline" | "overline" | "line-through";
+    text_align?: "start" | "center" | "end";
+    white_space?: "normal" | "pre" | "no-wrap" | "pre-wrap" | "pre-line";
+    wrap?: "normal" | "break-word" | "anywhere";
+}
+export type ThemeLineHeight = "normal" | number | {
+    px: number;
+};
+export type ThemePatch<T> = T | null;
+export type ThemeLength = number | {
+    px: number;
+} | {
+    percent: number;
+};
+export type ThemeInsets = number | {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+export type ThemePaint = string | {
+    kind: "transparent";
+} | {
+    kind: "solid";
+    color: string;
+} | {
+    kind: "linear-gradient";
+    angle_degrees: number;
+    stops: ThemeGradientStop[];
+    repetition?: ThemeLinearGradientRepetition;
+} | {
+    kind: "radial-gradient";
+    center_x: ThemeLength;
+    center_y: ThemeLength;
+    radius: ThemeLength;
+    stops: ThemeGradientStop[];
+    repetition?: ThemeRadialGradientRepetition;
+} | {
+    kind: "pattern";
+    pattern: "dots" | "grid" | "stripes";
+    cell_width: number;
+    cell_height: number;
+    foreground: string;
+    background?: string;
+    angle_degrees?: number;
+};
+export type ThemeLinearGradientRepetition = {
+    kind: "repeating";
+    period_px: number;
+} | {
+    kind: "tiled";
+    width_px: number;
+    height_px: number;
+};
+export type ThemeRadialGradientRepetition = {
+    kind: "repeating";
+} | {
+    kind: "tiled";
+    width_px: number;
+    height_px: number;
+};
+export interface ThemeGradientStop {
+    offset: number;
+    color: string;
+}
+export type ThemeStyleEntry = ThemeRuleEntry | ThemeOrdinalPaletteEntry;
+export interface ThemeRuleEntry {
+    kind: "rule";
+    target: string;
+    family?: string;
+    variant?: string;
+    ordinal?: {
+        exact: number;
+    } | {
+        cycle: {
+            period: number;
+            offset: number;
+        };
+    };
+    style: ThemeStylePatch;
+}
+export interface ThemeOrdinalPaletteEntry {
+    kind: "ordinal-palette";
+    target: string;
+    colors: string[];
+}
+export interface ThemeStylePatch {
+    fill?: ThemePatch<ThemePaint>;
+    opacity?: ThemePatch<number>;
+    fill_opacity?: ThemePatch<number>;
+    stroke?: ThemeStrokePatch;
+    radius?: ThemePatch<number>;
+    padding?: ThemePatch<ThemeInsets>;
+    typography?: ThemeTextStylePatch;
+    effect?: ThemePatch<string>;
+}
+export interface ThemeStrokePatch {
+    paint?: ThemePatch<ThemePaint>;
+    width?: ThemePatch<number>;
+    dasharray?: ThemePatch<number[]>;
+    linecap?: ThemePatch<"butt" | "round" | "square">;
+    linejoin?: ThemePatch<"miter" | "round" | "bevel">;
+    opacity?: ThemePatch<number>;
+}
+export interface ThemeTextStylePatch {
+    font_stack?: ThemePatch<string[]>;
+    font_size_px?: ThemePatch<number>;
+    font_weight?: ThemePatch<number>;
+    font_style?: ThemePatch<"normal" | "italic" | "oblique">;
+    line_height?: ThemePatch<ThemeLineHeight>;
+    letter_spacing_px?: ThemePatch<number>;
+    word_spacing_px?: ThemePatch<number>;
+    transform?: ThemePatch<"none" | "uppercase" | "lowercase" | "capitalize">;
+    decoration?: ThemePatch<"none" | "underline" | "overline" | "line-through">;
+    text_align?: ThemePatch<"start" | "center" | "end">;
+    white_space?: ThemePatch<"normal" | "pre" | "no-wrap" | "pre-wrap" | "pre-line">;
+    wrap?: ThemePatch<"normal" | "break-word" | "anywhere">;
+}
+export interface ThemeCanvasSpec {
+    base?: ThemePaint;
+    layers?: ThemeCanvasLayer[];
+    bleed?: ThemeInsets;
+}
+export interface ThemeCanvasLayer {
+    paint: ThemePaint;
+    opacity?: number;
+    blend_mode?: "normal" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "difference";
+    offset_x?: number;
+    offset_y?: number;
+}
+export type ThemeEffectEntry = ThemeEffectGraph | ThemeEffectBinding;
+export interface ThemeEffectGraph {
+    kind: "graph";
+    id: string;
+    /** Color interpolation for all primitives; defaults to linear-rgb when omitted. */
+    color_space?: "linear-rgb" | "srgb";
+    /** Independent composition accepts only drop-shadow primitives reading source-graphic. */
+    composition?: ThemeShadowCompositionV1;
+    primitives: ThemeEffectPrimitive[];
+}
+export interface ThemeEffectBinding {
+    kind: "binding";
+    target: string;
+    effect_id: string;
+}
+export type ThemeEffectInput = "source-graphic" | "previous";
+export type ThemeEffectPrimitive = {
+    kind: "drop-shadow";
+    input?: ThemeEffectInput;
+    offset_x: number;
+    offset_y: number;
+    blur_radius: number;
+    spread: number;
+    color: string;
+} | {
+    kind: "gaussian-blur";
+    input?: ThemeEffectInput;
+    std_deviation: number;
+} | {
+    kind: "color-matrix";
+    input?: ThemeEffectInput;
+    values: number[];
+} | {
+    kind: "turbulence";
+    input?: ThemeEffectInput;
+    base_frequency_x: number;
+    base_frequency_y: number;
+    octaves: number;
+    seed: number;
+} | {
+    kind: "displacement";
+    input?: ThemeEffectInput;
+    map_input: ThemeEffectInput;
+    scale: number;
+};
+export interface ThemeRequirementsSpec {
+    capabilities?: string[];
+    text_capabilities?: string[];
+}
+export interface ThemeAssetsSpec {
+    fonts?: ThemeFontAsset[];
+    aliases?: Array<{
+        alias: string;
+        target: string;
+    }>;
+    generic_families?: Array<{
+        generic: string;
+        target: string;
+    }>;
+    available_sources?: Array<"embedded" | "system">;
+    embedding?: "none" | "full-font" | "subset";
+}
+export interface ThemeFontAsset {
+    id: string;
+    format: "truetype" | "opentype" | "collection" | "woff2";
+    data_base64: string;
 }
-export interface PresentationOptions {
-    profile?: string;
-    theme?: PresentationThemeOptions;
+export interface MermaidSiteConfig {
+    [key: string]: unknown;
+    themeCSS?: never;
+    secure?: never;
 }
-export type MermaidSiteConfig = Record<string, unknown>;
 export interface AnalysisBindingOptions {
     fixed_today?: string;
     fixed_local_offset_minutes?: number;
@@ -188,24 +698,24 @@ export type EditorAnalysisBindingOptions = Omit<AnalysisBindingOptions, "resourc
     resources?: EditorResourceOptions;
 };
 interface BindingVersionOptions {
-    version?: 2;
+    version?: typeof BINDING_OPTIONS_SCHEMA_VERSION;
 }
-type NoDirectAnalysisBindingOptions<Options extends AnalysisBindingOptions> = {
+type NoDirectAnalysisBindingOptions<Options extends Omit<AnalysisBindingOptions, "resources">> = {
     [Property in keyof Options]?: never;
 };
-type DirectAnalysisBindingRoot<Options extends AnalysisBindingOptions> = Options & {
+type DirectAnalysisBindingRoot<Options extends Omit<AnalysisBindingOptions, "resources">> = Options & {
     analysis?: never;
     merman?: never;
 };
-type AnalysisWrappedBindingRoot<Options extends AnalysisBindingOptions> = NoDirectAnalysisBindingOptions<Options> & {
+type AnalysisWrappedBindingRoot<Options extends Omit<AnalysisBindingOptions, "resources">> = NoDirectAnalysisBindingOptions<Options> & {
     analysis: Options;
     merman?: never;
 };
-type MermanWrappedBindingRoot<Options extends AnalysisBindingOptions> = NoDirectAnalysisBindingOptions<Options> & {
+type MermanWrappedBindingRoot<Options extends Omit<AnalysisBindingOptions, "resources">> = NoDirectAnalysisBindingOptions<Options> & {
     analysis?: never;
     merman: Options;
 };
-type AnalysisBindingRoot<Options extends AnalysisBindingOptions> = (DirectAnalysisBindingRoot<Options> | AnalysisWrappedBindingRoot<Options> | MermanWrappedBindingRoot<Options>);
+type AnalysisBindingRoot<Options extends Omit<AnalysisBindingOptions, "resources">> = (DirectAnalysisBindingRoot<Options> | AnalysisWrappedBindingRoot<Options> | MermanWrappedBindingRoot<Options>);
 export type EditorBindingOptions = BindingVersionOptions & AnalysisBindingRoot<EditorAnalysisBindingOptions>;
 interface CommonBindingFields {
     parse?: ParseOptions;
@@ -284,7 +794,9 @@ interface AsciiBindingFields {
 }
 export type AsciiBindingOptions = CommonBindingOptions & AsciiBindingFields;
 interface SvgBindingFields {
-    presentation?: PresentationOptions;
+    /** Relative deadline for this Web/WASM operation, in milliseconds. */
+    timeout_ms?: number;
+    theme?: DiagramThemeSelection | null;
     environment?: RenderEnvironmentOptions;
     layout?: LayoutOptions;
     svg?: SvgOptions;
@@ -301,18 +813,22 @@ export interface RenderSessionOptions {
 /** Immutable constructor services, scoped to this session and its creating package runtime. */
 export interface BrowserRenderSession {
     renderSvg(source: string, options?: SvgBindingOptions | string): string;
+    renderSvgResult(source: string, options?: SvgBindingOptions | string): SvgRenderResult;
     layoutJson(source: string, options?: SvgBindingOptions | string): string;
     edgeGeometryJson(source: string, options?: SvgBindingOptions | string): string;
-    renderSvgWithTextMeasurer(source: string, measurer: HostTextMeasurer, options?: SvgBindingOptions | string): string;
-    layoutJsonWithTextMeasurer(source: string, measurer: HostTextMeasurer, options?: SvgBindingOptions | string): string;
-    edgeGeometryJsonWithTextMeasurer(source: string, measurer: HostTextMeasurer, options?: SvgBindingOptions | string): string;
+    renderSvgWithTextMeasurer(source: string, measurer: HostTextMeasurer, options?: HostTextMeasurerSvgBindingOptions | string): string;
+    renderSvgResultWithTextMeasurer(source: string, measurer: HostTextMeasurer, options?: HostTextMeasurerSvgBindingOptions | string): SvgRenderResult;
+    layoutJsonWithTextMeasurer(source: string, measurer: HostTextMeasurer, options?: HostTextMeasurerSvgBindingOptions | string): string;
+    edgeGeometryJsonWithTextMeasurer(source: string, measurer: HostTextMeasurer, options?: HostTextMeasurerSvgBindingOptions | string): string;
     dispose(): void;
 }
 export interface WasmRenderSessionBinding {
     renderSvg(source: string, optionsJson?: string | null): string;
+    renderSvgResult(source: string, optionsJson?: string | null): SvgRenderResult;
     layoutJson(source: string, optionsJson?: string | null): string;
     edgeGeometryJson(source: string, optionsJson?: string | null): string;
     renderSvgWithTextMeasurer(source: string, optionsJson: string | null | undefined, measurer: HostTextMeasurer): string;
+    renderSvgResultWithTextMeasurer(source: string, optionsJson: string | null | undefined, measurer: HostTextMeasurer): SvgRenderResult;
     layoutJsonWithTextMeasurer(source: string, optionsJson: string | null | undefined, measurer: HostTextMeasurer): string;
     edgeGeometryJsonWithTextMeasurer(source: string, optionsJson: string | null | undefined, measurer: HostTextMeasurer): string;
     free(): void;
@@ -320,6 +836,58 @@ export interface WasmRenderSessionBinding {
 export interface WasmRenderSessionConstructor {
     new (iconPacksJson?: string | null): WasmRenderSessionBinding;
 }
+/** Redraw settings for frozen parse facts. Prepare again to change configuration or theme. */
+export type PreparedSourceOutputOptions = BindingVersionOptions & {
+    /** Relative deadline for this output, in milliseconds. */
+    timeout_ms?: number;
+    resources?: ResourceOptions;
+    environment?: RenderEnvironmentOptions;
+    layout?: LayoutOptions;
+    svg?: SvgOptions;
+};
+export type HostTextMeasurerPreparedSourceOutputOptions = Omit<PreparedSourceOutputOptions, "environment"> & {
+    environment?: Omit<RenderEnvironmentOptions, "text_measurement">;
+};
+export interface BrowserPreparedSource {
+    renderSvg(options?: PreparedSourceOutputOptions | string): string;
+    renderSvgResult(options?: PreparedSourceOutputOptions | string): SvgRenderResult;
+    layoutJson(options?: PreparedSourceOutputOptions | string): string;
+    edgeGeometryJson(options?: PreparedSourceOutputOptions | string): string;
+    renderSvgWithTextMeasurer(measurer: HostTextMeasurer, options?: HostTextMeasurerPreparedSourceOutputOptions | string): string;
+    renderSvgResultWithTextMeasurer(measurer: HostTextMeasurer, options?: HostTextMeasurerPreparedSourceOutputOptions | string): SvgRenderResult;
+    layoutJsonWithTextMeasurer(measurer: HostTextMeasurer, options?: HostTextMeasurerPreparedSourceOutputOptions | string): string;
+    edgeGeometryJsonWithTextMeasurer(measurer: HostTextMeasurer, options?: HostTextMeasurerPreparedSourceOutputOptions | string): string;
+    dispose(): void;
+}
+export interface WasmPreparedSourceBinding {
+    renderSvg(optionsJson?: string | null): string;
+    renderSvgResult(optionsJson?: string | null): SvgRenderResult;
+    layoutJson(optionsJson?: string | null): string;
+    edgeGeometryJson(optionsJson?: string | null): string;
+    renderSvgWithTextMeasurer(optionsJson: string | null | undefined, measurer: HostTextMeasurer): string;
+    renderSvgResultWithTextMeasurer(optionsJson: string | null | undefined, measurer: HostTextMeasurer): SvgRenderResult;
+    layoutJsonWithTextMeasurer(optionsJson: string | null | undefined, measurer: HostTextMeasurer): string;
+    edgeGeometryJsonWithTextMeasurer(optionsJson: string | null | undefined, measurer: HostTextMeasurer): string;
+    free(): void;
+}
+export interface WasmPreparedSourceConstructor {
+    new (source: string, optionsJson?: string | null): WasmPreparedSourceBinding;
+}
+export type ThemeResourceLimitId = "max_theme_encoded_bytes" | "max_theme_base64_bytes" | "max_font_asset_compressed_bytes" | "max_font_asset_decoded_bytes" | "max_font_catalog_decoded_bytes" | "max_font_assets" | "max_font_faces" | "max_font_tables" | "max_font_aliases" | "max_font_decoded_expansion_ratio" | "max_effect_graphs" | "max_effect_primitives_per_graph" | "max_effect_bindings" | "max_effect_offset_magnitude" | "max_effect_filter_region_magnitude" | "max_effect_blur_magnitude" | "max_effect_displacement_scale" | "max_effect_turbulence_octaves";
+export interface ThemeAuthoringResourceOptions {
+    profile?: ResourceProfile;
+    limits?: Partial<Record<ThemeResourceLimitId, number>>;
+}
+type ThemeAuthoringAnalysisOptions = Omit<AnalysisBindingOptions, "resources"> & {
+    resources?: ThemeAuthoringResourceOptions;
+};
+export type ThemeAuthoringOptions = BindingVersionOptions & AnalysisBindingRoot<ThemeAuthoringAnalysisOptions> & CommonBindingFields & SvgBindingFields;
+type HostTextMeasurerEnvironmentOptions = Omit<RenderEnvironmentOptions, "text_measurement"> & {
+    text_measurement?: never;
+};
+export type HostTextMeasurerSvgBindingOptions = CommonBindingOptions & Omit<SvgBindingFields, "environment"> & {
+    environment?: HostTextMeasurerEnvironmentOptions;
+};
 export type BindingOptions = SvgBindingOptions;
 export interface HostTextMeasureRequest {
     operation: HostTextMeasurementOperation;
@@ -499,6 +1067,24 @@ export interface AnalysisDiagramSyntaxFacts {
     expected_syntax: AnalysisExpectedSyntaxFacts[];
 }
 export type DiagramParseDisposition = "parsed" | "recovered" | "unavailable";
+export interface SourceAppearanceDeclaration {
+    readonly value: string;
+    readonly origin: {
+        readonly kind: "frontmatter";
+    } | {
+        readonly kind: "directive";
+        readonly directive_index: number;
+    };
+    readonly construct_span: Readonly<AnalysisByteSpan>;
+}
+export type SourceAppearanceSummary = {
+    readonly state: "unknown";
+} | {
+    readonly state: "known";
+    readonly theme: SourceAppearanceDeclaration | null;
+    readonly font: SourceAppearanceDeclaration | null;
+    readonly look: SourceAppearanceDeclaration | null;
+};
 export interface AnalysisDiagramFacts {
     source_id: string;
     index: number;
@@ -510,11 +1096,68 @@ export interface AnalysisDiagramFacts {
     fence_delimiter?: AnalysisFenceDelimiterFacts | null;
     parse_disposition: DiagramParseDisposition;
     syntax: AnalysisDiagramSyntaxFacts;
+    appearance: SourceAppearanceSummary;
 }
 export interface AnalysisFactsResult extends AnalysisPayloadFields {
-    version: 2;
+    version: 3;
     diagrams: AnalysisDiagramFacts[];
 }
+/**
+ * An actual render explanation with open identifiers, not a portability certificate.
+ * Rule diagnostics may describe partially applied rules; only `property`, when present, names
+ * a specific property. Source paths are RFC 6901 pointers relative to the named recipe payload
+ * (`design` or `complete_spec`). Generated defaults and Rust input may have no source paths.
+ */
+export interface ThemeDiagnostic {
+    code: string;
+    subject: string;
+    target?: string | null;
+    property?: string | null;
+    source_document?: string | null;
+    source_paths: string[];
+    generated: boolean;
+}
+/** Renderer-owned outcome, with open status/reason IDs for forward-compatible consumers. */
+export interface ThemeExecutionEvidenceV2 {
+    version: 2;
+    family_id: string;
+    theme_status: string;
+    output_mutated: boolean;
+    target_kind: string;
+    target_status: string;
+    target_reason_ids: string[];
+    font_source: string;
+    materialized_theme: ThemeName | null;
+    /** Absent means not supplied. An empty list does not establish portability. */
+    diagnostics?: ThemeDiagnostic[];
+}
+/** Unknown versions stay opaque. Never treat an unknown status or version as portable. */
+export type ThemeExecutionEvidence = ThemeExecutionEvidenceV2 | {
+    version: number;
+    [key: string]: unknown;
+};
+/** Actual family placement width, before SVG viewport scaling. */
+export interface LayoutAdaptationObservation {
+    mode: "fit-width";
+    requested_width: number;
+    actual_width: number;
+    overflowed: boolean;
+}
+/** Existing binding metadata for the exact SVG returned by the same execution. */
+export interface SvgRenderMetadata {
+    version: 1;
+    operation_id: "svg";
+    media_type: "image/svg+xml";
+    runtime_policy: string;
+    byte_length: number;
+    theme_execution_evidence: ThemeExecutionEvidence;
+    layout_adaptation?: LayoutAdaptationObservation;
+    [key: string]: unknown;
+}
+export interface SvgRenderResult {
+    svg: string;
+    metadata: SvgRenderMetadata;
+}
 /**
  * Capability plan for one SVG render request.
  *
@@ -525,23 +1168,18 @@ export interface SvgPlanResult {
     schema_version: 1;
     planned_operation_id: "svg";
     diagram_type: string;
-    presentation_profile_id: string | null;
-    presentation_aspects: SvgPlanPresentationAspect[];
     required_capability_ids: string[];
     missing_capability_ids: string[];
+    supported_layout_adaptation_ids: ("none" | "fit-width")[];
     ready: boolean;
 }
-export interface SvgPlanPresentationAspect {
-    id: string;
-    state: string;
-    required_capability_id: string | null;
-}
 export interface AvailableDiagramDetectionFacts {
     readonly status: "available";
     readonly validity: "valid" | "recoverable-invalid";
     readonly diagramType: DiagramType;
     readonly syntaxId: string;
     readonly effectiveLayoutId: string;
+    readonly appearance?: SourceAppearanceSummary;
 }
 export interface UnavailableDiagramDetectionFacts {
     readonly status: "unavailable";
@@ -549,6 +1187,7 @@ export interface UnavailableDiagramDetectionFacts {
     readonly diagramType: null;
     readonly syntaxId: null;
     readonly effectiveLayoutId: null;
+    readonly appearance?: SourceAppearanceSummary;
 }
 export type DiagramDetectionFacts = AvailableDiagramDetectionFacts | UnavailableDiagramDetectionFacts;
 export interface EditorPosition {
@@ -715,11 +1354,14 @@ export interface MermanWasmModuleBase {
     default: (input?: WasmBindgenInitEnvelope) => Promise<unknown>;
 }
 export interface MermanWasmModule extends MermanWasmModuleBase {
-    RenderSession?: WasmRenderSessionConstructor;
     EditorSession?: WasmEditorSessionConstructor;
+    PreparedSource?: WasmPreparedSourceConstructor;
+    RenderSession?: WasmRenderSessionConstructor;
     transportApiVersion: () => number;
     packageVersion: () => string;
     renderSvg: (source: string, optionsJson?: string | null) => string;
+    renderSvgResult: (source: string, optionsJson?: string | null) => SvgRenderResult;
+    renderSvgResultWithTextMeasurer?: (source: string, optionsJson: string | null | undefined, measurer: HostTextMeasurer) => SvgRenderResult;
     edgeGeometryJson: (source: string, optionsJson?: string | null) => string;
     edgeGeometryJsonWithTextMeasurer?: (source: string, optionsJson: string | null | undefined, measurer: HostTextMeasurer) => string;
     svgPlanJson: (source: string, optionsJson?: string | null) => SvgPlanResult;
@@ -749,7 +1391,10 @@ export interface MermanWasmModule extends MermanWasmModuleBase {
     asciiSupportedDiagrams: () => string[];
     asciiCapabilities: () => AsciiCapability[];
     runtimeCatalog: () => RuntimeCatalog;
-    presentationCatalog: () => PresentationCatalog;
+    themeCatalog: () => ThemeCatalog;
+    materializeTheme: (designJson: string, optionsJson?: string | null) => MaterializedThemeWireV1;
+    describeThemeSupport: (queryJson: string, optionsJson?: string | null) => ThemeCapabilityDescriptor;
+    exportThemePreset: (presetId: string, optionsJson?: string | null) => ThemeRecipeV1;
     diagramFamilyCapabilities: () => DiagramFamilyCapability[];
     lintRuleCatalog?: () => LintRuleCatalogResponse;
     supportedDiagrams: () => string[];
@@ -761,4 +1406,36 @@ export interface MermanInitOptions<Module extends MermanWasmModuleBase = MermanW
     wasm?: MermanWasmSource | Promise<MermanWasmSource>;
 }
 export type MermanInitInput<Module extends MermanWasmModuleBase = MermanWasmModule> = MermanWasmLoader<Module> | MermanInitOptions<Module>;
+/** A persistent mount keeps its last successful drawing when a newer request fails. */
+export type MountedDiagramStatus = "pending" | "rendering" | "ready" | "failed" | "destroyed";
+export interface MountDiagramOptions {
+    /** Frozen parse inputs and output defaults. Changing these options prepares a new snapshot. */
+    prepareOptions?: SvgBindingOptions & {
+        svg?: Omit<SvgOptions, "diagram_id"> & {
+            diagram_id?: never;
+        };
+    };
+    /** Fresh redraw settings. The mount owns svg.diagram_id and fit-width container_width. */
+    outputOptions?: Omit<PreparedSourceOutputOptions, "svg"> & {
+        svg?: Omit<SvgOptions, "diagram_id"> & {
+            diagram_id?: never;
+        };
+    };
+    /** Browser measurement is opt-in; a supplied callback uses the existing host provider. */
+    textMeasurement?: "deterministic" | "browser" | HostTextMeasurer;
+    onRender?: (result: SvgRenderResult, mount: MountedDiagram) => void;
+    onError?: (error: unknown, mount: MountedDiagram) => void;
+}
+export interface MountedDiagram {
+    readonly source: string;
+    readonly result: SvgRenderResult | null;
+    readonly error: unknown;
+    readonly status: MountedDiagramStatus;
+    /** Omitted options retain the current options; supplied options replace them completely. */
+    update(source: string, options?: MountDiagramOptions): void;
+    /** Refresh after external typography changes or adoption into another Document. */
+    refresh(): void;
+    /** Releases resources and leaves the last published DOM in place. Idempotent. */
+    destroy(): void;
+}
 //# sourceMappingURL=public-types.d.ts.map