@vectoriox/iox-ui 5.78.0 → 5.80.0

package/generation-core/index.d.ts

@@ -1,3 +1,4 @@
+import { FrameSequence } from '@vectoriox/iox-ui/media-core';
 import { AnimateId, DesignChoices, DesignTokenLike } from '@vectoriox/iox-ui/design-core';
 import { SeoRawDoc } from '@vectoriox/iox-ui/seo-core';
 import { ContentFieldLike } from '@vectoriox/iox-ui/composite-core';
@@ -13,6 +14,10 @@ declare const SPEC_SITE_PLAN_SHAPE: {
         readonly dataSources: "(cmsDataSource | relativeDataSource)[] — merged by alias into the org library";
         readonly pages: "page[]";
         readonly globals: "globals";
+        readonly "film?": "film — the owner's film as pictures (SC6b), set by the build and placed by placeFilm; never a model's";
+    };
+    readonly film: {
+        readonly sequence: "object — a media-core FrameSequence: where the numbered pictures live, how many, their size";
     };
     readonly sourceTemplate: {
         readonly kind: "'template'";
@@ -399,6 +404,104 @@ declare const SPEC_SITE_PATTERNS: {
             }];
         };
     };
+    readonly "hero.scene-object": {
+        readonly family: "hero";
+        readonly scene: true;
+        readonly film: true;
+        readonly label: "Hero — your film plays as you scroll";
+        readonly intent: "The studio's own film plays forward and back with the scroll behind the headline while the page holds still.";
+        readonly node: {
+            readonly t: "Section";
+            readonly es: "section";
+            readonly scheme: "inverse";
+            readonly role: "scene";
+            readonly lay: {
+                readonly position: "relative";
+                readonly display: "block";
+                readonly width: "100%";
+                readonly height: "300vh";
+                readonly padding: "0px";
+            };
+            readonly c: readonly [{
+                readonly t: "Container";
+                readonly role: "scene.stage";
+                readonly lay: {
+                    readonly position: "sticky";
+                    readonly top: "0px";
+                    readonly display: "block";
+                    readonly width: "100%";
+                    readonly height: "100svh";
+                    readonly overflow: "hidden";
+                    readonly padding: "0px";
+                };
+                readonly c: readonly [{
+                    readonly t: "Video";
+                    readonly es: "media";
+                    readonly film: true;
+                    readonly lay: {
+                        readonly position: "absolute";
+                        readonly top: "0px";
+                        readonly left: "0px";
+                        readonly width: "100%";
+                        readonly height: "100%";
+                        readonly aspectRatio: "auto";
+                        readonly borderRadius: "0px";
+                    };
+                    readonly tracks: readonly [{
+                        readonly prop: "play";
+                        readonly keys: readonly [readonly [0, 0], readonly [1, 100]];
+                    }];
+                }, {
+                    readonly t: "Container";
+                    readonly es: "media-scrim";
+                    readonly lay: {
+                        readonly display: "flex";
+                        readonly flexDirection: "column";
+                        readonly gap: "14px";
+                        readonly position: "absolute";
+                        readonly left: "0px";
+                        readonly bottom: "0px";
+                        readonly width: "100%";
+                        readonly padding: "48px 32px 56px 32px";
+                    };
+                    readonly c: readonly [{
+                        readonly t: "Heading";
+                        readonly es: "display";
+                        readonly level: "h1";
+                        readonly slot: "headline";
+                        readonly max: 56;
+                        readonly fromBusiness: "name";
+                        readonly tracks: readonly [{
+                            readonly prop: "y";
+                            readonly keys: readonly [readonly [0, 0], readonly [1, -6]];
+                        }];
+                    }, {
+                        readonly t: "Text";
+                        readonly es: "lead";
+                        readonly slot: "lead";
+                        readonly max: 180;
+                        readonly fromBusiness: "tagline";
+                        readonly ph: "copy";
+                        readonly tracks: readonly [{
+                            readonly prop: "opacity";
+                            readonly keys: readonly [readonly [0.3, 0], readonly [0.45, 1]];
+                        }];
+                    }, {
+                        readonly t: "ButtonBlock";
+                        readonly es: "button-primary";
+                        readonly href: "/contact";
+                        readonly slot: "cta";
+                        readonly max: 24;
+                        readonly text: "Get in touch";
+                        readonly tracks: readonly [{
+                            readonly prop: "opacity";
+                            readonly keys: readonly [readonly [0.35, 0], readonly [0.5, 1]];
+                        }];
+                    }];
+                }];
+            }];
+        };
+    };
     readonly "story.scene-chapters": {
         readonly family: "story";
         readonly scene: true;
@@ -4523,6 +4626,10 @@ declare const SPEC_SITE_LIBRARY: readonly [{
     readonly id: "hero.scene-depth";
     readonly family: "hero";
     readonly composed: true;
+}, {
+    readonly id: "hero.scene-object";
+    readonly family: "hero";
+    readonly composed: true;
 }, {
     readonly id: "proof.logo-strip";
     readonly family: "proof";
@@ -4887,6 +4994,12 @@ 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). */
+interface PlanFilm {
+    readonly sequence: FrameSequence;
 }
 
 /**
@@ -5098,6 +5211,8 @@ interface PatternNode {
     /** SC6: a Scene layer's scene-core tracks, written to the node's `sceneTracks` (and `scenePhoneTracks`). */
     readonly tracks?: ReadonlyArray<PatternTrack>;
     readonly phoneTracks?: ReadonlyArray<PatternTrack>;
+    /** SC6b: the Video a film pattern plays the owner's film in (its `frames`). */
+    readonly film?: boolean;
 }
 /**
  * SC6: one scene-core track as the contract writes it — `{ prop, keys: [[progress, value]], from? }`. Typed here, not
@@ -5149,6 +5264,8 @@ interface SitePattern {
     /** SC6: a Scene section — held while the page scrolls, moved by the scroll. Only at How animated Expressive, at
      *  most one per page and on at most two pages (`validateSitePlan`); it never takes the look's entrances. */
     readonly scene?: boolean;
+    /** SC6b: a Scene that plays the owner's film. Placed by `placeFilm`, never chosen: no manifest or wire lists it. */
+    readonly film?: boolean;
     readonly node: PatternNode;
 }
 declare const SITE_PATTERNS: Readonly<Record<string, SitePattern>>;
