@vectoriox/iox-ui 5.8.0 → 5.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.8.0",
+  "version": "5.10.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
@@ -27,6 +27,10 @@
       "types": "./consent-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-consent-core.mjs"
     },
+    "./design-core": {
+      "types": "./design-core/index.d.ts",
+      "default": "./fesm2022/vectoriox-iox-ui-design-core.mjs"
+    },
     "./forms-core": {
       "types": "./forms-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-forms-core.mjs"

package/src/actions-core/element-actions.ts

@@ -75,6 +75,26 @@ export const ELEMENT_ACTION_DESCRIPTORS: readonly ActionDescriptor[] = Object.fr
     { type: 'openConsentPreferences', labelKey: 'builder.actions.openConsentPreferences', kind: 'instant', group: 'consent', builderBehaviour: 'run',
       target: { required: true, types: ['Dialog'] } },
 
+    // ── Server actions (A2 — Tier B): the canvas SIMULATES, the LIVE site POSTs the node's
+    // identity to ONE public route and the server re-derives the spec from the SAVED page.
+    // The author's saved params are the whole spec — a visitor contributes only the click.
+    { type: 'sendEmail', labelKey: 'builder.actions.sendEmail', kind: 'server', group: 'service', builderBehaviour: 'simulate',
+      connector: 'mailer',
+      params: [
+          { name: 'to',      type: 'string', label: 'To' },
+          { name: 'subject', type: 'string', label: 'Subject' },
+          { name: 'message', type: 'string', label: 'Message' },
+      ] },
+    { type: 'callWebhook', labelKey: 'builder.actions.callWebhook', kind: 'server', group: 'service', builderBehaviour: 'simulate',
+      params: [
+          { name: 'url', type: 'string', label: 'URL' },   // non-secret config (K2); the server SSRF-guards it
+      ] },
+    { type: 'createItem', labelKey: 'builder.actions.createItem', kind: 'server', group: 'data', builderBehaviour: 'simulate',
+      params: [
+          { name: 'contentType', type: 'string', label: 'Content type' },
+          { name: 'values',      type: 'string', label: 'Field values (JSON)' },
+      ] },
+
     // ── Services (D-A5: visible, greyed, with the reason — never hidden, never live) ──
     { type: 'signIn',        labelKey: 'builder.actions.signIn',        kind: 'server', group: 'service', builderBehaviour: 'inert',
       planned: true, entitlement: 'visitorIdentity' },
@@ -82,6 +102,11 @@ export const ELEMENT_ACTION_DESCRIPTORS: readonly ActionDescriptor[] = Object.fr
       planned: true, connector: 'payment', entitlement: 'commerce' },
 ]);
 
+/** The A2 server executors' dispatch set — the live engine POSTs these to the public actions
+ *  route; the canvas simulates them (a server action never runs from the ADMIN's browser). */
+export const SERVER_ELEMENT_ACTION_TYPES: ReadonlySet<string> =
+    new Set(['sendEmail', 'callWebhook', 'createItem']);
+
 /** The Tier-A behaviour executors' dispatch set (A1c) — the engines branch on it beside
  *  DIALOG/SWIPER. Dialog actions have their own set; context/visibility stay in the legacy path. */
 export const BEHAVIOUR_ACTION_TYPES: ReadonlySet<string> =

package/src/design-core/brand.ts

