@vectoriox/iox-ui 5.74.7 → 5.75.2

package/media-core/index.d.ts

@@ -61,6 +61,12 @@ declare function frameSetFor(sequence: FrameSequence, phone: boolean): {
 declare function framePosition(played: number, count: number): number;
 /** On a Video whose pictures are drawing: the poster has done its job and steps aside. */
 declare const FRAMES_SHOWING_ATTRIBUTE = "data-iox-frames-showing";
+/**
+ * Below this many pictures a second the film stops following the scroll exactly and lands on its own. A landing scroll
+ * slows exponentially, so the last picture or two would take most of a second as one slow dissolve between two places:
+ * the subject showing twice, and then settling. Landing at least this fast keeps the end of the move a move.
+ */
+declare const FILM_LANDING_SPEED = 10;
 /** How finely two neighbours mix. Finer than the eye reads, and a scroll that moves less than a step draws nothing. */
 declare const FRAME_BLEND_STEPS = 32;
 /** What to draw: picture `from`, with `to` over it at `mix` when the moment falls between two that have arrived. */
@@ -75,6 +81,28 @@ interface FrameBlend {
  * A neighbour still loading never blends: the nearest arrived picture stands in, and null means none has.
  */
 declare function frameBlendAt(loaded: ReadonlyArray<unknown>, position: number): FrameBlend | null;
+/** Where the film stands and how the scroll under it moves: what one landing step reads and writes. */
+interface FilmMotion {
+    /** The moment drawn, in pictures (2.5 = half way from the third to the fourth). */
+    position: number;
+    /** The moment the scroll asks for. */
+    wanted: number;
+    /** The scroll's speed, in pictures a second, smoothed. */
+    speed: number;
+    /** The way the scroll last moved: 1 onward, -1 back. */
+    direction: 1 | -1;
+}
+/** Where a film stands before its first step: on the moment asked for, still. */
+declare function filmAt(wanted: number): FilmMotion;
+/**
+ * One step of the film. Moving fast, it stands exactly where the scroll asks. Landing (slower than FILM_LANDING_SPEED
+ * pictures a second) it runs on at that speed to the whole picture at or past where the scroll will stop, and stands
+ * there: it never crawls through a dissolve, never stops between two pictures, and never steps back unless the scroll
+ * does. `aim` is where the scroll is heading, when the driver knows it (its undamped target); without it, it is guessed.
+ */
+declare function stepFilm(motion: FilmMotion, wanted: number, seconds: number, last: number, aim?: number): FilmMotion;
+/** Whether a film has landed: still, on the whole picture at or just past where the scroll stands. */
+declare function filmLanded(motion: FilmMotion): boolean;
 /** The picture at `played` % of a set of `count`. */
 declare function frameIndexAt(played: number, count: number): number;
 /**
@@ -130,8 +158,10 @@ declare class FramePlayer {
     private readonly el;
     private readonly sequence;
     private played;
-    private restTimer;
-    private restFrame;
+    private aim;
+    private motion;
+    private steppedAt;
+    private landingFrame;
     private readonly set;
     private readonly info;
     private readonly images;
@@ -140,7 +170,6 @@ declare class FramePlayer {
     private observer;
     private canvas;
     private context;
-    private position;
     private drawn;
     private nextToLoad;
     private loading;
@@ -148,11 +177,14 @@ declare class FramePlayer {
     private destroyed;
     private readonly pending;
     constructor(el: HTMLElement, sequence: FrameSequence, options?: FramePlayerOptions);
-    /** Stand at `played` %. */
-    seek(played: number): void;
-    /** A stopped scroll must not stand on two pictures at once: a moving subject would show twice. It settles on the nearer. */
-    private rest;
-    private stopResting;
+    /**
+     * Stand at `played` %, on the way to `aim` % when the caller knows where the scroll is going. `now` is the caller's
+     * frame time: the player keeps time by frames, so a frame asked twice moves once however long the page took.
+     */
+    seek(played: number, aim?: number, now?: number): void;
+    /** One step toward the moment asked for, drawn now; a landing goes on by itself until it stands on a whole picture. */
+    private step;
+    private stopLanding;
     /** Whether a re-render took the canvas away with the markup it sat in. */
     get detached(): boolean;
     destroy(): void;
@@ -445,5 +477,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, 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, isThirdPartyPoster, nearestLoadedFrame, normalizeFrameSequence, parseVideoUrl, phoneFrameCount, phoneFrameSrcset, planVideo, readConsentRecord, sampledFrameIndexes, serializeVideoAttributes, sortFrameFiles, 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 };
+export { CONSENT_GRANT_EVENT, CONSENT_PREFERENCES_EVENT, FILM_LANDING_SPEED, FRAMES_PHONE_MAX_WIDTH, FRAMES_SHOWING_ATTRIBUTE, 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, filmAt, filmLanded, fittedFrameSize, frameBlendAt, frameFileName, frameIndexAt, frameLoadOrder, framePosition, frameSetFor, frameSummary, frameUrl, isThirdPartyPoster, nearestLoadedFrame, normalizeFrameSequence, parseVideoUrl, phoneFrameCount, phoneFrameSrcset, planVideo, readConsentRecord, sampledFrameIndexes, serializeVideoAttributes, sortFrameFiles, stepFilm, videoConsentCategory, videoEmbedUrl, videoFrameCount, videoInnerHtml, videoPlayLabel, videoPosterFileName, videoProp, videoRefOf, videoRootAttributes, videoRuntimeOf, videoSourceOf, videoThumbnailRequest, videoWords };
+export type { ConsentGrantDetail, ConsentTransport, FilmMotion, 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.74.7",
+  "version": "5.75.2",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/media-core/frames.ts

@@ -111,9 +111,22 @@ export function framePosition(played: number, count: number): number {
 /** On a Video whose pictures are drawing: the poster has done its job and steps aside. */
 export const FRAMES_SHOWING_ATTRIBUTE = 'data-iox-frames-showing';
 
-/** How long a stopped scroll waits before settling on a whole picture, and how fast it gets there per frame. */
-const REST_AFTER_MS = 140;
-const REST_RATE = 0.25;
+/**
+ * Below this many pictures a second the film stops following the scroll exactly and lands on its own. A landing scroll
+ * slows exponentially, so the last picture or two would take most of a second as one slow dissolve between two places:
+ * the subject showing twice, and then settling. Landing at least this fast keeps the end of the move a move.
+ */
+export const FILM_LANDING_SPEED = 10;
+/** With no word from the driver on where the scroll is going, how fast a landing scroll is assumed to slow (per second). */
+const FILM_LANDING_DECAY = 5;
+/** How quickly the film catches up with a scroll that turned back while it was landing ahead of it (per second). */
+const FILM_CATCH_RATE = 25;
+/** How quickly the film's reading of the scroll's speed follows it (per second). */
+const FILM_SPEED_RATE = 30;
+/** A step this short is the same frame asked twice: it moves nothing and reads no speed. */
+const FILM_SAME_FRAME_SECONDS = 0.002;
+const FILM_MAX_STEP_SECONDS = 0.1;
+const FILM_EPSILON = 1e-6;
 
 /** How finely two neighbours mix. Finer than the eye reads, and a scroll that moves less than a step draws nothing. */
 export const FRAME_BLEND_STEPS = 32;
@@ -139,6 +152,58 @@ export function frameBlendAt(loaded: ReadonlyArray<unknown>, position: number):
     return nearest < 0 ? null : { from: nearest, to: nearest, mix: 0 };
 }
 
+/** Where the film stands and how the scroll under it moves: what one landing step reads and writes. */
+export interface FilmMotion {
+    /** The moment drawn, in pictures (2.5 = half way from the third to the fourth). */
+    position: number;
+    /** The moment the scroll asks for. */
+    wanted: number;
+    /** The scroll's speed, in pictures a second, smoothed. */
+    speed: number;
+    /** The way the scroll last moved: 1 onward, -1 back. */
+    direction: 1 | -1;
+}
+
+/** Where a film stands before its first step: on the moment asked for, still. */
+export function filmAt(wanted: number): FilmMotion {
+    return { position: wanted, wanted, speed: 0, direction: 1 };
+}
+
+/**
+ * One step of the film. Moving fast, it stands exactly where the scroll asks. Landing (slower than FILM_LANDING_SPEED
+ * pictures a second) it runs on at that speed to the whole picture at or past where the scroll will stop, and stands
+ * there: it never crawls through a dissolve, never stops between two pictures, and never steps back unless the scroll
+ * does. `aim` is where the scroll is heading, when the driver knows it (its undamped target); without it, it is guessed.
+ */
+export function stepFilm(motion: FilmMotion, wanted: number, seconds: number, last: number, aim?: number): FilmMotion {
+    const sameFrame = seconds < FILM_SAME_FRAME_SECONDS;
+    const step = Math.min(FILM_MAX_STEP_SECONDS, seconds);
+    const moved = wanted - motion.wanted;
+    const speed = sameFrame ? motion.speed : motion.speed + (moved / step - motion.speed) * (1 - Math.exp(-FILM_SPEED_RATE * step));
+    const heading = aim === undefined ? moved : aim - wanted;
+    const direction: 1 | -1 = Math.abs(heading) > FILM_EPSILON ? (heading > 0 ? 1 : -1) : Math.abs(moved) > FILM_EPSILON ? (moved > 0 ? 1 : -1) : motion.direction;
+    // Moving: with the scroll, but never back over a picture a landing already reached unless the scroll turned.
+    if (Math.abs(speed) >= FILM_LANDING_SPEED) {
+        const position = direction > 0 ? Math.max(wanted, Math.min(motion.position, Math.ceil(wanted))) : Math.min(wanted, Math.max(motion.position, Math.floor(wanted)));
+        return { position, wanted, speed, direction };
+    }
+    if (sameFrame) return { ...motion, wanted, direction };
+    const clamp = (value: number): number => Math.min(last, Math.max(0, value));
+    const stop = aim ?? wanted + speed / FILM_LANDING_DECAY;
+    const reached = direction > 0 ? Math.ceil(motion.position - FILM_EPSILON) : Math.floor(motion.position + FILM_EPSILON);
+    const goal = clamp(direction > 0 ? Math.max(Math.ceil(stop - FILM_EPSILON), reached) : Math.min(Math.floor(stop + FILM_EPSILON), reached));
+    const behind = (wanted - motion.position) * direction;
+    const reach = Math.max(FILM_LANDING_SPEED * step, behind > 0 ? behind * (1 - Math.exp(-FILM_CATCH_RATE * step)) : 0);
+    const position = direction > 0 ? Math.min(goal, motion.position + reach) : Math.max(goal, motion.position - reach);
+    return { position, wanted, speed, direction };
+}
+
+/** Whether a film has landed: still, on the whole picture at or just past where the scroll stands. */
+export function filmLanded(motion: FilmMotion): boolean {
+    const past = (motion.position - motion.wanted) * motion.direction;
+    return Math.abs(motion.speed) < 0.01 && Number.isInteger(motion.position) && past > -FILM_EPSILON && past < 1;
+}
+
 /** The picture at `played` % of a set of `count`. */
 export function frameIndexAt(played: number, count: number): number {
     if (count <= 1) return 0;
@@ -255,8 +320,10 @@ export interface FramePlayerOptions {
  */
 export class FramePlayer {
     private played: number | null = null;
-    private restTimer: number | null = null;
-    private restFrame: number | null = null;
+    private aim: number | undefined;
+    private motion: FilmMotion | null = null;
+    private steppedAt = 0;
+    private landingFrame: number | null = null;
     private readonly set: FrameSet;
     private readonly info: FrameSetInfo;
     private readonly images: Array<HTMLImageElement | null>;
@@ -265,7 +332,6 @@ export class FramePlayer {
     private observer: IntersectionObserver | null = null;
     private canvas: HTMLCanvasElement | null = null;
     private context: CanvasRenderingContext2D | null = null;
-    private position = 0;
     private drawn: FrameBlend | null = null;
     private nextToLoad = 0;
     private loading = 0;
@@ -292,36 +358,34 @@ export class FramePlayer {
         this.observer.observe(options.near ?? el);
     }
 
-    /** Stand at `played` %. */
-    seek(played: number): void {
-        if (played === this.played) return;
+    /**
+     * Stand at `played` %, on the way to `aim` % when the caller knows where the scroll is going. `now` is the caller's
+     * frame time: the player keeps time by frames, so a frame asked twice moves once however long the page took.
+     */
+    seek(played: number, aim?: number, now?: number): void {
+        if (played === this.played && aim === this.aim) return;
         this.played = played;
-        this.stopResting();
-        this.position = framePosition(played, this.info.count);
-        this.draw();
-        this.restTimer = this.host.setTimeout?.(() => this.rest(), REST_AFTER_MS) ?? null;
+        this.aim = aim;
+        this.step(now ?? this.host.performance?.now() ?? 0);
     }
 
-    /** A stopped scroll must not stand on two pictures at once: a moving subject would show twice. It settles on the nearer. */
-    private rest(): void {
-        this.restTimer = null;
-        const target = Math.round(this.position);
-        const step = (): void => {
-            this.restFrame = null;
-            if (this.destroyed) return;
-            const left = target - this.position;
-            this.position = Math.abs(left) < 1 / FRAME_BLEND_STEPS ? target : this.position + left * REST_RATE;
-            this.draw();
-            if (this.position !== target) this.restFrame = this.host.requestAnimationFrame(step);
-        };
-        step();
+    /** One step toward the moment asked for, drawn now; a landing goes on by itself until it stands on a whole picture. */
+    private step(now: number): void {
+        if (this.destroyed || this.played === null) return;
+        const wanted = framePosition(this.played, this.info.count);
+        const aim = this.aim === undefined ? undefined : framePosition(this.aim, this.info.count);
+        this.motion = this.motion ? stepFilm(this.motion, wanted, (now - this.steppedAt) / 1000, this.info.count - 1, aim) : filmAt(wanted);
+        this.steppedAt = now;
+        this.draw();
+        if (!filmLanded(this.motion) && this.landingFrame === null) this.landingFrame = this.host.requestAnimationFrame(time => {
+            this.landingFrame = null;
+            this.step(time);
+        });
     }
 
-    private stopResting(): void {
-        if (this.restTimer !== null) this.host.clearTimeout?.(this.restTimer);
-        if (this.restFrame !== null) this.host.cancelAnimationFrame?.(this.restFrame);
-        this.restTimer = null;
-        this.restFrame = null;
+    private stopLanding(): void {
+        if (this.landingFrame !== null) this.host.cancelAnimationFrame?.(this.landingFrame);
+        this.landingFrame = null;
     }
 
     /** Whether a re-render took the canvas away with the markup it sat in. */
@@ -331,7 +395,7 @@ export class FramePlayer {
 
     destroy(): void {
         this.destroyed = true;
-        this.stopResting();
+        this.stopLanding();
         this.el.removeAttribute(FRAMES_SHOWING_ATTRIBUTE);
         this.observer?.disconnect();
         this.observer = null;
@@ -392,7 +456,8 @@ export class FramePlayer {
     }
 
     private draw(): void {
-        const blend = frameBlendAt(this.images, this.position);
+        if (!this.motion) return;
+        const blend = frameBlendAt(this.images, this.motion.position);
         const last = this.drawn;
         if (!blend || (last && last.from === blend.from && last.to === blend.to && last.mix === blend.mix)) return;
         const image = this.images[blend.from]!;

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

@@ -267,7 +267,7 @@ export class ScrollDriver {
             scene.progress = settled ? target : next;
             scene.target = target;
             scene.fresh = false;
-            this.write(scene);
+            this.write(scene, now);
             this.options.onFrame?.(scene.root, { target, progress: scene.progress });
             moving = moving || !settled;
         }
@@ -283,11 +283,11 @@ export class ScrollDriver {
         return { scene, local, target: progress };
     }
 
-    private write(scene: Scene): void {
+    private write(scene: Scene, now: number): void {
         for (const layer of scene.layers) {
             const tracks = scene.phone && layer.phoneTracks.length ? layer.phoneTracks : layer.tracks;
             this.writeWords(layer, sceneWordsLit(tracks, scene.progress));
-            this.writePlayed(layer, scene, scenePlayed(tracks, scene.progress));
+            this.writePlayed(layer, scene, scenePlayed(tracks, scene.progress), scenePlayed(tracks, scene.target), now);
             const frame = sceneFrame(tracks, scene.progress, { inlineSign: scene.inlineSign });
             for (const key of Object.keys(frame) as (keyof SceneFrame)[]) {
                 if (layer.stale || frame[key] !== layer.last[key]) layer.el.style[key] = frame[key] ?? '';
@@ -305,7 +305,7 @@ export class ScrollDriver {
      * The picture this moment asks for. The attribute sits on the Video's own root, which is the layer on the string path
      * and inside it on the component path. A layer with no pictures, or no Play track, holds its poster.
      */
-    private writePlayed(layer: Layer, scene: Scene, played: number | null): void {
+    private writePlayed(layer: Layer, scene: Scene, played: number | null, aim: number | null, now: number): void {
         const target = played === null ? null : (layer.el.hasAttribute(VideoAttribute.Frames) ? layer.el : layer.el.querySelector<HTMLElement>(`[${VideoAttribute.Frames}]`));
         const raw = target?.getAttribute(VideoAttribute.Frames) ?? '';
         const sequence = raw ? normalizeFrameSequence(raw) : null;
@@ -319,7 +319,8 @@ export class ScrollDriver {
             layer.player = new FramePlayer(target, sequence, { phone: scene.phone, near: scene.root, host: this.host });
             layer.playerKey = key;
         }
-        layer.player.seek(played!);
+        // Where the damping is heading, so a landing film stops on the picture the scroll stops on, not one past it.
+        layer.player.seek(played!, aim ?? undefined, now);
     }
 
     /** One opacity per word, and a write only for the few the scroll actually changed. */