@vectoriox/iox-ui 5.13.1 → 5.15.0

package/index.d.ts

@@ -183,6 +183,12 @@ declare class BuilderImageComponent {
     src: string;
     alt: string;
     nodeId: string;
+    /**
+     * What a MARKED image shows while it has no source (design-system DS3) — set by each renderer from
+     * the shared `emptyImageSrc` (`@vectoriox/iox-ui/design-core`): the "Add image" label on the canvas,
+     * the blank on the live site, `null` for an unmarked image, which therefore renders as before.
+     */
+    emptySrc: string | null;
     /**
      * The `src` attribute value, or `null` to OMIT the attribute entirely when there is no image.
      *
@@ -194,8 +200,10 @@ declare class BuilderImageComponent {
      * filled when the visitor interacts (see element-context-state-plan.md).
      */
     get srcAttr(): string | null;
+    /** `data-iox-empty` while the placeholder stands in — the hook the shared fill rule keys on. */
+    get emptyAttr(): '' | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<BuilderImageComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<BuilderImageComponent, "img[iox-img]", never, { "src": { "alias": "src"; "required": false; }; "alt": { "alias": "alt"; "required": false; }; "nodeId": { "alias": "nodeId"; "required": false; }; }, {}, never, never, false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<BuilderImageComponent, "img[iox-img]", never, { "src": { "alias": "src"; "required": false; }; "alt": { "alias": "alt"; "required": false; }; "nodeId": { "alias": "nodeId"; "required": false; }; "emptySrc": { "alias": "emptySrc"; "required": false; }; }, {}, never, never, false, never>;
 }
 
 /** Directive-host spacer: the `<div>` IS the host — no wrapper. All styles on `.iox-node`. */
@@ -1634,6 +1642,19 @@ interface PageStyleSettings {
      */
     maxWidth: string;
 }
+interface PageStyleOptions {
+    /**
+     * `pageSettings.designSystem` (design-system DS3). A page created with the design system — or
+     * adopted into it (DS7) — falls back to the org's tokens for whatever it does not set itself:
+     * `background: var(--iox-page-bg)` (a PAINT — Glass and Midnight are gradients, so the shorthand),
+     * `color: var(--iox-text)`, `font-family: var(--iox-font-body)`. A page without the flag (every
+     * page saved before DS3) compiles exactly as before, so a seeded org never puts a new ground under
+     * legacy text — the page follows the same opt-in rule as the element-style marker (§3b-bis).
+     */
+    designSystem?: boolean;
+}
+/** The token fallbacks of a design-system page (spec tokens only). */
+declare const PAGE_TOKEN_FALLBACKS: Readonly<Record<string, string>>;
 /**
  * Compile page style settings into CSS declarations.
  *
@@ -1643,7 +1664,7 @@ interface PageStyleSettings {
  * `backgroundType` selects which background field wins — it is derived from the author's
  * colour/image choice rather than picked directly (see the builder's page-background.util).
  */
