@vectoriox/iox-ui 5.23.0 → 5.25.0

package/index.d.ts

@@ -1668,8 +1668,40 @@ interface PageStyleOptions {
      */
     designSystem?: boolean;
 }
-/** The token fallbacks of a design-system page (spec tokens only). */
+/** The three page-style fields a design-system page can inherit from the look. */
+declare enum PageStyleField {
+    Background = "background",
+    TextColor = "textColor",
+    FontFamily = "fontFamily"
+}
+/** Where a page-style field's value comes from. */
+declare enum PageStyleSource {
+    /** The page sets it itself. */
+    Own = "own",
+    /** A design-system page that sets nothing wears the look's token. */
+    Look = "look",
+    /** A page without the flag that sets nothing: the consumer's own default shows through. */
+    Unset = "unset"
+}
+/** The token a design-system page falls back to, per field (spec tokens only). */
+declare const PAGE_STYLE_TOKENS: Readonly<Record<PageStyleField, string>>;
+/** The token fallbacks of a design-system page, as CSS declarations. */
 declare const PAGE_TOKEN_FALLBACKS: Readonly<Record<string, string>>;
+/** One field as a panel shows it: where its value comes from and, when it is the look's, which token. */
+interface PageStyleFieldState {
+    field: PageStyleField;
+    source: PageStyleSource;
+    /** The token the field falls back to — set only when `source` is `Look`. */
+    token: string | null;
+}
+/**
+ * Where each page-style field comes from — decided by the SAME compile the renderers run, so the
+ * Page panel can never say "from the look" for a field the canvas paints from the page, or the other
+ * way round. A flagged page's empty field is the look's token; an unflagged page's is `Unset`.
+ */
+declare function describePageStyle(style: Partial<PageStyleSettings> | null | undefined, options?: PageStyleOptions): Record<PageStyleField, PageStyleFieldState>;
+/** The style with one field handed back to the look: cleared to '', every other key kept. */
+declare function resetPageStyleField<T extends Partial<PageStyleSettings>>(style: T | null | undefined, field: PageStyleField): T;
 /**
  * Compile page style settings into CSS declarations.
  *
@@ -2808,5 +2840,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_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 };
+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_STYLE_TOKENS, PAGE_TOKEN_FALLBACKS, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PageStyleField, PageStyleSource, 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, describePageStyle, 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, resetPageStyleField, 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, PageStyleFieldState, 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.23.0",
+  "version": "5.25.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

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

@@ -2,7 +2,9 @@ import { deriveBrandTokens } from './brand';
 import { SPEC_LEGACY_ALIASES } from './flavor-spec.generated';
 import { SWISS_FLAVOR } from './flavor';
 import { buildFlavorTokens } from './flavor-tokens';
-import { FlavorRevertPlan, FlavorSeedPlan, planFlavorRevert, planFlavorSeed, SeedBaseline, SeedExpectation } from './flavor-seed';
+import {
+    FlavorRevertPlan, FlavorSeedOptions, FlavorSeedPlan, planFlavorRevert, planFlavorSeed, SeedBaseline, SeedExpectation, untouchedSeedRow,
+} from './flavor-seed';
 import { DesignChoices, DesignTokenRow, flavorSourceStamp, StoredDesignTokenRow } from './design-token.model';
 import { fontFamilyKey, FontFamilyToken, fontRoleReferences, parseFontFamilies } from './fonts';
 import { flavorPackById, isRetiredFlavorId, packDesignChoices, StoredDesign } from './design-settings';
@@ -37,32 +39,64 @@ function swissExpectations(seed: string | null): Map<string, SeedExpectation> {
     return expectations(rows);
 }
 
+/** What a v2 pack writes at its OWN defaults, by pack id — computed once per id per caller. */
+function packDefaultsLookup(): (packId: string) => Map<string, SeedExpectation> | undefined {
+    const cache = new Map<string, Map<string, SeedExpectation> | undefined>();
+    return packId => {
+        if (!cache.has(packId)) {
+            const pack = isRetiredFlavorId(packId) ? undefined : flavorPackById(packId);
+            cache.set(packId, pack && pack.id === packId ? expectations(designTokenRows(packDesignChoices(pack.id))) : undefined);
+        }
+        return cache.get(packId);
+    };
+}
+
 /**
  * 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.
+ *
+ * A row a v2 pack stamped is ALSO untouched while it holds what that pack writes at its own defaults —
+ * what DS2's interim seed, a first run and every pack card at its defaults wrote. Without it, one row
+ * kept for any reason (a dark half iox-cms dropped, `untouchedSeedRow`) was judged against a design that
+ * had moved on, apply after apply, and stayed on the old value for good: the studio's brand colour
+ * reached the design row and never its accent.
  */
 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);