@@ -0,0 +1,302 @@
+import { FlavorPack, FlavorTokenDef } from './flavor';
+
+/**
+ * BRAND DERIVATION (flavors plan §6, F2): one colour in, an asserted accessible ramp out.
+ *
+ * Competitors ask for a palette of five and hope; we ask for ONE seed and compute the rest so
+ * that contrast is a TEST, not a promise. WCAG 2 ratios are the gate (every guarantee below is
+ * unit-asserted across seeds); APCA is exposed as the picker's quality read-out only.
+ *
+ * Colour math is OKLab (perceptually even lightness — the ramp steps LOOK even), hand-rolled
+ * from the published matrices because this module must stay dependency-free: it runs in the
+ * builder, the engine and (later) the generator's Node service.
+ */
+
+// ── sRGB ⇄ OKLab ─────────────────────────────────────────────────────────────
+
+export interface Rgb { r: number; g: number; b: number; }        // 0..1
+export interface OkLab { L: number; a: number; b: number; }
+
+export function parseHexColor(hex: string): Rgb | null {
+    const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec((hex ?? '').trim());
+    if (!m) return null;
+    let h = m[1];
+    if (h.length === 3) h = h.split('').map(c => c + c).join('');
+    const n = parseInt(h, 16);
+    return { r: ((n >> 16) & 255) / 255, g: ((n >> 8) & 255) / 255, b: (n & 255) / 255 };
+}
+
+export function toHexColor(c: Rgb): string {
+    const q = (v: number) => Math.round(Math.min(1, Math.max(0, v)) * 255).toString(16).padStart(2, '0');
+    return `#${q(c.r)}${q(c.g)}${q(c.b)}`;
+}
+
+const srgbToLinear = (v: number) => (v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4));
+const linearToSrgb = (v: number) => (v <= 0.0031308 ? v * 12.92 : 1.055 * Math.pow(v, 1 / 2.4) - 0.055);
+
+export function rgbToOklab(c: Rgb): OkLab {
+    const r = srgbToLinear(c.r), g = srgbToLinear(c.g), b = srgbToLinear(c.b);
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    return {
+        L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+        a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+        b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+    };
+}
+
+export function oklabToRgb(c: OkLab): Rgb {
+    const l = Math.pow(c.L + 0.3963377774 * c.a + 0.2158037573 * c.b, 3);
+    const m = Math.pow(c.L - 0.1055613458 * c.a - 0.0638541728 * c.b, 3);
+    const s = Math.pow(c.L - 0.0894841775 * c.a - 1.291485548 * c.b, 3);
+    return {
+        r: linearToSrgb(+4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
+        g: linearToSrgb(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+        b: linearToSrgb(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s),
+    };
+}
+
+const inGamut = (c: Rgb) => [c.r, c.g, c.b].every(v => v >= -1e-6 && v <= 1 + 1e-6);
+
+/** The OKLab colour at (L, hue, chroma), chroma reduced until it fits sRGB. */
+function atLightness(L: number, hueA: number, hueB: number, chroma: number): Rgb {
+    const len = Math.hypot(hueA, hueB) || 1;
+    const ua = hueA / len, ub = hueB / len;
+    let c = chroma;
+    for (let i = 0; i < 24; i++) {
+        const rgb = oklabToRgb({ L, a: ua * c, b: ub * c });
+        if (inGamut(rgb)) return rgb;
+        c *= 0.82;
+    }
+    return oklabToRgb({ L, a: 0, b: 0 });
+}
+
+// ── WCAG 2 (the gate) ────────────────────────────────────────────────────────
+
+export function relativeLuminance(c: Rgb): number {
+    return 0.2126 * srgbToLinear(c.r) + 0.7152 * srgbToLinear(c.g) + 0.0722 * srgbToLinear(c.b);
+}
+
+/** WCAG 2 contrast ratio between two colours (order-independent), 1..21. */
+export function wcagContrastRatio(a: string | Rgb, b: string | Rgb): number {
+    const ca = typeof a === 'string' ? parseHexColor(a) : a;
+    const cb = typeof b === 'string' ? parseHexColor(b) : b;
+    if (!ca || !cb) return 1;
+    const la = relativeLuminance(ca), lb = relativeLuminance(cb);
+    const [hi, lo] = la >= lb ? [la, lb] : [lb, la];
+    return (hi + 0.05) / (lo + 0.05);
+}
+
+// ── APCA (the read-out — WCAG 2 stays the gate) ─────────────────────────────
+
+/**
+ * APCA-W3 lightness contrast Lc (0.0.98G-4g constants), text-on-background and signed:
+ * positive for dark-on-light, negative for light-on-dark; |Lc| ≈ 106–108 at the extremes.
+ * Shown in the picker as the perceptual read-out; never used as the pass/fail gate here.
+ */
+export function apcaLc(text: string | Rgb, bg: string | Rgb): number {
+    const toY = (c: Rgb) =>
+        0.2126729 * Math.pow(c.r, 2.4) + 0.7151522 * Math.pow(c.g, 2.4) + 0.072175 * Math.pow(c.b, 2.4);
+    const clamp = (y: number) => (y < 0.022 ? y + Math.pow(0.022 - y, 1.414) : y);
+    const ct = typeof text === 'string' ? parseHexColor(text) : text;
+    const cb = typeof bg === 'string' ? parseHexColor(bg) : bg;
+    if (!ct || !cb) return 0;
+    const yTxt = clamp(toY(ct)), yBg = clamp(toY(cb));
+    let lc: number;
+    if (yBg > yTxt) lc = (Math.pow(yBg, 0.56) - Math.pow(yTxt, 0.57)) * 1.14;
+    else lc = (Math.pow(yBg, 0.65) - Math.pow(yTxt, 0.62)) * 1.14;
+    if (Math.abs(lc) < 0.1) return 0;
+    return Math.round((lc > 0 ? lc - 0.027 : lc + 0.027) * 1000) / 10;
+}
+
+// ── The ramp ─────────────────────────────────────────────────────────────────
+
+/** Fixed, perceptually even lightness ladder for brand-50 … brand-900. */
+const RAMP_STEPS: ReadonlyArray<{ step: number; L: number; chromaScale: number }> = [
+    { step: 50, L: 0.97, chromaScale: 0.22 },
+    { step: 100, L: 0.93, chromaScale: 0.42 },
+    { step: 200, L: 0.86, chromaScale: 0.66 },
+    { step: 300, L: 0.78, chromaScale: 0.85 },
+    { step: 400, L: 0.70, chromaScale: 0.96 },
+    { step: 500, L: 0.62, chromaScale: 1.0 },
+    { step: 600, L: 0.53, chromaScale: 0.96 },
+    { step: 700, L: 0.45, chromaScale: 0.88 },
+    { step: 800, L: 0.36, chromaScale: 0.76 },
+    { step: 900, L: 0.27, chromaScale: 0.62 },
+];
+
+const BLACK: Rgb = { r: 0, g: 0, b: 0 };
+const WHITE: Rgb = { r: 1, g: 1, b: 1 };
+
+/** Snap to the 8-bit hex the token will actually carry — contrast is judged on WHAT SHIPS.
+ *  (The first version searched in float space and hex rounding landed 6.9596 where 7 was owed.) */
+const quant = (c: Rgb): Rgb => parseHexColor(toHexColor(c))!;
+
+/** Binary-search an OKLab lightness so `contrast(colour, against) ≥ ratio`, darkening-or-lightening. */
+function atContrast(against: Rgb, ratio: number, hueA: number, hueB: number, chroma: number, darker: boolean): Rgb {
+    let lo = darker ? 0 : rgbToOklab(against).L;
+    let hi = darker ? rgbToOklab(against).L : 1;
+    let best = quant(atLightness(darker ? 0.18 : 0.92, hueA, hueB, chroma));
+    for (let i = 0; i < 28; i++) {
+        const mid = (lo + hi) / 2;
+        const candidate = quant(atLightness(mid, hueA, hueB, chroma));
+        if (wcagContrastRatio(candidate, against) >= ratio) {
+            best = candidate;
+            if (darker) lo = mid; else hi = mid; // pull back toward `against`: the LOWEST passing step
+        } else {
+            if (darker) hi = mid; else lo = mid;
+        }
+    }
+    return best;
+}
+
+/**
+ * The derived brand tokens (plan §6's table, every row asserted in brand.spec.ts):
+ * `brand-50…900` (monotonic OKLab lightness, gamut-safe) · `brandInk` (black or white, ≥4.5 on
+ * brand-500 — brand-500's lightness is nudged when neither side clears it) · `surface`/`ink`/
+ * `inkMuted` (seed-tinted neutrals, ≥7:1 / ≥4.5:1 on surface) · `line` (the LIGHTEST neutral that
+ * still clears 3:1 on surface) · `accent` (pack-rotated hue, ≥4.5:1 on surface) — with dark-scheme
+ * values for the neutral family riding `values.dark`.
+ *
+ * Throws on an unparseable seed: callers (the picker) validate; a silent fallback here would
+ * launch a studio into a palette nobody chose.
+ */
+export function deriveBrandTokens(seed: string, pack: Pick<FlavorPack, 'accentHueDeg'>): FlavorTokenDef[] {
+    const seedRgb = parseHexColor(seed);
+    if (!seedRgb) throw new TypeError(`deriveBrandTokens: not a colour: "${seed}"`);
+    const lab = rgbToOklab(seedRgb);
+    const chroma = Math.hypot(lab.a, lab.b);
+    const ua = chroma > 1e-6 ? lab.a : 0.0, ub = chroma > 1e-6 ? lab.b : 1e-6; // grey seeds: keep a stable (arbitrary) hue axis
+    const baseChroma = Math.max(chroma, 0.02); // near-grey seeds still get a usable, quiet ramp
+
+    const token = (name: string, value: string, dark?: string): FlavorTokenDef =>
+        ({ name, value, ...(dark ? { values: { dark } } : {}), type: 'color', group: 'colour' });
+
+    // 1 — the ramp
+    const ramp = RAMP_STEPS.map(({ step, L, chromaScale }) =>
+        ({ step, rgb: atLightness(L, ua, ub, baseChroma * chromaScale) }));
+
+    // 2 — brandInk on brand-500, nudging 500 (within its neighbours) when neither ink clears 4.5
+    let five = ramp.find(r => r.step === 500)!;
+    five.rgb = quant(five.rgb);
+    const inkFor = (bg: Rgb) => (wcagContrastRatio(WHITE, bg) >= wcagContrastRatio(BLACK, bg) ? WHITE : BLACK);
+    for (let i = 0; i < 40 && wcagContrastRatio(inkFor(five.rgb), five.rgb) < 4.5; i++) {
+        const L = rgbToOklab(five.rgb).L;
+        // Mid tones can fail both inks — walk toward whichever side is already winning, but
+        // never past the neighbouring steps: the ramp's monotonic lightness is a guarantee.
+        const towardDark = wcagContrastRatio(WHITE, five.rgb) >= wcagContrastRatio(BLACK, five.rgb);
+        const next = Math.min(0.695, Math.max(0.545, L + (towardDark ? -0.012 : 0.012)));
+        if (next === L) break;
+        five.rgb = quant(atLightness(next, ua, ub, baseChroma));
+    }
+    const brandInk = inkFor(five.rgb);
+
+    // 3 — the neutral family, faintly tinted by the seed hue. Surfaces are quantized FIRST:
+    // every later guarantee is measured against the hex that ships, not a float ideal.
+    const tint = 0.006;
+    const surface = quant(atLightness(0.985, ua, ub, tint));
+    const surfaceDark = quant(atLightness(0.145, ua, ub, tint * 1.5));
+    const ink = atContrast(surface, 7, ua, ub, tint * 2, true);
+    const inkDark = atContrast(surfaceDark, 7, ua, ub, tint * 2, false);
+    const inkMuted = atContrast(surface, 4.5, ua, ub, tint * 2, true);
+    const inkMutedDark = atContrast(surfaceDark, 4.5, ua, ub, tint * 2, false);
+    const line = atContrast(surface, 3, ua, ub, tint, true);
+    const lineDark = atContrast(surfaceDark, 3, ua, ub, tint, false);
+
+    // 4 — the accent: pack-defined hue rotation from the seed, readable on surface
+    const rot = ((pack.accentHueDeg ?? 150) * Math.PI) / 180;
+    const ra = ua * Math.cos(rot) - ub * Math.sin(rot);
+    const rb = ua * Math.sin(rot) + ub * Math.cos(rot);
+    const accent = atContrast(surface, 4.5, ra, rb, Math.max(baseChroma, 0.06), true);
+
+    return [
+        ...ramp.map(({ step, rgb }) => token(`brand-${step}`, toHexColor(rgb))),
+        token('brandInk', toHexColor(brandInk)),
+        token('surface', toHexColor(surface), toHexColor(surfaceDark)),
+        token('ink', toHexColor(ink), toHexColor(inkDark)),
+        token('inkMuted', toHexColor(inkMuted), toHexColor(inkMutedDark)),
+        token('line', toHexColor(line), toHexColor(lineDark)),
+        token('accent', toHexColor(accent)),
+    ];
+}
+
+// ── The design-system accent quartet (design-system plan §3e) ────────────────
+
+/** WCAG 2 AA for body text — the gate every quartet pair is held to. */
+export const WCAG_AA_TEXT = 4.5;
+
+export const ACCENT_TOKEN_NAMES = ['accent', 'accent-ink', 'accent-hover', 'accent-text'] as const;
+export type AccentTokenName = (typeof ACCENT_TOKEN_NAMES)[number];
+
+/** The page backgrounds the accent must read on, light and (optionally) dark. */
+export interface AccentBackgrounds {
+    bg: string;
+    bgDark?: string;
+}
+
+const RAMP_ORDER = RAMP_STEPS.map(s => s.step);
+const WHITE_HEX = toHexColor(WHITE);
+const BLACK_HEX = toHexColor(BLACK);
+const passesText = (fg: string, bg: string) => wcagContrastRatio(fg, bg) >= WCAG_AA_TEXT;
+const bestInkHex = (bg: string) =>
+    (wcagContrastRatio(WHITE_HEX, bg) >= wcagContrastRatio(BLACK_HEX, bg) ? WHITE_HEX : BLACK_HEX);
+
+/**
+ * The quartet a seed different from the pack's own becomes, built ON `deriveBrandTokens` (its
+ * ramp and its WCAG-gated `brandInk`) — never a second colour model:
+ *
+ * - `accent` = brand-500 (already nudged until `brandInk` clears 4.5:1 on it), `accent-ink` = brandInk
+ * - `accent-hover` = the neighbouring step AWAY from the ink, so ink-on-hover only gains contrast
+ * - `accent-text` = the first step from 500 toward the far end that clears 4.5:1 on `bg`
+ * - dark: the first of brand-300/200/400 an ink clears 4.5:1 on, the same hover rule, and
+ *   `accent-text` = the first light step that clears 4.5:1 on `bgDark`
+ *
+ * Every pair (ink/accent, ink/hover, text/bg) is asserted ≥ 4.5:1 in `brand.spec.ts`.
+ */
+export function deriveAccentTokens(
+    seed: string,
+    against: AccentBackgrounds,
+    pack: Pick<FlavorPack, 'accentHueDeg'> = {},
+): FlavorTokenDef[] {
+    const derived = deriveBrandTokens(seed, pack);
+    const hexOf = (name: string) => derived.find(t => t.name === name)!.value;
+    const step = (n: number) => hexOf(`brand-${n}`);
+
+    const hoverFor = (accentStep: number, ink: string): string => {
+        const i = RAMP_ORDER.indexOf(accentStep) + (ink === WHITE_HEX ? 1 : -1);
+        const candidate = RAMP_ORDER[i] !== undefined ? step(RAMP_ORDER[i]) : null;
+        return candidate && passesText(ink, candidate) ? candidate : step(accentStep);
+    };
+    const firstOn = (steps: number[], bg: string) => step(steps.find(n => passesText(step(n), bg)) ?? steps[steps.length - 1]);
+
+    const ink = hexOf('brandInk');
+    const light = {
+        accent: step(500),
+        ink,
+        hover: hoverFor(500, ink),
+        text: firstOn([500, 600, 700, 800, 900], against.bg),
+    };
+
+    const dark = against.bgDark ? (() => {
+        const darkStep = [300, 200, 400].find(n => passesText(bestInkHex(step(n)), step(n))) ?? 300;
+        const darkInk = bestInkHex(step(darkStep));
+        return {
+            accent: step(darkStep),
+            ink: darkInk,
+            hover: hoverFor(darkStep, darkInk),
+            text: firstOn([300, 200, 100, 50], against.bgDark),
+        };
+    })() : null;
+
+    const row = (name: AccentTokenName, value: string, darkValue?: string): FlavorTokenDef => ({
+        name, value, type: 'color', group: 'colour', tier: 'semantic',
+        ...(darkValue ? { values: { dark: darkValue } } : {}),
+    });
+    return [
+        row('accent', light.accent, dark?.accent),
+        row('accent-ink', light.ink, dark?.ink),
+        row('accent-hover', light.hover, dark?.hover),
+        row('accent-text', light.text, dark?.text),
+    ];
+}

package/src/design-core/css-names.ts

@@ -0,0 +1,4 @@
+/** camelCase style key → kebab CSS property (`borderRadius` → `border-radius`). */
+export function styleKeyToKebab(key: string): string {
+    return key.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);
+}

package/src/design-core/design-token.model.ts

@@ -0,0 +1,121 @@
+import { FLAVOR_SPEC } from './flavor-spec.generated';
+
+/**
+ * The design-token vocabulary (design-system plan §3a/§3f). Every list here is READ from the
+ * generated spec, so the contract has one source: iox-ai-guidance `flavor-spec.v1.json`.
+ */
+
+export type DesignTokenType = (typeof FLAVOR_SPEC.tokenTypes)[number];
+export const DESIGN_TOKEN_TYPES: ReadonlyArray<DesignTokenType> = FLAVOR_SPEC.tokenTypes;
+
+export type DesignTokenTier = keyof typeof FLAVOR_SPEC.tiers;
+export const DESIGN_TOKEN_TIERS = Object.keys(FLAVOR_SPEC.tiers) as ReadonlyArray<DesignTokenTier>;
+
+/** The spec carries groups per row, not as a list — `design-token.model.spec` pins this list
+ *  to exactly the set of groups the spec's rows use. */
+export type DesignTokenGroup = 'colour' | 'type' | 'shape' | 'depth' | 'space' | 'motion' | 'components';
+export const DESIGN_TOKEN_GROUPS: ReadonlyArray<DesignTokenGroup> =
+    ['colour', 'type', 'shape', 'depth', 'space', 'motion', 'components'];
+
+/** One `designtokens` row, transport-agnostic (stored rows add `_id`/`organization`). */
+export interface DesignTokenRow {
+    name: string;
+    type: DesignTokenType;
+    value: string;
+    /** Per-scheme overrides. Only `dark` exists; absent means the base value everywhere. */
+    values?: { dark?: string };
+    /** Machine stamp: `flavor:<id>@<version>` on seeded rows, `user` on a font the author chose. */
+    source?: string;
+    group?: DesignTokenGroup;
+    tier?: DesignTokenTier;
+}
+
+/** A row as the planners see it: a stored row may carry its id. */
+export interface StoredDesignTokenRow extends DesignTokenRow {
+    _id?: string;
+}
+
+export type ShapeId = keyof typeof FLAVOR_SPEC.axes.shapes;
+export type DensityId = keyof typeof FLAVOR_SPEC.axes.densities;
+export type MotionId = keyof typeof FLAVOR_SPEC.axes.motions;
+export type DesignMode = (typeof FLAVOR_SPEC.axes.modes)[number];
+export type SchemeId = keyof typeof FLAVOR_SPEC.schemes;
+export type FontRoleToken = (typeof FLAVOR_SPEC.fontRoles)[number]['token'];
+
+/** Everything a studio chose about its look — the `settings.design` row, typed. */
+export interface DesignChoices {
+    flavorId: string;
+    seed: string;
+    pairId: string;
+    shape: ShapeId;
+    density: DensityId;
+    motion: MotionId;
+    pillButtons: boolean;
+    mode: DesignMode;
+    fonts?: Partial<Record<FontRoleToken, string>>;
+}
+
+export interface FlavorSpecToken {
+    readonly name: string;
+    readonly tier: DesignTokenTier;
+    readonly type: DesignTokenType;
+    readonly group: DesignTokenGroup;
+    readonly value: string;
+    readonly dark?: string;
+    /** The flavor departs from the component token's semantic default. */
+    readonly overridden?: boolean;
+}
+
+export interface FontPair {
+    readonly id: string;
+    readonly label: string;
+    readonly tokens: Readonly<Record<string, string>>;
+    readonly families: ReadonlyArray<string>;
+}
+
+/** A flavor exactly as the spec writes it. */
+export interface FlavorPackV2 {
+    readonly id: string;
+    readonly name: string;
+    readonly personality: string;
+    readonly inspiredBy: string;
+    readonly blurb: string;
+    readonly popularFor: ReadonlyArray<string>;
+    readonly replaces?: string;
+    readonly defaults: {
+        readonly shape: ShapeId;
+        readonly density: DensityId;
+        readonly motion: MotionId;
+        readonly pillButtons: boolean;
+        readonly mode: DesignMode;
+    };
+    readonly seed: string;
+    readonly seeds: ReadonlyArray<string>;
+    readonly pairs: ReadonlyArray<FontPair>;
+    readonly tokens: ReadonlyArray<FlavorSpecToken>;
+}
+
+/** The spec's flavors, typed. Assignment here is the compile-time proof that the generated
+ *  data fits `FlavorPackV2`. */
+export const SPEC_FLAVORS: ReadonlyArray<FlavorPackV2> = FLAVOR_SPEC.flavors;
+
+export const FLAVOR_SPEC_VERSION: number = FLAVOR_SPEC.version;
+
+/** The stamp seeded rows carry, so an upgrade can tell the machine's rows from the author's. */
+export function flavorSourceStamp(flavorId: string, version: number = FLAVOR_SPEC_VERSION): string {
+    return `flavor:${flavorId}@${version}`;
+}
+
+export const USER_TOKEN_SOURCE = 'user';
+
+export function isDesignTokenType(v: unknown): v is DesignTokenType {
+    return typeof v === 'string' && (DESIGN_TOKEN_TYPES as ReadonlyArray<string>).includes(v);
+}
+
+export function isDesignTokenGroup(v: unknown): v is DesignTokenGroup {
+    return typeof v === 'string' && (DESIGN_TOKEN_GROUPS as ReadonlyArray<string>).includes(v);
+}
+
+export function isDesignTokenTier(v: unknown): v is DesignTokenTier {
+    return typeof v === 'string' && (DESIGN_TOKEN_TIERS as ReadonlyArray<string>).includes(v);
+}

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

@@ -0,0 +1,126 @@
+import { FlavorTokenDef } from './flavor';
+import { DesignTokenRow, StoredDesignTokenRow } from './design-token.model';
+
+/**
+ * Seeding and reverting a look, as pure plans (flavors F2, moved here from iox-cms-client in
+ * design-system DS1 so the builder, the wizard and the server-side site build share ONE merge).
+ * Each caller applies a plan with its own transport.
+ */
+
+const FLAVOR_SOURCE_PREFIX = 'flavor:';
+const DEFAULT_TOKEN_TYPE = 'other';
+
+/** One row's fate in a seed/re-seed pass (the §10 C2 merge semantics). */
+export interface FlavorSeedPlan {
+    create: DesignTokenRow[];
+    update: { id: string; data: Partial<DesignTokenRow> }[];
+    /** Names deliberately left alone: hand-made rows, and seeded rows the author edited. */
+    kept: string[];
+}
+
+/** What Apply stores so the 7-day revert is honest: the WHOLE pre-apply token set plus the
+ *  design identity it belonged to. */
+export interface FlavorRevertSnapshot {
+    appliedAt: number;
+    /** The design row's identity BEFORE the apply, restored with the tokens. */
+    from: { flavorId: string | null; flavorVersion: string | null; brandSeed: string | null };
+    tokens: Array<Pick<DesignTokenRow, 'name' | 'type' | 'value' | 'values' | 'source' | 'group' | 'tier'>>;
+}
+
+export interface FlavorRevertPlan {
+    create: DesignTokenRow[];
+    update: Array<{ id: string; data: Partial<DesignTokenRow> }>;
+    /** Rows the apply created (flavor-stamped, absent from the snapshot) — removed on revert. */
+    remove: string[];
+}
+
+export const REVERT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+const isSeeded = (row: { source?: string } | null | undefined) => (row?.source ?? '').startsWith(FLAVOR_SOURCE_PREFIX);
+
+const classification = (def: Pick<DesignTokenRow, 'group' | 'tier'>): Pick<DesignTokenRow, 'group' | 'tier'> => ({
+    ...(def.group ? { group: def.group } : {}),
+    ...(def.tier ? { tier: def.tier } : {}),
+});
+
+/** Board F7's footer promise, as a boundary: available through the 7th day, not beyond. */
+export function revertAvailable(appliedAt: number | null | undefined, now: number): boolean {
+    return typeof appliedAt === 'number' && appliedAt > 0 && now - appliedAt <= REVERT_WINDOW_MS;
+}
+
+/**
+ * Restore the snapshot EXACTLY: snapshot rows come back to their stored value/dark/source
+ * (update when present, recreate when deleted); rows the apply CREATED (flavor-stamped and
+ * absent from the snapshot) are removed. Hand-made rows born after the apply are not ours
+ * to touch — a revert undoes the FLAVOR, not the author's week.
+ */
+export function planFlavorRevert(
+    current: ReadonlyArray<StoredDesignTokenRow>,
+    snapshot: FlavorRevertSnapshot['tokens'],
+): FlavorRevertPlan {
+    const byName = new Map<string, StoredDesignTokenRow>();
+    for (const row of current ?? []) byName.set(row.name, row);
+    const snapNames = new Set<string>();
+    const plan: FlavorRevertPlan = { create: [], update: [], remove: [] };
+    for (const snap of 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) });
+            continue;
+        }
+        const differs = live.value !== snap.value
+            || (live.values?.dark ?? null) !== (snap.values?.dark ?? null)
+            || (live.source ?? null) !== (snap.source ?? null);
+        if (differs && live._id) {
+            plan.update.push({ id: live._id, data: { value: snap.value, values: snap.values, source: snap.source } });
+        }
+    }
+    for (const row of current ?? []) {
+        if (!snapNames.has(row.name) && row._id && isSeeded(row)) plan.remove.push(row._id);
+    }
+    return plan;
+}
+
+/**
+ * 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.
+ */
+export function planFlavorSeed(
+    desired: ReadonlyArray<FlavorTokenDef>,
+    existing: ReadonlyArray<StoredDesignTokenRow>,
+    stamp: string,
+    oldExpected: Map<string, { value: string; dark?: string }> | 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);
+        if (!row) {
+            plan.create.push({
+                name: def.name,
+                type: def.type ?? DEFAULT_TOKEN_TYPE,
+                value: def.value,
+                ...(def.values ? { values: def.values } : {}),
+                source: stamp,
+                ...classification(def),
+            });
+            continue;
+        }
+        if (!isSeeded(row)) { 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) } });
+        } else {
+            plan.kept.push(def.name); // edited since seeding (or unverifiable) — the author's hand wins
+        }
+    }
+    return plan;
+}