-declare function compilePageStyle(style: Partial<PageStyleSettings> | null | undefined): Record<string, string>;
+declare function compilePageStyle(style: Partial<PageStyleSettings> | null | undefined, options?: PageStyleOptions): Record<string, string>;
 
 /**
  * Shared data-source resolving pattern — the SINGLE source of truth for how an IoxDataSource
@@ -2772,5 +2793,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { AOSService, BACKDROP_TWIN_KEY, BACKDROP_WHOLE_KEY, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CONTAINER_HTML_TAGS, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ContainerComponent, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, HOVER_DEFAULT_TRANSITION, HOVER_STATES, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxDialogComponent, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LEGACY_HOVER_TRANSITION, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, RESERVED_ALIAS_PREFIX, STATE_PSEUDO_CLASS, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildPartSelector, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, compilePageStyle, composeVirtualTraits, computeRelative, containerHtmlTag, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, decomposeBackdropFilter, defaultHoverTransition, defaultMessageResolver, deriveSeoFromContent, describeSeoFields, effectiveTransitionId, excludeSelf, feelFor, getByPath, getSeoValue, hasHoverState, hasOwnTransition, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, isWholeBackdropSet, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, parentBreakpoint, parseUrlList, partClassName, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, statePseudoClass, stripSuppressedProps, variableAliases, variableItemsFrom, withContextSlots, withDefaultHoverTransition, wrapInBreakpointQuery, wrapInMediaQuery };
-export type { BoundValueSpec, BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OverrideBreakpoint, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SeoDerivedContent, SeoFieldSource, SeoFieldState, SeoResolveContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };
+export { AOSService, BACKDROP_TWIN_KEY, BACKDROP_WHOLE_KEY, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CONTAINER_HTML_TAGS, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ContainerComponent, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, HOVER_DEFAULT_TRANSITION, HOVER_STATES, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxDialogComponent, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LEGACY_HOVER_TRANSITION, LinkedContainerComponent, PAGE_TOKEN_FALLBACKS, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, RESERVED_ALIAS_PREFIX, STATE_PSEUDO_CLASS, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildPartSelector, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, compilePageStyle, composeVirtualTraits, computeRelative, containerHtmlTag, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, decomposeBackdropFilter, defaultHoverTransition, defaultMessageResolver, deriveSeoFromContent, describeSeoFields, effectiveTransitionId, excludeSelf, feelFor, getByPath, getSeoValue, hasHoverState, hasOwnTransition, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, isWholeBackdropSet, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, parentBreakpoint, parseUrlList, partClassName, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, statePseudoClass, stripSuppressedProps, variableAliases, variableItemsFrom, withContextSlots, withDefaultHoverTransition, wrapInBreakpointQuery, wrapInMediaQuery };
+export type { BoundValueSpec, BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OverrideBreakpoint, PageStyleOptions, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SeoDerivedContent, SeoFieldSource, SeoFieldState, SeoResolveContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.13.1",
+  "version": "5.15.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/design-core/design-apply.ts

@@ -0,0 +1,116 @@
+import { deriveBrandTokens } from './brand';
+import { SPEC_LEGACY_ALIASES } from './flavor-spec.generated';
+import { SWISS_FLAVOR } from './flavor';
+import { buildFlavorTokens } from './flavor-tokens';
+import { FlavorSeedPlan, planFlavorSeed, SeedBaseline, SeedExpectation } from './flavor-seed';
+import { DesignChoices, DesignTokenRow, flavorSourceStamp, StoredDesignTokenRow } from './design-token.model';
+import { flavorPackById, isRetiredFlavorId, packDesignChoices, StoredDesign } from './design-settings';
+
+/**
+ * Applying a look (design-system DS4): the COMPLETE `buildFlavorTokens` set for the chosen
+ * `DesignChoices`, merged into the org's rows by the §10 C2 rule — rewrite only what the previous
+ * seed wrote and nobody touched since, keep the author's rows, report what was kept. And the one
+ * migration the contract names: an org still on Swiss becomes Crisp.
+ * Pure plans; each caller (builder, the server-side site build) applies them with its own transport.
+ */
+
+const SEED_STAMP = /^flavor:([^@]+)@/;
+
+const expectations = (rows: ReadonlyArray<Pick<DesignTokenRow, 'name' | 'value' | 'values'>>): Map<string, SeedExpectation> =>
+    new Map(rows.map(r => [r.name, { value: r.value, ...(r.values?.dark ? { dark: r.values.dark } : {}) }]));
+
+/** Every row a design writes — `buildFlavorTokens` for its pack. Empty for an unknown pack. */
+export function designTokenRows(choices: DesignChoices): DesignTokenRow[] {
+    const pack = flavorPackById(choices.flavorId);
+    return pack ? buildFlavorTokens(pack, { ...choices, flavorId: pack.id }) : [];
+}
+
+/** What the F1/F2 Swiss seeding wrote: the four Swiss rows + the brand set derived from its seed. */
+function swissExpectations(seed: string | null): Map<string, SeedExpectation> {
+    const rows: Array<Pick<DesignTokenRow, 'name' | 'value' | 'values'>> =
+        SWISS_FLAVOR.tokens.map(t => ({ name: t.name, value: t.value, values: t.values }));
+    if (seed) {
+        try { rows.push(...deriveBrandTokens(seed, SWISS_FLAVOR).map(t => ({ name: t.name, value: t.value, values: t.values }))); }
+        catch { /* an unparseable stored seed proves nothing about the rows */ }
+    }
+    return expectations(rows);
+}
+
+/**
+ * What the PREVIOUS design wrote, as a baseline keyed by the row's own stamp: a row Swiss stamped is
+ * judged against what Swiss wrote, every other row against `buildFlavorTokens` of the stored choices
+ * (for an org with no design row, Crisp's defaults — exactly what DS2's interim seed wrote). In a
+ * Swiss org the only v2 rows are that interim seed's, so they are judged against Crisp's DEFAULTS,
+ * never against the brand-seeded Crisp the migration is about to write.
+ */
+export function designBaseline(previous: StoredDesign): SeedBaseline {
+    const retired = isRetiredFlavorId(previous.storedFlavorId);
+    const current = expectations(designTokenRows(retired ? packDesignChoices(previous.choices.flavorId) : previous.choices));
+    const swiss = swissExpectations(retired ? previous.storedSeed : null);
+    return (row: StoredDesignTokenRow) => {
+        const stampedBy = SEED_STAMP.exec(row.source ?? '')?.[1];
+        return stampedBy === SWISS_FLAVOR.id ? swiss.get(row.name) : current.get(row.name);
+    };
+}
+
+/** Apply `next` over the org's rows, judged against `previous` — the plan FlavorApplyService runs. */
+export function planDesignApply(
+    existing: ReadonlyArray<StoredDesignTokenRow>,
+    previous: StoredDesign,
+    next: DesignChoices,
+): FlavorSeedPlan {
+    const pack = flavorPackById(next.flavorId);
+    if (!pack) return { create: [], update: [], kept: [] };
+    return planFlavorSeed(designTokenRows(next), existing, flavorSourceStamp(pack.id), designBaseline(previous));
+}
+
+/** The rows a design is missing by name — the builder-load top-up (never touches an existing row). */
+export function missingDesignRows(existing: ReadonlyArray<{ name: string }>, choices: DesignChoices): DesignTokenRow[] {
+    const have = new Set((existing ?? []).map(r => r.name));
+    return designTokenRows(choices).filter(r => !have.has(r.name));
+}
+
+export interface SwissMigration {
+    /** The design the org now wears: Crisp, carrying the stored brand seed when it is a colour. */
+    choices: DesignChoices;
+    /** The token merge, the four legacy alias rewrites included. */
+    plan: FlavorSeedPlan;
+}
+
+const LEGACY_ALIASES: Readonly<Record<string, string>> = SPEC_LEGACY_ALIASES;
+
+/**
+ * Swiss → Crisp (spec `legacyAliases`; D1). Needed when the design row says a retired flavor, or when
+ * there is no design row but the org holds Swiss-stamped alias rows (F1 seeded those before the row
+ * existed). Idempotent: once the row says Crisp nothing is needed, and re-running the plan writes
+ * nothing.
+ *
+ * - 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.
+ */
+export function planSwissMigration(existing: ReadonlyArray<StoredDesignTokenRow>, stored: StoredDesign): SwissMigration | null {
+    const swissAliasRows = (existing ?? []).filter(r => r.name in LEGACY_ALIASES && SEED_STAMP.exec(r.source ?? '')?.[1] === SWISS_FLAVOR.id);
+    const needed = isRetiredFlavorId(stored.storedFlavorId) || (!stored.hasRow && swissAliasRows.length > 0);
+    if (!needed) return null;
+
+    const choices = stored.choices;
+    const previous: StoredDesign = isRetiredFlavorId(stored.storedFlavorId) ? stored : { ...stored, storedFlavorId: SWISS_FLAVOR.id };
+    const plan = planDesignApply(existing, previous, choices);
+    const stamp = flavorSourceStamp(choices.flavorId);
+    const swiss = swissExpectations(null);
+    for (const row of (existing ?? []).filter(r => r.name in LEGACY_ALIASES)) {
+        const alias = LEGACY_ALIASES[row.name];
+        if (row.value === alias) continue;
+        const was = swiss.get(row.name);
+        const untouched = SEED_STAMP.test(row.source ?? '') && !!was && row.value === was.value && !row.values?.dark;
+        if (untouched && row._id) {
+            plan.update.push({ id: row._id, data: { value: alias, values: {}, source: stamp } });
+        } else {
+            plan.kept.push(row.name);
+        }
+    }
+    return { choices, plan };
+}

