@vectoriox/iox-ui 5.5.2 → 5.7.0

package/index.d.ts

@@ -1490,6 +1490,115 @@ declare const PART_CLASS_NAMES: Record<string, Record<string, string>>;
  *  Undefined when the type declares no such part (or no parts at all). */
 declare function partClassName(type: string, partKey: string): string | undefined;
 
+/**
+ * Flavors (flavors-and-theming-plan.md, F1): the design language a studio launches with,
+ * expressed as data. THE invariant — a flavor never writes a literal into a node; it writes
+ * tokens, and element defaults that REFERENCE tokens. To that end a pack's `defaults` map
+ * holds TOKEN NAMES, not CSS values: the resolver builds `var(--iox-<name>, <packValue>)`,
+ * so smuggling a literal in is impossible by construction, and the validator only has to
+ * check that every referenced token exists.
+ *
+ * The fallback is the bootstrap: until F2 seeds the org's `designtokens` rows, no `--iox-*`
+ * var is defined anywhere, and `var(--iox-radius-control, 4px)` must still paint identically
+ * in the builder canvas and the SSR page. Once tokens ARE seeded (or re-themed), the var wins
+ * over the fallback everywhere — which is exactly the §3 propagation story.
+ */
+interface FlavorTokenDef {
+    name: string;
+    value: string;
+    /** Dark-scheme override, seeded into DesignToken.values.dark at F2. */
+    values?: {
+        dark?: string;
+    };
+    type?: 'color' | 'spacing' | 'size' | 'font' | 'other';
+    /** Tokens-panel grouping (flavors plan §10 C5). */
+    group?: 'colour' | 'type' | 'space' | 'radius' | 'shadow' | 'motion';
+}
+interface FlavorPack {
+    id: string;
+    /** Bumped when the pack's values change; seeding stamps `flavor:<id>@<version>` as DesignToken.source. */
+    version: number;
+    label: string;
+    blurb: string;
+    tokens: FlavorTokenDef[];
+    /** type → styleTrait → TOKEN NAME (never a CSS value — see the module header). */
+    defaults: Record<string, Record<string, string>>;
+    /** F2: the accent's hue rotation (degrees in OKLab) from the brand seed — a pack opinion. */
+    accentHueDeg?: number;
+}
+/** trait → `var(--iox-<token>, <packValue>)` for one node type. Unknown type → {}. */
+declare function resolveFlavorDefaults(type: string, pack: FlavorPack | null | undefined): Record<string, string>;
+/**
+ * The ENGINE's half of the cascade: kebab `prop: var(…)` declarations for every pack default
+ * the node's persisted styleProps does NOT set. Appended beside renderDefaultDeclarations —
+ * same guard-on-undefined discipline, so a node saved post-F1 (var already serialised via the
+ * builder's trait defaults) is untouched, and a legacy node picks the pack default up at
+ * render time. Node styleProps always wins.
+ */
+declare function flavorDefaultDeclarations(type: string, styleProps: Record<string, any> | null | undefined, pack: FlavorPack | null | undefined): string[];
+/**
+ * The CI gate (flavors plan §10 C4): a pack may only name types and traits that exist in the
+ * live component registry, and tokens it defines itself. Returns human-readable errors; a
+ * consumer spec feeds it the REAL registry and asserts [].
+ */
+declare function validateFlavorPack(pack: FlavorPack, knownTraitsByType: Record<string, ReadonlySet<string> | string[]>): string[];
+/**
+ * Swiss — the default pack (flavors plan §8: "the flavor that can never embarrass anyone").
+ * Deliberately SMALL at F1: radius + control padding on the clickables, surface radius on Card.
+ * Colour, type and motion arrive with the brand step (F2) — a colour default here would repaint
+ * legacy pages before anyone chose anything.
+ */
+declare const SWISS_FLAVOR: FlavorPack;
+/** What both renderers use until F2 lets an org choose. */
+declare const DEFAULT_FLAVOR: FlavorPack;
+
+/**
+ * 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.
+ */
+interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+interface OkLab {
+    L: number;
+    a: number;
+    b: number;
+}
+declare function parseHexColor(hex: string): Rgb | null;
+declare function toHexColor(c: Rgb): string;
+declare function rgbToOklab(c: Rgb): OkLab;
+declare function oklabToRgb(c: OkLab): Rgb;
+declare function relativeLuminance(c: Rgb): number;
+/** WCAG 2 contrast ratio between two colours (order-independent), 1..21. */
+declare function wcagContrastRatio(a: string | Rgb, b: string | Rgb): number;
+/**
+ * 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.
+ */
+declare function apcaLc(text: string | Rgb, bg: string | Rgb): number;
+/**
+ * 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.
+ */
+declare function deriveBrandTokens(seed: string, pack: FlavorPack): FlavorTokenDef[];
+
 /** Trait names whose value Swiper reads per breakpoint. Anything else is config-wide. */
 declare const SWIPER_RESPONSIVE_TRAITS: readonly string[];
 /** `{ [minWidth]: { slidesPerView, … } }` — Swiper's own `breakpoints` shape. */
