@vectoriox/iox-ui 5.83.1 → 5.85.0

package/src/generation-core/stock-photos.ts

@@ -231,6 +231,40 @@ export type StockPlacement<T extends StockTarget = StockTarget> = T & { photo: S
 export interface StockPlanOptions {
     /** The business type's imagery line (harness-core `BusinessType.imagery`) — its words count for every slot. */
     imagery?: string;
+    /**
+     * M7 (premium sites PS4): the SITE the photos are chosen for (its organization). Among the photos that answer a slot
+     * nearly as well as the best (`STOCK_SEED_MARGIN`), the seed decides — so two sites of the same kind of business stop
+     * opening on the same hero, and the same site always gets the same photos. No seed: the library's order decides.
+     */
+    seed?: string;
+    /** M7: library keys other sites of this studio already show — chosen only when no photo they do not show fits. */
+    avoid?: ReadonlyArray<string>;
+}
+
+/** How far below the best score a photo may be and still be the seed's choice (one word of the plan's, about). */
+export const STOCK_SEED_MARGIN = 2;
+
+/** A stable 32-bit hash (FNV-1a) — the seed's order of the library, the same in every runtime. */
+function seededRank(seed: string, key: string): number {
+    let hash = 0x811c9dc5;
+    for (const ch of `${seed}:${key}`) {
+        hash ^= ch.codePointAt(0)!;
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash;
+}
+
+/** The best of `pool` for `slot`: the highest score (ties: the library's order), or — with a seed — the seed's pick among
+ *  those within `STOCK_SEED_MARGIN` of it. */
+function bestFor(pool: ReadonlyArray<StockPhoto>, slot: StockNeed, imagery: ReadonlyArray<string>, seed: string | undefined): StockPhoto | undefined {
+    const scored = pool.map(photo => ({ photo, score: scoreStockPhoto(photo, slot, imagery) }));
+    const top = scored.reduce((m, s) => Math.max(m, s.score), -Infinity);
+    if (!seed) return scored.find(s => s.score === top)?.photo;
+    const near = scored.filter(s => s.score >= top - STOCK_SEED_MARGIN);
+    return near.reduce<{ photo: StockPhoto; rank: number } | undefined>((best, s) => {
+        const rank = seededRank(seed, s.photo.key);
+        return !best || rank < best.rank ? { photo: s.photo, rank } : best;
+    }, undefined)?.photo;
 }
 
 const intentRank = (intent: string) => STOCK_INTENT_ORDER.indexOf(intent as StockIntent);
@@ -239,15 +273,17 @@ const intentRank = (intent: string) => STOCK_INTENT_ORDER.indexOf(intent as Stoc
  * Which photo goes where (I2.1). Slots choose in intent order (the hero first, list items last; page order within),
  * each taking the best-scoring photo that FITS its shape (`stockFits`) and is not already on its page (or among its
  * type's samples) — a photo no slot has taken yet always before one another page shows. Ties go to the library's
- * order. A slot nothing fits keeps its empty box (a sample its abstract picture). None at all when the type says no
- * stock, and never a photo the review rejected or flagged. Returned in the slots' order.
+ * order — or, with a `seed` (M7), the site's own pick among those nearly as good, and another site's photos (`avoid`) only
+ * when nothing fresh fits. A slot nothing fits keeps its empty box (a sample its abstract picture). None at all when the
+ * type says no stock, and never a photo the review rejected or flagged. Returned in the slots' order.
  */
 export function planStockPhotos<T extends StockTarget>(slots: ReadonlyArray<T>, photos: ReadonlyArray<StockPhoto>, stockAllowed: boolean, opts: StockPlanOptions = {}): Array<StockPlacement<T>> {
     if (!stockAllowed) return [];
     const usable = photos.filter(stockPhotoUsable);
     const imagery = stockWords(opts.imagery);
     const order = slots.map((slot, i) => ({ slot, i })).sort((a, b) => intentRank(a.slot.intent) - intentRank(b.slot.intent) || a.i - b.i);
-    const used = new Set<string>();
+    // Another site's photos count as already shown: a fresh one that fits always comes first.
+    const used = new Set<string>(opts.avoid ?? []);
     const shownIn = new Map<string, Set<string>>();
     const placed = new Map<number, StockPlacement<T>>();
     for (const { slot, i } of order) {
@@ -255,13 +291,7 @@ export function planStockPhotos<T extends StockTarget>(slots: ReadonlyArray<T>,
         const here = shownIn.get(group) ?? new Set<string>();
         const candidates = usable.filter(p => !here.has(p.key) && stockFits(p, slot));
         const fresh = candidates.filter(p => !used.has(p.key));
-        const pool = fresh.length ? fresh : candidates;
-        let best: StockPhoto | undefined;
-        let bestScore = -Infinity;
-        for (const photo of pool) {
-            const score = scoreStockPhoto(photo, slot, imagery);
-            if (score > bestScore) { best = photo; bestScore = score; }
-        }
+        const best = bestFor(fresh.length ? fresh : candidates, slot, imagery, opts.seed);
         if (!best) continue;
         used.add(best.key);
         here.add(best.key);

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

@@ -10,6 +10,7 @@ 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,
 } from './site-plan.model';
+import { artDirectionIssues } from './art-direction';
 import { patternListGap } from './recipe-fields';
 import { SPEC_SITE_PLAN_SHAPE } from './site-spec.generated';
 import {
@@ -76,6 +77,8 @@ export enum SitePlanIssueCode {
     /** 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',
+    /** M7: the art direction is not a picture world with its five parts. Set by the generation, never by a model. */
+    ArtDirection = 'art-direction',
 }
 
 export type SitePlanIssue = PathIssue<SitePlanIssueCode>;
@@ -115,6 +118,7 @@ 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 ART_DIRECTION_KEYS = shapeKeys(SHAPE['artDirection']);
 const SECTION_KEYS = shapeKeys(SHAPE['section']);
 const GLOBAL_POSITION: Readonly<Record<`${GlobalSlot}`, `${PatternGlobalPosition}`>> = {
     [GlobalSlot.Header]: PatternGlobalPosition.Before,
@@ -508,6 +512,15 @@ function validateFilm(c: Collector, film: unknown, pages: unknown[]): void {
     });
 }
 
+/** M7: what every picture made for the site shares — a known world and its five parts (`artDirectionIssues`). */
+function validateArtDirection(c: Collector, direction: unknown): void {
+    if (direction === undefined) return;
+    if (isObject(direction)) c.keys(direction, ART_DIRECTION_KEYS, 'artDirection');
+    for (const issue of artDirectionIssues(direction)) {
+        c.add(issue.path ? SitePlanIssueCode.ArtDirection : SitePlanIssueCode.Shape, issue.path ? `artDirection.${issue.path}` : 'artDirection', issue.message);
+    }
+}
+
 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');
@@ -556,6 +569,7 @@ export function validateSitePlan(plan: unknown): SitePlanValidation {
     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', ''));
+    validateArtDirection(c, plan['artDirection']);
     return { valid: c.issues.length === 0, issues: c.issues };
 }
 

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

@@ -1,5 +1,5 @@
 import type { DensityId, DesignMotion, MoodId, MotionId, TintId } from '@vectoriox/iox-ui/design-core';
-import type { FactKey } from '@vectoriox/iox-ui/generation-core';
+import type { FactKey, PictureWorld } from '@vectoriox/iox-ui/generation-core';
 
 import {
     SPEC_BUSINESS_TYPES, SPEC_HARNESS_SOURCE, SPEC_NEEDS, SPEC_STRUCTURES, SPEC_USER_AVOIDS,
@@ -115,6 +115,8 @@ export interface BusinessType {
      *  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;
+    /** M7: the picture world a site's made pictures start in (generation-core `artDirectionFor`; contract site.pictureWorlds). */
+    readonly world: `${PictureWorld}`;
     readonly pages: ReadonlyArray<string>;
     /** The needs its page set implies, in page order (derived from `pages` at contract build). */
     readonly needs: ReadonlyArray<NeedId>;

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

@@ -1,6 +1,6 @@
 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 { AiGenerationStage, AiRefusalCode, AiStep, PictureRefusal, PlanChange, PlanEdit, SitePlan } from '@vectoriox/iox-ui/generation-core';
 
 import type { StyleRead } from './rank';
 import type { SiteAnalysis } from './site-analysis';
@@ -73,6 +73,44 @@ export interface PlanRevisionView {
     changed?: PlanChange[];
 }
 
+/** Why no picture can be made for this site right now (the Plan step says it instead of offering the switch). */
+export enum PicturesUnavailable {
+    /** No slot is left after the owner's photos and the refusals. */
+    Nothing = 'nothing',
+    /** The key in use has no model that makes pictures (a Claude key does not). */
+    NoModel = 'no-model',
+}
+
+/**
+ * M7: the pictures a generation may have MADE, as the Plan step shows them before the owner says yes, and while they are
+ * made. `estimate` is the cost shown — every picture and its review plus the second tries (generation-core
+ * `estimatePictures`) — and the most the run may spend on them.
+ */
+export interface GenerationPicturesView {
+    /** Pictures that would be made (after the owner's photos and the refusals). */
+    count: number;
+    /** The owner's photos that go first. */
+    own: number;
+    /** Slots no picture is made for, by why. */
+    refused: Partial<Record<`${PictureRefusal}`, number>>;
+    /** Credits — the cost shown and the run's ceiling. */
+    estimate: number;
+    /** One picture with its review, in credits. */
+    each: number;
+    rerolls: number;
+    /** The model that makes them, or null. */
+    model: string | null;
+    /** Why none can be made now — instead of the switch. A refusal code when credits or the plan say no. */
+    unavailable?: `${PicturesUnavailable}` | `${AiRefusalCode}`;
+    /** The owner said yes (Build with pictures): the run's progress. */
+    wanted?: boolean;
+    made?: number;
+    /** Slots whose review said no to every try — stock or the empty box stands in. */
+    failed?: number;
+    /** Credits the pictures have cost so far (the ledger). */
+    spent?: number;
+}
+
 export interface AiGenerationView {
     _id: string;
     organization: string;
@@ -101,6 +139,17 @@ export interface AiGenerationView {
     /** Derived from the ledger — the running credit total. */
     spent: number;
     error?: { code: string; detail: string; providerMessage?: string; issues?: Array<{ code: string; path: string }> };
+    /** M7: the pictures that may be made (on the Plan step) or are being made. Absent: no plan yet. */
+    pictures?: GenerationPicturesView;
+}
+
+/** `POST …/ai/generations/:id/build` (and `/auto`). */
+export interface GenerationBuildRequest {
+    replaceGlobals?: boolean;
+    /** SC6b: the owner's film as pictures. */
+    film?: FrameSequence;
+    /** M7: make pictures for the site first (the cost shown on the Plan step). */
+    pictures?: boolean;
 }
 
 /** `POST …/ai/generations`. */

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

@@ -207,6 +207,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "cinematic"
     },
     "ceiling": "expressive",
+    "world": "documentary",
     "imagery": "Your own photos only, large and uncropped; never stock.",
     "pages": [
       "home",
@@ -312,6 +313,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "cinematic"
     },
     "ceiling": "expressive",
+    "world": "architectural",
     "imagery": "Wide, bright room shots; details of materials.",
     "pages": [
       "home",
@@ -422,6 +424,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "expressive",
+    "world": "architectural",
     "imagery": "Large project photos and drawings.",
     "pages": [
       "home",
@@ -531,6 +534,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "slide"
     },
     "ceiling": "expressive",
+    "world": "hard-light",
     "imagery": "Case-study images of your own work.",
     "pages": [
       "home",
@@ -630,6 +634,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "expressive",
+    "world": "drawing",
     "imagery": "Your pieces, photographed flat and true to colour.",
     "pages": [
       "home",
@@ -735,6 +740,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "slide"
     },
     "ceiling": "expressive",
+    "world": "macro",
     "imagery": "Your pieces and hands at work; natural light.",
     "pages": [
       "home",
@@ -833,6 +839,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "cinematic"
     },
     "ceiling": "expressive",
+    "world": "macro",
     "imagery": "Close-ups on a plain ground.",
     "pages": [
       "home",
@@ -935,6 +942,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "slide"
     },
     "ceiling": "expressive",
+    "world": "low-key",
     "imagery": "Healed work, clean photos.",
     "pages": [
       "home",
@@ -1031,6 +1039,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "standard",
+    "world": "high-key",
     "imagery": "Rooms, textures, hands; no faces needed.",
     "pages": [
       "home",
@@ -1150,6 +1159,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "lively",
+    "world": "high-key",
     "imagery": "Your own before-and-after photos.",
     "pages": [
       "home",
@@ -1252,6 +1262,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "lively",
+    "world": "high-key",
     "imagery": "The room, real classes, daylight.",
     "pages": [
       "home",
@@ -1362,6 +1373,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "slide"
     },
     "ceiling": "lively",
+    "world": "hard-light",
     "imagery": "Real people training; movement.",
     "pages": [
       "home",
@@ -1464,6 +1476,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "none"
     },
     "ceiling": "subtle",
+    "world": "documentary",
     "imagery": "A calm room, daylight; your portrait.",
     "pages": [
       "home",
@@ -1574,6 +1587,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "subtle",
+    "world": "high-key",
     "imagery": "Your team and rooms; no stock doctors.",
     "pages": [
       "home",
@@ -1679,6 +1693,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "subtle",
+    "world": "high-key",
     "imagery": "Your clinic and team.",
     "pages": [
       "home",
@@ -1785,6 +1800,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "standard",
+    "world": "documentary",
     "imagery": "Real animals you treat (with permission).",
     "pages": [
       "home",
@@ -1883,6 +1899,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "expressive",
+    "world": "low-key",
     "imagery": "Your own food and room photos.",
     "pages": [
       "home",
@@ -1992,6 +2009,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "slide"
     },
     "ceiling": "lively",
+    "world": "documentary",
     "imagery": "Your bakes and drinks, close up.",
     "pages": [
       "home",
@@ -2095,6 +2113,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "cinematic"
     },
     "ceiling": "expressive",
+    "world": "nocturne",
     "imagery": "The cellar, the bar, the bottle.",
     "pages": [
       "home",
@@ -2198,6 +2217,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "slide"
     },
     "ceiling": "expressive",
+    "world": "high-key",
     "imagery": "Product photos on plain grounds; real people wearing them.",
     "pages": [
       "home",
@@ -2293,6 +2313,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "lively",
+    "world": "macro",
     "imagery": "Your own arrangements in daylight.",
     "pages": [
       "home",
@@ -2389,6 +2410,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "expressive",
+    "world": "documentary",
     "imagery": "Pieces in real rooms and on plain grounds.",
     "pages": [
       "home",
@@ -2486,6 +2508,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "standard",
+    "world": "architectural",
     "imagery": "Your portrait; diagrams over stock.",
     "pages": [
       "home",
@@ -2587,6 +2610,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "standard",
+    "world": "documentary",
     "imagery": "Your portrait, working with people.",
     "pages": [
       "home",
@@ -2683,6 +2707,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "none"
     },
     "ceiling": "subtle",
+    "world": "architectural",
     "imagery": "Your team; your office.",
     "pages": [
       "home",
@@ -2793,6 +2818,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "slide"
     },
     "ceiling": "lively",
+    "world": "architectural",
     "imagery": "Your own property photos; never stock.",
     "pages": [
       "home",
@@ -2898,6 +2924,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "fade"
     },
     "ceiling": "standard",
+    "world": "documentary",
     "imagery": "Real people you help (with permission).",
     "pages": [
       "home",
@@ -2991,6 +3018,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "cinematic"
     },
     "ceiling": "expressive",
+    "world": "nocturne",
     "imagery": "Real events at your venue.",
     "pages": [
       "home",
@@ -3093,6 +3121,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "cinematic"
     },
     "ceiling": "expressive",
+    "world": "documentary",
     "imagery": "Rooms, views, breakfast; your own photos.",
     "pages": [
       "home",
@@ -3201,6 +3230,7 @@ export const SPEC_BUSINESS_TYPES = [
       "between": "slide"
     },
     "ceiling": "lively",
+    "world": "documentary",
     "imagery": "Real classes (with permission).",
     "pages": [
       "home",

package/src/scene-core/scene.ts

@@ -80,6 +80,24 @@ export enum SceneAttribute {
     Root = 'data-iox-scene',
     Tracks = 'data-iox-tracks',
     PhoneTracks = 'data-iox-tracks-phone',
+    /** A root's stage that is not a Scene's `scene.stage` part: the slider a scroll plays (premium M4). */
+    Stage = 'data-iox-scene-stage',
+}
+
+/**
+ * A SLIDER THE SCROLL PLAYS (premium components M4 — M1.3's held gallery). Its progress rests on each picture and changes
+ * only over the middle share of each step, so every picture arrives and stays a moment while the page holds it: `p` is
+ * the scroll's progress through the runway (0–1), `n` the slides; the answer is Swiper's progress (0–1).
+ */
+export const SLIDER_HOLD_SHARE = 0.2;
+/** Page px of scroll per picture, as a share of the screen's height (the runway the renderers reserve). */
+export const SLIDER_SCROLL_STEP_SCREENS = 0.55;
+export function heldProgress(p: number, n: number): number {
+    if (!(n >= 2) || !Number.isFinite(p)) return 0;
+    const s = clamp01(p) * (n - 1);
+    const i = Math.min(n - 2, Math.floor(s));
+    const f = clamp01((s - i - SLIDER_HOLD_SHARE) / (1 - 2 * SLIDER_HOLD_SHARE));
+    return round((i + smoothstep(f)) / (n - 1));
 }
 
 /** At or under this stage width a layer plays its phone tracks. The `mobile` breakpoint's width. */

package/src/scene-core/scroll-driver.ts

@@ -1,7 +1,7 @@
 import { SceneRole } from '@vectoriox/iox-ui/composite-core';
 import { FramePlayer, normalizeFrameSequence, VideoAttribute } from '@vectoriox/iox-ui/media-core';
 
-import { normalizeTracks, SCENE_PHONE_MAX_WIDTH, SceneAttribute, sceneFrame, SceneFrame, scenePlayed, sceneWordOpacity, sceneWordsLit, SceneTrack } from './scene';
+import { heldProgress, normalizeTracks, SCENE_PHONE_MAX_WIDTH, SceneAttribute, sceneFrame, SceneFrame, scenePlayed, sceneWordOpacity, sceneWordsLit, SceneTrack } from './scene';
 import { LIGHT_UP_PIECE_CAP, SplitText, splitText } from './split-text';
 
 /**
@@ -24,9 +24,32 @@ const SETTLED_PX = 0.25;
 const MAX_FRAME_SECONDS = 0.1;
 /** The first frame after a sleep has no previous one to measure from: it counts as one frame, or a scroll would lose it. */
 const WAKING_FRAME_SECONDS = 1 / 60;
-const STAGE_SELECTOR = `.iox-role-${SceneRole.Stage.replace(/\./g, '-')}`;
+const STAGE_SELECTOR = `.iox-role-${SceneRole.Stage.replace(/\./g, '-')}, [${SceneAttribute.Stage}]`;
 const TRANSFORM_WILL_CHANGE = 'transform, opacity';
 
+/**
+ * Dispatched (bubbling) by something the driver plays that arrived after the driver last looked — a Swiper booted on a
+ * slider's stage. Never a DOM `scroll`: nothing that follows the driver may dispatch one (SC2).
+ */
+export const SCENE_WAKE_EVENT = 'iox-scene-wake';
+
+/**
+ * ONE driver per root (premium M4 — §0 "To verify first"). The live site attaches a driver per runtime instance (the
+ * page's and the globals'); an instance that scanned a container holding the other's Scenes would drive them a second
+ * time, two damped values fighting over one layer. A root is held by the first driver that adds it until that driver
+ * lets it go.
+ */
+const HELD = new WeakMap<HTMLElement, ScrollDriver>();
+
+/** The slider a stage carries when the scroll plays it: a booted Swiper (it sets `el.swiper`), read by shape. */
+interface PlayedSlider { slides?: ArrayLike<unknown>; setProgress?: (progress: number, speed?: number) => void; destroyed?: boolean }
+function sliderOf(stage: HTMLElement | null): PlayedSlider | null {
+    // The stage is the runway's child: the `.swiper` itself (both engine paths), or the canvas's shell around it.
+    const holder = (stage?.classList.contains('swiper') ? stage : stage?.querySelector('.swiper')) as (HTMLElement & { swiper?: PlayedSlider }) | null | undefined;
+    const swiper = holder?.swiper;
+    return swiper && typeof swiper.setProgress === 'function' && !swiper.destroyed ? swiper : null;
+}
+
 /** One frame of the damping: frame-rate independent, so 60 Hz and 120 Hz settle in the same time. */
 export function dampToward(current: number, target: number, seconds: number, rate: number = SCENE_DAMPING): number {
     return current + (target - current) * (1 - Math.exp(-seconds * rate));
@@ -86,6 +109,8 @@ interface Scene {
     /** Page px and the stage's own width, measured when something resizes and never per frame. */
     height: number;
     travel: number;
+    /** Page px from the top of the screen at which the stage holds: 0 for a Scene, mid-screen for a played slider. */
+    stick: number;
     phone: boolean;
     inlineSign: 1 | -1;
     /** No frame written yet: the first one lands exactly where the scroll is, with no glide. */
@@ -105,20 +130,28 @@ export class ScrollDriver {
     private frame = 0;
     private lastTime = 0;
     private readonly wakeUp = (): void => this.wake();
+    private readonly onWakeEvent = (e: Event): void => {
+        const scene = [...this.scenes.values()].find(s => s.root.contains(e.target as Node));
+        if (scene) { scene.fresh = true; this.wake(); }
+    };
 
     constructor(private readonly options: ScrollDriverOptions = {}) {
         this.host = options.host ?? window;
         // In capture: a scroll does not bubble, and the canvas's Lenis scrolls an element, not the window.
         this.host.addEventListener('scroll', this.wakeUp, { capture: true, passive: true });
         this.host.addEventListener('resize', this.wakeUp, { passive: true });
+        this.host.addEventListener(SCENE_WAKE_EVENT, this.onWakeEvent, { capture: true });
         const Observer = (this.host as Window & { ResizeObserver?: typeof ResizeObserver }).ResizeObserver;
         this.resize = Observer ? new Observer(() => this.remeasureAll()) : null;
     }
 
-    /** Drive a Scene's root. Idempotent: adding a root again re-reads it. */
-    add(root: HTMLElement): void {
+    /** Drive a Scene's root. Idempotent: adding a root again re-reads it. False when another driver holds it. */
+    add(root: HTMLElement): boolean {
+        const holder = HELD.get(root);
+        if (holder && holder !== this) return false;
         this.remove(root);
-        const scene: Scene = { root, stage: null, layers: [], progress: 0, target: 0, height: 0, travel: 0, phone: false, inlineSign: 1, fresh: true, mutations: null };
+        HELD.set(root, this);
+        const scene: Scene = { root, stage: null, layers: [], progress: 0, target: 0, height: 0, travel: 0, stick: 0, phone: false, inlineSign: 1, fresh: true, mutations: null };
         this.scenes.set(root, scene);
         this.resize?.observe(root);
         if (this.options.observe) {
@@ -129,11 +162,18 @@ export class ScrollDriver {
             }
         }
         this.readScene(scene);
+        return true;
+    }
+
+    /** True when this driver holds `root`. */
+    holds(root: HTMLElement): boolean {
+        return this.scenes.has(root);
     }
 
     remove(root: HTMLElement): void {
         const scene = this.scenes.get(root);
         if (!scene) return;
+        if (HELD.get(root) === this) HELD.delete(root);
         scene.mutations?.disconnect();
         this.resize?.unobserve(root);
         if (scene.stage) scene.stage.style.removeProperty('translate');
@@ -198,6 +238,7 @@ export class ScrollDriver {
         this.frame = 0;
         this.host.removeEventListener('scroll', this.wakeUp, { capture: true });
         this.host.removeEventListener('resize', this.wakeUp);
+        this.host.removeEventListener(SCENE_WAKE_EVENT, this.onWakeEvent, { capture: true });
         for (const root of [...this.scenes.keys()]) this.remove(root);
         this.resize?.disconnect();
     }
@@ -250,6 +291,9 @@ export class ScrollDriver {
     private measure(scene: Scene): void {
         scene.height = scene.root.offsetHeight;
         scene.travel = Math.max(0, scene.height - (scene.stage?.offsetHeight ?? scene.height));
+        // Where the stage holds: its sticky top (a played slider holds mid-screen; a Scene's stage at 0). Read when
+        // something resizes, never per frame.
+        scene.stick = scene.stage ? (parseFloat(this.host.getComputedStyle(scene.stage).top) || 0) : 0;
         scene.phone = (scene.stage?.offsetWidth ?? Infinity) <= SCENE_PHONE_MAX_WIDTH;
         scene.inlineSign = scene.stage && this.host.getComputedStyle(scene.stage).direction === 'rtl' ? -1 : 1;
         for (const layer of scene.layers) layer.stale = true;
@@ -281,11 +325,14 @@ export class ScrollDriver {
         const rect = scene.root.getBoundingClientRect();
         const origin = this.options.originOf?.(scene.root)?.getBoundingClientRect().top ?? 0;
         const zoom = scene.height ? rect.height / scene.height : 1;
-        const { local, progress } = sceneScrollState(rect.top, origin, zoom, scene.travel);
+        const { local, progress } = sceneScrollState(rect.top, origin + scene.stick * zoom, zoom, scene.travel);
         return { scene, local, target: progress };
     }
 
     private write(scene: Scene): void {
+        // A slider the scroll plays (M4): the damped moment, held on each picture.
+        const slider = sliderOf(scene.stage);
+        if (slider) slider.setProgress!(heldProgress(scene.progress, slider.slides?.length ?? 0), 0);
         for (const layer of scene.layers) {
             const tracks = scene.phone && layer.phoneTracks.length ? layer.phoneTracks : layer.tracks;
             this.writeWords(layer, sceneWordsLit(tracks, scene.progress));
@@ -359,3 +406,33 @@ export function attachScenes(container: HTMLElement, options: ScrollDriverOption
     roots.forEach(root => driver.add(root));
     return driver;
 }
+
+/**
+ * The Scene roots that belong to `elements` (each, and what it holds) — what one runtime instance owns: the page's nodes,
+ * or the globals'. Never a whole container that also holds another instance's Scenes (premium M4: the globals' instance
+ * scanned the app root and drove the page's Scenes a second time).
+ */
+export function sceneRootsIn(elements: Iterable<Element>): HTMLElement[] {
+    const out = new Set<HTMLElement>();
+    for (const el of elements) {
+        if ((el as HTMLElement).hasAttribute?.(SceneAttribute.Root)) out.add(el as HTMLElement);
+        // A wrapper the node renders around itself (a played slider's runway around its `.swiper`) is the node's own.
+        const parent = el.parentElement;
+        if (parent?.hasAttribute(SceneAttribute.Root) && parent.children.length === 1) out.add(parent);
+        el.querySelectorAll?.<HTMLElement>(`[${SceneAttribute.Root}]`).forEach(root => out.add(root));
+    }
+    return [...out];
+}
+
+/** The live site's door for a runtime that owns some nodes: their Scenes on one driver (null when none, or under reduced
+ *  motion — the page's own CSS then lets each Scene flow). A root another driver holds stays with it. */
+export function attachSceneRoots(roots: ReadonlyArray<HTMLElement>, options: ScrollDriverOptions = {}): ScrollDriver | null {
+    if (!roots.length) return null;
+    const host = options.host ?? window;
+    if (host.matchMedia?.('(prefers-reduced-motion: reduce)').matches) return null;
+    const driver = new ScrollDriver(options);
+    const held = roots.filter(root => driver.add(root));
+    if (held.length) return driver;
+    driver.destroy();
+    return null;
+}