package/src/design-core/design-settings.ts

@@ -0,0 +1,194 @@
+import { SPEC_AXES, SPEC_FONT_ROLES } from './flavor-spec.generated';
+import { parseHexColor } from './brand';
+import { DesignChoices, DesignMode, FlavorPackV2, FontRoleToken, SPEC_FLAVORS } from './design-token.model';
+import type { FlavorRevertSnapshot } from './flavor-seed';
+
+/**
+ * The `settings.design` row (design-system plan §3f), read and written by ONE pair of functions so
+ * the builder, the server's public page read (the engine's mode) and the site build agree on what a
+ * stored row MEANS. The row is the settings collection's generic `config: [{ key, value }]`; values
+ * are strings there (Boolean "true"/"false", Object as JSON), but a reader also accepts the typed
+ * value a client control may have sent.
+ */
+
+/** The look a studio wears until it picks one (DS2's interim seed, and DS6's first-run selection). */
+export const DEFAULT_FLAVOR_ID = 'crisp';
+
+/** One `config` entry of a settings row. */
+export interface DesignConfigEntry {
+    key: string;
+    value: unknown;
+}
+
+export enum DesignConfigKey {
+    FlavorId = 'flavorId',
+    FlavorVersion = 'flavorVersion',
+    BrandSeed = 'brandSeed',
+    PairId = 'pairId',
+    Shape = 'shape',
+    Density = 'density',
+    Motion = 'motion',
+    PillButtons = 'pillButtons',
+    Mode = 'mode',
+    Fonts = 'fonts',
+    Revert = 'revert',
+}
+
+/** A stored design, resolved: `choices` is ALWAYS complete and valid (pack defaults fill the gaps). */
+export interface StoredDesign {
+    choices: DesignChoices;
+    /** The flavor id exactly as stored — `swiss` until the DS4 migration rewrites it; null when no row. */
+    storedFlavorId: string | null;
+    /** The seed exactly as stored (F2 orgs carry their brand colour here); null when absent. */
+    storedSeed: string | null;
+    flavorVersion: string | null;
+    revert: FlavorRevertSnapshot | null;
+    /** False when the org has never stored a design — DS6's first run. */
+    hasRow: boolean;
+}
+
+const MODES: ReadonlyArray<string> = SPEC_AXES.modes;
+const FONT_ROLE_TOKENS: ReadonlyArray<string> = SPEC_FONT_ROLES.map(r => r.token);
+
+/** The pack for an id; a retired id (Swiss) resolves to the pack that `replaces` it. */
+export function flavorPackById(id: string | null | undefined): FlavorPackV2 | undefined {
+    if (!id) return undefined;
+    return SPEC_FLAVORS.find(f => f.id === id) ?? SPEC_FLAVORS.find(f => f.replaces === id);
+}
+
+/** True when `id` names a retired flavor that a v2 pack replaces (Swiss → Crisp). */
+export function isRetiredFlavorId(id: string | null | undefined): boolean {
+    return !!id && !SPEC_FLAVORS.some(f => f.id === id) && SPEC_FLAVORS.some(f => f.replaces === id);
+}
+
+const defaultPack = (): FlavorPackV2 => flavorPackById(DEFAULT_FLAVOR_ID) as FlavorPackV2;
+
+const asString = (v: unknown): string | null => (typeof v === 'string' && v.trim() !== '' ? v.trim() : null);
+
+function asBoolean(v: unknown): boolean | null {
+    if (v === true || v === 'true') return true;
+    if (v === false || v === 'false') return false;
+    return null;
+}
+
+function asObject<T>(v: unknown): T | null {
+    if (v && typeof v === 'object') return v as T;
+    if (typeof v !== 'string' || v.trim() === '') return null;
+    try {
+        const parsed = JSON.parse(v);
+        return parsed && typeof parsed === 'object' ? parsed as T : null;
+    } catch {
+        return null;
+    }
+}
+
+function asFonts(v: unknown): DesignChoices['fonts'] | undefined {
+    const raw = asObject<Record<string, unknown>>(v);
+    if (!raw) return undefined;
+    const fonts: Partial<Record<FontRoleToken, string>> = {};
+    for (const role of FONT_ROLE_TOKENS) {
+        const family = raw[role];
+        if (typeof family === 'string' && family.trim() !== '') fonts[role as FontRoleToken] = family.trim();
+    }
+    return Object.keys(fonts).length ? fonts : undefined;
+}
+
+const keyOf = <K extends string>(table: Readonly<Record<K, unknown>>, v: string | null): K | null =>
+    v !== null && Object.prototype.hasOwnProperty.call(table, v) ? v as K : null;
+
+/** A config array → the key/value map (last entry wins, as the settings form writes it). */
+function configMap(config: ReadonlyArray<DesignConfigEntry> | null | undefined): Map<string, unknown> {
+    const map = new Map<string, unknown>();
+    for (const kv of config ?? []) if (kv && typeof kv.key === 'string') map.set(kv.key, kv.value);
+    return map;
+}
+
+/**
+ * A partial set of choices completed against its pack: every missing or invalid value falls back to
+ * the pack's own default (an unknown pair → the pack's first, a bad seed → the pack's seed).
+ */
+export function resolveDesignChoices(partial: Partial<DesignChoices> | null | undefined): DesignChoices {
+    const pack = flavorPackById(partial?.flavorId) ?? defaultPack();
+    const seed = asString(partial?.seed);
+    const pairId = asString(partial?.pairId);
+    const fonts = asFonts(partial?.fonts);
+    return {
+        flavorId: pack.id,
+        seed: seed && parseHexColor(seed) ? seed : pack.seed,
+        pairId: pairId && pack.pairs.some(p => p.id === pairId) ? pairId : pack.pairs[0]?.id ?? '',
+        shape: keyOf(SPEC_AXES.shapes, asString(partial?.shape)) ?? pack.defaults.shape,
+        density: keyOf(SPEC_AXES.densities, asString(partial?.density)) ?? pack.defaults.density,
+        motion: keyOf(SPEC_AXES.motions, asString(partial?.motion)) ?? pack.defaults.motion,
+        pillButtons: asBoolean(partial?.pillButtons) ?? pack.defaults.pillButtons,
+        mode: (MODES.includes(asString(partial?.mode) ?? '') ? asString(partial?.mode) : pack.defaults.mode) as DesignMode,
+        ...(fonts ? { fonts } : {}),
+    };
+}
+
+/** The pack's own defaults for `flavorId` — what picking a card means before anything is tuned. */
+export function packDesignChoices(flavorId: string): DesignChoices {
+    return resolveDesignChoices({ flavorId });
+}
+
+/** A stored `settings.design` config → the resolved design. No row (or no config) → Crisp's defaults. */
+export function readDesignConfig(config: ReadonlyArray<DesignConfigEntry> | null | undefined, hasRow = !!config): StoredDesign {
+    const map = configMap(config);
+    const storedFlavorId = asString(map.get(DesignConfigKey.FlavorId));
+    const storedSeed = asString(map.get(DesignConfigKey.BrandSeed));
+    const choices = resolveDesignChoices({
+        flavorId: storedFlavorId ?? undefined,
+        seed: storedSeed ?? undefined,
+        pairId: asString(map.get(DesignConfigKey.PairId)) ?? undefined,
+        shape: map.get(DesignConfigKey.Shape) as DesignChoices['shape'],
+        density: map.get(DesignConfigKey.Density) as DesignChoices['density'],
+        motion: map.get(DesignConfigKey.Motion) as DesignChoices['motion'],
+        pillButtons: asBoolean(map.get(DesignConfigKey.PillButtons)) ?? undefined,
+        mode: map.get(DesignConfigKey.Mode) as DesignMode,
+        fonts: map.get(DesignConfigKey.Fonts) as DesignChoices['fonts'],
+    });
+    return {
+        choices,
+        storedFlavorId,
+        storedSeed,
+        flavorVersion: asString(map.get(DesignConfigKey.FlavorVersion)),
+        revert: asObject<FlavorRevertSnapshot>(map.get(DesignConfigKey.Revert)),
+        hasRow,
+    };
+}
+
+/** The colour mode a stored config compiles in — what the public page read hands the engine. */
+export function designModeOf(config: ReadonlyArray<DesignConfigEntry> | null | undefined): DesignMode {
+    return readDesignConfig(config).choices.mode;
+}
+
+/** Resolved choices (+ the revert snapshot) → the config array a settings row stores. */
+export function designConfigEntries(
+    choices: DesignChoices,
+    flavorVersion: string | number,
+    revert?: FlavorRevertSnapshot | null,
+): DesignConfigEntry[] {
+    const c = resolveDesignChoices(choices);
+    return [
+        { key: DesignConfigKey.FlavorId, value: c.flavorId },
+        { key: DesignConfigKey.FlavorVersion, value: String(flavorVersion) },
+        { key: DesignConfigKey.BrandSeed, value: c.seed },
+        { key: DesignConfigKey.PairId, value: c.pairId },
+        { key: DesignConfigKey.Shape, value: c.shape },
+        { key: DesignConfigKey.Density, value: c.density },
+        { key: DesignConfigKey.Motion, value: c.motion },
+        { key: DesignConfigKey.PillButtons, value: String(c.pillButtons) },
+        { key: DesignConfigKey.Mode, value: c.mode },
+        ...(c.fonts ? [{ key: DesignConfigKey.Fonts, value: JSON.stringify(c.fonts) }] : []),
+        ...(revert ? [{ key: DesignConfigKey.Revert, value: JSON.stringify(revert) }] : []),
+    ];
+}
+
+/** Two choice sets describe the same look (fonts compared by role). */
+export function sameDesignChoices(a: DesignChoices, b: DesignChoices): boolean {
+    const x = resolveDesignChoices(a);
+    const y = resolveDesignChoices(b);
+    return x.flavorId === y.flavorId && x.seed.toLowerCase() === y.seed.toLowerCase() && x.pairId === y.pairId
+        && x.shape === y.shape && x.density === y.density && x.motion === y.motion
+        && x.pillButtons === y.pillButtons && x.mode === y.mode
+        && JSON.stringify(x.fonts ?? {}) === JSON.stringify(y.fonts ?? {});
+}