@@ -1553,66 +1662,6 @@ declare function compileTokenCss(tokens: ReadonlyArray<DesignTokenLike> | null |
     dark: string;
 };
 
-/**
- * Flavors (flavors-and-theming-plan.md, F1): the design language a studio launches with,
- * expressed as data. THE invariant — a flavor never writes a literal into a node; it writes
- * tokens, and element defaults that REFERENCE tokens. To that end a pack's `defaults` map
- * holds TOKEN NAMES, not CSS values: the resolver builds `var(--iox-<name>, <packValue>)`,
- * so smuggling a literal in is impossible by construction, and the validator only has to
- * check that every referenced token exists.
- *
- * The fallback is the bootstrap: until F2 seeds the org's `designtokens` rows, no `--iox-*`
- * var is defined anywhere, and `var(--iox-radius-control, 4px)` must still paint identically
- * in the builder canvas and the SSR page. Once tokens ARE seeded (or re-themed), the var wins
- * over the fallback everywhere — which is exactly the §3 propagation story.
- */
-interface FlavorTokenDef {
-    name: string;
-    value: string;
-    /** Dark-scheme override, seeded into DesignToken.values.dark at F2. */
-    values?: {
-        dark?: string;
-    };
-    type?: 'color' | 'spacing' | 'size' | 'font' | 'other';
-    /** Tokens-panel grouping (flavors plan §10 C5). */
-    group?: 'colour' | 'type' | 'space' | 'radius' | 'shadow' | 'motion';
-}
-interface FlavorPack {
-    id: string;
-    /** Bumped when the pack's values change; seeding stamps `flavor:<id>@<version>` as DesignToken.source. */
-    version: number;
-    label: string;
-    blurb: string;
-    tokens: FlavorTokenDef[];
-    /** type → styleTrait → TOKEN NAME (never a CSS value — see the module header). */
-    defaults: Record<string, Record<string, string>>;
-}
-/** trait → `var(--iox-<token>, <packValue>)` for one node type. Unknown type → {}. */
-declare function resolveFlavorDefaults(type: string, pack: FlavorPack | null | undefined): Record<string, string>;
-/**
- * The ENGINE's half of the cascade: kebab `prop: var(…)` declarations for every pack default
- * the node's persisted styleProps does NOT set. Appended beside renderDefaultDeclarations —
- * same guard-on-undefined discipline, so a node saved post-F1 (var already serialised via the
- * builder's trait defaults) is untouched, and a legacy node picks the pack default up at
- * render time. Node styleProps always wins.
- */
-declare function flavorDefaultDeclarations(type: string, styleProps: Record<string, any> | null | undefined, pack: FlavorPack | null | undefined): string[];
-/**
- * The CI gate (flavors plan §10 C4): a pack may only name types and traits that exist in the
- * live component registry, and tokens it defines itself. Returns human-readable errors; a
- * consumer spec feeds it the REAL registry and asserts [].
- */
-declare function validateFlavorPack(pack: FlavorPack, knownTraitsByType: Record<string, ReadonlySet<string> | string[]>): string[];
-/**
- * Swiss — the default pack (flavors plan §8: "the flavor that can never embarrass anyone").
- * Deliberately SMALL at F1: radius + control padding on the clickables, surface radius on Card.
- * Colour, type and motion arrive with the brand step (F2) — a colour default here would repaint
- * legacy pages before anyone chose anything.
- */
-declare const SWISS_FLAVOR: FlavorPack;
-/** What both renderers use until F2 lets an org choose. */
-declare const DEFAULT_FLAVOR: FlavorPack;
-
 /**
  * page-style — the ONE compiler that turns a page's style settings into CSS.
  *
@@ -2782,5 +2831,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { AOSService, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ContainerComponent, ContextStore, DEFAULT_FLAVOR, 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, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SWISS_FLAVOR, 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, compileTokenCss, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, deriveSeoFromContent, describeSeoFields, effectiveTransitionId, excludeSelf, feelFor, flavorDefaultDeclarations, getByPath, getSeoValue, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, parentBreakpoint, parseUrlList, partClassName, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveFlavorDefaults, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, stripSuppressedProps, styleKeyToKebab, tokensToDarkVarMap, tokensToVarMap, validateFlavorPack, variableAliases, variableItemsFrom, withContextSlots, wrapInBreakpointQuery, wrapInMediaQuery };
-export type { BoundValueSpec, BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, DesignTokenLike, FlavorPack, FlavorTokenDef, 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, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ContainerComponent, ContextStore, DEFAULT_FLAVOR, 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, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SWISS_FLAVOR, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, activeActions, apcaLc, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildPartSelector, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, compilePageStyle, compileTokenCss, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, deriveBrandTokens, deriveSeoFromContent, describeSeoFields, effectiveTransitionId, excludeSelf, feelFor, flavorDefaultDeclarations, getByPath, getSeoValue, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, oklabToRgb, parentBreakpoint, parseHexColor, parseUrlList, partClassName, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, relativeLuminance, renderDefaultDeclarations, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveFlavorDefaults, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, rgbToOklab, safeSetInput, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, stripSuppressedProps, styleKeyToKebab, toHexColor, tokensToDarkVarMap, tokensToVarMap, validateFlavorPack, variableAliases, variableItemsFrom, wcagContrastRatio, withContextSlots, wrapInBreakpointQuery, wrapInMediaQuery };
+export type { BoundValueSpec, BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, DesignTokenLike, FlavorPack, FlavorTokenDef, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OkLab, OverrideBreakpoint, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, Rgb, 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.5.2",
+  "version": "5.7.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/actions-core/action.model.ts

@@ -11,7 +11,7 @@ export type ActionKind = 'animated' | 'instant' | 'server';
 
 /** Picker grouping. Flat lists die at ~10 entries; the group is data, never a second list. */
 export type ActionGroup =
