@vectoriox/iox-ui 5.42.0 → 5.44.0

package/data-core/index.d.ts

@@ -0,0 +1,360 @@
+/**
+ * Shared data-source resolving pattern — the SINGLE source of truth for how an IoxDataSource
+ * becomes a backend fetch, consumed by BOTH the page builder (iox-cms-client bindings panel) and
+ * the SSR client engine (iox-client-engine DataSourceResolverService). There must be no second
+ * copy of this decision logic; only the transport differs between the two:
+ *
+ *   builder → authenticated org-scoped controllers (admin session):
+ *              single by id → GET admin.../resources/:type/:id   (ContentService.getContentById)
+ *              collection    → GET admin.../resources/:type        (ContentService.getContent)
+ *   engine  → @Public() controllers (no auth, isPublished filter applied server-side):
+ *              single by id → GET api/:type/:id                    (UserResourcesController)
+ *              collection    → GET api/:type?filters                (UserResourcesController)
+ *
+ * The DECISION (by-id vs collection, which id, which filters, how to pick the single result) is
+ * identical for both — that's what this module owns. Each app maps the returned {@link DataSourcePlan}
+ * onto its own transport. A single item is ALWAYS fetched by its id as a path segment — never a
+ * `?_id=` query — to match the builder's getContentById.
+ */
+type DataSourceMode = 'single' | 'list';
+type DataSourceDomain = 'cms' | 'shop';
+interface DataSourceRouteFilter {
+    field?: string;
+    routeParam?: string;
+    defaultId?: string;
+}
+interface DataSourceQueryFilter {
+    field?: string;
+    /** URL query param the value is read from. OMIT for a CONSTANT filter — then `defaultValue`
+     *  alone is the value, so `isReviewShow=true` filters identically in preview and on the site. */
+    queryParam?: string;
+    /** Value used when the query param is absent — i.e. always, for a constant filter, and in the
+     *  builder preview, where there are no live query params. NOT preview-only: it is the runtime
+     *  fallback too. An empty default with no query-param value means the filter is DROPPED. */
+    defaultValue?: string;
+}
+/** The order a query source returns its rows in (CC2, board 4 "Sort" — the data source popover). */
+declare enum DataSourceSortDir {
+    Asc = "asc",
+    Desc = "desc"
+}
+interface DataSourceSort {
+    /** A field of the content type (a dot path into a nested object is allowed). */
+    field?: string;
+    dir?: DataSourceSortDir | `${DataSourceSortDir}`;
+}
+/** The query parameter carrying the order: `sort=order` ascending, `sort=-order` descending. A CONTROL like
+ *  `limit`, not a field filter — the public controllers split it out (iox-cms `query-controls.ts`). */
+declare const SORT_PARAM = "sort";
+/** `sort`'s wire value, or null when the source sets no (valid) order. */
+declare function sortParamValue(sort: DataSourceSort | null | undefined): string | null;
+interface DataSourceRequestSpec {
+    contentType?: string;
+    limit?: number;
+    /** A query source's order (CC2). Absent = the backend's natural order, as before. */
+    sort?: DataSourceSort;
+    filterByRouteParam?: DataSourceRouteFilter;
+    filterByQueryParams?: DataSourceQueryFilter[];
+}
+/** Structural (duck-typed) view of an IoxDataSource — kept free of the editor model so both libs
+ *  can depend on it without pulling in iox-builder. */
+interface DataSourceSpec {
+    alias?: string;
+    type?: string;
+    mode?: DataSourceMode;
+    request?: {
+        cms?: DataSourceRequestSpec;
+        shop?: DataSourceRequestSpec;
+        endpoint?: string;
+        data?: any;
+        /** `derived` alias: a VIEW into another variable — resolve `from` then getByPath(value, path)
+         *  (e.g. galleryImages = product.gallery). See repeater-binding-ux-plan.md. */
+        derived?: {
+            from: string;
+            path: string;
+        };
+    };
+}
+type DataSourcePlan = {
+    kind: 'by-id';
+    domain: DataSourceDomain;
+    resource: string;
+    id: string;
+    mode: DataSourceMode;
+} | {
+    kind: 'collection';
+    domain: DataSourceDomain;
+    resource: string;
+    filter: Record<string, any>;
+    limit?: number;
+    sort?: string;
+    mode: DataSourceMode;
+} | {
+    kind: 'external';
+    endpoint: string;
+    mode: DataSourceMode;
+} | {
+    kind: 'static';
+    data: any;
+    mode: DataSourceMode;
+} | {
+    kind: 'derived';
+    from: string;
+    path: string;
+    mode: DataSourceMode;
+} | {
+    kind: 'none';
+};
+/**
+ * Match a page route template against an actual path and extract named params.
+ *   matchRouteParams('/project/:projectId', 'project/68abc') → { projectId: '68abc' }
+ * Both sides are normalised (leading slash stripped) and split on '/'; values are URL-decoded.
+ */
+declare function matchRouteParams(template: string | undefined, actual: string | undefined): Record<string, string>;
+/**
+ * Build the query filter for a data-source request from its filterByRouteParam / filterByQueryParams
+ * config. `field` is filtered by the route-param value (falling back to `defaultId`); query filters
+ * map each `field` to a query-param value (falling back to `defaultValue`), and a filter with NO
+ * `queryParam` is a constant on `defaultValue`. Empty values are omitted so the source isn't
+ * accidentally filtered to nothing.
+ */
+declare function buildDataSourceFilter(req: DataSourceRequestSpec | undefined, routeParams?: Record<string, any>, queryParams?: Record<string, any>): Record<string, any>;
+/**
+ * Mirrors the builder's getContentById decision. When a SINGLE source is filtered by the item id
+ * (`_id`) via a route param, the item is fetched by PATH (`.../:type/:id`), not a `?_id=` query.
+ * Returns that id (route-param value, else `defaultId`), or `null` when the source isn't a
+ * single-by-id fetch — in which case the caller uses the collection endpoint + filters. The
+ * path-based form only applies to the id field; a single source filtered by any other field still
+ * goes through the collection endpoint.
+ */
+declare function resolveSingleItemId(req: DataSourceRequestSpec | undefined, routeParams?: Record<string, any>): string | null;
+/**
+ * Resolve an IoxDataSource into a transport-agnostic {@link DataSourcePlan}. This is the shared
+ * decision both the builder and the SSR engine run; each then executes the plan with its own
+ * HTTP layer. Single sources with a route-param id resolve to a `by-id` (path) fetch — exactly like
+ * the builder's getContentById.
+ */
+declare function planDataSource(ds: DataSourceSpec | undefined, routeParams?: Record<string, any>, queryParams?: Record<string, any>): DataSourcePlan;
+/**
+ * The aliases on a page that are VARIABLES — runtime-written resources, not fetched data.
+ *
+ * Shared so the builder and the SSR engine agree on which aliases start empty and are filled by
+ * interactions. See element-context-state-plan.md.
+ */
+declare function variableAliases(dataSources: readonly {
+    alias?: string;
+    type?: string;
+}[] | undefined): Set<string>;
+/** The source alias whose items a variable holds, if it declares one (for field suggestions). */
+declare function variableItemsFrom(dataSources: readonly {
+    alias?: string;
+    type?: string;
+    request?: any;
+}[] | undefined, alias: string): string | undefined;
+/**
+ * Normalise a collection response into the shape a source expects: unwraps `{items}`/`{data}`
+ * envelopes, then returns the first item for a `single` source or the whole array for a `list`.
+ * A `by-id` response is already the item, so callers pass it through unchanged.
+ */
+declare function normalizeCollectionResult(mode: DataSourceMode, data: any): any;
+/** Navigate a dot/bracket path into an object, e.g. `gallery`, `details.images`, `variants[0].skus`.
+ *  Returns undefined if any segment is missing. Kept minimal + self-contained so it is shareable by
+ *  both the builder and the SSR engine (the two have divergent local `resolvePath` copies). */
+declare function getByPath(obj: any, path: string): any;
+/**
+ * The array a Repeater (or a repeating Slider) iterates over — the SHARED decision so the builder
+ * canvas and the SSR engine agree (see data-source-resolving.md).
+ * - No `sourcePath`: the resolved source IS the list. An array passes through; a lone object degrades
+ *   to a single-row list (back-compat with the old `fetchItems`); null/undefined → `[]`.
+ * - With `sourcePath`: the source resolved to a SINGLE resource (e.g. a product); dive into the
+ *   nested array property (e.g. `gallery`). Non-array / missing → `[]`.
+ */
+/**
+ * Fill in `derived` aliases in an already-resolved map. Given the data sources and a map of resolved
+ * NON-derived values (by alias), compute each `type:'derived'` alias as `getByPath(parent, path)` in
+ * dependency order (chains resolved by iterating until stable). Mutates + returns the map. Used by the
+ * SSR engine after it resolves the root sources; the builder resolves derived lazily per alias.
+ */
+declare function resolveDerivedInto(dataSources: DataSourceSpec[], resolved: Record<string, any>): Record<string, any>;
+declare function resolveRepeaterItems(resolved: any, sourcePath?: string | null): any[];
+/** Aliases referenced anywhere in a node tree: a repeater/slider `source` (a `bindings` entry with
+ *  `prop === 'source'`, or `props.source` for the slider) plus every binding's `source`. */
+declare function collectReferencedAliases(nodes: any[], acc?: Set<string>): Set<string>;
+/** The subset of `all` whose `alias` is referenced by `nodes` (shallow — direct references only). */
+declare function referencedDataSources(nodes: any[], all: any[]): any[];
+/** Like `referencedDataSources`, but also pulls in a referenced source's DEPENDENCIES (transitively),
+ *  none of which the layout names directly:
+ *   - a `derived` alias needs its `request.derived.from` parent;
+ *   - a `relative` (route-context) alias needs its `request.relative.subjectFrom` (the current item)
+ *     and `request.relative.from` (the collection it navigates).
+ *  Use this when RESOLVING (the engine) so derived views and siblings/related don't resolve to nothing. */
+declare function referencedDataSourcesDeep(nodes: any[], all: any[]): any[];
+/** Base URLs for the PUBLIC content controllers. Both must end with `/`. The builder and the SSR
+ *  engine pass their own host (they proxy `/api` differently) but MUST target the public
+ *  (`@Public()`) controllers, never the authed admin ones — data resolving is storefront data. */
+interface DataSourceEndpoints {
+    /** cms resources, e.g. `${HOST}` (engine, HOST ends `/api/`) or `${HOST}api/` (builder). */
+    cmsBase: string;
+    /** shop resources, e.g. `${HOST}shop/` (engine) or `${HOST}api/shop/` (builder). */
+    shopBase: string;
+}
+interface DataSourceRequest {
+    url: string;
+    params: Record<string, any>;
+}
+/**
+ * Turn a resolved {@link DataSourcePlan} into the concrete public HTTP request (url + params) — the
+ * SINGLE place that decides the URL shape, shared by the builder binding preview and the SSR engine
+ * so both hit the SAME public endpoints (no admin, no duplication). Returns `null` for `static` /
+ * `none` plans (no HTTP call). A single item is a PATH segment (`/:resource/:id`), never `?_id=`.
+ */
+declare function dataSourcePlanToRequest(plan: DataSourcePlan, endpoints: DataSourceEndpoints): DataSourceRequest | null;
+
+/**
+ * Shared RELATIVE (route-context) data resolving — the SINGLE source of truth for how a detail page
+ * derives values FROM its current route item, consumed by BOTH the page builder (iox-cms-client) and
+ * the SSR client engine (iox-client-engine). Companion to `data-source-resolver.ts`.
+ *
+ * These are the pure, transport-agnostic pieces behind the Route binding scope
+ * (`$route` / `$current` / `$siblings` / `$related`). Resolution is a DEPENDENT SECOND PASS: the
+ * consumer resolves `$current` first (the existing single by-id fetch via `planDataSource`), then
+ * calls these to derive the relative values — there is NO new `DataSourcePlan` kind (`$related` still
+ * feeds a normal `collection` plan built from {@link buildRelatedFilter}). See
+ * `architecture/builder/relative-data-sources-plan.md`.
+ *
+ * There must be no second copy of this decision logic; only the transport (which HTTP layer fetches
+ * the ordered collection / related list) differs between the two consumers.
+ */
+/** Aliases in the Route scope are platform-owned and start with this prefix; a USER alias may never
+ *  start with it, which keeps the Route scope structurally collision-proof with Local/Global. Used to
+ *  validate new/renamed aliases and to render the reserved (read-only) item state in the bind picker. */
+declare const RESERVED_ALIAS_PREFIX = "$";
+/** True for a platform-owned Route-scope alias (`$route`, `$current`, `$siblings`, `$related`, …). */
+declare function isReservedAlias(alias: string | null | undefined): boolean;
+/** The `$siblings` value: the current item's neighbours within an ordered set. */
+interface SiblingsResult<T = any> {
+    /** The item before the current one (`null` at the start, unless `wrap`). */
+    prev: T | null;
+    /** The item after the current one (`null` at the end, unless `wrap`). */
+    next: T | null;
+    /** Zero-based position of the current item in the ordered set; `-1` when not found. */
+    index: number;
+    /** Total items in the set. */
+    count: number;
+    /** `true` when the current item is the first in the set. */
+    isFirst: boolean;
+    /** `true` when the current item is the last in the set. */
+    isLast: boolean;
+}
+interface ResolveSiblingsOptions {
+    /** Field identifying the current item within the list. Default `_id`. */
+    idField?: string;
+    /** Dot/bracket path to sort by BEFORE locating neighbours (e.g. `order`, `date`). Omit to use the
+     *  list's existing order. The same item neighbours differently per ordering, so this is the one
+     *  choice `$siblings` requires. */
+    sortBy?: string;
+    /** Sort direction when `sortBy` is set. Default `asc`. */
+    sortDir?: 'asc' | 'desc';
+    /** Wrap around the ends (`last.next` → first, `first.prev` → last). Only applies when `count > 1`.
+     *  Default `false`. */
+    wrap?: boolean;
+}
+/**
+ * Locate the current item within an ordered set and return its neighbours + position. Pure: the input
+ * list is never mutated (sorting works on a shallow copy). `currentId` is compared to each item's
+ * `idField` via string equality (route-param values are strings). When the current id isn't found,
+ * `index` is `-1` and `prev`/`next` are `null` (but `count` still reflects the set size).
+ */
+declare function resolveSiblings<T = any>(items: T[] | null | undefined, currentId: string | number | null | undefined, options?: ResolveSiblingsOptions): SiblingsResult<T>;
+interface BuildRelatedFilterOptions {
+    /** Field(s) on the current item whose value(s) the related items must match (e.g. `category`,
+     *  or `['category', 'brand']`). Each contributes an equality filter on that field. */
+    matchFields: string | string[];
+}
+/**
+ * Build the collection filter for `$related` from the resolved current item: an equality match on
+ * each `matchField`'s value (e.g. same `category`). Feeds a normal `collection` plan — no new plan
+ * kind. Fields whose value is not a scalar (or is empty) are omitted, matching
+ * `buildDataSourceFilter`'s "don't over-filter" rule. Exclude-self is applied to the RESULT via
+ * {@link excludeSelf} (the public query controllers are equality-only, so it can't be a `$ne` param).
+ */
+declare function buildRelatedFilter(current: any, options: BuildRelatedFilterOptions): Record<string, any>;
+/**
+ * Drop the current item from a list by `idField` (default `_id`). Used to exclude self from a
+ * `$related` result after fetch. A nullish/empty `currentId` leaves the list unchanged.
+ */
+declare function excludeSelf<T = any>(items: T[] | null | undefined, currentId: string | number | null | undefined, idField?: string): T[];
+/** The resolved Route-scope context bound values read from (`$route.projectId`, `$current.title`,
+ *  `$siblings.next`, `$related`). Assembled by each consumer during its dependent second pass. */
+interface RouteContext {
+    /** Route path params for the current URL (from `matchRouteParams`). */
+    $route: Record<string, string>;
+    /** The resolved current item (the page's single by-id source). */
+    $current: any;
+    /** Neighbours of the current item within a chosen ordered set. */
+    $siblings?: SiblingsResult;
+    /** Items related to the current one (same-attribute), excluding self. */
+    $related?: any[];
+}
+type RelativeSourceKind = 'route' | 'current' | 'siblings' | 'related';
+interface RelativeSourceSpec {
+    kind: RelativeSourceKind;
+    /** The source alias this derives from: for `current` the subject single-source; for
+     *  `siblings`/`related` the COLLECTION alias to locate within / search. Unused for `route`. */
+    from?: string;
+    /** `siblings`/`related`: the SUBJECT source alias (the current item) whose id / field values drive
+     *  the computation. Defaults to `from` when omitted. May reference `$current`. */
+    subjectFrom?: string;
+    /** Field identifying an item. Default `_id`. */
+    idField?: string;
+    /** `siblings`: sort the set before locating neighbours. */
+    sortBy?: string;
+    sortDir?: 'asc' | 'desc';
+    wrap?: boolean;
+    /** `siblings`: resolve to a SINGLE neighbour ITEM (`next`/`prev`) instead of the whole
+     *  `{prev,next,index,count,…}` object — so a source can be named e.g. `nextProject` and bound
+     *  directly (`nextProject.route`). Omit for the whole-object shape. */
+    pick?: 'next' | 'prev';
+    /** `related`: field(s) on the subject the results must match. */
+    matchFields?: string | string[];
+    /** `related`: drop the subject from its own results. Default `true`. */
+    excludeSelf?: boolean;
+}
+/** Duck-typed view of a data source carrying an optional relative descriptor (avoids a hard dep on
+ *  the full editor model / a circular type import). */
+interface RelativeCapableSource {
+    alias?: string;
+    type?: string;
+    request?: {
+        relative?: RelativeSourceSpec;
+    };
+}
+/** The already-resolved inputs a single relative source computes from. Assembled by each consumer:
+ *  the batch pass reads them from the resolved map; the builder resolves them async per alias. */
+interface RelativeInputs {
+    /** The subject item (the current resource) — for `current`/`siblings`/`related`. */
+    subject?: any;
+    /** The collection to locate within / search — for `siblings`/`related`. */
+    collection?: any;
+    /** Route path params — for `route`. */
+    routeParams?: Record<string, any>;
+}
+/**
+ * Compute ONE relative source's value from its already-resolved {@link RelativeInputs} — the SHARED
+ * kind→computation decision, so the batch pass ({@link resolveRelativeInto}) and the builder's async
+ * per-alias resolver produce identical results with no forked switch. `route` → the route params;
+ * `current` → the subject; `siblings` → {@link resolveSiblings} over the collection; `related` → the
+ * collection filtered by {@link buildRelatedFilter}'s predicate (+ {@link excludeSelf}).
+ */
+declare function computeRelative(spec: RelativeSourceSpec, inputs: RelativeInputs): any;
+/**
+ * Compute every `type:'relative'` source into `resolved` (keyed by alias), IN PLACE. Pure w.r.t. HTTP
+ * — it only reads already-resolved roots + the route params, so both consumers run it identically as
+ * a second pass. Delegates each source to {@link computeRelative}. `current`'s subject is `from`;
+ * `siblings`/`related` take `collection` = `from` and `subject` = `subjectFrom ?? from`. Mutates and
+ * returns `resolved`.
+ */
+declare function resolveRelativeInto(dataSources: RelativeCapableSource[], resolved: Record<string, any>, routeParams?: Record<string, any>): Record<string, any>;
+
+export { DataSourceSortDir, RESERVED_ALIAS_PREFIX, SORT_PARAM, buildDataSourceFilter, buildRelatedFilter, collectReferencedAliases, computeRelative, dataSourcePlanToRequest, excludeSelf, getByPath, isReservedAlias, matchRouteParams, normalizeCollectionResult, planDataSource, referencedDataSources, referencedDataSourcesDeep, resolveDerivedInto, resolveRelativeInto, resolveRepeaterItems, resolveSiblings, resolveSingleItemId, sortParamValue, variableAliases, variableItemsFrom };
+export type { BuildRelatedFilterOptions, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSort, DataSourceSpec, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, RouteContext, SiblingsResult };

