@vectoriox/iox-ui 5.16.0 → 5.18.0

package/design-core/index.d.ts

@@ -8655,7 +8655,9 @@ type SeedBaseline = ReadonlyMap<string, SeedExpectation> | ((row: StoredDesignTo
  * write is never touched: no `flavor:` stamp, unless it is a `user` row (a font the author CHOSE in
  * the design) whose value is exactly what the previous design wrote — that row is the design's own
  * choice, so a new choice may replace it. `group`/`tier` ride every write; a desired row's own
- * `source` (a chosen font's `user`) wins over the pack stamp.
+ * `source` (a chosen font's `user`) wins over the pack stamp. A machine-owned row that already holds
+ * the desired value but another pack's stamp is RE-STAMPED (§10 C2 provenance: the stamp names the
+ * design that owns the row, so the next switch judges it against the right baseline).
  */
 declare function planFlavorSeed(desired: ReadonlyArray<FlavorTokenDef & {
     source?: string;
@@ -8692,8 +8694,43 @@ declare const FONT_FAMILY_TOKENS: readonly ["font-display", "font-body", "font-l
  * uploaded family named `</style><script>` would otherwise close the element.
  */
 declare function cssString(value: string): string;
-/** One `@font-face` per file, carrying its real weight and style — so bold is never synthesised. */
+/** The file extensions a studio may upload as a font, and the descriptor format each one IS (§5b). */
+declare const FONT_FILE_FORMATS: Readonly<Record<string, FontFormat>>;
+declare const FONT_FILE_EXTENSIONS: ReadonlyArray<string>;
+/** For a file input's `accept` — the same list the server validates against. */
+declare const FONT_FILE_ACCEPT: string;
+/** The CSS weights a face can be declared at, for an editor that offers them. */
+declare const FONT_WEIGHTS: ReadonlyArray<number>;
+declare const FONT_STYLES: ReadonlyArray<FontStyle>;
+/** A stored key's original file name: the folder prefix and the `-<timestamp>` upload suffix removed. */
+declare function fontFileName(key: string | null | undefined): string;
+/** The descriptor format of a font file, from its extension — null for anything we do not serve. */
+declare function fontFormatOf(fileNameOrKey: string | null | undefined): FontFormat | null;
+/** The family a file had before DS5 — its name without the extension. Legacy files with no parsed
+ *  name table keep it, so a page saved with `font-family: 'Rubik-Regular'` keeps its face (D5). */
+declare function fontFileStem(key: string | null | undefined): string;
+/** A weight as CSS can use it: 100–900, a bad value → 400. */
+declare function normalizeFontWeight(w: unknown): number;
+declare function normalizeFontStyle(style: unknown): FontStyle;
+/** CSS family names match case-insensitively; this is the one comparison key. */
+declare function fontFamilyKey(family: string | null | undefined): string;
+/**
+ * One `@font-face` per FACE (family × weight × style), carrying its real weight and style — so bold is
+ * never synthesised. Files that declare the same face (a woff2 and a ttf of one cut) share one rule
+ * whose `src` lists them best format first, which is what the two retired forks did per file stem.
+ */
 declare function buildFontFaceCss(descriptors: ReadonlyArray<FontDescriptor> | null | undefined): string;
+/** An uploaded family: every file sharing a family name (case-insensitively), with its real cuts. */
+interface FontFamilyGroup {
+    family: string;
+    /** Distinct weights, ascending. */
+    weights: number[];
+    styles: FontStyle[];
+    /** Every file of the family, lightest first. */
+    faces: FontDescriptor[];
+}
+/** Files → families (§5b "Group into families"): the Files tile, the typeface dropdown and Design ▸ Type. */
+declare function groupFontFamilies(descriptors: ReadonlyArray<FontDescriptor> | null | undefined): FontFamilyGroup[];
 /** The family names in a CSS `font-family` stack, unquoted, in order. */
 declare function parseFontFamilies(stack: string): string[];
 /** Where Google serves the stylesheets, and the origin the font FILES come from (preconnect). */
@@ -8717,6 +8754,28 @@ interface FontsForTokensOptions {
  * one bad id cannot sink the others), in role order.
  */
 declare function fontsForTokens(tokens: ReadonlyArray<DesignTokenLike> | null | undefined, opts?: FontsForTokensOptions): string[];
+type FontFamilyToken = (typeof FONT_FAMILY_TOKENS)[number];
+/** True when `stack` (a CSS `font-family` value) names `family` anywhere in it. */
+declare function stackNamesFamily(stack: string | null | undefined, family: string | null | undefined): boolean;
+/**
+ * The font tokens whose value names `family` — what the delete guard asks before an uploaded family's
+ * last file goes (§5b): deleting it would silently drop those roles to their fallback.
+ */
+declare function fontRoleReferences(tokens: ReadonlyArray<DesignTokenLike> | null | undefined, family: string | null | undefined): FontFamilyToken[];
+/**
+ * The face CSS font matching picks for `weight` from `faces` (CSS Fonts §5.2): 400 tries 500 next,
+ * 500 tries 400; lighter weights look down first, heavier ones up. So an `h1` at 600 over a family
+ * uploaded at 400 + 700 renders the real 700 cut — the one worth preloading.
+ */
+declare function matchFontWeight<T extends {
+    weight: number;
+}>(faces: ReadonlyArray<T>, weight: number): T | null;
+/**
+ * The uploaded files the SSR head preloads (§5b — no flash of the fallback face): for the display and
+ * body roles, the family each token names (its first uploaded family), the woff2 normal-style cut CSS
+ * matching would pick for that role's weights. One file per weight that renders, never the family.
+ */
+declare function fontPreloads(descriptors: ReadonlyArray<FontDescriptor> | null | undefined, tokens: ReadonlyArray<DesignTokenLike> | null | undefined): FontDescriptor[];
 
 /**
  * Which `--iox-<name>` a piece of COMPONENT CSS may reference (design-system §3b-bis: "component CSS
@@ -8735,7 +8794,9 @@ declare function unknownTokenReferences(css: string, alsoAllowed?: Iterable<stri
  * Tokens read by a LEGACY rule — any rule whose selector is scoped `:not(.iox-es)` (the pre-DS2 look
  * of a node that wears no element style, design-system §3b-bis). Such a rule must read NO token at
  * all: a token it reads repaints a pre-DS2 page the moment the org's rows are seeded or a flavor is
- * applied (D5). Returns `selector → names` for each offending rule; comments are ignored.
+ * applied (D5). Returns `selector → names` for each offending rule; comments are ignored. SCSS
+ * nesting is resolved (DS4.1): `.x:where(:not(.iox-es)) { &:hover { … } }` is the legacy rule
+ * `.x:where(:not(.iox-es)):hover`, and an at-rule (`@media`) between them does not break the chain.
  */
 declare function legacyRuleTokenReferences(css: string): Array<{
     selector: string;
@@ -8792,6 +8853,12 @@ declare function isRetiredFlavorId(id: string | null | undefined): boolean;
 declare function resolveDesignChoices(partial: Partial<DesignChoices> | null | undefined): DesignChoices;
 /** The pack's own defaults for `flavorId` — what picking a card means before anything is tuned. */
 declare function packDesignChoices(flavorId: string): DesignChoices;
+/**
+ * What picking a pack card means, given the design the studio wears: the applied pack → the applied
+ * choices; another pack → that pack's defaults, CARRYING the author's chosen fonts (§5b — a font the
+ * author chose survives a pack switch unless the author changes it). Both picker homes call this.
+ */
+declare function choicesForPack(flavorId: string, applied: DesignChoices | null | undefined): DesignChoices;
 /** A stored `settings.design` config → the resolved design. No row (or no config) → Crisp's defaults. */
 declare function readDesignConfig(config: ReadonlyArray<DesignConfigEntry> | null | undefined, hasRow?: boolean): StoredDesign;
 /** The colour mode a stored config compiles in — what the public page read hands the engine. */
@@ -8817,6 +8884,15 @@ declare function planDesignApply(existing: ReadonlyArray<StoredDesignTokenRow>,
 declare function missingDesignRows(existing: ReadonlyArray<{
     name: string;
 }>, choices: DesignChoices): DesignTokenRow[];
+/**
+ * The builder-load REPAIR (DS4.1): rows the design owns and nobody touched — stamped by the current
+ * pack, light value exactly the pack's — whose dark override differs from the pack's are rewritten.
+ * iox-cms dropped `values.dark` on every write from F0 to DS4 (`values` was an implicit relation),
+ * and a revert could leave the previous apply's dark behind; both leave a row whose light half is the
+ * design's and whose dark half is not. No author edit can produce that shape — the Tokens panel edits
+ * the light value only — so rewriting it heals existing orgs without the author doing anything.
+ */
+declare function designTokenRepairs(existing: ReadonlyArray<StoredDesignTokenRow>, choices: DesignChoices): FlavorSeedPlan['update'];
 interface SwissMigration {
     /** The design the org now wears: Crisp, carrying the stored brand seed when it is a colour. */
     choices: DesignChoices;
@@ -8831,11 +8907,33 @@ interface SwissMigration {
  *
  * - The look: `planDesignApply` from Swiss to Crisp — Swiss-stamped rows untouched since Swiss seeded
  *   them (incl. F2's `surface` / `line` / `accent`) become Crisp's; edited ones are kept.
- * - The aliases: `radius-control` / `radius-surface` / `space-control` / `space-stack` are rewritten to
- *   their alias reference ONLY while still machine-owned and untouched, so a node saved since F1 that
- *   reads `var(--iox-radius-control)` keeps resolving — now to Crisp's button radius.
+ * - The aliases (`SPEC_LEGACY_ALIASES`: `radius-control` / `radius-surface` / `space-stack`) are rewritten
+ *   to their alias reference ONLY while still machine-owned and untouched, so a node saved since F1 that
+ *   reads `var(--iox-radius-control)` keeps resolving — now to Crisp's button radius. `space-control` is
+ *   NOT an alias: it is a v2 semantic token (`button-pad` reads it), and aliasing it closed a `var()`
+ *   cycle; it migrates like any other Swiss row.
  */
 declare function planSwissMigration(existing: ReadonlyArray<StoredDesignTokenRow>, stored: StoredDesign): SwissMigration | null;
+/** What deleting an uploaded family does to the look (§5b delete guard). */
+interface FontFamilyRemoval {
+    /** The font tokens that name the family — empty means nothing references it and nothing changes. */
+    roles: FontFamilyToken[];
+    /** The design without the family: every font role it held goes back to the pack's pairing. */
+    choices: DesignChoices;
+    /** The token writes: the look's own merge, plus any OTHER row still naming the family (one typed
+     *  in the Tokens panel), rewritten to the pack's value too — a deleted face must not stay named. */
+    plan: FlavorSeedPlan;
+    /** Per role, the family it falls back to — what the guard tells the author before they confirm. */
+    fallbacks: Array<{
+        role: FontFamilyToken;
+        family: string;
+    }>;
+}
+/**
+ * Plan the removal of an uploaded family from the look: the roles naming it fall back to the pack's
+ * own font (the design's pairing), as the guard promises — "Nothing else changes".
+ */
+declare function planFontFamilyRemoval(existing: ReadonlyArray<StoredDesignTokenRow>, previous: StoredDesign, family: string): FontFamilyRemoval;
 
-export { ACCENT_TOKEN_NAMES, BUTTON_VARIANT_TO_STYLE, COLOR_SCHEMES, COLOR_SCHEME_TRAIT, COLOR_SCHEME_TYPES, ColorScheme, DEFAULT_FLAVOR_ID, DESIGN_TOKEN_GROUPS, DESIGN_TOKEN_TIERS, DESIGN_TOKEN_TYPES, DesignConfigKey, ELEMENT_STYLES, ELEMENT_STYLE_MARKER_CLASS, ELEMENT_STYLE_STATES, EMPTY_IMAGE_ATTRIBUTE, EMPTY_IMAGE_SRC, ElementStyleState, FLAVOR_SPEC_VERSION, FONT_CATALOG, FONT_FAMILY_TOKENS, GOOGLE_FONTS_CSS_ORIGIN, GOOGLE_FONTS_FILE_ORIGIN, OwnedTraitLink, PALETTE_PRESETS, REDUCED_MOTION_OVERRIDES, REDUCED_TRANSPARENCY_OVERRIDES, REVERT_WINDOW_MS, SPEC_A11Y, SPEC_AXES, SPEC_BUTTON_VARIANT_TO_STYLE, SPEC_CONTRAST, SPEC_DEFAULT_ELEMENT_STYLE, SPEC_ELEMENT_STYLES, SPEC_FIELD_CLASS_BASELINE, SPEC_FLAVORS, SPEC_FLAVOR_PACKS, SPEC_FONTS, SPEC_FONT_ROLES, SPEC_LEGACY_ALIASES, SPEC_PALETTE_PRESETS, SPEC_SCHEMES, SPEC_SPRINGS, SPEC_TIERS, SPEC_TIER_IDS, SPEC_TOKEN_TYPES, SWISS_FLAVOR, USER_TOKEN_SOURCE, WCAG_AA_TEXT, apcaLc, applyElementStyle, applyHeadingLevelRule, buildFlavorTokens, buildFontFaceCss, catalogFontId, colorSchemeClass, colorSchemeOf, compileSchemeCss, compileTokenCss, compileTokenCssBlocks, cssString, defaultDesignChoices, defaultElementStyleFor, deriveAccentTokens, deriveBrandTokens, designBaseline, designConfigEntries, designModeOf, designTokenRows, elementStyleById, elementStyleClass, elementStylesFor, emptyImageLabelSrc, emptyImagePlaceholder, emptyImageSrc, flavorPackById, flavorSourceStamp, fontsForTokens, googleFontHref, hasElementStyleMarker, isDesignTokenGroup, isDesignTokenTier, isDesignTokenType, isRetiredFlavorId, legacyRuleTokenReferences, missingDesignRows, nodeDesignClasses, oklabToRgb, ownedTraitStatus, packDesignChoices, parseFontFamilies, parseHexColor, planDesignApply, planFlavorRevert, planFlavorSeed, planSwissMigration, readDesignConfig, relativeLuminance, resolveDesignChoices, resolveTokenReferences, resolveTokenValues, revertAvailable, rgbToOklab, sameDesignChoices, specTokenNames, springToLinear, styleKeyToKebab, switchElementStyle, syncNodeDesignClasses, toHexColor, tokenReferences, tokensToDarkVarMap, tokensToVarMap, unknownTokenReferences, userFontStack, validateFlavorPack, wcagContrastRatio };
-export type { AccentBackgrounds, AccentTokenName, ApplyElementStyleResult, DensityId, DesignChoices, DesignClassSource, DesignConfigEntry, DesignMode, DesignTokenGroup, DesignTokenLike, DesignTokenRow, DesignTokenTier, DesignTokenType, ElementStyle, ElementStyleTarget, ElementStyleTraitLike, FlavorPack, FlavorPackV2, FlavorRevertPlan, FlavorRevertSnapshot, FlavorSeedPlan, FlavorSpecToken, FlavorTokenDef, FontDescriptor, FontFormat, FontPair, FontRoleToken, FontStyle, FontsForTokensOptions, LinearSpring, MotionId, OkLab, OwnedTrait, OwnedTraitStatus, PalettePreset, ResolvedMode, Rgb, SchemeId, SeedBaseline, SeedExpectation, ShapeId, StoredDesign, StoredDesignTokenRow, SwissMigration, SwitchElementStyleResult, TokenCssBlocks, TokenCssOptions };
+export { ACCENT_TOKEN_NAMES, BUTTON_VARIANT_TO_STYLE, COLOR_SCHEMES, COLOR_SCHEME_TRAIT, COLOR_SCHEME_TYPES, ColorScheme, DEFAULT_FLAVOR_ID, DESIGN_TOKEN_GROUPS, DESIGN_TOKEN_TIERS, DESIGN_TOKEN_TYPES, DesignConfigKey, ELEMENT_STYLES, ELEMENT_STYLE_MARKER_CLASS, ELEMENT_STYLE_STATES, EMPTY_IMAGE_ATTRIBUTE, EMPTY_IMAGE_SRC, ElementStyleState, FLAVOR_SPEC_VERSION, FONT_CATALOG, FONT_FAMILY_TOKENS, FONT_FILE_ACCEPT, FONT_FILE_EXTENSIONS, FONT_FILE_FORMATS, FONT_STYLES, FONT_WEIGHTS, GOOGLE_FONTS_CSS_ORIGIN, GOOGLE_FONTS_FILE_ORIGIN, OwnedTraitLink, PALETTE_PRESETS, REDUCED_MOTION_OVERRIDES, REDUCED_TRANSPARENCY_OVERRIDES, REVERT_WINDOW_MS, SPEC_A11Y, SPEC_AXES, SPEC_BUTTON_VARIANT_TO_STYLE, SPEC_CONTRAST, SPEC_DEFAULT_ELEMENT_STYLE, SPEC_ELEMENT_STYLES, SPEC_FIELD_CLASS_BASELINE, SPEC_FLAVORS, SPEC_FLAVOR_PACKS, SPEC_FONTS, SPEC_FONT_ROLES, SPEC_LEGACY_ALIASES, SPEC_PALETTE_PRESETS, SPEC_SCHEMES, SPEC_SPRINGS, SPEC_TIERS, SPEC_TIER_IDS, SPEC_TOKEN_TYPES, SWISS_FLAVOR, USER_TOKEN_SOURCE, WCAG_AA_TEXT, apcaLc, applyElementStyle, applyHeadingLevelRule, buildFlavorTokens, buildFontFaceCss, catalogFontId, choicesForPack, colorSchemeClass, colorSchemeOf, compileSchemeCss, compileTokenCss, compileTokenCssBlocks, cssString, defaultDesignChoices, defaultElementStyleFor, deriveAccentTokens, deriveBrandTokens, designBaseline, designConfigEntries, designModeOf, designTokenRepairs, designTokenRows, elementStyleById, elementStyleClass, elementStylesFor, emptyImageLabelSrc, emptyImagePlaceholder, emptyImageSrc, flavorPackById, flavorSourceStamp, fontFamilyKey, fontFileName, fontFileStem, fontFormatOf, fontPreloads, fontRoleReferences, fontsForTokens, googleFontHref, groupFontFamilies, hasElementStyleMarker, isDesignTokenGroup, isDesignTokenTier, isDesignTokenType, isRetiredFlavorId, legacyRuleTokenReferences, matchFontWeight, missingDesignRows, nodeDesignClasses, normalizeFontStyle, normalizeFontWeight, oklabToRgb, ownedTraitStatus, packDesignChoices, parseFontFamilies, parseHexColor, planDesignApply, planFlavorRevert, planFlavorSeed, planFontFamilyRemoval, planSwissMigration, readDesignConfig, relativeLuminance, resolveDesignChoices, resolveTokenReferences, resolveTokenValues, revertAvailable, rgbToOklab, sameDesignChoices, specTokenNames, springToLinear, stackNamesFamily, styleKeyToKebab, switchElementStyle, syncNodeDesignClasses, toHexColor, tokenReferences, tokensToDarkVarMap, tokensToVarMap, unknownTokenReferences, userFontStack, validateFlavorPack, wcagContrastRatio };
+export type { AccentBackgrounds, AccentTokenName, ApplyElementStyleResult, DensityId, DesignChoices, DesignClassSource, DesignConfigEntry, DesignMode, DesignTokenGroup, DesignTokenLike, DesignTokenRow, DesignTokenTier, DesignTokenType, ElementStyle, ElementStyleTarget, ElementStyleTraitLike, FlavorPack, FlavorPackV2, FlavorRevertPlan, FlavorRevertSnapshot, FlavorSeedPlan, FlavorSpecToken, FlavorTokenDef, FontDescriptor, FontFamilyGroup, FontFamilyRemoval, FontFamilyToken, FontFormat, FontPair, FontRoleToken, FontStyle, FontsForTokensOptions, LinearSpring, MotionId, OkLab, OwnedTrait, OwnedTraitStatus, PalettePreset, ResolvedMode, Rgb, SchemeId, SeedBaseline, SeedExpectation, ShapeId, StoredDesign, StoredDesignTokenRow, SwissMigration, SwitchElementStyleResult, TokenCssBlocks, TokenCssOptions };

package/fesm2022/vectoriox-iox-ui-design-core.mjs

@@ -9533,23 +9533,68 @@ function unknownTokenReferences(css, alsoAllowed = []) {
     return tokenReferences(css).filter(name => !spec.has(name) && !extra.has(name));
 }
 const LEGACY_SCOPE = /:not\(\s*\.iox-es\s*\)/;
-const RULE = /([^{}]+)\{([^{}]*)\}/g;
+/** Comments out: block comments, and SCSS `//` line comments (never the `//` of a `url(https://…)`). */
+const stripComments = (css) => String(css ?? '')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:\\])\/\/[^\n]*/g, '$1');
+/** A nested SCSS selector against its parent's: `&` is the parent; no `&` means a descendant. */
+function resolveNested(parent, selector) {
+    if (!parent)
+        return selector;
+    return selector.split(',').map(part => {
+        const own = part.trim();
+        return own.includes('&') ? own.replace(/&/g, parent) : `${parent} ${own}`;
+    }).join(', ');
+}
 /**
  * Tokens read by a LEGACY rule — any rule whose selector is scoped `:not(.iox-es)` (the pre-DS2 look
  * of a node that wears no element style, design-system §3b-bis). Such a rule must read NO token at
  * all: a token it reads repaints a pre-DS2 page the moment the org's rows are seeded or a flavor is
- * applied (D5). Returns `selector → names` for each offending rule; comments are ignored.
+ * applied (D5). Returns `selector → names` for each offending rule; comments are ignored. SCSS
+ * nesting is resolved (DS4.1): `.x:where(:not(.iox-es)) { &:hover { … } }` is the legacy rule
+ * `.x:where(:not(.iox-es)):hover`, and an at-rule (`@media`) between them does not break the chain.
  */
 function legacyRuleTokenReferences(css) {
-    const text = String(css ?? '').replace(/\/\*[\s\S]*?\*\//g, '');
+    const text = stripComments(css);
     const out = [];
-    for (const m of text.matchAll(RULE)) {
-        const selector = m[1].trim().replace(/\s+/g, ' ');
-        if (!LEGACY_SCOPE.test(selector))
-            continue;
-        const tokens = tokenReferences(m[2]);
+    const stack = [];
+    const report = (frame) => {
+        if (!LEGACY_SCOPE.test(frame.selector))
+            return;
+        const tokens = tokenReferences(frame.body);
         if (tokens.length)
-            out.push({ selector, tokens });
+            out.push({ selector: frame.selector, tokens });
+    };
+    let buffer = '';
+    for (const ch of text) {
+        if (ch === '{') {
+            const head = buffer.trim().replace(/\s+/g, ' ');
+            buffer = '';
+            // Declarations before a nested block belong to the parent (`color: x; &:hover {`).
+            const cut = head.lastIndexOf(';');
+            const prelude = cut >= 0 ? head.slice(cut + 1).trim() : head;
+            const parent = stack[stack.length - 1];
+            if (parent && cut >= 0)
+                parent.body += head.slice(0, cut + 1);
+            const inherited = parent?.selector ?? '';
+            const selector = prelude.startsWith('@') ? inherited : resolveNested(inherited, prelude);
+            stack.push({ selector, body: '' });
+        }
+        else if (ch === '}') {
+            const frame = stack.pop();
+            if (frame) {
+                frame.body += buffer;
+                report(frame);
+            }
+            buffer = '';
+        }
+        else if (ch === ';' && stack.length) {
+            stack[stack.length - 1].body += buffer + ch;
+            buffer = '';
+        }
+        else {
+            buffer += ch;
+        }
     }
     return out;
 }
@@ -10416,28 +10461,107 @@ function cssString(value) {
         .replace(/>/g, '\\3e ');
     return `'${body}'`;
 }
-const clampWeight = (w) => {
+/** The file extensions a studio may upload as a font, and the descriptor format each one IS (§5b). */
+const FONT_FILE_FORMATS = Object.freeze({
+    woff2: 'woff2', woff: 'woff', ttf: 'truetype', otf: 'opentype',
+});
+const FONT_FILE_EXTENSIONS = Object.keys(FONT_FILE_FORMATS);
+/** For a file input's `accept` — the same list the server validates against. */
+const FONT_FILE_ACCEPT = FONT_FILE_EXTENSIONS.map(ext => `.${ext}`).join(',');
+/** The CSS weights a face can be declared at, for an editor that offers them. */
+const FONT_WEIGHTS = [100, 200, 300, 400, 500, 600, 700, 800, 900];
+const FONT_STYLES = ['normal', 'italic'];
+/** When two files declare the same face, the browser should try the smallest, best-supported first. */
+const FORMAT_PREFERENCE = ['woff2', 'woff', 'opentype', 'truetype'];
+const UPLOAD_SUFFIX = /-\d+$/;
+/** A stored key's original file name: the folder prefix and the `-<timestamp>` upload suffix removed. */
+function fontFileName(key) {
+    const name = String(key ?? '');
+    return name.substring(name.lastIndexOf('/') + 1).replace(UPLOAD_SUFFIX, '');
+}
+/** The descriptor format of a font file, from its extension — null for anything we do not serve. */
+function fontFormatOf(fileNameOrKey) {
+    const ext = /\.([a-z0-9]+)$/i.exec(fontFileName(fileNameOrKey))?.[1]?.toLowerCase() ?? '';
+    return FONT_FILE_FORMATS[ext] ?? null;
+}
+/** The family a file had before DS5 — its name without the extension. Legacy files with no parsed
+ *  name table keep it, so a page saved with `font-family: 'Rubik-Regular'` keeps its face (D5). */
+function fontFileStem(key) {
+    return fontFileName(key).replace(/\.[^.]+$/, '');
+}
+/** A weight as CSS can use it: 100–900, a bad value → 400. */
+function normalizeFontWeight(w) {
     const n = Math.round(Number(w));
     return Number.isFinite(n) && n > 0 ? Math.min(MAX_WEIGHT, Math.max(MIN_WEIGHT, n)) : DEFAULT_WEIGHT;
+}
+function normalizeFontStyle(style) {
+    return style === 'italic' ? 'italic' : 'normal';
+}
+/** CSS family names match case-insensitively; this is the one comparison key. */
+function fontFamilyKey(family) {
+    return String(family ?? '').trim().toLowerCase();
+}
+const usableDescriptor = (d) => !!d && typeof d.family === 'string' && d.family.trim() !== '' && typeof d.url === 'string' && d.url !== '';
+const preference = (format) => {
+    const i = FORMAT_PREFERENCE.indexOf(format);
+    return i < 0 ? FORMAT_PREFERENCE.length : i;
 };
-/** One `@font-face` per file, carrying its real weight and style — so bold is never synthesised. */
+/**
+ * One `@font-face` per FACE (family × weight × style), carrying its real weight and style — so bold is
+ * never synthesised. Files that declare the same face (a woff2 and a ttf of one cut) share one rule
+ * whose `src` lists them best format first, which is what the two retired forks did per file stem.
+ */
 function buildFontFaceCss(descriptors) {
-    return (descriptors ?? [])
-        .filter(d => !!d && typeof d.family === 'string' && d.family.trim() !== '' && typeof d.url === 'string' && d.url !== '')
-        .map(d => {
-        const format = FONT_FORMATS.includes(d.format) ? ` format(${cssString(d.format)})` : '';
+    const faces = new Map();
+    for (const d of (descriptors ?? []).filter(usableDescriptor)) {
+        const family = d.family.trim();
+        const weight = normalizeFontWeight(d.weight);
+        const style = normalizeFontStyle(d.style);
+        const id = `${fontFamilyKey(family)}|${weight}|${style}`;
+        const face = faces.get(id) ?? { family, weight, style, files: [] };
+        face.files.push(d);
+        faces.set(id, face);
+    }
+    return [...faces.values()]
+        .map(face => {
+        const src = [...face.files]
+            .sort((a, b) => preference(a.format) - preference(b.format))
+            .map(d => `url(${cssString(d.url)})${FONT_FORMATS.includes(d.format) ? ` format(${cssString(d.format)})` : ''}`)
+            .join(', ');
         return [
             '@font-face {',
-            `  font-family: ${cssString(d.family.trim())};`,
-            `  src: url(${cssString(d.url)})${format};`,
-            `  font-weight: ${clampWeight(d.weight)};`,
-            `  font-style: ${d.style === 'italic' ? 'italic' : 'normal'};`,
+            `  font-family: ${cssString(face.family)};`,
+            `  src: ${src};`,
+            `  font-weight: ${face.weight};`,
+            `  font-style: ${face.style};`,
             '  font-display: swap;',
             '}',
         ].join('\n');
     })
         .join('\n');
 }
+/** Files → families (§5b "Group into families"): the Files tile, the typeface dropdown and Design ▸ Type. */
+function groupFontFamilies(descriptors) {
+    const groups = new Map();
+    for (const d of (descriptors ?? []).filter(usableDescriptor)) {
+        const key = fontFamilyKey(d.family);
+        const group = groups.get(key) ?? { family: d.family.trim(), weights: [], styles: [], faces: [] };
+        group.faces.push(d);
+        groups.set(key, group);
+    }
+    return [...groups.values()]
+        .map(g => {
+        const faces = [...g.faces].sort((a, b) => normalizeFontWeight(a.weight) - normalizeFontWeight(b.weight)
+            || normalizeFontStyle(a.style).localeCompare(normalizeFontStyle(b.style)));
+        return {
+            family: g.family,
+            weights: [...new Set(faces.map(f => normalizeFontWeight(f.weight)))].sort((a, b) => a - b),
+            styles: FONT_STYLES.filter(s => faces.some(f => normalizeFontStyle(f.style) === s)),
+            faces,
+        };
+    })
+        .sort((a, b) => a.family.localeCompare(b.family));
+}
 /** The family names in a CSS `font-family` stack, unquoted, in order. */
 function parseFontFamilies(stack) {
     return String(stack ?? '')
@@ -10484,6 +10608,70 @@ function fontsForTokens(tokens, opts = {}) {
     }
     return ids;
 }
+/** True when `stack` (a CSS `font-family` value) names `family` anywhere in it. */
+function stackNamesFamily(stack, family) {
+    const key = fontFamilyKey(family);
+    return key !== '' && parseFontFamilies(stack ?? '').some(f => fontFamilyKey(f) === key);
+}
+/**
+ * The font tokens whose value names `family` — what the delete guard asks before an uploaded family's
+ * last file goes (§5b): deleting it would silently drop those roles to their fallback.
+ */
+function fontRoleReferences(tokens, family) {
+    const rows = (tokens ?? []).filter(t => !!t && typeof t.name === 'string');
+    return FONT_FAMILY_TOKENS.filter(role => rows.some(t => t.name === role && stackNamesFamily(t.value, family)));
+}
+/**
+ * The face CSS font matching picks for `weight` from `faces` (CSS Fonts §5.2): 400 tries 500 next,
+ * 500 tries 400; lighter weights look down first, heavier ones up. So an `h1` at 600 over a family
+ * uploaded at 400 + 700 renders the real 700 cut — the one worth preloading.
+ */
+function matchFontWeight(faces, weight) {
+    if (!faces?.length)
+        return null;
+    const want = normalizeFontWeight(weight);
+    const exact = faces.find(f => normalizeFontWeight(f.weight) === want);
+    if (exact)
+        return exact;
+    const w = (f) => normalizeFontWeight(f.weight);
+    const below = (max) => [...faces].filter(f => w(f) < max).sort((a, b) => w(b) - w(a))[0] ?? null;
+    const above = (min) => [...faces].filter(f => w(f) > min).sort((a, b) => w(a) - w(b))[0] ?? null;
+    if (want >= 400 && want <= 500) {
+        const within = [...faces].filter(f => w(f) > want && w(f) <= 500).sort((a, b) => w(a) - w(b))[0];
+        return within ?? below(want) ?? above(500);
+    }
+    return want < 400 ? (below(want) ?? above(want)) : (above(want) ?? below(want));
+}
+/** The roles a preload serves, and the weight tokens whose cuts render above the fold. */
+const PRELOAD_ROLES = [
+    { role: 'font-display', weights: ['weight-display', 'weight-heading'], fallback: 700 },
+    { role: 'font-body', weights: ['weight-body', 'weight-strong'], fallback: DEFAULT_WEIGHT },
+];
+const PRELOAD_FORMAT = 'woff2';
+/**
+ * The uploaded files the SSR head preloads (§5b — no flash of the fallback face): for the display and
+ * body roles, the family each token names (its first uploaded family), the woff2 normal-style cut CSS
+ * matching would pick for that role's weights. One file per weight that renders, never the family.
+ */
+function fontPreloads(descriptors, tokens) {
+    const families = groupFontFamilies(descriptors);
+    if (!families.length)
+        return [];
+    const resolved = resolveTokenValues(tokens);
+    const out = new Map();
+    for (const { role, weights, fallback } of PRELOAD_ROLES) {
+        const named = parseFontFamilies(resolved[role] ?? '').map(fontFamilyKey);
+        const family = named.map(key => families.find(f => fontFamilyKey(f.family) === key)).find(Boolean);
+        const faces = family?.faces.filter(f => f.format === PRELOAD_FORMAT && normalizeFontStyle(f.style) === 'normal') ?? [];
+        for (const token of weights) {
+            const weight = Number.parseInt(resolved[token] ?? '', 10);
+            const face = matchFontWeight(faces, Number.isFinite(weight) ? weight : fallback);
+            if (face)
+                out.set(face.url, face);
+        }
+    }
+    return [...out.values()];
+}
 
 /**
  * A flavor's COMPLETE token set for a studio's choices (design-system plan §3a/§3e). A flavor IS
@@ -10606,14 +10794,16 @@ function planFlavorRevert(current, snapshot) {
         snapNames.add(snap.name);
         const live = byName.get(snap.name);
         if (!live) {
-            plan.create.push({ name: snap.name, type: snap.type, value: snap.value, values: snap.values, source: snap.source, ...classification(snap) });
+            plan.create.push({ name: snap.name, type: snap.type, value: snap.value, ...(snap.values?.dark ? { values: snap.values } : {}), source: snap.source, ...classification(snap) });
             continue;
         }
         const differs = live.value !== snap.value
             || (live.values?.dark ?? null) !== (snap.values?.dark ?? null)
             || (live.source ?? null) !== (snap.source ?? null);
+        // `values` is ALWAYS sent: an absent key is dropped by JSON and a `$set` then keeps the
+        // apply's dark override — a snapshot row with no dark must clear it, so it sends `{}`.
         if (differs && live._id) {
-            plan.update.push({ id: live._id, data: { value: snap.value, values: snap.values, source: snap.source } });
+            plan.update.push({ id: live._id, data: { value: snap.value, values: snap.values ?? {}, source: snap.source } });
         }
     }
     for (const row of current ?? []) {
@@ -10632,7 +10822,9 @@ const sameValue = (row, e) => row.value === e.value && (row.values?.dark ?? '')
  * write is never touched: no `flavor:` stamp, unless it is a `user` row (a font the author CHOSE in
  * the design) whose value is exactly what the previous design wrote — that row is the design's own
  * choice, so a new choice may replace it. `group`/`tier` ride every write; a desired row's own
- * `source` (a chosen font's `user`) wins over the pack stamp.
+ * `source` (a chosen font's `user`) wins over the pack stamp. A machine-owned row that already holds
+ * the desired value but another pack's stamp is RE-STAMPED (§10 C2 provenance: the stamp names the
+ * design that owns the row, so the next switch judges it against the right baseline).
  */
 function planFlavorSeed(desired, existing, stamp, baseline) {
     const byName = new Map((existing ?? []).map(r => [r.name, r]));
@@ -10662,8 +10854,6 @@ function planFlavorSeed(desired, existing, stamp, baseline) {
         const sameAsDesired = row.value === def.value && (row.values?.dark ?? '') === (def.values?.dark ?? '');
         if (sameAsDesired && (row.source ?? '') === source)
             continue; // already exactly this
-        if (sameAsDesired && isSeeded(row) && source !== USER_TOKEN_SOURCE)
-            continue; // same value, another pack's stamp — nothing to write
         const untouched = !!old && sameValue(row, old);
         if ((untouched || sameAsDesired) && row._id) {
             plan.update.push({ id: row._id, data: { value: def.value, values: def.values ?? {}, source, ...classification(def) } });
@@ -10825,6 +11015,17 @@ function resolveDesignChoices(partial) {
 function packDesignChoices(flavorId) {
     return resolveDesignChoices({ flavorId });
 }
+/**
+ * What picking a pack card means, given the design the studio wears: the applied pack → the applied
+ * choices; another pack → that pack's defaults, CARRYING the author's chosen fonts (§5b — a font the
+ * author chose survives a pack switch unless the author changes it). Both picker homes call this.
+ */
+function choicesForPack(flavorId, applied) {
+    const pack = flavorPackById(flavorId) ?? defaultPack();
+    if (applied && resolveDesignChoices(applied).flavorId === pack.id)
+        return resolveDesignChoices(applied);
+    return resolveDesignChoices({ flavorId: pack.id, fonts: applied?.fonts });
+}
 /** A stored `settings.design` config → the resolved design. No row (or no config) → Crisp's defaults. */
 function readDesignConfig(config, hasRow = !!config) {
     const map = configMap(config);
@@ -10934,6 +11135,31 @@ function missingDesignRows(existing, choices) {
     const have = new Set((existing ?? []).map(r => r.name));
     return designTokenRows(choices).filter(r => !have.has(r.name));
 }
+/**
+ * The builder-load REPAIR (DS4.1): rows the design owns and nobody touched — stamped by the current
+ * pack, light value exactly the pack's — whose dark override differs from the pack's are rewritten.
+ * iox-cms dropped `values.dark` on every write from F0 to DS4 (`values` was an implicit relation),
+ * and a revert could leave the previous apply's dark behind; both leave a row whose light half is the
+ * design's and whose dark half is not. No author edit can produce that shape — the Tokens panel edits
+ * the light value only — so rewriting it heals existing orgs without the author doing anything.
+ */
+function designTokenRepairs(existing, choices) {
+    const pack = flavorPackById(choices.flavorId);
+    if (!pack)
+        return [];
+    const stamp = flavorSourceStamp(pack.id);
+    const desired = new Map(designTokenRows(choices).map(r => [r.name, r]));
+    const out = [];
+    for (const row of existing ?? []) {
+        const want = desired.get(row.name);
+        if (!want || !row._id || row.source !== stamp || want.source !== stamp || row.value !== want.value)
+            continue;
+        if ((row.values?.dark ?? '') === (want.values?.dark ?? ''))
+            continue;
+        out.push({ id: row._id, data: { value: want.value, values: want.values ?? {}, source: stamp, ...(want.group ? { group: want.group } : {}), ...(want.tier ? { tier: want.tier } : {}) } });
+    }
+    return out;
+}
 const LEGACY_ALIASES = SPEC_LEGACY_ALIASES;
 /**
  * Swiss → Crisp (spec `legacyAliases`; D1). Needed when the design row says a retired flavor, or when
@@ -10943,9 +11169,11 @@ const LEGACY_ALIASES = SPEC_LEGACY_ALIASES;
  *
  * - The look: `planDesignApply` from Swiss to Crisp — Swiss-stamped rows untouched since Swiss seeded
  *   them (incl. F2's `surface` / `line` / `accent`) become Crisp's; edited ones are kept.
- * - The aliases: `radius-control` / `radius-surface` / `space-control` / `space-stack` are rewritten to
- *   their alias reference ONLY while still machine-owned and untouched, so a node saved since F1 that
- *   reads `var(--iox-radius-control)` keeps resolving — now to Crisp's button radius.
+ * - The aliases (`SPEC_LEGACY_ALIASES`: `radius-control` / `radius-surface` / `space-stack`) are rewritten
+ *   to their alias reference ONLY while still machine-owned and untouched, so a node saved since F1 that
+ *   reads `var(--iox-radius-control)` keeps resolving — now to Crisp's button radius. `space-control` is
+ *   NOT an alias: it is a v2 semantic token (`button-pad` reads it), and aliasing it closed a `var()`
+ *   cycle; it migrates like any other Swiss row.
  */
 function planSwissMigration(existing, stored) {
     const swissAliasRows = (existing ?? []).filter(r => r.name in LEGACY_ALIASES && SEED_STAMP.exec(r.source ?? '')?.[1] === SWISS_FLAVOR.id);
@@ -10972,6 +11200,34 @@ function planSwissMigration(existing, stored) {
     }
     return { choices, plan };
 }
+/**
+ * Plan the removal of an uploaded family from the look: the roles naming it fall back to the pack's
+ * own font (the design's pairing), as the guard promises — "Nothing else changes".
+ */
+function planFontFamilyRemoval(existing, previous, family) {
+    const roles = fontRoleReferences(existing, family);
+    const fonts = Object.fromEntries(Object.entries(previous.choices.fonts ?? {})
+        .filter(([, chosen]) => fontFamilyKey(chosen) !== fontFamilyKey(family)));
+    const choices = { ...previous.choices };
+    if (Object.keys(fonts).length)
+        choices.fonts = fonts;
+    else
+        delete choices.fonts;
+    if (!roles.length)
+        return { roles, choices: previous.choices, plan: { create: [], update: [], kept: [] }, fallbacks: [] };
+    const plan = planDesignApply(existing, previous, choices);
+    const desired = new Map(designTokenRows(choices).map(r => [r.name, r]));
+    const planned = new Set(plan.update.map(u => u.id));
+    for (const row of existing ?? []) {
+        const want = desired.get(row.name);
+        if (!row._id || !want || planned.has(row._id) || !roles.includes(row.name))
+            continue;
+        plan.update.push({ id: row._id, data: { value: want.value, values: want.values ?? {}, source: want.source } });
+        plan.kept = plan.kept.filter(name => name !== row.name);
+    }
+    const fallbacks = roles.map(role => ({ role, family: parseFontFamilies(desired.get(role)?.value ?? '')[0] ?? '' }));
+    return { roles, choices, plan, fallbacks };
+}
 
 /**
  * @vectoriox/iox-ui/design-core — the shared, FRAMEWORK-FREE core of the design system
@@ -10988,5 +11244,5 @@ function planSwissMigration(existing, stored) {
  * Generated bundle index. Do not edit.
  */
 
-export { ACCENT_TOKEN_NAMES, BUTTON_VARIANT_TO_STYLE, COLOR_SCHEMES, COLOR_SCHEME_TRAIT, COLOR_SCHEME_TYPES, ColorScheme, DEFAULT_FLAVOR_ID, DESIGN_TOKEN_GROUPS, DESIGN_TOKEN_TIERS, DESIGN_TOKEN_TYPES, DesignConfigKey, ELEMENT_STYLES, ELEMENT_STYLE_MARKER_CLASS, ELEMENT_STYLE_STATES, EMPTY_IMAGE_ATTRIBUTE, EMPTY_IMAGE_SRC, ElementStyleState, FLAVOR_SPEC_VERSION, FONT_CATALOG, FONT_FAMILY_TOKENS, GOOGLE_FONTS_CSS_ORIGIN, GOOGLE_FONTS_FILE_ORIGIN, OwnedTraitLink, PALETTE_PRESETS, REDUCED_MOTION_OVERRIDES, REDUCED_TRANSPARENCY_OVERRIDES, REVERT_WINDOW_MS, SPEC_A11Y, SPEC_AXES, SPEC_BUTTON_VARIANT_TO_STYLE, SPEC_CONTRAST, SPEC_DEFAULT_ELEMENT_STYLE, SPEC_ELEMENT_STYLES, SPEC_FIELD_CLASS_BASELINE, SPEC_FLAVORS, SPEC_FLAVOR_PACKS, SPEC_FONTS, SPEC_FONT_ROLES, SPEC_LEGACY_ALIASES, SPEC_PALETTE_PRESETS, SPEC_SCHEMES, SPEC_SPRINGS, SPEC_TIERS, SPEC_TIER_IDS, SPEC_TOKEN_TYPES, SWISS_FLAVOR, USER_TOKEN_SOURCE, WCAG_AA_TEXT, apcaLc, applyElementStyle, applyHeadingLevelRule, buildFlavorTokens, buildFontFaceCss, catalogFontId, colorSchemeClass, colorSchemeOf, compileSchemeCss, compileTokenCss, compileTokenCssBlocks, cssString, defaultDesignChoices, defaultElementStyleFor, deriveAccentTokens, deriveBrandTokens, designBaseline, designConfigEntries, designModeOf, designTokenRows, elementStyleById, elementStyleClass, elementStylesFor, emptyImageLabelSrc, emptyImagePlaceholder, emptyImageSrc, flavorPackById, flavorSourceStamp, fontsForTokens, googleFontHref, hasElementStyleMarker, isDesignTokenGroup, isDesignTokenTier, isDesignTokenType, isRetiredFlavorId, legacyRuleTokenReferences, missingDesignRows, nodeDesignClasses, oklabToRgb, ownedTraitStatus, packDesignChoices, parseFontFamilies, parseHexColor, planDesignApply, planFlavorRevert, planFlavorSeed, planSwissMigration, readDesignConfig, relativeLuminance, resolveDesignChoices, resolveTokenReferences, resolveTokenValues, revertAvailable, rgbToOklab, sameDesignChoices, specTokenNames, springToLinear, styleKeyToKebab, switchElementStyle, syncNodeDesignClasses, toHexColor, tokenReferences, tokensToDarkVarMap, tokensToVarMap, unknownTokenReferences, userFontStack, validateFlavorPack, wcagContrastRatio };
+export { ACCENT_TOKEN_NAMES, BUTTON_VARIANT_TO_STYLE, COLOR_SCHEMES, COLOR_SCHEME_TRAIT, COLOR_SCHEME_TYPES, ColorScheme, DEFAULT_FLAVOR_ID, DESIGN_TOKEN_GROUPS, DESIGN_TOKEN_TIERS, DESIGN_TOKEN_TYPES, DesignConfigKey, ELEMENT_STYLES, ELEMENT_STYLE_MARKER_CLASS, ELEMENT_STYLE_STATES, EMPTY_IMAGE_ATTRIBUTE, EMPTY_IMAGE_SRC, ElementStyleState, FLAVOR_SPEC_VERSION, FONT_CATALOG, FONT_FAMILY_TOKENS, FONT_FILE_ACCEPT, FONT_FILE_EXTENSIONS, FONT_FILE_FORMATS, FONT_STYLES, FONT_WEIGHTS, GOOGLE_FONTS_CSS_ORIGIN, GOOGLE_FONTS_FILE_ORIGIN, OwnedTraitLink, PALETTE_PRESETS, REDUCED_MOTION_OVERRIDES, REDUCED_TRANSPARENCY_OVERRIDES, REVERT_WINDOW_MS, SPEC_A11Y, SPEC_AXES, SPEC_BUTTON_VARIANT_TO_STYLE, SPEC_CONTRAST, SPEC_DEFAULT_ELEMENT_STYLE, SPEC_ELEMENT_STYLES, SPEC_FIELD_CLASS_BASELINE, SPEC_FLAVORS, SPEC_FLAVOR_PACKS, SPEC_FONTS, SPEC_FONT_ROLES, SPEC_LEGACY_ALIASES, SPEC_PALETTE_PRESETS, SPEC_SCHEMES, SPEC_SPRINGS, SPEC_TIERS, SPEC_TIER_IDS, SPEC_TOKEN_TYPES, SWISS_FLAVOR, USER_TOKEN_SOURCE, WCAG_AA_TEXT, apcaLc, applyElementStyle, applyHeadingLevelRule, buildFlavorTokens, buildFontFaceCss, catalogFontId, choicesForPack, colorSchemeClass, colorSchemeOf, compileSchemeCss, compileTokenCss, compileTokenCssBlocks, cssString, defaultDesignChoices, defaultElementStyleFor, deriveAccentTokens, deriveBrandTokens, designBaseline, designConfigEntries, designModeOf, designTokenRepairs, designTokenRows, elementStyleById, elementStyleClass, elementStylesFor, emptyImageLabelSrc, emptyImagePlaceholder, emptyImageSrc, flavorPackById, flavorSourceStamp, fontFamilyKey, fontFileName, fontFileStem, fontFormatOf, fontPreloads, fontRoleReferences, fontsForTokens, googleFontHref, groupFontFamilies, hasElementStyleMarker, isDesignTokenGroup, isDesignTokenTier, isDesignTokenType, isRetiredFlavorId, legacyRuleTokenReferences, matchFontWeight, missingDesignRows, nodeDesignClasses, normalizeFontStyle, normalizeFontWeight, oklabToRgb, ownedTraitStatus, packDesignChoices, parseFontFamilies, parseHexColor, planDesignApply, planFlavorRevert, planFlavorSeed, planFontFamilyRemoval, planSwissMigration, readDesignConfig, relativeLuminance, resolveDesignChoices, resolveTokenReferences, resolveTokenValues, revertAvailable, rgbToOklab, sameDesignChoices, specTokenNames, springToLinear, stackNamesFamily, styleKeyToKebab, switchElementStyle, syncNodeDesignClasses, toHexColor, tokenReferences, tokensToDarkVarMap, tokensToVarMap, unknownTokenReferences, userFontStack, validateFlavorPack, wcagContrastRatio };
 //# sourceMappingURL=vectoriox-iox-ui-design-core.mjs.map