-    | 'motion' | 'visibility' | 'navigate' | 'dialog' | 'form' | 'data' | 'service';
+    | 'motion' | 'visibility' | 'navigate' | 'dialog' | 'form' | 'data' | 'consent' | 'service';
 
 /**
  * What a step does inside the live builder canvas (the canvas RUNS interactions):
@@ -25,6 +25,8 @@ export interface ActionParamSpec {
     name: string;
     type: 'number' | 'string' | 'boolean' | 'page' | 'node' | 'form';
     label: string;
+    /** Closed value set — the editor renders a select instead of a free text input. */
+    options?: readonly { value: string; labelKey: string }[];
 }
 
 /** Does this action point at another node — and may it be any node or only certain types? */

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

@@ -59,6 +59,22 @@ export const ELEMENT_ACTION_DESCRIPTORS: readonly ActionDescriptor[] = Object.fr
     { type: 'copyToClipboard', labelKey: 'builder.actions.copyToClipboard', kind: 'instant', group: 'data', builderBehaviour: 'run',
       params: [{ name: 'text', type: 'string', label: 'Text' }] },
 
+    // ── Consent (C3 — the banner's vocabulary; all pure writes of the consent cookie) ──
+    // The canvas SIMULATES the recording ones: the builder runs in the ADMIN's browser, and an
+    // admin's cookie is not a visitor's decision. Opening the preferences dialog is honest to run.
+    { type: 'grantConsent', labelKey: 'builder.actions.grantConsent', kind: 'instant', group: 'consent', builderBehaviour: 'simulate' },
+    { type: 'denyConsent',  labelKey: 'builder.actions.denyConsent',  kind: 'instant', group: 'consent', builderBehaviour: 'simulate' },
+    { type: 'setConsentCategory', labelKey: 'builder.actions.setConsentCategory', kind: 'instant', group: 'consent', builderBehaviour: 'simulate',
+      params: [
+          { name: 'category', type: 'string', label: 'Category', options: [
+              { value: 'analytics', labelKey: 'builder.actions.params.categoryAnalytics' },
+              { value: 'marketing', labelKey: 'builder.actions.params.categoryMarketing' },
+          ] },
+          { name: 'granted', type: 'boolean', label: 'Granted' },
+      ] },
+    { type: 'openConsentPreferences', labelKey: 'builder.actions.openConsentPreferences', kind: 'instant', group: 'consent', builderBehaviour: 'run',
+      target: { required: true, types: ['Dialog'] } },
+
     // ── 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' },