package/src/design-core/element-styles.ts

@@ -272,10 +272,10 @@ export function switchElementStyle(
 
 /**
  * The element-style MARKER (design-system §3b-bis, spec `elementStyleMarker`). A node that wears an
- * element style renders `iox-es iox-es-<id>` in BOTH renderers; every piece of component CSS that
- * carries the system look is scoped to it, so a node saved before DS2 (no `elementStyle`) keeps its
- * exact pre-DS2 component CSS no matter which tokens the org holds. This is the ONLY thing a
- * renderer reads `elementStyle` for.
+ * element style renders `iox-es iox-es-<id>` in BOTH renderers, through the one node-class helper
+ * `nodeDesignClasses` (node-classes.ts); every piece of component CSS that carries the system look is
+ * scoped to it, so a node saved before DS2 (no `elementStyle`) keeps its exact pre-DS2 component CSS
+ * no matter which tokens the org holds.
  */
 export const ELEMENT_STYLE_MARKER_CLASS = 'iox-es';
 
@@ -286,22 +286,6 @@ export function elementStyleClass(id: string | null | undefined): string | null
     return elementStyleById(id) ? `${MARKER_PREFIX}${id}` : null;
 }
 
-/** The marker classes a node renders: `'iox-es iox-es-<id>'`, or `''` for a node with no (known) style. */
-export function elementStyleClasses(node: { elementStyle?: string | null } | null | undefined): string {
-    const own = elementStyleClass(node?.elementStyle);
-    return own ? `${ELEMENT_STYLE_MARKER_CLASS} ${own}` : '';
-}
-
-/** Make an element's marker match `elementStyle` — the live switch on the canvas, and the
- *  component path's one-time stamp. Removes a stale `iox-es-<old>`; touches no other class. */
-export function syncElementStyleMarker(el: { classList: DOMTokenList } | null | undefined, elementStyle: string | null | undefined): void {
-    if (!el?.classList) return;
-    const stale = Array.from(el.classList).filter(c => c === ELEMENT_STYLE_MARKER_CLASS || c.startsWith(MARKER_PREFIX));
-    for (const c of stale) el.classList.remove(c);
-    const classes = elementStyleClasses({ elementStyle });
-    if (classes) el.classList.add(...classes.split(' '));
-}
-
 /**
  * The spec's `headingLevelRule`: changing a Heading's level moves it to the new level's DEFAULT
  * style only when it still wears its old level's default (author changes kept, via

package/src/design-core/empty-image.ts

@@ -0,0 +1,52 @@
+import { hasElementStyleMarker } from './node-classes';
+
+/**
+ * Empty images (design-system DS3). A MARKED Image (`.iox-es-media`) with no source renders a box in
+ * the `surface-2` token with its aspect ratio kept — on the canvas with an "Add image" label, on the
+ * live site with nothing in it. An UNMARKED empty Image renders exactly as before (no `src`).
+ *
+ * Why a placeholder `src` instead of a src-less `<img>`: Chromium paints a src-less image as a broken
+ * image (a frame, an icon and the alt text) and ignores `aspect-ratio` once alt text is present, and no
+ * pseudo-element paints on an `<img>`. A real image with no natural size of its own (an SVG with no
+ * width/height) is a proper replaced element: `aspect-ratio`/`object-fit` apply, the background shows
+ * through, and its default object size (300×150) is the SAME for the canvas label and the live blank,
+ * so both renderers lay the box out identically. The fill itself is shared CSS (`iox-design.css`)
+ * keyed on {@link EMPTY_IMAGE_ATTRIBUTE}.
+ */
+
+/** Set on a marked Image while it has no source — the hook the shared fill rule keys on. */
+export const EMPTY_IMAGE_ATTRIBUTE = 'data-iox-empty';
+
+const svgUri = (svg: string) => `data:image/svg+xml,${encodeURIComponent(svg)}`;
+
+/** The live site's blank: an SVG with no intrinsic size and nothing in it. */
+export const EMPTY_IMAGE_SRC = svgUri('<svg xmlns="http://www.w3.org/2000/svg"/>');
+
+const xmlEscape = (s: string) => s.replace(/[&<>"']/g, c => `&#${c.charCodeAt(0)};`);
+
+/**
+ * The canvas blank: the same no-size SVG with `label` centred as a chip. The chip carries its own
+ * light ground, so it reads on every flavor's `surface-2`, light or dark; it is builder chrome, never
+ * site content. Width is estimated from the label length (an image cannot measure text).
+ */
+export function emptyImageLabelSrc(label: string): string {
+    const text = xmlEscape(label);
+    const width = Math.round(28 + label.length * 7);
+    return svgUri(
+        '<svg xmlns="http://www.w3.org/2000/svg"><svg x="50%" y="50%" overflow="visible">'
+        + `<rect x="${-width / 2}" y="-13" width="${width}" height="26" rx="13" fill="#ffffff" fill-opacity="0.92"/>`
+        + '<text x="0" y="0" text-anchor="middle" dominant-baseline="central" font-family="system-ui, -apple-system, \'Segoe UI\', sans-serif" '
+        + `font-size="12" font-weight="500" fill="#1f1d1b">${text}</text></svg></svg>`,
+    );
+}
+
+/**
+ * The `src` a node's Image renders when its own source is empty: the canvas label (when `label` is
+ * given) or the live blank for a MARKED node; `null` — render exactly as before — for an unmarked
+ * node or one that has a source.
+ */
+export function emptyImageSrc(node: { elementStyle?: string | null } | null | undefined, src: unknown, label?: string | null): string | null {
+    if (src != null && src !== '') return null;
+    if (!hasElementStyleMarker(node)) return null;
+    return label ? emptyImageLabelSrc(label) : EMPTY_IMAGE_SRC;
+}

package/src/design-core/flavor-seed.ts

@@ -1,5 +1,5 @@
 import { FlavorTokenDef } from './flavor';
-import { DesignTokenRow, StoredDesignTokenRow } from './design-token.model';
+import { DesignTokenRow, StoredDesignTokenRow, USER_TOKEN_SOURCE } from './design-token.model';
 
 /**
  * Seeding and reverting a look, as pure plans (flavors F2, moved here from iox-cms-client in
@@ -82,42 +82,68 @@ export function planFlavorRevert(
     return plan;
 }
 
+/** What a previous seed wrote for one row — the "untouched" comparison base. */
+export interface SeedExpectation {
+    value: string;
+    dark?: string;
+}
+
+/**
+ * What the PREVIOUS seed wrote, per row: a map by name, or a function of the stored row (a baseline
+ * that depends on WHICH seed stamped the row — the Swiss → Crisp migration's case).
+ */
+export type SeedBaseline =
+    | ReadonlyMap<string, SeedExpectation>
+    | ((row: StoredDesignTokenRow) => SeedExpectation | undefined);
+
+const expectationFor = (baseline: SeedBaseline | null | undefined, row: StoredDesignTokenRow): SeedExpectation | undefined =>
+    !baseline ? undefined : typeof baseline === 'function' ? baseline(row) : baseline.get(row.name);
+
+const sameValue = (row: { value: string; values?: { dark?: string } }, e: SeedExpectation) =>
+    row.value === e.value && (row.values?.dark ?? '') === (e.dark ?? '');
+
 /**
  * The seeding MERGE: desired tokens vs existing rows, deciding create / update / keep. The §10 C2
  * rule — "an upgrade only rewrites untouched rows" — is a comparison against what the PREVIOUS
- * seed wrote (`oldExpected`): a seeded row whose value still equals it is the machine's and may be
- * rewritten; any drift means the author took it over, and their hand wins. A row without a
- * `flavor:` stamp is never touched at all. `group`/`tier` ride every write.
+ * seed wrote (`baseline`): a seeded row whose value still equals it is the machine's and may be
+ * rewritten; any drift means the author took it over, and their hand wins. A row the design did not
+ * 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.
  */
 export function planFlavorSeed(
-    desired: ReadonlyArray<FlavorTokenDef>,
+    desired: ReadonlyArray<FlavorTokenDef & { source?: string }>,
     existing: ReadonlyArray<StoredDesignTokenRow>,
     stamp: string,
-    oldExpected: Map<string, { value: string; dark?: string }> | null,
+    baseline: SeedBaseline | null,
 ): FlavorSeedPlan {
     const byName = new Map((existing ?? []).map(r => [r.name, r]));
     const plan: FlavorSeedPlan = { create: [], update: [], kept: [] };
     for (const def of desired ?? []) {
         if (!def?.name) continue;
         const row = byName.get(def.name);
+        const source = def.source ?? stamp;
         if (!row) {
             plan.create.push({
                 name: def.name,
                 type: def.type ?? DEFAULT_TOKEN_TYPE,
                 value: def.value,
                 ...(def.values ? { values: def.values } : {}),
-                source: stamp,
+                source,
                 ...classification(def),
             });
             continue;
         }
-        if (!isSeeded(row)) { plan.kept.push(def.name); continue; }
+        const old = expectationFor(baseline, row);
+        const designOwned = isSeeded(row) || (row.source === USER_TOKEN_SOURCE && !!old && sameValue(row, old));
+        if (!designOwned) { plan.kept.push(def.name); continue; }
         const sameAsDesired = row.value === def.value && (row.values?.dark ?? '') === (def.values?.dark ?? '');
-        if (sameAsDesired) continue; // already exactly this — nothing to write, nothing kept-against
-        const old = oldExpected?.get(def.name);
-        const untouched = !!old && row.value === old.value && (row.values?.dark ?? '') === (old.dark ?? '');
-        if (untouched && row._id) {
-            plan.update.push({ id: row._id, data: { value: def.value, values: def.values ?? {}, source: stamp, ...classification(def) } });
+        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) } });
         } else {
             plan.kept.push(def.name); // edited since seeding (or unverifiable) — the author's hand wins
         }

