@vectoriox/iox-ui 5.78.0 → 5.79.0

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

@@ -12,7 +12,11 @@ export const SPEC_SITE_PLAN_SHAPE = {
     "contentTypes": "contentType[]",
     "dataSources": "(cmsDataSource | relativeDataSource)[] — merged by alias into the org library",
     "pages": "page[]",
-    "globals": "globals"
+    "globals": "globals",
+    "film?": "film — the owner's film as pictures (SC6b), set by the build and placed by placeFilm; never a model's"
+  },
+  "film": {
+    "sequence": "object — a media-core FrameSequence: where the numbered pictures live, how many, their size"
   },
   "sourceTemplate": {
     "kind": "'template'",
@@ -582,6 +586,157 @@ export const SPEC_SITE_PATTERNS = {
       ]
     }
   },
+  "hero.scene-object": {
+    "family": "hero",
+    "scene": true,
+    "film": true,
+    "label": "Hero — your film plays as you scroll",
+    "intent": "The studio's own film plays forward and back with the scroll behind the headline while the page holds still.",
+    "node": {
+      "t": "Section",
+      "es": "section",
+      "scheme": "inverse",
+      "role": "scene",
+      "lay": {
+        "position": "relative",
+        "display": "block",
+        "width": "100%",
+        "height": "300vh",
+        "padding": "0px"
+      },
+      "c": [
+        {
+          "t": "Container",
+          "role": "scene.stage",
+          "lay": {
+            "position": "sticky",
+            "top": "0px",
+            "display": "block",
+            "width": "100%",
+            "height": "100svh",
+            "overflow": "hidden",
+            "padding": "0px"
+          },
+          "c": [
+            {
+              "t": "Video",
+              "es": "media",
+              "film": true,
+              "lay": {
+                "position": "absolute",
+                "top": "0px",
+                "left": "0px",
+                "width": "100%",
+                "height": "100%",
+                "aspectRatio": "auto",
+                "borderRadius": "0px"
+              },
+              "tracks": [
+                {
+                  "prop": "play",
+                  "keys": [
+                    [
+                      0,
+                      0
+                    ],
+                    [
+                      1,
+                      100
+                    ]
+                  ]
+                }
+              ]
+            },
+            {
+              "t": "Container",
+              "es": "media-scrim",
+              "lay": {
+                "display": "flex",
+                "flexDirection": "column",
+                "gap": "14px",
+                "position": "absolute",
+                "left": "0px",
+                "bottom": "0px",
+                "width": "100%",
+                "padding": "48px 32px 56px 32px"
+              },
+              "c": [
+                {
+                  "t": "Heading",
+                  "es": "display",
+                  "level": "h1",
+                  "slot": "headline",
+                  "max": 56,
+                  "fromBusiness": "name",
+                  "tracks": [
+                    {
+                      "prop": "y",
+                      "keys": [
+                        [
+                          0,
+                          0
+                        ],
+                        [
+                          1,
+                          -6
+                        ]
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "t": "Text",
+                  "es": "lead",
+                  "slot": "lead",
+                  "max": 180,
+                  "fromBusiness": "tagline",
+                  "ph": "copy",
+                  "tracks": [
+                    {
+                      "prop": "opacity",
+                      "keys": [
+                        [
+                          0.3,
+                          0
+                        ],
+                        [
+                          0.45,
+                          1
+                        ]
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "t": "ButtonBlock",
+                  "es": "button-primary",
+                  "href": "/contact",
+                  "slot": "cta",
+                  "max": 24,
+                  "text": "Get in touch",
+                  "tracks": [
+                    {
+                      "prop": "opacity",
+                      "keys": [
+                        [
+                          0.35,
+                          0
+                        ],
+                        [
+                          0.5,
+                          1
+                        ]
+                      ]
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  },
   "story.scene-chapters": {
     "family": "story",
     "scene": true,
@@ -5491,6 +5646,11 @@ export const SPEC_SITE_LIBRARY = [
     "family": "hero",
     "composed": true
   },
+  {
+    "id": "hero.scene-object",
+    "family": "hero",
+    "composed": true
+  },
   {
     "id": "proof.logo-strip",
     "family": "proof",

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

@@ -1,5 +1,6 @@
 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 {
@@ -72,6 +73,9 @@ export enum SitePlanIssueCode {
     /** 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>;
@@ -110,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,
@@ -476,6 +481,33 @@ function validateScenes(c: Collector, pages: unknown[], animate: string | null):
     });
 }
 
+/** 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');
@@ -523,6 +555,7 @@ export function validateSitePlan(plan: unknown): SitePlanValidation {
     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/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/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. */