@@ -71,9 +87,14 @@ export const ELEMENT_ACTION_DESCRIPTORS: readonly ActionDescriptor[] = Object.fr
 export const BEHAVIOUR_ACTION_TYPES: ReadonlySet<string> =
     new Set(['navigate', 'scrollTo', 'submitForm', 'copyToClipboard']);
 
+/** The consent actions' dispatch set (C3) — the engines branch on it beside DIALOG/BEHAVIOUR.
+ *  `openConsentPreferences` is dialog-opening by nature and included so ONE branch owns consent. */
+export const CONSENT_ACTION_TYPES: ReadonlySet<string> =
+    new Set(['grantConsent', 'denyConsent', 'setConsentCategory', 'openConsentPreferences']);
+
 /** Picker order — most-used groups first, services last (they are the shop window, not the shop). */
 export const ELEMENT_ACTION_GROUP_ORDER: readonly string[] =
-    Object.freeze(['motion', 'visibility', 'navigate', 'dialog', 'form', 'data', 'service']);
+    Object.freeze(['motion', 'visibility', 'navigate', 'dialog', 'form', 'data', 'consent', 'service']);
 
 /** The catalog, grouped and ordered for the picker — one derivation, no hand-kept second list. */
 export function groupedElementActions(): ReadonlyArray<{ group: string; actions: ActionDescriptor[] }> {

package/src/consent-core/consent-mode.ts

@@ -1,4 +1,5 @@
 import { ConsentCategory, ConsentDecision, hasConsent } from './consent.model';
+import { gtagLoaderUrl } from './decisions';
 
 /**
  * Google Consent Mode v2 (consent plan §4): four parameters, mandatory for EEA/UK measurement
@@ -44,10 +45,11 @@ export function consentModeBootstrapJs(): string {
  */
 export function analyticsInjectionHtml(measurementId: string, decision: ConsentDecision): string {
     const id = (measurementId ?? '').trim();
-    if (!id || !/^[A-Za-z0-9-]+$/.test(id)) return '';
+    const loader = gtagLoaderUrl(id);
+    if (!loader) return '';
     if (!hasConsent(decision, ConsentCategory.Analytics)) return '';
     const signals = JSON.stringify(toConsentModeSignals(decision));
     return `<script>gtag('consent','update',${signals});</script>` +
-        `<script async src="https://www.googletagmanager.com/gtag/js?id=${id}"></script>` +
+        `<script async src="${loader}"></script>` +
         `<script>gtag('js',new Date());gtag('config','${id}');</script>`;
 }

package/src/consent-core/decisions.ts

@@ -0,0 +1,111 @@
+import { ConsentCategory, ConsentDecision } from './consent.model';
+
+/**
+ * Decision construction for the banner's actions (consent plan C3). Pure on purpose: the builder
+ * canvas SIMULATES these (it is the admin's browser, not a visitor's), the engine executes them,
+ * and the e2e asserts the cookies they produce — one implementation of what each button means.
+ *
+ * `necessary` is always granted and never asked. A deny writes an EXPLICIT false per offered
+ * category — a recorded "no" is a decision (`needsPrompt` contract, C1), never an absence.
+ */
+
+/** What an org offers when it has not chosen yet — the two non-necessary categories. */
+export const DEFAULT_OFFERED_CATEGORIES: readonly ConsentCategory[] =
+    Object.freeze([ConsentCategory.Analytics, ConsentCategory.Marketing]);
+
+function base(anonymousId: string, policyVersion: string, now: Date): ConsentDecision {
+    return {
+        categories: { [ConsentCategory.Necessary]: true },
+        policyVersion,
+        decidedAt: now.toISOString(),
+        anonymousId,
+    };
+}
+
+/** "Accept all": every OFFERED category granted. */
+export function grantAllDecision(
+    offered: readonly ConsentCategory[],
+    anonymousId: string,
+    policyVersion: string,
+    now: Date = new Date(),
+): ConsentDecision {
+    const decision = base(anonymousId, policyVersion, now);
+    for (const category of offered) {
+        if (category !== ConsentCategory.Necessary) decision.categories[category] = true;
+    }
+    return decision;
+}
+
+/** "Reject all": every OFFERED category recorded as an explicit no. */
+export function denyAllDecision(
+    offered: readonly ConsentCategory[],
+    anonymousId: string,
+    policyVersion: string,
+    now: Date = new Date(),
+): ConsentDecision {
+    const decision = base(anonymousId, policyVersion, now);
+    for (const category of offered) {
+        if (category !== ConsentCategory.Necessary) decision.categories[category] = false;
+    }
+    return decision;
+}
+
+/**
+ * One category set explicitly (the preferences modal's per-category buttons). Carries every
+ * other category of the PREVIOUS decision forward; with no previous decision the rest stay
+ * unrecorded — the prompt logic still owes the visitor a first-layer ask.
+ */
+export function setCategoryDecision(
+    previous: ConsentDecision | null | undefined,
+    category: ConsentCategory,
+    granted: boolean,
+    anonymousId: string,
+    policyVersion: string,
+    now: Date = new Date(),
+): ConsentDecision {
+    const decision = base(anonymousId, policyVersion, now);
+    if (previous?.categories) {
+        for (const [key, value] of Object.entries(previous.categories)) {
+            decision.categories[key as ConsentCategory] = value === true;
+        }
+        decision.categories[ConsentCategory.Necessary] = true;
+    }
+    if (category !== ConsentCategory.Necessary) decision.categories[category] = granted;
+    return decision;
+}
+
+/** The per-site config the SSR server embeds for the prompt + the post-grant loader (C3). */
+export interface ConsentSiteConfig {
+    policyVersion: string;
+    /** The categories the org offers beyond `necessary`. */
+    categories: readonly ConsentCategory[];
+    /** Site-tag id so a grant can inject the loader WITHOUT a reload; null = none configured. */
+    measurementId?: string | null;
+    /** Route of the org's policy page, for the banner's link; null = not chosen (C5 blocks publish). */
+    policyRoute?: string | null;
+}
+
+/** The window global the engine's runtime reads the config from. */
+export const CONSENT_CONFIG_GLOBAL = '__ioxConsentCfg';
+
+/**
+ * The inline `<head>` embed carrying the config to the browser. Values are JSON-escaped and
+ * `<` is unicode-escaped so user-set strings (a policy version is author input) can never
+ * close the script tag.
+ */
+export function consentConfigJs(config: ConsentSiteConfig): string {
+    const json = JSON.stringify({
+        policyVersion: config.policyVersion,
+        categories: config.categories,
+        measurementId: config.measurementId ?? null,
+        policyRoute: config.policyRoute ?? null,
+    }).replace(/</g, '\\u003c');
+    return `window.${CONSENT_CONFIG_GLOBAL}=${json};`;
+}
+
+/** The gtag loader URL for a measurement id — one spelling for SSR injection and client inject. */
+export function gtagLoaderUrl(measurementId: string): string | null {
+    const id = (measurementId ?? '').trim();
+    if (!id || !/^[A-Za-z0-9-]+$/.test(id)) return null;
+    return `https://www.googletagmanager.com/gtag/js?id=${id}`;
+}

package/src/consent-core/public-api.ts

@@ -12,3 +12,4 @@
 export * from './consent.model';
 export * from './storage';
 export * from './consent-mode';
+export * from './decisions';

package/src/consent-core/storage.ts

@@ -36,8 +36,12 @@ export function decode(raw: string | null | undefined): ConsentDecision | null {
     }
 }
 
-/** `Set-Cookie` attributes for the decision: a NECESSARY cookie, 12 months, first-party. */
-export function cookieAttributes(maxMonths = 12): string {
+/**
+ * `Set-Cookie` attributes for the decision: a NECESSARY cookie, 12 months, first-party.
+ * `secure` is a parameter because a Secure cookie is silently DROPPED on plain http — the
+ * engine passes `location.protocol === 'https:'` so dev servers and the e2e still record.
+ */
+export function cookieAttributes(maxMonths = 12, secure = true): string {
     const maxAge = Math.floor(maxMonths * 30.44 * 24 * 60 * 60);
-    return `Path=/; Max-Age=${maxAge}; SameSite=Lax; Secure`;
+    return `Path=/; Max-Age=${maxAge}; SameSite=Lax${secure ? '; Secure' : ''}`;
 }