package/src/design-core/flavor-spec.generated.ts

@@ -1077,7 +1077,7 @@ export const SPEC_SPRINGS = {
 } as const;
 
 export const SPEC_FONTS = {
-  "Inter": "Inter:wght@400;500;600;700",
+  "Inter": "Inter:wght@300;400;500;600;700",
   "Inter Tight": "Inter+Tight:wght@500;600;700",
   "Manrope": "Manrope:wght@400;500;600;700",
   "IBM Plex Sans": "IBM+Plex+Sans:wght@400;500;600;700",
@@ -1092,12 +1092,21 @@ export const SPEC_FONTS = {
   "Figtree": "Figtree:wght@400;500;600;700;800",
   "Google Sans Flex": "Google+Sans+Flex:wght@400;500;600;700",
   "Bricolage Grotesque": "Bricolage+Grotesque:opsz,wght@12..96,500;12..96,700",
-  "Nunito": "Nunito:wght@400;600;700;800",
+  "Nunito": "Nunito:wght@300;400;600;700;800",
   "DM Sans": "DM+Sans:wght@400;500;700",
   "Archivo": "Archivo:wght@400;500;700",
   "Archivo Black": "Archivo+Black",
   "Syne": "Syne:wght@600;700;800",
-  "Space Mono": "Space+Mono:wght@400;700"
+  "Space Mono": "Space+Mono:wght@400;700",
+  "Poppins": "Poppins:ital,wght@0,300;0,400;0,500;0,600;0,700;1,400",
+  "Roboto": "Roboto:ital,wght@0,300;0,400;0,500;0,700;1,400",
+  "Lato": "Lato:ital,wght@0,300;0,400;0,700;1,400",
+  "Open Sans": "Open+Sans:ital,wght@0,300;0,400;0,600;0,700;1,400",
+  "Montserrat": "Montserrat:ital,wght@0,300;0,400;0,500;0,600;0,700;1,400",
+  "Raleway": "Raleway:wght@300;400;500;600;700",
+  "Playfair Display": "Playfair+Display:ital,wght@0,400;0,500;0,700;1,400",
+  "Oswald": "Oswald:wght@300;400;500;600;700",
+  "Ubuntu": "Ubuntu:ital,wght@0,300;0,400;0,500;0,700;1,400"
 } as const;
 
 export const SPEC_SCHEMES = {
@@ -1762,7 +1771,6 @@ export const SPEC_FIELD_CLASS_BASELINE = {
 export const SPEC_LEGACY_ALIASES = {
   "radius-control": "var(--iox-button-radius)",
   "radius-surface": "var(--iox-card-radius)",
-  "space-control": "var(--iox-button-pad)",
   "space-stack": "var(--iox-space-gap)"
 } as const;
 

package/src/design-core/flavor.ts

@@ -4,8 +4,9 @@ import { DesignTokenGroup, DesignTokenTier, DesignTokenType } from './design-tok
  * Flavors v1 (flavors-and-theming-plan.md, F1–F2): a pack is its TOKENS plus the accent hue
  * opinion the brand derivation reads. The per-type `defaults` map and its resolvers are gone
  * (design-system plan §3e, DS2): a new element is born wearing an ELEMENT STYLE
- * (`element-styles.ts`), which references tokens and is flavor-independent. Swiss survives only
- * until DS4 migrates orgs to Crisp.
+ * (`element-styles.ts`), which references tokens and is flavor-independent. Swiss is retired (DS4
+ * migrates `flavorId: swiss` orgs to Crisp); its pack stays as the migration's BASELINE — what F1/F2
+ * wrote, so "untouched since seeding" stays a comparison (`design-apply.ts`).
  */
 
 export interface FlavorTokenDef {
@@ -40,9 +41,9 @@ export function validateFlavorPack(pack: FlavorPack): string[] {
 }
 
 /**
- * Swiss — the F1 pack: four tokens (control/surface radius, control/stack spacing) and the hue
- * opinion F2's brand step reads. Kept until DS4 migrates `flavorId: swiss` orgs to Crisp; its four
- * rows are the spec's `legacyAliases`.
+ * Swiss — the retired F1 pack: four tokens (control/surface radius, control/stack spacing) and the
+ * hue opinion F2's brand step read. Three of its rows become the spec's `legacyAliases` on migration;
+ * `space-control` is a v2 token in every pack and takes Crisp's value.
  */
 export const SWISS_FLAVOR: FlavorPack = {
     id: 'swiss',