@@ -5513,7 +5630,10 @@ declare enum SitePlanIssueCode {
     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"
+    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"
 }
 type SitePlanIssue = PathIssue<SitePlanIssueCode>;
 interface SitePlanValidation {
@@ -5920,7 +6040,11 @@ 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. */
+declare const SHOWCASE_FILM: FrameSequence;
 /** The showcase's pages: Home (the heroes), one page per other family in library order, and the item page. */
 declare function showcasePages(): PagePlan[];
 /** Every header and footer pattern, in contract order. */
@@ -5933,7 +6057,7 @@ declare 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).
  */
 declare function showcasePlans(input: ShowcaseInput): SitePlan[];
 
@@ -6226,7 +6350,7 @@ declare function planPartOfPath(path: string): PlanPart;
 declare function planWireGaps(): string[];
 declare class PlanWireShapeError extends Error {
 }
-/** The patterns a page section may use (every non-global one), in library order. */
+/** The patterns a page section may use (every non-global one but a film's, which `placeFilm` places), in library order. */
 declare function sectionPatternIds(): string[];
 declare function wireFieldJsonSchema(): JsonSchema;
 /** What an object of the wire travels without when its children are written as their own entries (a plan edit's). */
@@ -6380,7 +6504,10 @@ declare function modelCanDo(model: Pick<AiModelEntry, 'capabilities'>, step: AiS
 declare enum AiRefusalCode {
     NotInPlan = "ai.notInPlan",
     OutOfCredits = "ai.outOfCredits",
+    /** A step used more than twice its estimate (a loop), or the build its plan's `aiCreditsPerGeneration`. */
     CapReached = "ai.capReached",
+    /** The build asked for `GENERATION_LIMITS.plans` plans already — build one, change it with a sentence, or start over. */
+    PlansUsed = "ai.plansUsed",
     NotConnected = "ai.notConnected",
     KeyInvalid = "ai.keyInvalid",
     PlanUnknown = "ai.planUnknown"
@@ -6394,7 +6521,9 @@ declare enum AiNextKind {
     /** Open Settings ▸ AI. */
     Settings = "settings",
     /** Try again later, or with less. */
-    Retry = "retry"
+    Retry = "retry",
+    /** Keep the plan there is: build it, or change it with a sentence. */
+    KeepPlan = "keepPlan"
 }
 declare const AI_REFUSAL_NEXT: Readonly<Record<AiRefusalCode, AiNextKind>>;
 interface AiRefusal {
@@ -6404,6 +6533,8 @@ interface AiRefusal {
     remaining?: number;
     /** What the refused call would have cost, about. */
     estimate?: number;
+    /** `PlansUsed`: how many plans one build may ask for. */
+    plans?: number;
     next: {
         kind: AiNextKind;
         href?: string;
@@ -7177,5 +7308,54 @@ declare function stockCreditNode(index: number, credit: StockLink): SerializedNo
 /** Append the credit lines to the footer root (once each). Returns how many it added. */
 declare function addStockCredits(footer: SerializedNode, credits: ReadonlyArray<StockLink>): number;
 
-export { ACTIVE_BUILD_STATUSES, AI_REFUSAL_NEXT, AI_REFUSAL_STATUS, AI_STEPS, AI_STEP_LABELS, AI_STEP_NEEDS, AI_STEP_PART_TOKENS, AI_STEP_TYPICAL_TOKENS, AiCallStatus, AiCapability, AiFeature, AiGenerationStage, AiKeyMode, AiLimit, AiNextKind, AiProviderId, AiRefusalCode, AiStep, BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BUILD_STEPS, BaselineRole, BindScope, BuildNoticeCode, BuildStep, CONTENT_ROLE_MEANINGS, CREDITS_PER_USD, CardBindTarget, CheckSeverity, ComposeError, ComposeIssueCode, ContentFieldControl, ContentFieldType, ContentRole, ContentTypeAction, CreatedKind, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, DEFAULT_SITE_LOCALE, ENTRANCE_EASING, ENTRANCE_ORIGIN_LOOK, ENTRANCE_TRIGGER, EntrancePart, EntranceSide, FACT_KEYS, FIELD_TYPE_OF_CONTROL, FINAL_GENERATION_STAGES, FINDING_SEVERITY, GRAMMAR_TOO_LARGE_MESSAGE, GlobalSlot, HEBREW_PREFIXES, JSON_SCHEMA_BANNED_KEYWORDS, JsonSchemaShapeError, KeptReason, NAV_PART_LABELS, NAV_SHAPE_COPY, NEUTRAL_STYLE_PROPS, NODE_BASELINES, NO_TOKENS, NavPagesSource, NavRole, NavShape, NavShapeError, PAGE_ARCHETYPES, PLAN_EDITS_ANSWER_SHAPES, PLAN_EDITS_PART_SCHEMA_NAMES, PLAN_EDIT_OP_PART, PLAN_EDIT_SHAPE, PLAN_EDIT_WIRE_KEYS, PLAN_PARTS, PLAN_PART_KEYS, PLAN_WIRE_DERIVED, PLAN_WIRE_PART_SCHEMA_NAMES, PLAN_WIRE_SHAPE, PRICING_PATTERN, PUBLISH_BLOCKING_PLACEHOLDERS, PageDataKind, PathIssueCollector, PatternDirective, PatternGlobalPosition, PatternOpens, PatternPlaceholder, PatternRecipe, PhoneMenuBreakpoint, PlaceholderKind, PlanChangeAction, PlanChangeKind, PlanDataSourceMode, PlanDataSourceType, PlanEditIssueCode, PlanEditOp, PlanEditsOutcome, PlanPart, PlanWireEntry, PlanWireShapeError, PlanWordIssueCode, PreflightRefusalCode, PublishRefusalCode, REQUIRED_CONTENT_ROLES, RelativeOp, SAMPLE_IMAGE_REF, SCENE_LEVEL, SCENE_OTHER_PAGES, SITE_CHECKS, SITE_FACT_LABELS, SITE_HEADER_PATTERN, SITE_LIBRARY, SITE_LOCALES, SITE_NEED_IDS, SITE_PATTERNS, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_ARCHETYPES, SPEC_SITE_COPY_LENGTHS, SPEC_SITE_DENSITY_COPY, SPEC_SITE_FACTS, SPEC_SITE_LIBRARY, SPEC_SITE_LOCALES, SPEC_SITE_NEED_IDS, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_REQUIRED_ROLES, SPEC_SITE_ROLES, SPEC_SITE_TEMPLATES, STOCK_FAMILIES, STOCK_FAMILY_INTENTS, STOCK_INTENT_ORDER, STOCK_INTENT_SUBJECTS, STOCK_ITEM_ASPECT, STOCK_MIN_KEPT, STOCK_PROVIDER_TERMS, STOCK_SUBJECT_WORDS, STRICT_SCHEMA_BUDGET, STRICT_SCHEMA_LIMITS, STUDIO_TEMPLATE, SiteBuildKind, SiteBuildStatus, SiteCheckId, SiteFindingCode, SiteLocale, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, StepState, StockIntent, StockOrientation, StockProviderId, StockReviewFlag, StockReviewVerdict, StockSlotKind, StockSubject, addBarItem, addStockCredits, aiStepParts, applyOwnPhotoGalleries, applyPlanEdits, applyStockItemPhotos, applyStockPhotos, archetypeIssues, aspectRatioOf, assertStyleSlots, assertValidSitePlan, auditSite, barIconForRoute, blocksPublish, buildKeys, buildStepFacts, builtHomePageId, composeNavHeader, composeSection, composeSite, contentTypePreviewFields, contentTypeToWire, copyLengthOf, costUsd, createSerializedNode, creditsOfUsd, dataSourceToWire, derivedDataSources, describePlanData, describeShapeKey, entranceAction, entranceInteraction, estimateStepCredits, expandPlanWire, expandWireContentType, expandWireDataSource, expandWireEdit, expandWireField, expandWirePage, expandWireSection, failedBuildStep, fieldToWire, findNavRoot, isActiveBuild, isNonEmptyString, isPlainObject, isRtlLocale, jsonAnyOf, jsonBoolean, jsonClosedObject, jsonInteger, jsonListOf, jsonOneOf, jsonSchemaKeywords, jsonSchemaObjects, jsonShapedObject, jsonText, modelCanDo, moveBarItem, navPages, navShapeBreakpoint, navShapeOf, nextSourceOf, nodeBindPaths, orientationOfRatio, pageToWire, parsePatternPath, parseSampleImageRef, pathAt, patternById, patternHasForm, patternLinkSlots, patternListGap, patternManifest, patternNeedsBinding, patternNodes, patternOptionalParts, patternRoleNeeds, patternScopes, patternSlotBudgets, patternSlots, patternTakesBinding, phoneMenuPages, planEditOps, planEditToWire, planEditWireGaps, planEditWireKeys, planEditWireOps, planEditWireShape, planEditsFromWire, planEditsJsonSchema, planEditsToWire, planEntrances, planFromTemplate, planNavShape, planOwnPhotos, planPartOfPath, planPartToWire, planStockPhotos, planToWire, planWireGaps, planWirePartJsonSchema, planWirePartShape, planWordIssues, publishRefusal, publishVerdict, recipeListBinds, releasedLayoutDefaults, removeBarItem, requiredAcknowledgements, requiredShapeKeys, roleField, routeMatches, routeParams, sampleImageRef, scoreStockPhoto, sectionEntrances, sectionPatternIds, sectionToWire, setStyleProps, shapeKeys, showcaseGlobals, showcasePages, showcasePlans, showcaseScenes, siteNavPages, slotBudget, stockCopyKey, stockCreditLine, stockCreditLines, stockCreditNode, stockCreditNodeId, stockFits, stockGroupOf, stockItemSlots, stockKept, stockPhotoRatio, stockPhotoSubject, stockPhotoUsable, stockPhotoWords, stockSlots, stockWord, stockWords, strictSchemaComplexity, strictSchemaRefusal, typicalStepTokens, validatePlanEdits, validateSitePlan, walkSerialized, wireContentTypeJsonSchema, wireDataSourceJsonSchema, wireFieldJsonSchema, wirePageJsonSchema, wireSectionJsonSchema, withDerivedSources, wordPattern, writtenTexts };
-export type { AddBarItemResult, AiEntitlementsView, AiMeter, AiModelEntry, AiRefusal, AiTokenCounts, AiTokenPrice, AuditPage, AuditPlaceholder, BarItemsEditResult, BuildNotice, BuildStepError, BuildStepFacts, BuildStepRecord, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedNavHeader, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSection, ComposedSite, ContentFieldPlan, ContentRoles, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, CreatedRecord, DataSourcePlan, DynamicKeysAsList, EntranceAction, EntranceActionOptions, EntranceInteraction, EntranceMark, EntranceSpec, EntranceStamp, FactKey, JsonSchema, NavHeaderInput, NavHeaderOptions, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, OwnPhotoPlacement, PageArchetype, PageArchetypeId, PageArchetypeSlot, PageData, PageDataLine, PagePlan, PageSectionPlan, PageSeoPlan, PathIssue, PatternManifestEntry, PatternManifestOptions, PatternNode, PatternPath, PatternRoleNeed, PatternTrack, PlainObject, PlanChange, PlanEdit, PlanEditIssue, PlanEditResult, PlanEditsAnswer, PlanEntrancesInput, PlanWireContext, PlanWireParts, PlanWordContext, PlanWordIssue, PreflightRefusal, PublishRefusal, RecipeListBinds, RelativeDataSourcePlan, SectionEntrances, SectionInput, SectionOptions, SerializedBinding, SerializedNode, SerializedResponsive, ShapeEntry, ShapeIssueCodes, ShowcaseInput, SiteAudit, SiteAuditOptions, SiteAuditSnapshot, SiteBuildRun, SiteBusiness, SiteCheck, SiteFinding, SiteNeedId, SitePageRef, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, StockCredit, StockItemSlot, StockLink, StockNeed, StockPhoto, StockPhotoTraits, StockPlacement, StockPlanOptions, StockProviderTerms, StockReview, StockSlot, StockTarget, StrictSchemaComplexity, StrictSchemaRefusal, TemplatePlanInput, UndoKept, UndoPreview, UndoRecord, WireOptions, WrittenText };
+/**
+ * The owner's film on a built site (premium sites SC6b). The owner gives a video in Analysis; the wizard's browser makes
+ * it pictures (cms-client `FramesPrepareService`); the build places it. A model never picks the film's pattern — the
+ * manifest and the plan wire leave it out — so ONE pure placement decides where it goes, run by the wizard to draw the
+ * Plan and by the server to build: they cannot disagree.
+ */
+/** The pattern a film plays in: the one whose Video is marked `film` in the contract. */
+declare const FILM_PATTERN: string;
+/** Why a film stays off the site. Each is said to the owner on the Plan step. */
+declare enum FilmUnplaced {
+    /** How animated is below Expressive: no section holds the page there. */
+    NotExpressive = "notExpressive",
+    /** The home page does not open with a hero to play it in. */
+    NoHero = "noHero",
+    /** The home page already holds the page elsewhere (one Scene per page). */
+    AnotherScene = "anotherScene",
+    /** Too few pictures to play smoothly over the shortest hold (media-core `FILM_MIN_PICTURES`). */
+    TooShort = "tooShort"
+}
+/** Where the film plays: the home page's first section when it is a hero. */
+interface FilmTarget {
+    readonly page: number;
+    readonly section: number;
+}
+type FilmPlacement = {
+    readonly target: FilmTarget;
+    readonly unplaced?: undefined;
+} | {
+    readonly target?: undefined;
+    readonly unplaced: FilmUnplaced;
+};
+/** Where a film WOULD play on this plan (the Plan step asks before the pictures exist). */
+declare function filmPlacement(plan: Pick<SitePlan, 'design' | 'pages'>): FilmPlacement;
+interface PlacedFilm {
+    readonly plan: SitePlan;
+    readonly unplaced?: FilmUnplaced;
+}
+/**
+ * The plan with the owner's film in it: `film` set, and the home page's hero becomes the film's pattern, keeping the
+ * hero's words and links that the film's pattern has. A film that cannot play (unreadable, too few pictures) or a plan
+ * with no place for it leaves the plan as it was — the hero keeps its picture, and the builder can add the film later.
+ */
+declare function placeFilm(plan: SitePlan, sequence: unknown): PlacedFilm;
+/** The film's pictures as the composer stamps them, and the height its Scene holds the page for. */
+declare function filmOfPlan(plan: Pick<SitePlan, 'film'>): {
+    sequence: FrameSequence;
+    heightVh: number;
+} | null;
+
+export { ACTIVE_BUILD_STATUSES, AI_REFUSAL_NEXT, AI_REFUSAL_STATUS, AI_STEPS, AI_STEP_LABELS, AI_STEP_NEEDS, AI_STEP_PART_TOKENS, AI_STEP_TYPICAL_TOKENS, AiCallStatus, AiCapability, AiFeature, AiGenerationStage, AiKeyMode, AiLimit, AiNextKind, AiProviderId, AiRefusalCode, AiStep, BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BUILD_STEPS, BaselineRole, BindScope, BuildNoticeCode, BuildStep, CONTENT_ROLE_MEANINGS, CREDITS_PER_USD, CardBindTarget, CheckSeverity, ComposeError, ComposeIssueCode, ContentFieldControl, ContentFieldType, ContentRole, ContentTypeAction, CreatedKind, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, DEFAULT_SITE_LOCALE, ENTRANCE_EASING, ENTRANCE_ORIGIN_LOOK, ENTRANCE_TRIGGER, EntrancePart, EntranceSide, FACT_KEYS, FIELD_TYPE_OF_CONTROL, FILM_PATTERN, FINAL_GENERATION_STAGES, FINDING_SEVERITY, FilmUnplaced, GRAMMAR_TOO_LARGE_MESSAGE, GlobalSlot, HEBREW_PREFIXES, JSON_SCHEMA_BANNED_KEYWORDS, JsonSchemaShapeError, KeptReason, NAV_PART_LABELS, NAV_SHAPE_COPY, NEUTRAL_STYLE_PROPS, NODE_BASELINES, NO_TOKENS, NavPagesSource, NavRole, NavShape, NavShapeError, PAGE_ARCHETYPES, PLAN_EDITS_ANSWER_SHAPES, PLAN_EDITS_PART_SCHEMA_NAMES, PLAN_EDIT_OP_PART, PLAN_EDIT_SHAPE, PLAN_EDIT_WIRE_KEYS, PLAN_PARTS, PLAN_PART_KEYS, PLAN_WIRE_DERIVED, PLAN_WIRE_PART_SCHEMA_NAMES, PLAN_WIRE_SHAPE, PRICING_PATTERN, PUBLISH_BLOCKING_PLACEHOLDERS, PageDataKind, PathIssueCollector, PatternDirective, PatternGlobalPosition, PatternOpens, PatternPlaceholder, PatternRecipe, PhoneMenuBreakpoint, PlaceholderKind, PlanChangeAction, PlanChangeKind, PlanDataSourceMode, PlanDataSourceType, PlanEditIssueCode, PlanEditOp, PlanEditsOutcome, PlanPart, PlanWireEntry, PlanWireShapeError, PlanWordIssueCode, PreflightRefusalCode, PublishRefusalCode, REQUIRED_CONTENT_ROLES, RelativeOp, SAMPLE_IMAGE_REF, SCENE_LEVEL, SCENE_OTHER_PAGES, SHOWCASE_FILM, SITE_CHECKS, SITE_FACT_LABELS, SITE_HEADER_PATTERN, SITE_LIBRARY, SITE_LOCALES, SITE_NEED_IDS, SITE_PATTERNS, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_ARCHETYPES, SPEC_SITE_COPY_LENGTHS, SPEC_SITE_DENSITY_COPY, SPEC_SITE_FACTS, SPEC_SITE_LIBRARY, SPEC_SITE_LOCALES, SPEC_SITE_NEED_IDS, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_REQUIRED_ROLES, SPEC_SITE_ROLES, SPEC_SITE_TEMPLATES, STOCK_FAMILIES, STOCK_FAMILY_INTENTS, STOCK_INTENT_ORDER, STOCK_INTENT_SUBJECTS, STOCK_ITEM_ASPECT, STOCK_MIN_KEPT, STOCK_PROVIDER_TERMS, STOCK_SUBJECT_WORDS, STRICT_SCHEMA_BUDGET, STRICT_SCHEMA_LIMITS, STUDIO_TEMPLATE, SiteBuildKind, SiteBuildStatus, SiteCheckId, SiteFindingCode, SiteLocale, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, StepState, StockIntent, StockOrientation, StockProviderId, StockReviewFlag, StockReviewVerdict, StockSlotKind, StockSubject, addBarItem, addStockCredits, aiStepParts, applyOwnPhotoGalleries, applyPlanEdits, applyStockItemPhotos, applyStockPhotos, archetypeIssues, aspectRatioOf, assertStyleSlots, assertValidSitePlan, auditSite, barIconForRoute, blocksPublish, buildKeys, buildStepFacts, builtHomePageId, composeNavHeader, composeSection, composeSite, contentTypePreviewFields, contentTypeToWire, copyLengthOf, costUsd, createSerializedNode, creditsOfUsd, dataSourceToWire, derivedDataSources, describePlanData, describeShapeKey, entranceAction, entranceInteraction, estimateStepCredits, expandPlanWire, expandWireContentType, expandWireDataSource, expandWireEdit, expandWireField, expandWirePage, expandWireSection, failedBuildStep, fieldToWire, filmOfPlan, filmPlacement, findNavRoot, isActiveBuild, isNonEmptyString, isPlainObject, isRtlLocale, jsonAnyOf, jsonBoolean, jsonClosedObject, jsonInteger, jsonListOf, jsonOneOf, jsonSchemaKeywords, jsonSchemaObjects, jsonShapedObject, jsonText, modelCanDo, moveBarItem, navPages, navShapeBreakpoint, navShapeOf, nextSourceOf, nodeBindPaths, orientationOfRatio, pageToWire, parsePatternPath, parseSampleImageRef, pathAt, patternById, patternHasForm, patternLinkSlots, patternListGap, patternManifest, patternNeedsBinding, patternNodes, patternOptionalParts, patternRoleNeeds, patternScopes, patternSlotBudgets, patternSlots, patternTakesBinding, phoneMenuPages, placeFilm, planEditOps, planEditToWire, planEditWireGaps, planEditWireKeys, planEditWireOps, planEditWireShape, planEditsFromWire, planEditsJsonSchema, planEditsToWire, planEntrances, planFromTemplate, planNavShape, planOwnPhotos, planPartOfPath, planPartToWire, planStockPhotos, planToWire, planWireGaps, planWirePartJsonSchema, planWirePartShape, planWordIssues, publishRefusal, publishVerdict, recipeListBinds, releasedLayoutDefaults, removeBarItem, requiredAcknowledgements, requiredShapeKeys, roleField, routeMatches, routeParams, sampleImageRef, scoreStockPhoto, sectionEntrances, sectionPatternIds, sectionToWire, setStyleProps, shapeKeys, showcaseGlobals, showcasePages, showcasePlans, showcaseScenes, siteNavPages, slotBudget, stockCopyKey, stockCreditLine, stockCreditLines, stockCreditNode, stockCreditNodeId, stockFits, stockGroupOf, stockItemSlots, stockKept, stockPhotoRatio, stockPhotoSubject, stockPhotoUsable, stockPhotoWords, stockSlots, stockWord, stockWords, strictSchemaComplexity, strictSchemaRefusal, typicalStepTokens, validatePlanEdits, validateSitePlan, walkSerialized, wireContentTypeJsonSchema, wireDataSourceJsonSchema, wireFieldJsonSchema, wirePageJsonSchema, wireSectionJsonSchema, withDerivedSources, wordPattern, writtenTexts };
+export type { AddBarItemResult, AiEntitlementsView, AiMeter, AiModelEntry, AiRefusal, AiTokenCounts, AiTokenPrice, AuditPage, AuditPlaceholder, BarItemsEditResult, BuildNotice, BuildStepError, BuildStepFacts, BuildStepRecord, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedNavHeader, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSection, ComposedSite, ContentFieldPlan, ContentRoles, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, CreatedRecord, DataSourcePlan, DynamicKeysAsList, EntranceAction, EntranceActionOptions, EntranceInteraction, EntranceMark, EntranceSpec, EntranceStamp, FactKey, FilmPlacement, FilmTarget, JsonSchema, NavHeaderInput, NavHeaderOptions, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, OwnPhotoPlacement, PageArchetype, PageArchetypeId, PageArchetypeSlot, PageData, PageDataLine, PagePlan, PageSectionPlan, PageSeoPlan, PathIssue, PatternManifestEntry, PatternManifestOptions, PatternNode, PatternPath, PatternRoleNeed, PatternTrack, PlacedFilm, PlainObject, PlanChange, PlanEdit, PlanEditIssue, PlanEditResult, PlanEditsAnswer, PlanEntrancesInput, PlanFilm, PlanWireContext, PlanWireParts, PlanWordContext, PlanWordIssue, PreflightRefusal, PublishRefusal, RecipeListBinds, RelativeDataSourcePlan, SectionEntrances, SectionInput, SectionOptions, SerializedBinding, SerializedNode, SerializedResponsive, ShapeEntry, ShapeIssueCodes, ShowcaseInput, SiteAudit, SiteAuditOptions, SiteAuditSnapshot, SiteBuildRun, SiteBusiness, SiteCheck, SiteFinding, SiteNeedId, SitePageRef, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, StockCredit, StockItemSlot, StockLink, StockNeed, StockPhoto, StockPhotoTraits, StockPlacement, StockPlanOptions, StockProviderTerms, StockReview, StockSlot, StockTarget, StrictSchemaComplexity, StrictSchemaRefusal, TemplatePlanInput, UndoKept, UndoPreview, UndoRecord, WireOptions, WrittenText };

package/harness-core/index.d.ts

@@ -1,6 +1,7 @@
 import { MotionId, MoodId, TintId, DensityId, DesignMotion, DesignChoices, DesignMode, StylePreset, ShapeId, AnimateId } from '@vectoriox/iox-ui/design-core';
 import { FactKey, PathIssue, PlainObject, JsonSchema, SiteTemplate, ShapeEntry, AiGenerationStage, AiStep, SitePlan, PlanEdit, PlanChange, SiteAudit } from '@vectoriox/iox-ui/generation-core';
 export { JsonSchema } from '@vectoriox/iox-ui/generation-core';
+import { FrameSequence } from '@vectoriox/iox-ui/media-core';
 
 declare const SPEC_HARNESS_SOURCE: {
     readonly repo: "nextlevelbuilder/ui-ux-pro-max-skill";
@@ -2948,11 +2949,13 @@ interface AiGenerationView {
     stage: `${AiGenerationStage}`;
     /** The model step the runner is working on; null = the owner's move. */
     task: `${AiStep}` | null;
+    /** `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: {
@@ -2984,7 +2987,9 @@ 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?: {
@@ -3006,12 +3011,14 @@ 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). */
 declare const GENERATION_LIMITS: {
     readonly promptChars: 4000;
     readonly files: 12;
     readonly addresses: 3;
     readonly sentenceChars: 500;
+    readonly plans: 5;
 };
 
 /**

package/media-core/index.d.ts

@@ -111,6 +111,24 @@ declare const PHONE_LONG_SIDE = 1100;
 declare function fittedFrameSize(width: number, height: number, longSide: number): FrameSizes;
 /** How many pictures a video of `seconds` becomes. */
 declare function videoFrameCount(seconds: number): number;
+/**
+ * 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.
+ */
+declare 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. */
+declare const FILM_MIN_SCREENS = 1;
+declare 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. */
+declare const FILM_PREPARED_PICTURES: number;
+/** The fewest pictures a placed film may have: smooth over the shortest hold. */
+declare const FILM_MIN_PICTURES: number;
+/**
+ * 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.
+ */
+declare function filmScreensFor(count: number): number | null;
 /** Which of `sourceCount` pictures make a set of `count`, spread evenly, first and last always in. */
 declare function sampledFrameIndexes(sourceCount: number, count: number): number[];
 /** Rendered frames in their real order: `frame2` before `frame10`. */
@@ -473,5 +491,5 @@ declare function attachVideos(container: ParentNode, options?: VideoRuntimeOptio
 /** The runtime already running at `el`, if any. */
 declare function videoRuntimeOf(el: Element | null | undefined): VideoRuntime | null;
 
-export { CONSENT_GRANT_EVENT, CONSENT_PREFERENCES_EVENT, FRAMES_PHONE_MAX_WIDTH, FRAMES_SHOWING_ATTRIBUTE, FRAMES_UNPACKED_BYTES, FRAME_BLEND_STEPS, FRAME_SEQUENCE_ID, FrameExtension, FramePlayer, FrameSet, FramesClass, MAX_FRAMES, MAX_FRAME_BYTES, PHONE_LONG_SIDE, VIDEO_EMBED_ORIGINS, VIDEO_NODE_TYPE, VIDEO_PROVIDER_COMPANY, VIDEO_PROVIDER_LABEL, VIDEO_WORDS, VideoAttribute, VideoClass, VideoIcon, VideoKind, VideoMode, VideoRuntime, VideoSource, VideoTrait, WIDE_LONG_SIDE, attachVideoAt, attachVideos, documentConsentTransport, fittedFrameSize, frameBlendAt, frameFileName, frameIndexAt, frameLoadOrder, framePosition, frameSetFor, frameSummary, frameUrl, framesToHold, isThirdPartyPoster, nearestLoadedFrame, normalizeFrameSequence, parseVideoUrl, phoneFrameSrcset, planVideo, readConsentRecord, sampledFrameIndexes, serializeVideoAttributes, sortFrameFiles, unpackedFrameCount, videoConsentCategory, videoEmbedUrl, videoFrameCount, videoInnerHtml, videoPlayLabel, videoPosterFileName, videoProp, videoRefOf, videoRootAttributes, videoRuntimeOf, videoSourceOf, videoThumbnailRequest, videoWords };
+export { CONSENT_GRANT_EVENT, CONSENT_PREFERENCES_EVENT, FILM_MAX_SCREENS, FILM_MIN_PICTURES, FILM_MIN_SCREENS, FILM_PREPARED_PICTURES, FILM_SMOOTH_PER_SCREEN, FRAMES_PHONE_MAX_WIDTH, FRAMES_SHOWING_ATTRIBUTE, FRAMES_UNPACKED_BYTES, FRAME_BLEND_STEPS, FRAME_SEQUENCE_ID, FrameExtension, FramePlayer, FrameSet, FramesClass, MAX_FRAMES, MAX_FRAME_BYTES, PHONE_LONG_SIDE, VIDEO_EMBED_ORIGINS, VIDEO_NODE_TYPE, VIDEO_PROVIDER_COMPANY, VIDEO_PROVIDER_LABEL, VIDEO_WORDS, VideoAttribute, VideoClass, VideoIcon, VideoKind, VideoMode, VideoRuntime, VideoSource, VideoTrait, WIDE_LONG_SIDE, attachVideoAt, attachVideos, documentConsentTransport, filmScreensFor, fittedFrameSize, frameBlendAt, frameFileName, frameIndexAt, frameLoadOrder, framePosition, frameSetFor, frameSummary, frameUrl, framesToHold, isThirdPartyPoster, nearestLoadedFrame, normalizeFrameSequence, parseVideoUrl, phoneFrameSrcset, planVideo, readConsentRecord, sampledFrameIndexes, serializeVideoAttributes, sortFrameFiles, unpackedFrameCount, videoConsentCategory, videoEmbedUrl, videoFrameCount, videoInnerHtml, videoPlayLabel, videoPosterFileName, videoProp, videoRefOf, videoRootAttributes, videoRuntimeOf, videoSourceOf, videoThumbnailRequest, videoWords };
 export type { ConsentGrantDetail, ConsentTransport, FrameBlend, FramePlayerOptions, FrameSequence, FrameSetInfo, FrameSizes, VideoMarkupOptions, VideoNodeLike, VideoPlan, VideoRef, VideoRuntimeOptions, VideoThumbnailRequest, VideoWords };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.78.0",
+  "version": "5.80.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/scene-core/index.d.ts

@@ -218,10 +218,7 @@ declare const SCENE_MAX_SCREENS = 20;
  */
 declare function sceneScreensOf(height: string | null | undefined): number | null;
 declare function sceneHeightForScreens(screens: number): string;
-/**
- * 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.
- */
+/** Pictures per screen of scrolling at which a played film stays smooth (media-core's, which the composer sizes by). */
 declare const SCENE_FILM_SMOOTH = 40;
 interface SceneFilmDensity {
     /** Pictures per screen of scrolling over most of the play: half its scroll holds at least this many. */

package/src/generation-core/ai-run.ts

@@ -177,7 +177,10 @@ export function modelCanDo(model: Pick<AiModelEntry, 'capabilities'>, step: AiSt
 export enum AiRefusalCode {
     NotInPlan = 'ai.notInPlan',
     OutOfCredits = 'ai.outOfCredits',
+    /** A step used more than twice its estimate (a loop), or the build its plan's `aiCreditsPerGeneration`. */
     CapReached = 'ai.capReached',
+    /** The build asked for `GENERATION_LIMITS.plans` plans already — build one, change it with a sentence, or start over. */
+    PlansUsed = 'ai.plansUsed',
     NotConnected = 'ai.notConnected',
     KeyInvalid = 'ai.keyInvalid',
     PlanUnknown = 'ai.planUnknown',
@@ -188,6 +191,7 @@ export const AI_REFUSAL_STATUS: Readonly<Record<AiRefusalCode, number>> = {
     [AiRefusalCode.NotInPlan]: 403,
     [AiRefusalCode.OutOfCredits]: 402,
     [AiRefusalCode.CapReached]: 402,
+    [AiRefusalCode.PlansUsed]: 409,
     [AiRefusalCode.NotConnected]: 409,
     [AiRefusalCode.KeyInvalid]: 409,
     [AiRefusalCode.PlanUnknown]: 503,
@@ -201,12 +205,15 @@ export enum AiNextKind {
     Settings = 'settings',
     /** Try again later, or with less. */
     Retry = 'retry',
+    /** Keep the plan there is: build it, or change it with a sentence. */
+    KeepPlan = 'keepPlan',
 }
 
 export const AI_REFUSAL_NEXT: Readonly<Record<AiRefusalCode, AiNextKind>> = {
     [AiRefusalCode.NotInPlan]: AiNextKind.Contact,
     [AiRefusalCode.OutOfCredits]: AiNextKind.Contact,
     [AiRefusalCode.CapReached]: AiNextKind.Retry,
+    [AiRefusalCode.PlansUsed]: AiNextKind.KeepPlan,
     [AiRefusalCode.NotConnected]: AiNextKind.Settings,
     [AiRefusalCode.KeyInvalid]: AiNextKind.Settings,
     [AiRefusalCode.PlanUnknown]: AiNextKind.Retry,
@@ -219,6 +226,8 @@ export interface AiRefusal {
     remaining?: number;
     /** What the refused call would have cost, about. */
     estimate?: number;
+    /** `PlansUsed`: how many plans one build may ask for. */
+    plans?: number;
     next: { kind: AiNextKind; href?: string };
 }
 

package/src/generation-core/compose-site.ts

@@ -10,6 +10,7 @@ import {
 } from '@vectoriox/iox-ui/composite-core';
 
 import { EntranceMark, EntrancePart, planEntrances } from './entrances';
+import { filmOfPlan } from './film';
 import { NODE_BASELINES } from './node-baselines.generated';
 import {
     BindScope, CardBindTarget, parsePatternPath, PatternDirective, PatternNode, PatternOpens, PatternPlaceholder, PatternRecipe, PatternTrack, SitePattern, patternById,
@@ -206,6 +207,8 @@ const IMAGE = 'Image';
 const VIDEO = 'Video';
 /** A Video's source prop (media-core `VideoTrait.Source` — not `source`, which names a data source). */
 const VIDEO_SOURCE_PROP = 'videoSource';
+/** A Video's pictures the scroll plays (media-core `VideoTrait.Frames`). */
+const VIDEO_FRAMES_PROP = 'frames';
 const DIALOG = 'Dialog';
 const SUBMIT_BUTTON = 'SubmitButton';
 const FORM_SUCCESS = 'FormSuccess';
@@ -602,6 +605,13 @@ function composeNode(given: PatternNode, id: string, repeater: RepeaterScope | n
         setProp(node, VIDEO_SOURCE_PROP, 'file');
         setProp(node, 'mode', pn.video);
     }
+    // SC6b: a film pattern's Video plays the owner's pictures (the build places the pattern only with a film).
+    if (pn.film) {
+        if (type !== VIDEO) throw new ComposeError(`${id}: "film" belongs on a Video`);
+        const film = filmOfPlan(ctx.plan);
+        if (!film) throw new ComposeError(`${id}: a film's pattern on a plan with no film`);
+        setProp(node, VIDEO_FRAMES_PROP, film.sequence);
+    }
     if (pn.ph === PatternPlaceholder.Video) {
         setProp(node, 'src', '');
         ctx.placeholders.push({ nodeId: id, owner: ctx.owner, kind: PlaceholderKind.Video, text: '' });
@@ -1013,6 +1023,9 @@ function composePattern(pattern: SitePattern, id: string, ctx: Ctx, motion: Sect
     wireShownWhen(node, own.shownWhen ?? []);
     // A Scene moves by the scroll alone: the look's entrances would fade its pinned stage in on arrival (SC6).
     if (motion && !pattern.global && !pattern.scene) stampEntrances(node, pattern.family, own.entrances ?? [], motion);
+    // SC6b, the density rule: a film's Scene holds the page as long as its pictures stay smooth, and no longer.
+    const film = pattern.film ? filmOfPlan(ctx.plan) : null;
+    if (film) setStyleProps(node, { height: `${film.heightVh}vh` });
     node.label = pattern.label;
     return node;
 }

package/src/generation-core/film.ts

@@ -0,0 +1,91 @@
+import { filmScreensFor, FrameSequence, normalizeFrameSequence } from '@vectoriox/iox-ui/media-core';
+
+import { patternById, patternLinkSlots, patternSlots, SCENE_LEVEL, SITE_PATTERNS } from './patterns';
+import { PageSectionPlan, SitePlan } from './site-plan.model';
+
+/**
+ * The owner's film on a built site (premium sites SC6b). The owner gives a video in Analysis; the wizard's browser makes
+ * it pictures (cms-client `FramesPrepareService`); the build places it. A model never picks the film's pattern — the
+ * manifest and the plan wire leave it out — so ONE pure placement decides where it goes, run by the wizard to draw the
+ * Plan and by the server to build: they cannot disagree.
+ */
+
+/** The pattern a film plays in: the one whose Video is marked `film` in the contract. */
+export const FILM_PATTERN: string = Object.entries(SITE_PATTERNS).find(([, p]) => p.film)?.[0] ?? '';
+
+/** Why a film stays off the site. Each is said to the owner on the Plan step. */
+export enum FilmUnplaced {
+    /** How animated is below Expressive: no section holds the page there. */
+    NotExpressive = 'notExpressive',
+    /** The home page does not open with a hero to play it in. */
+    NoHero = 'noHero',
+    /** The home page already holds the page elsewhere (one Scene per page). */
+    AnotherScene = 'anotherScene',
+    /** Too few pictures to play smoothly over the shortest hold (media-core `FILM_MIN_PICTURES`). */
+    TooShort = 'tooShort',
+}
+
+/** Where the film plays: the home page's first section when it is a hero. */
+export interface FilmTarget {
+    readonly page: number;
+    readonly section: number;
+}
+
+export type FilmPlacement = { readonly target: FilmTarget; readonly unplaced?: undefined } | { readonly target?: undefined; readonly unplaced: FilmUnplaced };
+
+/** Where a film WOULD play on this plan (the Plan step asks before the pictures exist). */
+export function filmPlacement(plan: Pick<SitePlan, 'design' | 'pages'>): FilmPlacement {
+    if ((plan.design as { animate?: string }).animate !== SCENE_LEVEL) return { unplaced: FilmUnplaced.NotExpressive };
+    const page = plan.pages.findIndex(p => p.isHome);
+    const sections = page >= 0 ? plan.pages[page].sections : [];
+    const first = patternById(sections[0]?.pattern);
+    if (!first || first.family !== FILM_FAMILY) return { unplaced: FilmUnplaced.NoHero };
+    if (sections.slice(1).some(s => patternById(s.pattern)?.scene)) return { unplaced: FilmUnplaced.AnotherScene };
+    return { target: { page, section: 0 } };
+}
+
+const FILM_FAMILY = SITE_PATTERNS[FILM_PATTERN]?.family ?? 'hero';
+
+export interface PlacedFilm {
+    readonly plan: SitePlan;
+    readonly unplaced?: FilmUnplaced;
+}
+
+/**
+ * The plan with the owner's film in it: `film` set, and the home page's hero becomes the film's pattern, keeping the
+ * hero's words and links that the film's pattern has. A film that cannot play (unreadable, too few pictures) or a plan
+ * with no place for it leaves the plan as it was — the hero keeps its picture, and the builder can add the film later.
+ */
+export function placeFilm(plan: SitePlan, sequence: unknown): PlacedFilm {
+    const film = normalizeFrameSequence(sequence);
+    if (!film || filmScreensFor(film.wide.count) === null) return { plan, unplaced: FilmUnplaced.TooShort };
+    const placement = filmPlacement(plan);
+    if (!placement.target) return { plan, unplaced: placement.unplaced };
+    const { page, section } = placement.target;
+    const pages = plan.pages.map((p, i) => i !== page ? p : {
+        ...p,
+        sections: p.sections.map((s, j) => (j === section ? filmSection(s) : s)),
+    });
+    return { plan: { ...plan, pages, film: { sequence: film } } };
+}
+
+function filmSection(hero: PageSectionPlan): PageSectionPlan {
+    const pattern = SITE_PATTERNS[FILM_PATTERN];
+    const slots = new Set(patternSlots(pattern));
+    const links = new Set(patternLinkSlots(pattern));
+    const keep = (values: Readonly<Record<string, string>> | undefined, allowed: Set<string>) => {
+        const kept = Object.entries(values ?? {}).filter(([key]) => allowed.has(key));
+        return kept.length ? Object.fromEntries(kept) : undefined;
+    };
+    const keptSlots = keep(hero.slots, slots);
+    const keptLinks = keep(hero.links, links);
+    return { pattern: FILM_PATTERN, ...(keptSlots ? { slots: keptSlots } : {}), ...(keptLinks ? { links: keptLinks } : {}) };
+}
+
+/** The film's pictures as the composer stamps them, and the height its Scene holds the page for. */
+export function filmOfPlan(plan: Pick<SitePlan, 'film'>): { sequence: FrameSequence; heightVh: number } | null {
+    const sequence = normalizeFrameSequence(plan.film?.sequence);
+    const screens = sequence ? filmScreensFor(sequence.wide.count) : null;
+    // A Scene's root holds the page for its height less the one screen its stage fills.
+    return sequence && screens !== null ? { sequence, heightVh: Math.round((screens + 1) * 100) } : null;
+}

package/src/generation-core/patterns.ts

@@ -93,6 +93,8 @@ export interface PatternNode {
     /** SC6: a Scene layer's scene-core tracks, written to the node's `sceneTracks` (and `scenePhoneTracks`). */
     readonly tracks?: ReadonlyArray<PatternTrack>;
     readonly phoneTracks?: ReadonlyArray<PatternTrack>;
+    /** SC6b: the Video a film pattern plays the owner's film in (its `frames`). */
+    readonly film?: boolean;
 }
 
 /**
@@ -154,6 +156,8 @@ export interface SitePattern {
     /** SC6: a Scene section — held while the page scrolls, moved by the scroll. Only at How animated Expressive, at
      *  most one per page and on at most two pages (`validateSitePlan`); it never takes the look's entrances. */
     readonly scene?: boolean;
+    /** SC6b: a Scene that plays the owner's film. Placed by `placeFilm`, never chosen: no manifest or wire lists it. */
+    readonly film?: boolean;
     readonly node: PatternNode;
 }
 
@@ -352,7 +356,7 @@ export interface PatternManifestOptions {
  */
 export function patternManifest(density?: string | null, options: PatternManifestOptions = {}): PatternManifestEntry[] {
     const scenes = !('animate' in options) || options.animate === SCENE_LEVEL;
-    return Object.entries(SITE_PATTERNS).filter(([, p]) => scenes || !p.scene).map(([id, p]) => ({
+    return Object.entries(SITE_PATTERNS).filter(([, p]) => !p.film && (scenes || !p.scene)).map(([id, p]) => ({
         id, family: p.family, label: p.label, intent: p.intent, ...(p.global ? { global: p.global } : {}),
         slots: Object.fromEntries(Object.keys(patternSlotBudgets(p)).map(slot => [slot, slotBudget(p, slot, density) as number])),
         links: patternLinkSlots(p),

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

@@ -196,6 +196,8 @@ export const PLAN_WIRE_DERIVED: Readonly<Record<string, string>> = {
     sourceTemplate: 'the AI never writes a template plan',
     sourceAi: 'this run (the context)',
     design: "the owner's pick (the context)",
+    'plan.film': "the owner's film, set by the build (SC6b)",
+    film: "the owner's film, set by the build (SC6b)",
 };
 
 const wireText = (spec: WireKey): string => {
@@ -252,9 +254,9 @@ const orNone = (values: ReadonlyArray<string>): JsonSchema => jsonOneOf([NONE, .
 const closedOrText = (values: ReadonlyArray<string>): JsonSchema => (values.length ? jsonOneOf(values) : jsonText());
 const shaped = (entry: `${PlanWireEntry}`, properties: Record<string, JsonSchema>) => jsonShapedObject(PLAN_WIRE_SHAPE[entry], properties, `wire ${entry}`);
 
-/** The patterns a page section may use (every non-global one), in library order. */
+/** The patterns a page section may use (every non-global one but a film's, which `placeFilm` places), in library order. */
 export function sectionPatternIds(): string[] {
-    return Object.entries(SITE_PATTERNS).filter(([, p]) => !p.global).map(([id]) => id);
+    return Object.entries(SITE_PATTERNS).filter(([, p]) => !p.global && !p.film).map(([id]) => id);
 }
 
 const sectionPatterns = () => sectionPatternIds().map(id => SITE_PATTERNS[id]);