@vectoriox/iox-ui 5.78.0 → 5.80.0

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

@@ -36,3 +36,4 @@ export * from './plan-words';
 export * from './audit-site';
 export * from './stock-match';
 export * from './stock-photos';
+export * from './film';

package/src/generation-core/showcase.ts

@@ -1,4 +1,5 @@
 import type { DesignChoices } from '@vectoriox/iox-ui/design-core';
+import { FILM_PREPARED_PICTURES, FrameExtension, FrameSequence } from '@vectoriox/iox-ui/media-core';
 
 import { BindScope, patternNeedsBinding, PatternGlobalPosition, patternScopes, SCENE_LEVEL, SITE_PATTERNS } from './patterns';
 import { GlobalSlot, PagePlan, PageSectionPlan, SiteBusiness, SiteLocale, SitePlan, SitePlanSourceKind, SITE_PLAN_VERSION } from './site-plan.model';
@@ -15,8 +16,17 @@ export interface ShowcaseInput {
     business: SiteBusiness;
     design: DesignChoices;
     locale?: `${SiteLocale}`;
+    /** SC6b: the film the film's Scene plays — a render-parity run serves its own; absent, `SHOWCASE_FILM`. */
+    film?: FrameSequence;
 }
 
+/** SC6b: a film's description for the showcase — as many pictures as the build prepares; nothing is fetched to compose it. */
+export const SHOWCASE_FILM: FrameSequence = {
+    base: 'https://showcase.iox.invalid/film', ext: FrameExtension.Webp,
+    wide: { count: FILM_PREPARED_PICTURES, width: 1600, height: 900 },
+    phone: { count: FILM_PREPARED_PICTURES, width: 1100, height: 619 },
+};
+
 const ITEM_ROUTE = '/work/:slug';
 const LIST_SOURCE = 'projects';
 
@@ -70,7 +80,7 @@ export function showcaseScenes(): string[] {
 /**
  * The showcase as Site Plans — as many as it takes for every header and every footer to be composed once, then one per
  * Scene pattern (SC6): its home page holds that Scene and nothing else, at How animated Expressive, the only level a
- * Scene is composed at.
+ * Scene is composed at; the film's Scene with a film (SC6b).
  */
 export function showcasePlans(input: ShowcaseInput): SitePlan[] {
     const { headers, footers } = showcaseGlobals();
@@ -87,6 +97,10 @@ export function showcasePlans(input: ShowcaseInput): SitePlan[] {
         pages: JSON.parse(JSON.stringify(planPages)),
         globals: { [GlobalSlot.Header]: headers[i % headers.length], [GlobalSlot.Footer]: footers[i % footers.length] } as SitePlan['globals'],
     });
-    const scenes = showcaseScenes().map((id, i) => plan(i, [{ key: 'home', name: 'Home', route: '/', isHome: true, inNav: false, sections: [sectionFor(id)] }], { ...input.design, animate: SCENE_LEVEL }));
+    const scenes = showcaseScenes().map((id, i) => {
+        const scene = plan(i, [{ key: 'home', name: 'Home', route: '/', isHome: true, inNav: false, sections: [sectionFor(id)] }], { ...input.design, animate: SCENE_LEVEL });
+        // A film's Scene plays a film (SC6b): the plan carries one, as the build's would.
+        return SITE_PATTERNS[id].film ? { ...scene, film: { sequence: JSON.parse(JSON.stringify(input.film ?? SHOWCASE_FILM)) } } : scene;
+    });
     return [...Array.from({ length: count }, (_, i) => plan(i, pages, input.design)), ...scenes];
 }

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

@@ -1,3 +1,4 @@
+import type { FrameSequence } from '@vectoriox/iox-ui/media-core';
 import type { AnimateId, DesignChoices } from '@vectoriox/iox-ui/design-core';
 
 import { SPEC_SITE_ARCHETYPES, SPEC_SITE_FACTS, SPEC_SITE_LOCALES, SPEC_SITE_NEED_IDS, SPEC_SITE_REQUIRED_ROLES, SPEC_SITE_ROLES } from './site-spec.generated';
@@ -246,4 +247,11 @@ export interface SitePlan {
     readonly dataSources: ReadonlyArray<DataSourcePlan>;
     readonly pages: ReadonlyArray<PagePlan>;
     readonly globals: Readonly<Record<`${GlobalSlot}`, string>>;
+    /** SC6b: the owner's film as pictures, set by the build and placed by `placeFilm` — never a model's. */
+    readonly film?: PlanFilm;
+}
+
+/** SC6b: the owner's film — the numbered pictures the wizard's browser made of their video (media-core). */
+export interface PlanFilm {
+    readonly sequence: FrameSequence;
 }

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. */
@@ -93,7 +95,9 @@ export interface AiGenerationView {
     siteBuildId?: string;
     models: Partial<Record<`${AiStep}`, string>>;
     estimate: number;
-    cap: number;
+    /** The plan's `aiCreditsPerGeneration` for the whole build, or null when it sets none (a step's own ceiling is
+     *  twice that step's estimate — going back and planning again starts a new step). */
+    cap: number | null;
     /** Derived from the ledger — the running credit total. */
     spent: number;
     error?: { code: string; detail: string; providerMessage?: string; issues?: Array<{ code: string; path: string }> };
@@ -106,10 +110,12 @@ export interface GenerationStartRequest {
     addresses?: string[];
 }
 
-/** The longest message, the most files and addresses a generation starts from (Start's limits). */
+/** The longest message, the most files and addresses a generation starts from (Start's limits), and how many plans
+ *  one build may ask for (a Design pick, a Try again or "Build with these" each asks one). */
 export const GENERATION_LIMITS = {
     promptChars: 4_000,
     files: 12,
     addresses: 3,
     sentenceChars: 500,
+    plans: 5,
 } as const;

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. */