package/data-core/package.json

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

package/design-core/index.d.ts

@@ -1173,6 +1173,170 @@ declare const SPEC_AXES: {
             };
         };
     };
+    readonly scrolls: {
+        readonly normal: {
+            readonly label: "Normal";
+            readonly he: "רגילה";
+            readonly hint: "The browser's own scrolling.";
+            readonly lenis: null;
+        };
+        readonly smooth: {
+            readonly label: "Smooth";
+            readonly he: "חלקה";
+            readonly hint: "A short glide after each wheel turn — what every IOX site does today.";
+            readonly lenis: {
+                readonly duration: 1.2;
+                readonly easing: "expo-out";
+                readonly wheelMultiplier: 1;
+                readonly syncTouch: false;
+            };
+        };
+        readonly extra: {
+            readonly label: "Extra smooth";
+            readonly he: "חלקה מאוד";
+            readonly hint: "A longer, softer glide; each wheel turn moves a little less.";
+            readonly lenis: {
+                readonly duration: 1.8;
+                readonly easing: "expo-out";
+                readonly wheelMultiplier: 0.9;
+                readonly syncTouch: false;
+            };
+        };
+    };
+    readonly animations: {
+        readonly still: {
+            readonly label: "Still";
+            readonly he: "ללא";
+            readonly hint: "Nothing moves in as you scroll. Buttons and cards still respond to the pointer (Speed).";
+            readonly parts: {};
+        };
+        readonly subtle: {
+            readonly label: "Subtle";
+            readonly he: "עדינה";
+            readonly hint: "Each section's content fades in once, together.";
+            readonly parts: {
+                readonly content: {
+                    readonly type: "fadeIn";
+                    readonly duration: 500;
+                };
+            };
+        };
+        readonly standard: {
+            readonly label: "Standard";
+            readonly he: "רגילה";
+            readonly hint: "Headings rise in; cards, prices and steps follow one after another.";
+            readonly parts: {
+                readonly heading: {
+                    readonly type: "moveUp";
+                    readonly distance: 16;
+                    readonly duration: 500;
+                };
+                readonly items: {
+                    readonly type: "moveUp";
+                    readonly distance: 16;
+                    readonly duration: 450;
+                    readonly stagger: 80;
+                    readonly cap: 6;
+                };
+                readonly media: {
+                    readonly type: "fadeIn";
+                    readonly duration: 600;
+                };
+            };
+        };
+        readonly lively: {
+            readonly label: "Lively";
+            readonly he: "תוססת";
+            readonly hint: "Bigger, longer entrances; side-by-side rows slide in from their side; the hero's words fade in.";
+            readonly parts: {
+                readonly heroText: {
+                    readonly type: "fadeIn";
+                    readonly duration: 400;
+                };
+                readonly heading: {
+                    readonly type: "moveUp";
+                    readonly distance: 24;
+                    readonly duration: 600;
+                };
+                readonly items: {
+                    readonly type: "moveUp";
+                    readonly distance: 24;
+                    readonly duration: 600;
+                    readonly stagger: 100;
+                    readonly cap: 8;
+                };
+                readonly media: {
+                    readonly type: "fadeIn";
+                    readonly duration: 700;
+                };
+                readonly rowMedia: {
+                    readonly type: "moveLeft";
+                    readonly mirror: "moveRight";
+                    readonly distance: 24;
+                    readonly duration: 600;
+                };
+            };
+        };
+    };
+    readonly animationFamilies: {
+        readonly nav: readonly [];
+        readonly footer: readonly [];
+        readonly hero: readonly ["heroText"];
+        readonly header: readonly ["heading"];
+        readonly detail: readonly ["heading", "media"];
+        readonly proof: readonly ["content", "heading", "items"];
+        readonly feature: readonly ["content", "heading", "items", "media", "rowMedia"];
+        readonly collection: readonly ["content", "heading", "items"];
+        readonly story: readonly ["content", "heading", "media"];
+        readonly cta: readonly ["content", "heading"];
+        readonly contact: readonly ["content", "heading"];
+        readonly faq: readonly ["content", "heading"];
+        readonly pricing: readonly ["content", "heading", "items"];
+    };
+    readonly betweens: {
+        readonly none: {
+            readonly label: "None";
+            readonly he: "ללא";
+            readonly hint: "The next page simply appears.";
+            readonly transition: "none";
+        };
+        readonly fade: {
+            readonly label: "Fade";
+            readonly he: "דהייה";
+            readonly hint: "The page fades into the next.";
+            readonly transition: "fade";
+            readonly feel: "snappy";
+        };
+        readonly slide: {
+            readonly label: "Slide";
+            readonly he: "החלקה";
+            readonly hint: "The next page pushes this one aside (from the left on a Hebrew site). On phones: Fade.";
+            readonly transition: "move-left";
+            readonly rtl: "move-right";
+            readonly feel: "smooth";
+            readonly phone: "fade";
+        };
+        readonly cinematic: {
+            readonly label: "Cinematic";
+            readonly he: "קולנועית";
+            readonly hint: "This page sinks back while the next rises over it. On phones: Fade.";
+            readonly transition: "parallax-up";
+            readonly feel: "cinematic";
+            readonly phone: "fade";
+        };
+    };
+    readonly motionChoices: {
+        readonly pre: {
+            readonly scroll: "smooth";
+            readonly animate: "still";
+            readonly between: "cinematic";
+        };
+        readonly reduced: {
+            readonly scroll: "normal";
+            readonly animate: "still";
+            readonly between: "none";
+        };
+    };
 };
 declare const SPEC_SPRINGS: {
     readonly lively: {
@@ -11992,6 +12156,25 @@ type TintId = keyof typeof SPEC_AXES.tints;
 declare const TINT_IDS: ReadonlyArray<TintId>;
 /** What a studio that stored its look BEFORE the tint existed wears: exactly the look's own palette. */
 declare const PRE_TINT_DEFAULT: TintId;
+/** How the site scrolls (AI plan rev 3.1 §3p): Normal (the browser's own) · Smooth · Extra smooth. */
+type ScrollId = keyof typeof SPEC_AXES.scrolls;
+/** How much the sections move in as they scroll into view: Still · Subtle · Standard · Lively. */
+type AnimateId = keyof typeof SPEC_AXES.animations;
+/** What plays between pages: None · Fade · Slide · Cinematic. */
+type BetweenId = keyof typeof SPEC_AXES.betweens;
+declare const SCROLL_IDS: ReadonlyArray<ScrollId>;
+declare const ANIMATE_IDS: ReadonlyArray<AnimateId>;
+declare const BETWEEN_IDS: ReadonlyArray<BetweenId>;
+/** The look's motion — the three choices the runtime and the composer read from `settings.design`. */
+interface DesignMotion {
+    scroll: ScrollId;
+    animate: AnimateId;
+    between: BetweenId;
+}
+/** What a look stored BEFORE rev 3.1 wears: exactly what every live site did (Smooth · Still · Cinematic). */
+declare const PRE_MOTION: Readonly<DesignMotion>;
+/** What a visitor who asks for reduced motion always gets, whatever the look chose. */
+declare const REDUCED_DESIGN_MOTION: Readonly<DesignMotion>;
 type SchemeId = keyof typeof SPEC_SCHEMES;
 type FontRoleToken = (typeof SPEC_FONT_ROLES)[number]['token'];
 /** Everything a studio chose about its look — the `settings.design` row, typed. */
@@ -12008,6 +12191,10 @@ interface DesignChoices {
      *  `neutral` — the palette it was applied with. */
     tint?: TintId;
     fonts?: Partial<Record<FontRoleToken, string>>;
+    /** Absent = `PRE_MOTION` (a row stored before rev 3.1 reads what its site already did). */
+    scroll?: ScrollId;
+    animate?: AnimateId;
+    between?: BetweenId;
 }
 interface FlavorSpecToken {
     readonly name: string;
@@ -13293,6 +13480,9 @@ declare enum DesignConfigKey {
     Mode = "mode",
     Tint = "tint",
     Fonts = "fonts",
+    Scroll = "scroll",
+    Animate = "animate",
+    Between = "between",
     Revert = "revert"
 }
 /** A stored design, resolved: `choices` is ALWAYS complete and valid (pack defaults fill the gaps). */
@@ -13316,12 +13506,15 @@ declare function isRetiredFlavorId(id: string | null | undefined): boolean;
  * the pack's own default (an unknown pair → the pack's first, a bad seed → the pack's seed).
  */
 declare function resolveDesignChoices(partial: Partial<DesignChoices> | null | undefined): DesignChoices;
+/** The look's motion, completed: an absent or unknown choice reads `PRE_MOTION` — what the site already does. */
+declare function resolveDesignMotion(partial: Readonly<Partial<Record<keyof DesignMotion, unknown>>> | null | undefined): DesignMotion;
 /** The pack's own defaults for `flavorId` — what picking a card means before anything is tuned. */
 declare function packDesignChoices(flavorId: string): DesignChoices;
 /**
  * What picking a pack card means, given the design the studio wears: the applied pack → the applied
  * choices; another pack → that pack's defaults, CARRYING the author's chosen fonts (§5b — a font the
- * author chose survives a pack switch unless the author changes it). Both picker homes call this.
+ * author chose survives a pack switch unless the author changes it) and the site's motion (rev 3.1 MO-D3 —
+ * how it scrolls and changes page is not a pack's, so a Look pick never resets it). Both picker homes call this.
  */
 declare function choicesForPack(flavorId: string, applied: DesignChoices | null | undefined): DesignChoices;
 /**
@@ -13332,6 +13525,8 @@ declare function choicesForPack(flavorId: string, applied: DesignChoices | null
 declare function readDesignConfig(config: ReadonlyArray<DesignConfigEntry> | null | undefined, hasRow?: boolean): StoredDesign;
 /** The colour mode a stored config compiles in — what the public page read hands the engine. */
 declare function designModeOf(config: ReadonlyArray<DesignConfigEntry> | null | undefined): DesignMode;
+/** The look's motion of a stored config — what the public page read hands the engine (`designMotion`). */
+declare function designMotionOf(config: ReadonlyArray<DesignConfigEntry> | null | undefined): DesignMotion;
 /** Resolved choices (+ the revert snapshot) → the config array a settings row stores. */
 declare function designConfigEntries(choices: DesignChoices, flavorVersion: string | number, revert?: FlavorRevertSnapshot | null): DesignConfigEntry[];
 /** Two choice sets describe the same look (fonts compared by role). */
@@ -13375,6 +13570,23 @@ declare function planDesignApply(existing: ReadonlyArray<StoredDesignTokenRow>,
  * `null` when the design holds no snapshot.
  */
 declare function planDesignRevert(current: ReadonlyArray<StoredDesignTokenRow>, design: StoredDesign): FlavorRevertPlan | null;
+/** The revert snapshot an Apply stores in `settings.design` (board F7): design-core's snapshot plus the design
+ *  row's previous config VERBATIM, so a revert restores every choice (pair, axes, mode, fonts), not only the
+ *  flavor id and seed. */
+interface DesignRevertSnapshot extends FlavorRevertSnapshot {
+    fromConfig?: DesignConfigEntry[];
+}
+/**
+ * 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.
+ */
+declare function designApplySnapshot(previous: StoredDesign, previousConfig: ReadonlyArray<DesignConfigEntry> | null | undefined, existing: ReadonlyArray<StoredDesignTokenRow>, plan: FlavorSeedPlan, appliedAt: number): DesignRevertSnapshot | null;
+/** The config a revert puts back: the snapshot's verbatim config, else (a snapshot older than `fromConfig`)
+ *  the identity it recorded. */
+declare function designRevertConfig(snapshot: DesignRevertSnapshot): DesignConfigEntry[];
 /** The rows a design is missing by name — the builder-load top-up (never touches an existing row). */
 declare function missingDesignRows(existing: ReadonlyArray<{
     name: string;
@@ -13439,5 +13651,5 @@ interface FontFamilyRemoval {
  */
 declare function planFontFamilyRemoval(existing: ReadonlyArray<StoredDesignTokenRow>, previous: StoredDesign, family: string): FontFamilyRemoval;
 
-export { ACCENT_TOKEN_NAMES, AdoptOutcome, AdoptSkipReason, BAR_RESERVE_BREAKPOINTS, BAR_RESERVE_CLASS, BOTTOM_BAR_STYLE, BUTTON_VARIANT_TO_STYLE, CANVAS_LINK_ATTRIBUTE, CARD_LINK_CLASS, COLOR_SCHEMES, COLOR_SCHEME_TRAIT, COLOR_SCHEME_TYPES, ColorScheme, ColourCheckId, DEFAULT_FLAVOR_ID, DESIGN_TOKEN_GROUPS, DESIGN_TOKEN_TIERS, DESIGN_TOKEN_TYPES, DesignConfigKey, ELEMENT_STYLES, ELEMENT_STYLE_MARKER_CLASS, ELEMENT_STYLE_STATES, EMPTY_IMAGE_ATTRIBUTE, EMPTY_IMAGE_SRC, ElementStyleState, FLAVOR_SPEC_VERSION, FONT_CATALOG, FONT_FAMILY_TOKENS, FONT_FILE_ACCEPT, FONT_FILE_EXTENSIONS, FONT_FILE_FORMATS, FONT_STYLES, FONT_WEIGHTS, FontUploadError, GOOGLE_FONTS_CSS_ORIGIN, GOOGLE_FONTS_FILE_ORIGIN, HELD_CONTRAST, INHERITED_TEXT, LinkType, MAX_FONT_FILE_BYTES, NEW_NODE_STYLE_DEFAULTS, OwnedTraitLink, PALETTE_PRESETS, PRE_DS2_FLAVOR_DEFAULTS, PRE_TINT_DEFAULT, REDUCED_MOTION_OVERRIDES, REDUCED_TRANSPARENCY_OVERRIDES, REVERT_WINDOW_MS, SCHEME_INK, SPEC_A11Y, SPEC_AXES, SPEC_BUTTON_VARIANT_TO_STYLE, SPEC_CONTRAST, SPEC_CONTRAST_AUDIT, SPEC_DEFAULT_ELEMENT_STYLE, SPEC_ELEMENT_STYLES, SPEC_FIELD_CLASS_BASELINE, SPEC_FLAVORS, SPEC_FLAVOR_PACKS, SPEC_FONTS, SPEC_FONT_ROLES, SPEC_INK_SCOPES, SPEC_LEGACY_ALIASES, SPEC_PALETTE_PRESETS, SPEC_SCHEMES, SPEC_SCHEME_INK, SPEC_SPRINGS, SPEC_TIERS, SPEC_TIER_IDS, SPEC_TOKEN_TYPES, SUPERSEDED_STYLE_VALUES, SWISS_FLAVOR, TINT_FULL_CHROMA, TINT_IDS, TINT_LEVELS, TINT_OWN_HUE_CHROMA, TINT_TURN_CHROMA, USER_TOKEN_SOURCE, WCAG_AA_TEXT, WCAG_AA_UI, adoptElementStyles, adoptionStyleFor, apcaLc, applyElementStyle, applyHeadingLevelRule, atLightness, atLightnessMaxChroma, auditDesignContrast, barReserveClass, buildFlavorTokens, buildFontFaceCss, buttonBlockHref, catalogFontId, checkFontWeight, choicesForPack, colorSchemeClass, colorSchemeOf, colourTabChecks, compareFontWeights, compileSchemeCss, compileTokenCss, compileTokenCssBlocks, compositeOver, cssString, defaultDesignChoices, defaultElementStyleFor, deriveAccentTokens, deriveBrandTokens, designBaseline, designConfigEntries, designModeOf, designTokenRepairs, designTokenRows, elementStyleById, elementStyleClass, elementStylesFor, emptyImageLabelSrc, emptyImagePlaceholder, emptyImageSrc, ensureAlpha, ensureContrast, flavorColours, flavorPackById, flavorSeedWrites, flavorSourceStamp, fontFamilyKey, fontFileName, fontFileStem, fontFormatOf, fontPreloads, fontRoleReferences, fontStackWithout, fontWeightCovers, fontWeightRange, fontWeightValue, fontsForTokens, formatFontFamilies, formatFontFamily, formatFontWeight, googleFontHref, groupFontFamilies, hasElementStyleMarker, headingHref, inSrgbGamut, isDesignTokenGroup, isDesignTokenTier, isDesignTokenType, isFontWeightRange, isRetiredFlavorId, legacyDesignTokenRows, legacyFlavorTokens, legacyRuleTokenReferences, matchFontWeight, missingDesignRows, missingFontRoles, nodeDesignClasses, normalizeFontStyle, normalizeFontWeight, normalizeFontWeightValue, oklabToRgb, ownedTraitStatus, ownedTraitsOf, packDesignChoices, paintColours, parseCssColour, parseFontFamilies, parseFontWeight, parseHexColor, planDesignApply, planDesignRevert, planFlavorRevert, planFlavorSeed, planFontFamilyRemoval, planSwissMigration, preTintAccentGrounds, previewElementStyleAdoption, previewFontWeight, quantizeRgb, readDesignConfig, readOwnedTrait, relativeLuminance, releaseElementStyle, resolveDesignChoices, resolveSchemeTokenValues, resolveTokenReferences, resolveTokenValues, revertAvailable, rgbToOklab, ringColour, roleClass, sameDesignChoices, setColorScheme, specTokenNames, splitTopLevel, springToLinear, stackNamesFamily, styleKeyToKebab, switchElementStyle, syncNodeDesignClasses, toHexColor, tokenReferences, tokensToDarkVarMap, tokensToVarMap, unknownTokenReferences, untouchedSeedRow, userFontStack, validateFlavorPack, wcagContrastRatio, withSchemeInk, writeOwnedTrait };
-export type { AccentBackgrounds, AccentGround, AccentTokenName, AdoptContext, AdoptReport, AdoptableNode, AdoptedNode, ApplyElementStyleResult, ButtonBlockLinkProps, ColourCheck, ColourFlavor, ContrastFinding, DensityId, DesignApplyOptions, DesignChoices, DesignClassSource, DesignConfigEntry, DesignMode, DesignTokenGroup, DesignTokenLike, DesignTokenRow, DesignTokenTier, DesignTokenType, ElementStyle, ElementStyleTarget, ElementStyleTraitLike, FlavorColours, FlavorPack, FlavorPackV2, FlavorPalette, FlavorRevertPlan, FlavorRevertSnapshot, FlavorRevertWrite, FlavorSeedOptions, FlavorSeedPlan, FlavorSpecToken, FlavorTintConfig, FlavorTokenDef, FontDescriptor, FontFamilyGroup, FontFamilyRemoval, FontFamilyToken, FontFormat, FontPair, FontRoleToken, FontStyle, FontWeight, FontWeightRange, FontsForTokensOptions, KeptEdit, LinearSpring, MissingFontRole, MotionId, NodeLinkProps, OkLab, OwnedTrait, OwnedTraitStatus, PalettePreset, ResolvedMode, Rgb, Rgba, SchemeId, SeedBaseline, SeedExpectation, ShapeId, SkippedNode, StoredDesign, StoredDesignTokenRow, SupersededStyleValue, SwissMigration, SwitchElementStyleResult, TintId, TintLevel, TokenCssBlocks, TokenCssOptions };
+export { ACCENT_TOKEN_NAMES, ANIMATE_IDS, AdoptOutcome, AdoptSkipReason, BAR_RESERVE_BREAKPOINTS, BAR_RESERVE_CLASS, BETWEEN_IDS, BOTTOM_BAR_STYLE, BUTTON_VARIANT_TO_STYLE, CANVAS_LINK_ATTRIBUTE, CARD_LINK_CLASS, COLOR_SCHEMES, COLOR_SCHEME_TRAIT, COLOR_SCHEME_TYPES, ColorScheme, ColourCheckId, DEFAULT_FLAVOR_ID, DESIGN_TOKEN_GROUPS, DESIGN_TOKEN_TIERS, DESIGN_TOKEN_TYPES, DesignConfigKey, ELEMENT_STYLES, ELEMENT_STYLE_MARKER_CLASS, ELEMENT_STYLE_STATES, EMPTY_IMAGE_ATTRIBUTE, EMPTY_IMAGE_SRC, ElementStyleState, FLAVOR_SPEC_VERSION, FONT_CATALOG, FONT_FAMILY_TOKENS, FONT_FILE_ACCEPT, FONT_FILE_EXTENSIONS, FONT_FILE_FORMATS, FONT_STYLES, FONT_WEIGHTS, FontUploadError, GOOGLE_FONTS_CSS_ORIGIN, GOOGLE_FONTS_FILE_ORIGIN, HELD_CONTRAST, INHERITED_TEXT, LinkType, MAX_FONT_FILE_BYTES, NEW_NODE_STYLE_DEFAULTS, OwnedTraitLink, PALETTE_PRESETS, PRE_DS2_FLAVOR_DEFAULTS, PRE_MOTION, PRE_TINT_DEFAULT, REDUCED_DESIGN_MOTION, REDUCED_MOTION_OVERRIDES, REDUCED_TRANSPARENCY_OVERRIDES, REVERT_WINDOW_MS, SCHEME_INK, SCROLL_IDS, SPEC_A11Y, SPEC_AXES, SPEC_BUTTON_VARIANT_TO_STYLE, SPEC_CONTRAST, SPEC_CONTRAST_AUDIT, SPEC_DEFAULT_ELEMENT_STYLE, SPEC_ELEMENT_STYLES, SPEC_FIELD_CLASS_BASELINE, SPEC_FLAVORS, SPEC_FLAVOR_PACKS, SPEC_FONTS, SPEC_FONT_ROLES, SPEC_INK_SCOPES, SPEC_LEGACY_ALIASES, SPEC_PALETTE_PRESETS, SPEC_SCHEMES, SPEC_SCHEME_INK, SPEC_SPRINGS, SPEC_TIERS, SPEC_TIER_IDS, SPEC_TOKEN_TYPES, SUPERSEDED_STYLE_VALUES, SWISS_FLAVOR, TINT_FULL_CHROMA, TINT_IDS, TINT_LEVELS, TINT_OWN_HUE_CHROMA, TINT_TURN_CHROMA, USER_TOKEN_SOURCE, WCAG_AA_TEXT, WCAG_AA_UI, adoptElementStyles, adoptionStyleFor, apcaLc, applyElementStyle, applyHeadingLevelRule, atLightness, atLightnessMaxChroma, auditDesignContrast, barReserveClass, buildFlavorTokens, buildFontFaceCss, buttonBlockHref, catalogFontId, checkFontWeight, choicesForPack, colorSchemeClass, colorSchemeOf, colourTabChecks, compareFontWeights, compileSchemeCss, compileTokenCss, compileTokenCssBlocks, compositeOver, cssString, defaultDesignChoices, defaultElementStyleFor, deriveAccentTokens, deriveBrandTokens, designApplySnapshot, designBaseline, designConfigEntries, designModeOf, designMotionOf, designRevertConfig, designTokenRepairs, designTokenRows, elementStyleById, elementStyleClass, elementStylesFor, emptyImageLabelSrc, emptyImagePlaceholder, emptyImageSrc, ensureAlpha, ensureContrast, flavorColours, flavorPackById, flavorSeedWrites, flavorSourceStamp, fontFamilyKey, fontFileName, fontFileStem, fontFormatOf, fontPreloads, fontRoleReferences, fontStackWithout, fontWeightCovers, fontWeightRange, fontWeightValue, fontsForTokens, formatFontFamilies, formatFontFamily, formatFontWeight, googleFontHref, groupFontFamilies, hasElementStyleMarker, headingHref, inSrgbGamut, isDesignTokenGroup, isDesignTokenTier, isDesignTokenType, isFontWeightRange, isRetiredFlavorId, legacyDesignTokenRows, legacyFlavorTokens, legacyRuleTokenReferences, matchFontWeight, missingDesignRows, missingFontRoles, nodeDesignClasses, normalizeFontStyle, normalizeFontWeight, normalizeFontWeightValue, oklabToRgb, ownedTraitStatus, ownedTraitsOf, packDesignChoices, paintColours, parseCssColour, parseFontFamilies, parseFontWeight, parseHexColor, planDesignApply, planDesignRevert, planFlavorRevert, planFlavorSeed, planFontFamilyRemoval, planSwissMigration, preTintAccentGrounds, previewElementStyleAdoption, previewFontWeight, quantizeRgb, readDesignConfig, readOwnedTrait, relativeLuminance, releaseElementStyle, resolveDesignChoices, resolveDesignMotion, resolveSchemeTokenValues, resolveTokenReferences, resolveTokenValues, revertAvailable, rgbToOklab, ringColour, roleClass, sameDesignChoices, setColorScheme, specTokenNames, splitTopLevel, springToLinear, stackNamesFamily, styleKeyToKebab, switchElementStyle, syncNodeDesignClasses, toHexColor, tokenReferences, tokensToDarkVarMap, tokensToVarMap, unknownTokenReferences, untouchedSeedRow, userFontStack, validateFlavorPack, wcagContrastRatio, withSchemeInk, writeOwnedTrait };
+export type { AccentBackgrounds, AccentGround, AccentTokenName, AdoptContext, AdoptReport, AdoptableNode, AdoptedNode, AnimateId, ApplyElementStyleResult, BetweenId, ButtonBlockLinkProps, ColourCheck, ColourFlavor, ContrastFinding, DensityId, DesignApplyOptions, DesignChoices, DesignClassSource, DesignConfigEntry, DesignMode, DesignMotion, DesignRevertSnapshot, DesignTokenGroup, DesignTokenLike, DesignTokenRow, DesignTokenTier, DesignTokenType, ElementStyle, ElementStyleTarget, ElementStyleTraitLike, FlavorColours, FlavorPack, FlavorPackV2, FlavorPalette, FlavorRevertPlan, FlavorRevertSnapshot, FlavorRevertWrite, FlavorSeedOptions, FlavorSeedPlan, FlavorSpecToken, FlavorTintConfig, FlavorTokenDef, FontDescriptor, FontFamilyGroup, FontFamilyRemoval, FontFamilyToken, FontFormat, FontPair, FontRoleToken, FontStyle, FontWeight, FontWeightRange, FontsForTokensOptions, KeptEdit, LinearSpring, MissingFontRole, MotionId, NodeLinkProps, OkLab, OwnedTrait, OwnedTraitStatus, PalettePreset, ResolvedMode, Rgb, Rgba, SchemeId, ScrollId, SeedBaseline, SeedExpectation, ShapeId, SkippedNode, StoredDesign, StoredDesignTokenRow, SupersededStyleValue, SwissMigration, SwitchElementStyleResult, TintId, TintLevel, TokenCssBlocks, TokenCssOptions };