@vectoriox/iox-ui 5.77.0 → 5.79.0

package/src/generation-core/validate-site-plan.ts

@@ -1,11 +1,11 @@
 import { flavorPackById, parseHexColor, SPEC_AXES } from '@vectoriox/iox-ui/design-core';
 import { formPresetById } from '@vectoriox/iox-ui/forms-core';
+import { filmScreensFor, normalizeFrameSequence } from '@vectoriox/iox-ui/media-core';
 import { SEO_DESCRIPTION_MAX, SEO_TITLE_MAX } from '@vectoriox/iox-ui/seo-core';
 
 import {
     BindScope, patternById, patternHasForm, patternLinkSlots, patternNeedsBinding, patternOptionalParts, patternRoleNeeds, patternTakesBinding, patternScopes,
-    patternSlots, PatternGlobalPosition, slotBudget,
-} from './patterns';
+    patternSlots, PatternGlobalPosition, slotBudget, SCENE_LEVEL, SCENE_OTHER_PAGES } from './patterns';
 import { ContentFieldControl, FIELD_TYPE_OF_CONTROL,
     FACT_KEYS, GlobalSlot, PAGE_ARCHETYPES, SITE_NEED_IDS, PlanDataSourceMode, PlanDataSourceType, RelativeOp, REQUIRED_CONTENT_ROLES, SitePlan, SitePlanSourceKind,
     SITE_LOCALES, SITE_PLAN_VERSION,
@@ -70,6 +70,12 @@ export enum SitePlanIssueCode {
     UnknownNeed = 'unknown-need',
     /** A page key that is a global slot's name (`header`, `footer`): its sections' ids would be the global's. */
     ReservedPageKey = 'reserved-page-key',
+    /** SC6: a Scene below How animated Expressive, a second Scene on a page, or Scenes on more than the home page and
+     *  one other — the pages answer by choosing another pattern. */
+    SceneBudget = 'scene-budget',
+    /** SC6b: the owner's film — pictures that cannot play, too few to play smoothly, or a film's pattern on a plan with
+     *  no film (or twice). Set by the build, never by a model. */
+    Film = 'film',
 }
 
 export type SitePlanIssue = PathIssue<SitePlanIssueCode>;
@@ -108,6 +114,7 @@ const SEED_FIXED_KEYS = shapeKeys(SHAPE['seed']);
 const CMS_SOURCE_KEYS = shapeKeys(SHAPE['cmsDataSource']);
 const RELATIVE_SOURCE_KEYS = shapeKeys(SHAPE['relativeDataSource']);
 const PAGE_KEYS = shapeKeys(SHAPE['page']);
+const FILM_KEYS = shapeKeys(SHAPE['film']);
 const SECTION_KEYS = shapeKeys(SHAPE['section']);
 const GLOBAL_POSITION: Readonly<Record<`${GlobalSlot}`, `${PatternGlobalPosition}`>> = {
     [GlobalSlot.Header]: PatternGlobalPosition.Before,
@@ -455,6 +462,52 @@ function validatePages(c: Collector, list: unknown[], types: Map<string, Content
 }
 
 
+/** SC6 (premium-sites plan, APPROVED 2026-11-05): who may hold the page — Scenes only at Expressive, one per page, on the
+ *  home page and at most one other. A Scene past that is an issue at its pattern, so the pages choose another. */
+function validateScenes(c: Collector, pages: unknown[], animate: string | null): void {
+    let otherPages = 0;
+    pages.forEach((raw, i) => {
+        if (!isObject(raw) || !Array.isArray(raw['sections'])) return;
+        let onPage = 0;
+        const counted = raw['isHome'] === true;
+        raw['sections'].forEach((s, j) => {
+            const pattern = isObject(s) && typeof s['pattern'] === 'string' ? patternById(s['pattern']) : null;
+            if (!pattern?.scene) return;
+            const at = `pages[${i}].sections[${j}].pattern`;
+            if (animate !== SCENE_LEVEL) return c.add(SitePlanIssueCode.SceneBudget, at, `"${s['pattern']}" holds the page as it scrolls — only on a site whose How animated is Expressive (this one is ${animate ?? 'unset'})`);
+            if (++onPage > 1) return c.add(SitePlanIssueCode.SceneBudget, at, 'one Scene per page — choose a section that does not hold the page');
+            if (!counted && onPage === 1 && ++otherPages > SCENE_OTHER_PAGES) c.add(SitePlanIssueCode.SceneBudget, at, `Scenes on the home page and at most ${SCENE_OTHER_PAGES} other page — choose a section that does not hold the page`);
+        });
+    });
+}
+
+/** SC6b: a film plays only when its pictures can (and smoothly over the shortest hold); its pattern only with a film, once. */
+function validateFilm(c: Collector, film: unknown, pages: unknown[]): void {
+    let playable = false;
+    if (film !== undefined) {
+        if (!isObject(film)) {
+            c.add(SitePlanIssueCode.Shape, 'film', 'must be an object');
+        } else {
+            c.keys(film, FILM_KEYS, 'film');
+            const sequence = normalizeFrameSequence(film['sequence']);
+            if (!sequence) c.add(SitePlanIssueCode.Film, 'film.sequence', 'not a film\'s pictures (a media-core FrameSequence)');
+            else if (filmScreensFor(sequence.wide.count) === null) c.add(SitePlanIssueCode.Film, 'film.sequence', `${sequence.wide.count} pictures — too few to play smoothly`);
+            else playable = true;
+        }
+    }
+    let placed = 0;
+    pages.forEach((raw, i) => {
+        if (!isObject(raw) || !Array.isArray(raw['sections'])) return;
+        raw['sections'].forEach((s, j) => {
+            const pattern = isObject(s) && typeof s['pattern'] === 'string' ? patternById(s['pattern']) : null;
+            if (!pattern?.film) return;
+            const path = `pages[${i}].sections[${j}].pattern`;
+            if (!playable) c.add(SitePlanIssueCode.Film, path, `"${s['pattern']}" plays the owner's film — this plan has none`);
+            else if (++placed > 1) c.add(SitePlanIssueCode.Film, path, 'the film plays once on a site');
+        });
+    });
+}
+
 function validatePageSeo(c: Collector, seo: unknown, path: string): void {
     if (seo === undefined) return;
     if (!isObject(seo)) return c.add(SitePlanIssueCode.Shape, path, 'must be an object');
@@ -501,6 +554,8 @@ export function validateSitePlan(plan: unknown): SitePlanValidation {
     const design = isObject(plan['design']) ? plan['design'] : {};
     validatePages(c, c.array(plan, 'pages', ''), types, sources, typeof design['density'] === 'string' ? design['density'] : null);
     validateGlobals(c, plan['globals']);
+    validateScenes(c, c.array(plan, 'pages', ''), typeof design['animate'] === 'string' ? design['animate'] : null);
+    validateFilm(c, plan['film'], c.array(plan, 'pages', ''));
     return { valid: c.issues.length === 0, issues: c.issues };
 }
 

package/src/harness-core/business-types.ts

@@ -111,6 +111,9 @@ export interface BusinessType {
     readonly motion: MotionId;
     /** How its site usually scrolls, how animated it is and what plays between pages (rev 3.1). */
     readonly moves: Readonly<DesignMotion>;
+    /** SC6: the most How animated a GENERATED site of this type may start at (`motionFor`). A Scene needs Expressive,
+     *  so a type capped below it never gets one. Binds generated output only — the owner may choose any level. */
+    readonly ceiling: DesignMotion['animate'];
     readonly imagery: string;
     readonly pages: ReadonlyArray<string>;
     /** The needs its page set implies, in page order (derived from `pages` at contract build). */

package/src/harness-core/generation-view.ts

@@ -1,4 +1,5 @@
 import type { DesignChoices } from '@vectoriox/iox-ui/design-core';
+import type { FrameSequence } from '@vectoriox/iox-ui/media-core';
 import type { AiGenerationStage, AiStep, PlanChange, PlanEdit, SitePlan } from '@vectoriox/iox-ui/generation-core';
 
 import type { StyleRead } from './rank';
@@ -78,7 +79,8 @@ export interface AiGenerationView {
     stage: `${AiGenerationStage}`;
     /** The model step the runner is working on; null = the owner's move. */
     task: `${AiStep}` | null;
-    intake: { prompt: string; files: GenerationFileView[]; addresses: string[]; auto: boolean };
+    /** `film`: the owner's film as pictures (SC6b), told by the wizard at Build — `placeFilm` places it. */
+    intake: { prompt: string; files: GenerationFileView[]; addresses: string[]; auto: boolean; film?: FrameSequence };
     readers: GenerationReadersView;
     reads: { analysis?: { value: SiteAnalysis; model: string; usageIds: string[] }; style?: StyleRead | null };
     /** What Design and Plan use: the owner's edit, else the reading. */

package/src/harness-core/harness-spec.generated.ts

@@ -206,6 +206,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "subtle",
       "between": "cinematic"
     },
+    "ceiling": "expressive",
     "imagery": "Your own photos only, large and uncropped; never stock.",
     "pages": [
       "home",
@@ -310,6 +311,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "subtle",
       "between": "cinematic"
     },
+    "ceiling": "expressive",
     "imagery": "Wide, bright room shots; details of materials.",
     "pages": [
       "home",
@@ -419,6 +421,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "subtle",
       "between": "fade"
     },
+    "ceiling": "expressive",
     "imagery": "Large project photos and drawings.",
     "pages": [
       "home",
@@ -524,9 +527,10 @@ export const SPEC_BUSINESS_TYPES = [
     "motion": "standard",
     "moves": {
       "scroll": "smooth",
-      "animate": "lively",
+      "animate": "expressive",
       "between": "slide"
     },
+    "ceiling": "expressive",
     "imagery": "Case-study images of your own work.",
     "pages": [
       "home",
@@ -625,6 +629,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "standard",
       "between": "fade"
     },
+    "ceiling": "expressive",
     "imagery": "Your pieces, photographed flat and true to colour.",
     "pages": [
       "home",
@@ -726,9 +731,10 @@ export const SPEC_BUSINESS_TYPES = [
     "motion": "calm",
     "moves": {
       "scroll": "normal",
-      "animate": "lively",
+      "animate": "expressive",
       "between": "slide"
     },
+    "ceiling": "expressive",
     "imagery": "Your pieces and hands at work; natural light.",
     "pages": [
       "home",
@@ -826,6 +832,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "subtle",
       "between": "cinematic"
     },
+    "ceiling": "expressive",
     "imagery": "Close-ups on a plain ground.",
     "pages": [
       "home",
@@ -927,6 +934,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "standard",
       "between": "slide"
     },
+    "ceiling": "expressive",
     "imagery": "Healed work, clean photos.",
     "pages": [
       "home",
@@ -1022,6 +1030,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "subtle",
       "between": "fade"
     },
+    "ceiling": "standard",
     "imagery": "Rooms, textures, hands; no faces needed.",
     "pages": [
       "home",
@@ -1140,6 +1149,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "standard",
       "between": "fade"
     },
+    "ceiling": "lively",
     "imagery": "Your own before-and-after photos.",
     "pages": [
       "home",
@@ -1241,6 +1251,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "subtle",
       "between": "fade"
     },
+    "ceiling": "lively",
     "imagery": "The room, real classes, daylight.",
     "pages": [
       "home",
@@ -1350,6 +1361,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "lively",
       "between": "slide"
     },
+    "ceiling": "lively",
     "imagery": "Real people training; movement.",
     "pages": [
       "home",
@@ -1451,6 +1463,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "subtle",
       "between": "none"
     },
+    "ceiling": "subtle",
     "imagery": "A calm room, daylight; your portrait.",
     "pages": [
       "home",
@@ -1560,6 +1573,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "subtle",
       "between": "fade"
     },
+    "ceiling": "subtle",
     "imagery": "Your team and rooms; no stock doctors.",
     "pages": [
       "home",
@@ -1664,6 +1678,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "subtle",
       "between": "fade"
     },
+    "ceiling": "subtle",
     "imagery": "Your clinic and team.",
     "pages": [
       "home",
@@ -1769,6 +1784,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "standard",
       "between": "fade"
     },
+    "ceiling": "standard",
     "imagery": "Real animals you treat (with permission).",
     "pages": [
       "home",
@@ -1866,6 +1882,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "standard",
       "between": "fade"
     },
+    "ceiling": "expressive",
     "imagery": "Your own food and room photos.",
     "pages": [
       "home",
@@ -1974,6 +1991,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "standard",
       "between": "slide"
     },
+    "ceiling": "lively",
     "imagery": "Your bakes and drinks, close up.",
     "pages": [
       "home",
@@ -2076,6 +2094,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "subtle",
       "between": "cinematic"
     },
+    "ceiling": "expressive",
     "imagery": "The cellar, the bar, the bottle.",
     "pages": [
       "home",
@@ -2178,6 +2197,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "standard",
       "between": "slide"
     },
+    "ceiling": "expressive",
     "imagery": "Product photos on plain grounds; real people wearing them.",
     "pages": [
       "home",
@@ -2272,6 +2292,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "standard",
       "between": "fade"
     },
+    "ceiling": "lively",
     "imagery": "Your own arrangements in daylight.",
     "pages": [
       "home",
@@ -2367,6 +2388,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "subtle",
       "between": "fade"
     },
+    "ceiling": "expressive",
     "imagery": "Pieces in real rooms and on plain grounds.",
     "pages": [
       "home",
@@ -2463,6 +2485,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "subtle",
       "between": "fade"
     },
+    "ceiling": "standard",
     "imagery": "Your portrait; diagrams over stock.",
     "pages": [
       "home",
@@ -2563,6 +2586,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "standard",
       "between": "fade"
     },
+    "ceiling": "standard",
     "imagery": "Your portrait, working with people.",
     "pages": [
       "home",
@@ -2658,6 +2682,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "still",
       "between": "none"
     },
+    "ceiling": "subtle",
     "imagery": "Your team; your office.",
     "pages": [
       "home",
@@ -2767,6 +2792,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "standard",
       "between": "slide"
     },
+    "ceiling": "lively",
     "imagery": "Your own property photos; never stock.",
     "pages": [
       "home",
@@ -2871,6 +2897,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "standard",
       "between": "fade"
     },
+    "ceiling": "standard",
     "imagery": "Real people you help (with permission).",
     "pages": [
       "home",
@@ -2963,6 +2990,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "standard",
       "between": "cinematic"
     },
+    "ceiling": "expressive",
     "imagery": "Real events at your venue.",
     "pages": [
       "home",
@@ -3064,6 +3092,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "subtle",
       "between": "cinematic"
     },
+    "ceiling": "expressive",
     "imagery": "Rooms, views, breakfast; your own photos.",
     "pages": [
       "home",
@@ -3171,6 +3200,7 @@ export const SPEC_BUSINESS_TYPES = [
       "animate": "lively",
       "between": "slide"
     },
+    "ceiling": "lively",
     "imagery": "Real classes (with permission).",
     "pages": [
       "home",

package/src/harness-core/motion.ts

@@ -25,6 +25,8 @@ export interface MotionBasis {
     references: boolean;
     /** The owner asked for little movement: all three were capped. */
     littleMovement: boolean;
+    /** SC6: How animated was held at the type's ceiling (a law firm stays calm whatever the style or references). */
+    ceiling: boolean;
 }
 
 export interface MotionStart extends DesignMotion {
@@ -66,9 +68,14 @@ export function motionFor(
     const wanted = ref ?? base.animate;
     let out: DesignMotion = { scroll: base.scroll, animate: calmerChoice('animate', wanted, preset.moves.animate), between: base.between };
     const why = [type ? `${type.label}: ${triple(base)}` : `${preset.name}: the style's own`];
-    const basis: MotionBasis = { type: type?.id ?? null, calmerStyle: out.animate !== wanted, references: !!(ref && type), littleMovement: false };
+    const basis: MotionBasis = { type: type?.id ?? null, calmerStyle: out.animate !== wanted, references: !!(ref && type), littleMovement: false, ceiling: false };
     if (basis.calmerStyle) why.push(`${preset.name} moves less (${label('animate', preset.moves.animate)})`);
     if (basis.references) why.push(`your references: ${label('animate', ref!)}`);
+    if (type && calmerChoice('animate', out.animate, type.ceiling) !== out.animate) {
+        out = { ...out, animate: type.ceiling };
+        basis.ceiling = true;
+        why.push(`${type.label} goes no further than ${label('animate', type.ceiling)}`);
+    }
     if ((input.avoid ?? []).includes(LITTLE_MOVEMENT_AVOID)) {
         basis.littleMovement = true;
         out = {

package/src/media-core/frames.ts

@@ -226,6 +226,29 @@ export function videoFrameCount(seconds: number): number {
     return Math.min(VIDEO_MAX_FRAMES, Math.max(2, Math.ceil(seconds * VIDEO_FRAMES_PER_SECOND)));
 }
 
+/**
+ * Pictures per screen of scrolling at which a played film stays smooth as a glide slows to a stop. Measured on Doron's
+ * iPhone (2026-11-05): Studio Alma's film at about 11 a screen stepped, at about 55 it did not.
+ */
+export const FILM_SMOOTH_PER_SCREEN = 40;
+/** The fewest and most screens a film the build places holds the page for (SC6b): long enough to feel, short enough to pass. */
+export const FILM_MIN_SCREENS = 1;
+export const FILM_MAX_SCREENS = 4;
+/** What the build prepares a film to: about 60 pictures a screen at the longest hold — denser than smooth, never wasted. */
+export const FILM_PREPARED_PICTURES = FILM_MAX_SCREENS * 60 + 1;
+/** The fewest pictures a placed film may have: smooth over the shortest hold. */
+export const FILM_MIN_PICTURES = FILM_MIN_SCREENS * FILM_SMOOTH_PER_SCREEN + 1;
+
+/**
+ * The screens a film of `count` pictures holds the page for (SC6b, the composer's density rule): the stretches between
+ * pictures are what scroll, so `(count − 1) ÷ 40`, rounded DOWN to a tenth (150 pictures over 3.75 screens measure 39.7 a
+ * screen, thin), within the hold's limits. Null: too few pictures to play smoothly over the shortest hold.
+ */
+export function filmScreensFor(count: number): number | null {
+    if (!Number.isInteger(count) || count < FILM_MIN_PICTURES) return null;
+    return Math.min(FILM_MAX_SCREENS, Math.floor(((count - 1) / FILM_SMOOTH_PER_SCREEN) * 10) / 10);
+}
+
 /** Which of `sourceCount` pictures make a set of `count`, spread evenly, first and last always in. */
 export function sampledFrameIndexes(sourceCount: number, count: number): number[] {
     if (count >= sourceCount) return Array.from({ length: sourceCount }, (_, i) => i);

package/src/scene-core/scene-edit.ts

@@ -1,4 +1,5 @@
 import { SceneRole } from '@vectoriox/iox-ui/composite-core';
+import { FILM_SMOOTH_PER_SCREEN } from '@vectoriox/iox-ui/media-core';
 
 import { normalizeTracks, SCENE_REVEAL_DEFAULT, SceneKey, SceneNodeSource, SceneProp, SceneRevealFrom, SceneTrack, valueAt } from './scene';
 
@@ -238,11 +239,8 @@ export function sceneHeightForScreens(screens: number): string {
     return `${roundTo((held + 1) * 100, 1)}vh`;
 }
 
-/**
- * Pictures per screen of scrolling at which a played film stays smooth as a glide slows to a stop. Measured on Doron's
- * iPhone (2026-11-05): Studio Alma's film at about 11 a screen stepped, at about 55 it did not.
- */
-export const SCENE_FILM_SMOOTH = 40;
+/** Pictures per screen of scrolling at which a played film stays smooth (media-core's, which the composer sizes by). */
+export const SCENE_FILM_SMOOTH = FILM_SMOOTH_PER_SCREEN;
 
 export interface SceneFilmDensity {
     /** Pictures per screen of scrolling over most of the play: half its scroll holds at least this many. */