+    const packDefaults = packDefaultsLookup();
     return (row: StoredDesignTokenRow) => {
         const stampedBy = SEED_STAMP.exec(row.source ?? '')?.[1];
-        return stampedBy === SWISS_FLAVOR.id ? swiss.get(row.name) : current.get(row.name);
+        if (stampedBy === SWISS_FLAVOR.id) return swiss.get(row.name);
+        const ownDefault = stampedBy ? packDefaults(stampedBy)?.get(row.name) : undefined;
+        return [current.get(row.name), ownDefault].filter((e): e is SeedExpectation => !!e);
     };
 }
 
-/** Apply `next` over the org's rows, judged against `previous` — the plan FlavorApplyService runs. */
+/** Options of an apply. */
+export interface DesignApplyOptions {
+    /** The kept rows the author asked to take the look's values too (`FlavorSeedOptions.reclaim`). */
+    reclaim?: FlavorSeedOptions['reclaim'];
+}
+
+/**
+ * Apply `next` over the org's rows, judged against `previous` — the plan FlavorApplyService runs. The
+ * plan's `kept` names the author's rows the look leaves alone; the Design card lists them before Apply,
+ * and `options.reclaim` writes the look's value into the ones the author hands back.
+ */
 export function planDesignApply(
     existing: ReadonlyArray<StoredDesignTokenRow>,
     previous: StoredDesign,
     next: DesignChoices,
+    options: DesignApplyOptions = {},
 ): FlavorSeedPlan {
     const pack = flavorPackById(next.flavorId);
     if (!pack) return { create: [], update: [], kept: [] };
-    return planFlavorSeed(designTokenRows(next), existing, flavorSourceStamp(pack.id), designBaseline(previous));
+    return planFlavorSeed(designTokenRows(next), existing, flavorSourceStamp(pack.id), designBaseline(previous), { reclaim: options.reclaim });
 }
 
 /**
@@ -85,23 +119,34 @@ export function missingDesignRows(existing: ReadonlyArray<{ name: string }>, cho
 }
 
 /**
- * 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.
+ * The builder-load REPAIR (DS4.1): rows the design writes that are the machine's and nobody touched,
+ * yet hold something other than the design's value, are rewritten — so an org heals on its next load
+ * with no author action. Two shapes:
+ * - stamped by the current pack, light value exactly the pack's, dark half not: 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;
+ * - stamped by a v2 pack and still holding what THAT pack writes at its own defaults (its dark half
+ *   possibly lost the same way) while the stored design says otherwise: an apply that judged the row
+ *   edited (before 5.24.0, a lost dark half did) left it on the default — the six brand rows of a studio
+ *   whose brand colour never reached its accent.
+ * No author edit produces either shape — the Tokens panel edited the light value only, and since DS8 an
+ * edit makes the row `source: user`, which this never touches.
  */
 export function designTokenRepairs(existing: ReadonlyArray<StoredDesignTokenRow>, choices: DesignChoices): FlavorSeedPlan['update'] {
     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 packDefaults = packDefaultsLookup();
     const out: FlavorSeedPlan['update'] = [];
     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;
+        if (!want || !row._id || want.source !== stamp) continue;
+        if (row.value === want.value && (row.values?.dark ?? '') === (want.values?.dark ?? '') && row.source === stamp) continue;
+        const stampedBy = SEED_STAMP.exec(row.source ?? '')?.[1];
+        const darkOnly = row.source === stamp && row.value === want.value;
+        const ownDefault = stampedBy ? packDefaults(stampedBy)?.get(row.name) : undefined;
+        if (!darkOnly && !(ownDefault && untouchedSeedRow(row, [ownDefault]))) 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;

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

@@ -125,19 +125,44 @@ export interface SeedExpectation {
 }
 
 /**
- * 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).
+ * What a 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). The function may name
+ * several values: a machine row is untouched when it holds ANY of them (`designBaseline`: what the
+ * previous design wrote, and what the row's own pack writes at its defaults).
  */
 export type SeedBaseline =
     | ReadonlyMap<string, SeedExpectation>
-    | ((row: StoredDesignTokenRow) => SeedExpectation | undefined);
+    | ((row: StoredDesignTokenRow) => SeedExpectation | ReadonlyArray<SeedExpectation> | undefined);
 
-const expectationFor = (baseline: SeedBaseline | null | undefined, row: StoredDesignTokenRow): SeedExpectation | undefined =>
-    !baseline ? undefined : typeof baseline === 'function' ? baseline(row) : baseline.get(row.name);
+/** Options of a seed pass. */
+export interface FlavorSeedOptions {
+    /** Rows the author asked to take the look's values too ("Use the look's values for these too"):
+     *  written like an untouched row instead of being kept. */
+    reclaim?: Iterable<string> | null;
+}
+
+function expectationsFor(baseline: SeedBaseline | null | undefined, row: StoredDesignTokenRow): SeedExpectation[] {
+    if (!baseline) return [];
+    const found = typeof baseline === 'function' ? baseline(row) : baseline.get(row.name);
+    if (!found) return [];
+    return (Array.isArray(found) ? found : [found]).filter(Boolean) as SeedExpectation[];
+}
 
 const sameValue = (row: { value: string; values?: { dark?: string } }, e: SeedExpectation) =>
     row.value === e.value && (row.values?.dark ?? '') === (e.dark ?? '');
 
+/**
+ * A machine-stamped row is untouched when it holds what a seed wrote — or that seed's LIGHT value with no
+ * dark half at all: iox-cms dropped every `values.dark` from F0 to DS4.1, and no author edit produces that
+ * shape (the Tokens panel edited the light value only, and since DS8 an edit makes the row `source: user`).
+ * Judging it edited kept the six brand rows of every studio seeded before DS4.1 on the default blue for
+ * good — a later brand never reached them.
+ */
+export function untouchedSeedRow(row: StoredDesignTokenRow, expected: ReadonlyArray<SeedExpectation>): boolean {
+    const darkLost = isSeeded(row) && !row.values?.dark;
+    return expected.some(e => sameValue(row, e) || (darkLost && row.value === e.value));
+}
+
 /**
  * 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
@@ -148,15 +173,18 @@ const sameValue = (row: { value: string; values?: { dark?: string } }, e: SeedEx
  * 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. 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).
+ * design that owns the row, so the next switch judges it against the right baseline). A row named in
+ * `options.reclaim` is written whatever it holds — the author chose the look's value over their own.
  */
 export function planFlavorSeed(
     desired: ReadonlyArray<FlavorTokenDef & { source?: string }>,
     existing: ReadonlyArray<StoredDesignTokenRow>,
     stamp: string,
     baseline: SeedBaseline | null,
+    options: FlavorSeedOptions = {},
 ): FlavorSeedPlan {
     const byName = new Map((existing ?? []).map(r => [r.name, r]));
+    const reclaim = new Set(options.reclaim ?? []);
     const plan: FlavorSeedPlan = { create: [], update: [], kept: [] };
     for (const def of desired ?? []) {
         if (!def?.name) continue;
@@ -173,13 +201,14 @@ export function planFlavorSeed(
             });
             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 olds = expectationsFor(baseline, row);
+        const reclaimed = reclaim.has(def.name);
+        const designOwned = isSeeded(row) || (row.source === USER_TOKEN_SOURCE && olds.some(o => sameValue(row, o)));
+        if (!designOwned && !reclaimed) { plan.kept.push(def.name); continue; }
         const sameAsDesired = row.value === def.value && (row.values?.dark ?? '') === (def.values?.dark ?? '');
         if (sameAsDesired && (row.source ?? '') === source) continue; // already exactly this
-        const untouched = !!old && sameValue(row, old);
-        if ((untouched || sameAsDesired) && row._id) {
+        const untouched = untouchedSeedRow(row, olds);
+        if ((untouched || sameAsDesired || reclaimed) && 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