@vectoriox/iox-ui 5.46.0 → 5.48.0

package/harness-core/package.json

@@ -0,0 +1,3 @@
+{
+  "module": "../fesm2022/vectoriox-iox-ui-harness-core.mjs"
+}

package/index.d.ts

@@ -113,13 +113,15 @@ interface PageScrollStart {
  * Scrolling choice (`planScroll`); `scrollTo` actions and the dialog lock go through it whether or not
  * Lenis runs. Never on the server: there is no window to scroll.
  */
-declare class PageScrollProvider {
+declare class PageScrollProvider implements OnDestroy {
     private zone;
     private lenis;
     private rafId?;
     private wrapper;
     private lockedOverflow;
     init(start: PageScrollStart): void;
+    /** Provided by a component (a page, the Design step's specimen): its Lenis and loop go with it. */
+    ngOnDestroy(): void;
     /** Stop Lenis and its loop; the page falls back to the browser's own scrolling. */
     destroy(): void;
     /** Hard-stop page scroll (dialog open, A1b): wheel/touch frozen until start(). */
@@ -3034,6 +3036,23 @@ declare function hasOwnPageTransition(anim: RouteAnimationLike | null | undefine
  */
 declare function pageTransitionOf(anim: RouteAnimationLike | null | undefined, ctx?: PageTransitionContext): PlannedPageTransition;
 
+/** The two layers a builder preview of a page change plays on, and the stage that holds them. */
+interface TransitionPreviewLayers {
+    /** Holds both layers; it carries the perspective the 3D presets need. */
+    stage: HTMLElement;
+    /** The page that leaves. */
+    out: HTMLElement | null;
+    /** The page that arrives. */
+    in: HTMLElement | null;
+}
+/**
+ * Play a resolved page change (`resolvePageTransition`) on two stacked layers — the ONE dual-layer preview the
+ * builder's Page panel and the Design step's specimen both play (rev 3.1 §3o). The live site plays the same
+ * frames through its own transition service. Resolves when the arriving layer has finished (or at once when
+ * there is no arriving layer). The layers are left at their last frame: the caller decides what to show after.
+ */
+declare function playDualLayerTransition(resolved: ResolvedPageTransition, layers: TransitionPreviewLayers): Promise<void>;
+
 /**
  * Gallery effect registry — the SHARED, effect-agnostic description of how each gallery slide looks
  * and animates in a given crossfade state. Modeled on `binding-pipes.ts` / `PAGE_TRANSITION_PRESETS`:
@@ -3156,5 +3175,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { A11yAttribute, A11yTrait, ACCESSIBLE_NAME_TYPES, AOSService, ARIA_CURRENT_PAGE, BACKDROP_TWIN_KEY, BACKDROP_WHOLE_KEY, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, COMPONENT_STATE_SELECTOR, CONTAINER_HTML_TAGS, CONTEXT_ACTION_TYPES, CURRENT_LINK_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ComponentState, ContainerComponent, ContextStore, DECORATIVE_TYPES, 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, DIALOG_CLOSE_ABOVE_ATTRIBUTE, DIALOG_NODE_TYPE, DeclarationContext, ENTRANCE_ACTION_TYPES, EXIT_ACTION_TYPES, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, HOVER_DEFAULT_TRANSITION, HOVER_STATES, INTERACTION_HIDDEN_ATTRIBUTE, 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, IoxVideoComponent, LAST_EMITTED_STATES, LEGACY_DIRECTION_KEY, LEGACY_HOVER_TRANSITION, LEGACY_SWIPER_CONTROLS, LinkedContainerComponent, MANAGED_A11Y_ATTRIBUTES, MAX_LINES_KEY, NAMED_GROUP_ROLES, NO_PAGE_TRANSITION, ON_STATE_ROLES, PAGE_STYLE_TOKENS, PAGE_TOKEN_FALLBACKS, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PART_PAGINATION_MODIFIER, PHONE_TRANSITION_QUERY, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PageStyleField, PageStyleSource, REDUCED_MOTION_QUERY, SCROLL_EASINGS, SLIDER_INPUTS_ATTRIBUTE, SLIDER_INPUT_NAMES, STATE_PSEUDO_CLASS, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_A11Y_OPTIONS, SWIPER_RESPONSIVE_TRAITS, SWIPER_TRIGGER_EVENTS, ScrollEasing, SectionComponent, SwiperModuleName, TARGETED_STATE_SUFFIX, TEXT_ALIGN_KEY, TEXT_DIRECTION_KEY, TRANSITION_FEELS, TextAlign, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, VisibilityActionType, activeActions, applyBindingPipes, applyFeel, bootSlider, breakpointDef, breakpointForWidth, breakpointQueryFor, buildInteractionKeyframes, buildPartSelector, buildSwiperBreakpoints, buildTargetedStateSelector, buildTargetedSuffixSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, closeAboveMediaQuery, collectContextSlotKeys, compileDeclarations, compilePageStyle, componentStatesFor, composeVirtualTraits, containerHtmlTag, contextActionEffect, contextSlotKeys, countOverrides, declaredInputNames, decomposeBackdropFilter, defaultHoverTransition, defaultMessageResolver, deriveSeoFromContent, describePageStyle, describeSeoFields, dialogCloseAboveMinWidth, domHasSliderParts, effectiveActionType, effectiveTransitionId, entrancePreStateStyle, feelFor, finalKeyframe, getSeoValue, hasHoverState, hasOwnPageTransition, hasOwnTransition, initialSlotValues, isActionEnabled, isContextAction, isCurrentLink, isExternalOrFragment, isGradientPaint, isInputOverriddenAt, isLastEmittedStateKey, isOverriddenAt, isValidSlotKey, isWholeBackdropSet, keyframePropertyName, keyframeStyleEntries, legacyEnterToTransition, mediaQueryFor, mergeSwiperBreakpoints, migrateLegacyDirection, migrateLegacyTextAlign, motionAllowed, nearestCommonAncestorId, needsAccessibleName, needsGroupName, nodeA11yAttributes, nodeCssId, nodeTraitValue, nodeUsesContext, normalizeAppPath, normalizeGalleryImage, normalizeIconClass, orderStatesForEmit, pageTransitionOf, parentBreakpoint, parseUrlList, partClassName, planResponsiveRules, planScroll, planSwiperOptions, prefersReducedMotion, renderDefaultDeclarations, resetPageStyleField, resetSeoField, resolveBoundValue, resolveContextValue, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveSeo, resolveStateStyles, resolveStyleProps, resolveToggleVisibility, resolveValueChain, rewriteViewportUnits, safeSetInput, serializeA11yAttributes, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, sliderControlElements, sliderInputsFromProps, sliderInputsOf, stateNamesIn, statePseudoClass, stateSelectorSuffix, stripSuppressedProps, swiperAutoplayAllowed, swiperLoopOptions, swiperModuleNames, syncNodeA11yAttributes, targetedStateSelector, viewportTransitionContext, withContextSlots, withDefaultHoverTransition, wrapInBreakpointQuery, wrapInMediaQuery };
-export type { A11yNodeSource, BoundValueSpec, BreakpointDef, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, CurrentLinkOptions, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, InteractionKeyframe, IoxContextSlot, IoxPipe, MatchMediaHost, NodeA11yContext, OverrideBreakpoint, PageScrollStart, PageStyleFieldState, PageStyleOptions, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionContext, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, PlannedPageTransition, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteAnimationLike, ScrollPlanContext, SeoDerivedContent, SeoFieldSource, SeoFieldState, SeoResolveContext, SetContextParams, SliderBootOptions, SliderControlElements, SliderInputs, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, SwiperModuleFlags, SwiperPlan, SwiperPlanContext, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, TransitionViewport, ValueSource, VirtualTraitGroup };
+export { A11yAttribute, A11yTrait, ACCESSIBLE_NAME_TYPES, AOSService, ARIA_CURRENT_PAGE, BACKDROP_TWIN_KEY, BACKDROP_WHOLE_KEY, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, COMPONENT_STATE_SELECTOR, CONTAINER_HTML_TAGS, CONTEXT_ACTION_TYPES, CURRENT_LINK_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ComponentState, ContainerComponent, ContextStore, DECORATIVE_TYPES, 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, DIALOG_CLOSE_ABOVE_ATTRIBUTE, DIALOG_NODE_TYPE, DeclarationContext, ENTRANCE_ACTION_TYPES, EXIT_ACTION_TYPES, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, HOVER_DEFAULT_TRANSITION, HOVER_STATES, INTERACTION_HIDDEN_ATTRIBUTE, 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, IoxVideoComponent, LAST_EMITTED_STATES, LEGACY_DIRECTION_KEY, LEGACY_HOVER_TRANSITION, LEGACY_SWIPER_CONTROLS, LinkedContainerComponent, MANAGED_A11Y_ATTRIBUTES, MAX_LINES_KEY, NAMED_GROUP_ROLES, NO_PAGE_TRANSITION, ON_STATE_ROLES, PAGE_STYLE_TOKENS, PAGE_TOKEN_FALLBACKS, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PART_PAGINATION_MODIFIER, PHONE_TRANSITION_QUERY, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PageStyleField, PageStyleSource, REDUCED_MOTION_QUERY, SCROLL_EASINGS, SLIDER_INPUTS_ATTRIBUTE, SLIDER_INPUT_NAMES, STATE_PSEUDO_CLASS, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_A11Y_OPTIONS, SWIPER_RESPONSIVE_TRAITS, SWIPER_TRIGGER_EVENTS, ScrollEasing, SectionComponent, SwiperModuleName, TARGETED_STATE_SUFFIX, TEXT_ALIGN_KEY, TEXT_DIRECTION_KEY, TRANSITION_FEELS, TextAlign, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, VisibilityActionType, activeActions, applyBindingPipes, applyFeel, bootSlider, breakpointDef, breakpointForWidth, breakpointQueryFor, buildInteractionKeyframes, buildPartSelector, buildSwiperBreakpoints, buildTargetedStateSelector, buildTargetedSuffixSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, closeAboveMediaQuery, collectContextSlotKeys, compileDeclarations, compilePageStyle, componentStatesFor, composeVirtualTraits, containerHtmlTag, contextActionEffect, contextSlotKeys, countOverrides, declaredInputNames, decomposeBackdropFilter, defaultHoverTransition, defaultMessageResolver, deriveSeoFromContent, describePageStyle, describeSeoFields, dialogCloseAboveMinWidth, domHasSliderParts, effectiveActionType, effectiveTransitionId, entrancePreStateStyle, feelFor, finalKeyframe, getSeoValue, hasHoverState, hasOwnPageTransition, hasOwnTransition, initialSlotValues, isActionEnabled, isContextAction, isCurrentLink, isExternalOrFragment, isGradientPaint, isInputOverriddenAt, isLastEmittedStateKey, isOverriddenAt, isValidSlotKey, isWholeBackdropSet, keyframePropertyName, keyframeStyleEntries, legacyEnterToTransition, mediaQueryFor, mergeSwiperBreakpoints, migrateLegacyDirection, migrateLegacyTextAlign, motionAllowed, nearestCommonAncestorId, needsAccessibleName, needsGroupName, nodeA11yAttributes, nodeCssId, nodeTraitValue, nodeUsesContext, normalizeAppPath, normalizeGalleryImage, normalizeIconClass, orderStatesForEmit, pageTransitionOf, parentBreakpoint, parseUrlList, partClassName, planResponsiveRules, planScroll, planSwiperOptions, playDualLayerTransition, prefersReducedMotion, renderDefaultDeclarations, resetPageStyleField, resetSeoField, resolveBoundValue, resolveContextValue, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveSeo, resolveStateStyles, resolveStyleProps, resolveToggleVisibility, resolveValueChain, rewriteViewportUnits, safeSetInput, serializeA11yAttributes, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, sliderControlElements, sliderInputsFromProps, sliderInputsOf, stateNamesIn, statePseudoClass, stateSelectorSuffix, stripSuppressedProps, swiperAutoplayAllowed, swiperLoopOptions, swiperModuleNames, syncNodeA11yAttributes, targetedStateSelector, viewportTransitionContext, withContextSlots, withDefaultHoverTransition, wrapInBreakpointQuery, wrapInMediaQuery };
+export type { A11yNodeSource, BoundValueSpec, BreakpointDef, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, CurrentLinkOptions, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, InteractionKeyframe, IoxContextSlot, IoxPipe, MatchMediaHost, NodeA11yContext, OverrideBreakpoint, PageScrollStart, PageStyleFieldState, PageStyleOptions, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionContext, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, PlannedPageTransition, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteAnimationLike, ScrollPlanContext, SeoDerivedContent, SeoFieldSource, SeoFieldState, SeoResolveContext, SetContextParams, SliderBootOptions, SliderControlElements, SliderInputs, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, SwiperModuleFlags, SwiperPlan, SwiperPlanContext, ToggleableAction, TransitionFeel, TransitionPhase, TransitionPreviewLayers, TransitionTimelineInput, TransitionViewport, ValueSource, VirtualTraitGroup };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.46.0",
+  "version": "5.48.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
@@ -47,6 +47,10 @@
       "types": "./generation-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-generation-core.mjs"
     },
+    "./harness-core": {
+      "types": "./harness-core/index.d.ts",
+      "default": "./fesm2022/vectoriox-iox-ui-harness-core.mjs"
+    },
     "./media-core": {
       "types": "./media-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-media-core.mjs"

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

@@ -8,7 +8,7 @@ import {
 } from './flavor-seed';
 import { DesignChoices, DesignTokenRow, flavorSourceStamp, StoredDesignTokenRow } from './design-token.model';
 import { FONT_FAMILY_TOKENS, fontFamilyKey, FontFamilyToken, fontRoleReferences, parseFontFamilies, withoutScriptPartners } from './fonts';
-import { DesignConfigEntry, DesignConfigKey, designConfigEntries, flavorPackById, isRetiredFlavorId, packDesignChoices, StoredDesign } from './design-settings';
+import { DesignConfigEntry, DesignConfigKey, designConfigEntries, flavorPackById, isRetiredFlavorId, packDesignChoices, sameDesignChoices, StoredDesign } from './design-settings';
 
 /**
  * Applying a look (design-system DS4): the COMPLETE `buildFlavorTokens` set for the chosen
@@ -147,8 +147,10 @@ export interface DesignRevertSnapshot extends FlavorRevertSnapshot {
  * What an Apply of `plan` stores as its revert snapshot — the ONE rule the builder's Apply and the
  * server-side site build (W2) share: the whole pre-apply token set, what the apply writes into each row,
  * and where a revert goes back to — never a null flavor (a studio with no design row wore its design's
- * defaults, so that is what it returns to). An apply that writes nothing keeps the previous snapshot:
- * clobbering a useful one with "nothing changed" would be a lie.
+ * defaults, so that is what it returns to). An apply that changes NOTHING keeps the previous snapshot:
+ * clobbering a useful one with "nothing changed" would be a lie. A choice that lives in the config only
+ * (Scrolling · How animated · Between pages) IS a change — pass `next` so a motion-only Apply gets its own
+ * snapshot and Revert goes back to the motion worn just before it (vectoriox/iox-ui#28).
  */
 export function designApplySnapshot(
     previous: StoredDesign,
@@ -156,8 +158,10 @@ export function designApplySnapshot(
     existing: ReadonlyArray<StoredDesignTokenRow>,
     plan: FlavorSeedPlan,
     appliedAt: number,
+    next?: DesignChoices,
 ): DesignRevertSnapshot | null {
-    if (!plan.create.length && !plan.update.length) return previous.revert;
+    const wroteTokens = plan.create.length > 0 || plan.update.length > 0;
+    if (!wroteTokens && (!next || sameDesignChoices(previous.choices, next))) return previous.revert;
     const origin: Pick<DesignRevertSnapshot, 'from' | 'fromConfig'> = previous.storedFlavorId
         ? {
             from: { flavorId: previous.storedFlavorId, flavorVersion: previous.flavorVersion, brandSeed: previous.storedSeed },

package/src/generation-core/entrances.ts

@@ -0,0 +1,110 @@
+import { AnimateId, SPEC_AXES } from '@vectoriox/iox-ui/design-core';
+
+/**
+ * How animated (AI plan rev 3.1 §3p) — the ONE reading of the contract's `axes.animations` (what each level
+ * moves, how) and `axes.animationFamilies` (which parts a section family lets move). The pieces every stamper
+ * shares: the Design step's business specimen (H4-4) today, `planEntrances` in the composer (M1-6b) next. Pure.
+ *
+ * A level with `content` moves a section's content together, once; otherwise it names parts (heading, items,
+ * media…) and each part enters on its own, items one after another. Navigation, footers and globals are a family
+ * with no parts, so nothing there ever moves.
+ */
+
+export enum EntrancePart {
+    Content = 'content',
+    Heading = 'heading',
+    Items = 'items',
+    Media = 'media',
+    RowMedia = 'rowMedia',
+    HeroText = 'heroText',
+}
+
+/** What an entrance stamp is marked with — a later restamp touches only what the look made (H4-5). */
+export const ENTRANCE_ORIGIN_LOOK = 'look';
+/** The trigger every entrance plays on. */
+export const ENTRANCE_TRIGGER = 'viewportEnter';
+/** The easing every entrance plays with (only `opacity` and `transform` move). */
+export const ENTRANCE_EASING = 'ease-out';
+
+/** One entrance as the contract states it. */
+export interface EntranceSpec {
+    readonly type: string;
+    readonly duration: number;
+    readonly distance?: number;
+    /** Items: ms added per item, up to `cap` items. */
+    readonly stagger?: number;
+    readonly cap?: number;
+    /** The type a right-to-left page plays instead (a side-by-side row slides in from ITS side). */
+    readonly mirror?: string;
+}
+
+/** What one section family moves at one level. `content` set = the whole content together, and no parts. */
+export interface SectionEntrances {
+    readonly content: EntranceSpec | null;
+    readonly parts: Readonly<Partial<Record<EntrancePart, EntranceSpec>>>;
+}
+
+/** The interaction action a stamp carries — the shape both interaction runtimes play. */
+export interface EntranceAction {
+    type: string;
+    target: 'self';
+    duration: number;
+    delay: number;
+    easing: typeof ENTRANCE_EASING;
+    once: true;
+    params?: { distance: number };
+}
+
+export interface EntranceInteraction {
+    id: string;
+    trigger: typeof ENTRANCE_TRIGGER;
+    actions: [EntranceAction];
+    origin: typeof ENTRANCE_ORIGIN_LOOK;
+}
+
+type Level = Readonly<{ parts: Readonly<Partial<Record<EntrancePart, EntranceSpec>>> }>;
+const LEVELS = SPEC_AXES.animations as unknown as Readonly<Record<string, Level>>;
+const FAMILIES = SPEC_AXES.animationFamilies as unknown as Readonly<Record<string, ReadonlyArray<EntrancePart>>>;
+
+const NOTHING: SectionEntrances = { content: null, parts: {} };
+
+/** What a section of `family` moves at `level` — nothing for an unknown level or family. */
+export function sectionEntrances(level: AnimateId | string | null | undefined, family: string): SectionEntrances {
+    const lv = level ? LEVELS[level] : undefined;
+    const allow = FAMILIES[family] ?? [];
+    if (!lv || !allow.length) return NOTHING;
+    if (lv.parts.content && allow.includes(EntrancePart.Content)) return { content: lv.parts.content, parts: {} };
+    const parts: Partial<Record<EntrancePart, EntranceSpec>> = {};
+    for (const part of allow) {
+        if (part === EntrancePart.Content) continue;
+        // A level without its own side-by-side entrance gives a row's picture the plain picture one.
+        const spec = lv.parts[part] ?? (part === EntrancePart.RowMedia ? lv.parts.media : undefined);
+        if (spec) parts[part] = spec;
+    }
+    return { content: null, parts };
+}
+
+/** The literal delay of the `index`-th item: `stagger` ms each, the last `cap` waiting no longer than the one before. */
+export function staggerDelay(spec: EntranceSpec, index = 0): number {
+    if (!spec.stagger) return 0;
+    const cap = Math.max(1, spec.cap ?? 1);
+    return Math.min(Math.max(0, index), cap - 1) * spec.stagger;
+}
+
+/** The action a node plays: the spec's type (mirrored on a right-to-left page), its distance and its delay. */
+export function entranceAction(spec: EntranceSpec, opts: { index?: number; rtl?: boolean } = {}): EntranceAction {
+    return {
+        type: opts.rtl && spec.mirror ? spec.mirror : spec.type,
+        target: 'self',
+        duration: spec.duration,
+        delay: staggerDelay(spec, opts.index),
+        easing: ENTRANCE_EASING,
+        once: true,
+        ...(spec.distance ? { params: { distance: spec.distance } } : {}),
+    };
+}
+
+/** The stamp on a node: `viewportEnter`, once, on itself (a duplicated node needs no remap), from the look. */
+export function entranceInteraction(nodeId: string, action: EntranceAction): EntranceInteraction {
+    return { id: `${nodeId}-enter`, trigger: ENTRANCE_TRIGGER, actions: [action], origin: ENTRANCE_ORIGIN_LOOK };
+}

package/src/generation-core/plan-data.ts

@@ -0,0 +1,71 @@
+import { BindScope, patternById, patternNodes, patternScopes } from './patterns';
+import { CmsDataSourcePlan, DataSourcePlan, PagePlan, PlanDataSourceMode, PlanDataSourceType, SitePlan } from './site-plan.model';
+
+/**
+ * What each page of a plan shows and where its data comes from (AI plan rev 3 §3d, `describePlanData`) — the
+ * Plan step's data lines, in the vocabulary the builder already uses. Pure and STRUCTURED: the screen words
+ * each kind in its own language ("Lists every Project", "One Project, found by its address /work/:slug").
+ */
+
+export enum PageDataKind {
+    /** A section repeats every item of a content type. */
+    List = 'list',
+    /** A section repeats the newest `count` items. */
+    Latest = 'latest',
+    /** A template page: one item, found by its address — one page per item. */
+    One = 'one',
+    /** The next (or previous) item beside the page's own. */
+    Siblings = 'siblings',
+    /** A form: what it sends, to the studio's inbox (+ an email when Email is connected). */
+    Form = 'form',
+    /** Words and pictures, no data. */
+    Static = 'static',
+}
+
+export interface PageDataLine {
+    kind: PageDataKind;
+    /** The content type's label ("Projects"), for every kind that reads one. */
+    contentType?: string;
+    /** Latest: how many. */
+    count?: number;
+    /** One: the page's own address, with its parameter. */
+    route?: string;
+    /** Form: the form preset (`contact`). */
+    form?: string;
+}
+
+export interface PageData {
+    pageKey: string;
+    lines: PageDataLine[];
+}
+
+const sameLine = (a: PageDataLine, b: PageDataLine) => JSON.stringify(a) === JSON.stringify(b);
+
+function sourceLine(source: DataSourcePlan | undefined, label: (name: string) => string): PageDataLine | null {
+    if (!source || source.type !== PlanDataSourceType.Cms) return null;
+    const cms = source as CmsDataSourcePlan;
+    if (cms.mode !== PlanDataSourceMode.Query) return null;
+    return cms.limit
+        ? { kind: PageDataKind.Latest, contentType: label(cms.contentType), count: cms.limit }
+        : { kind: PageDataKind.List, contentType: label(cms.contentType) };
+}
+
+function pageLines(page: PagePlan, plan: SitePlan, label: (name: string) => string): PageDataLine[] {
+    const lines: PageDataLine[] = [];
+    const add = (line: PageDataLine | null) => { if (line && !lines.some(l => sameLine(l, line))) lines.push(line); };
+    if (page.template) add({ kind: PageDataKind.One, contentType: label(page.template), route: page.route });
+    for (const section of page.sections) {
+        const pattern = patternById(section.pattern);
+        if (!pattern) continue;
+        if (section.binding) add(sourceLine(plan.dataSources.find(d => d.alias === section.binding), label));
+        if (page.template && patternScopes(pattern).has(BindScope.Next)) add({ kind: PageDataKind.Siblings, contentType: label(page.template) });
+        for (const node of patternNodes(pattern)) if (node.preset) add({ kind: PageDataKind.Form, form: node.preset });
+    }
+    return lines.length ? lines : [{ kind: PageDataKind.Static }];
+}
+
+/** One entry per page of the plan, in plan order. */
+export function describePlanData(plan: SitePlan): PageData[] {
+    const label = (name: string) => plan.contentTypes.find(t => t.name === name)?.label ?? name;
+    return plan.pages.map(page => ({ pageKey: page.key, lines: pageLines(page, plan, label) }));
+}

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

@@ -17,6 +17,9 @@ export * from './site-plan.model';
 export * from './patterns';
 export * from './templates';
 export * from './serialized-node';
+export * from './shape-check';
 export * from './validate-site-plan';
 export * from './compose-site';
 export * from './nav-shape';
+export * from './entrances';
+export * from './plan-data';

package/src/generation-core/shape-check.ts

@@ -0,0 +1,92 @@
+/**
+ * The ONE way a framework-free gate refuses a document "with a path, never repairs" (W1's site-plan gate, the
+ * harness's analysis gate): a documented shape table (key → type text; `key?` optional, `[name]` the object's
+ * own field names) whose key lists the gate READS — so the shape a model is told about is the shape refused —
+ * and a collector that records each refusal at its dotted path. Generic over each gate's issue-code enum.
+ */
+
+export type ShapeEntry = Readonly<Record<string, string>>;
+export type PlainObject = Record<string, unknown>;
+
+const OPTIONAL_MARK = '?';
+const DYNAMIC_KEY = /^\[[^\]]+\]\??$/;
+const isDynamic = (key: string) => DYNAMIC_KEY.test(key);
+
+/** Every fixed key an object of the shape may carry. */
+export function shapeKeys(entry: ShapeEntry): string[] {
+    return Object.keys(entry).filter(k => !isDynamic(k)).map(k => (k.endsWith(OPTIONAL_MARK) ? k.slice(0, -1) : k));
+}
+
+/** The keys an object of the shape must carry. */
+export function requiredShapeKeys(entry: ShapeEntry): string[] {
+    return Object.keys(entry).filter(k => !isDynamic(k) && !k.endsWith(OPTIONAL_MARK));
+}
+
+export const isPlainObject = (v: unknown): v is PlainObject => !!v && typeof v === 'object' && !Array.isArray(v);
+export const isNonEmptyString = (v: unknown): v is string => typeof v === 'string' && v.trim() !== '';
+/** `path.key`, or `key` at the root. */
+export const pathAt = (path: string, key: string) => (path ? `${path}.${key}` : key);
+
+export interface PathIssue<C extends string> {
+    code: C;
+    /** Where, as a dotted path into the document (`pages[2].sections[0].binding`). */
+    path: string;
+    message: string;
+}
+
+/** The three refusals every shape gate shares, named in that gate's own code enum. */
+export interface ShapeIssueCodes<C extends string> {
+    /** A value of the wrong type, or a required value missing. */
+    shape: C;
+    /** A key the shape does not have. */
+    unknownKey: C;
+    /** A name used twice where it must be unique. */
+    duplicate: C;
+}
+
+export class PathIssueCollector<C extends string> {
+    readonly issues: PathIssue<C>[] = [];
+
+    /** `subject` names the document in a refusal ("… is not part of the plan shape"). */
+    constructor(private readonly subject: string, private readonly codes: ShapeIssueCodes<C>) {}
+
+    add(code: C, path: string, message: string): void {
+        this.issues.push({ code, path, message });
+    }
+
+    keys(obj: PlainObject, allowed: ReadonlyArray<string>, path: string): void {
+        for (const key of Object.keys(obj)) if (!allowed.includes(key)) this.add(this.codes.unknownKey, pathAt(path, key), `"${key}" is not part of the ${this.subject} shape`);
+    }
+
+    string(obj: PlainObject, key: string, path: string, required = true): string | null {
+        const v = obj[key];
+        if (v === undefined && !required) return null;
+        if (!isNonEmptyString(v)) {
+            this.add(this.codes.shape, pathAt(path, key), 'must be a non-empty string');
+            return null;
+        }
+        return v;
+    }
+
+    boolean(obj: PlainObject, key: string, path: string): void {
+        if (obj[key] !== undefined && typeof obj[key] !== 'boolean') this.add(this.codes.shape, pathAt(path, key), 'must be a boolean');
+    }
+
+    array(obj: PlainObject, key: string, path: string): unknown[] {
+        const v = obj[key];
+        if (!Array.isArray(v)) {
+            this.add(this.codes.shape, pathAt(path, key), 'must be an array');
+            return [];
+        }
+        return v;
+    }
+
+    unique(values: Array<string | null>, path: (i: number) => string, what: string): void {
+        const seen = new Set<string>();
+        values.forEach((v, i) => {
+            if (v === null) return;
+            if (seen.has(v)) this.add(this.codes.duplicate, path(i), `${what} "${v}" is used twice`);
+            seen.add(v);
+        });
+    }
+}

package/src/generation-core/site-spec.generated.ts

@@ -25,7 +25,7 @@ export const SPEC_SITE_PLAN_SHAPE = {
   "business": {
     "name": "string — the brand: the header, the hero, the copyright line",
     "tagline?": "string — the hero lead and the footer line",
-    "facts?": "{ [fact]: string } — facts (email, phone, city): only the customer's own words; a blank fact is a publish-blocking placeholder, never invented"
+    "facts?": "{ [fact]: string } — facts (email, phone, city, address, hours): only the customer's own words; a blank fact is a publish-blocking placeholder, never invented"
   },
   "design": {
     "flavorId": "string — a v2 flavor pack id",
@@ -104,7 +104,9 @@ export const SPEC_SITE_PLAN_SHAPE = {
 export const SPEC_SITE_FACTS = {
   "email": "Email address",
   "phone": "Phone number",
-  "city": "City or area"
+  "city": "City or area",
+  "address": "Street address",
+  "hours": "Opening hours"
 } as const;
 
 export const SPEC_SITE_PATTERNS = {
@@ -2052,3 +2054,130 @@ export const SPEC_SITE_TEMPLATES = {
     }
   }
 } as const;
+
+export const SPEC_SITE_LIBRARY = [
+  {
+    "id": "nav.inline-cta",
+    "family": "nav"
+  },
+  {
+    "id": "nav.centered-logo",
+    "family": "nav"
+  },
+  {
+    "id": "nav.overlay-menu",
+    "family": "nav"
+  },
+  {
+    "id": "hero.split",
+    "family": "hero"
+  },
+  {
+    "id": "hero.centered",
+    "family": "hero"
+  },
+  {
+    "id": "hero.full-bleed-media",
+    "family": "hero"
+  },
+  {
+    "id": "hero.stacked-editorial",
+    "family": "hero"
+  },
+  {
+    "id": "proof.logo-strip",
+    "family": "proof"
+  },
+  {
+    "id": "proof.stat-row",
+    "family": "proof"
+  },
+  {
+    "id": "proof.testimonial-single",
+    "family": "proof"
+  },
+  {
+    "id": "proof.testimonial-carousel",
+    "family": "proof"
+  },
+  {
+    "id": "feature.triad",
+    "family": "feature"
+  },
+  {
+    "id": "feature.alternating-rows",
+    "family": "feature"
+  },
+  {
+    "id": "feature.icon-list",
+    "family": "feature"
+  },
+  {
+    "id": "feature.tabbed",
+    "family": "feature"
+  },
+  {
+    "id": "collection.card-grid",
+    "family": "collection"
+  },
+  {
+    "id": "collection.masonry-gallery",
+    "family": "collection"
+  },
+  {
+    "id": "collection.slider",
+    "family": "collection"
+  },
+  {
+    "id": "collection.list-detail",
+    "family": "collection"
+  },
+  {
+    "id": "story.long-form",
+    "family": "story"
+  },
+  {
+    "id": "story.timeline",
+    "family": "story"
+  },
+  {
+    "id": "story.quote-break",
+    "family": "story"
+  },
+  {
+    "id": "cta.banner",
+    "family": "cta"
+  },
+  {
+    "id": "cta.split-form",
+    "family": "cta"
+  },
+  {
+    "id": "contact.split-map",
+    "family": "contact"
+  },
+  {
+    "id": "contact.simple",
+    "family": "contact"
+  },
+  {
+    "id": "faq.accordion",
+    "family": "faq"
+  },
+  {
+    "id": "pricing.tiers",
+    "family": "pricing"
+  },
+  {
+    "id": "footer.three-column",
+    "family": "footer"
+  },
+  {
+    "id": "footer.mega",
+    "family": "footer"
+  },
+  {
+    "id": "footer.minimal",
+    "family": "footer"
+  }
+] as const;