@vectoriox/iox-ui 5.75.3 → 5.76.1

package/media-core/index.d.ts

@@ -61,12 +61,6 @@ 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. */
@@ -81,28 +75,6 @@ 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 nearest where the scroll will stop, and stands there:
- * it never crawls through a dissolve, never stops between two pictures, and never steps back over a picture it reached
- * unless the scroll turns. `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 a whole picture beside 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;
 /**
@@ -113,6 +85,16 @@ declare function frameIndexAt(played: number, count: number): number;
 declare function frameLoadOrder(count: number): number[];
 /** The loaded picture nearest `index`, or -1 when none has arrived. Ties go backward: the picture already passed. */
 declare function nearestLoadedFrame(loaded: ReadonlyArray<unknown>, index: number): number;
+/**
+ * How much unpacked picture one player holds at once. A browser keeps few of 300 unpacked pictures (a wide set is 1.7 GB
+ * unpacked) and unpacked again on the page's own thread, at the moment of drawing, 22 ms a 1600×900 picture: longer than a
+ * whole frame, so the film and the page beside it skipped a beat for every new picture (Doron's recording, 2026-11-04).
+ */
+declare const FRAMES_UNPACKED_BYTES: number;
+/** How many pictures of `width`×`height` a player holds unpacked. */
+declare function unpackedFrameCount(width: number, height: number): number;
+/** The `size` pictures to hold unpacked around `position`, nearest first, each side in turn starting ahead. */
+declare function framesToHold(position: number, count: number, size: number): number[];
 interface FrameSizes {
     width: number;
     height: number;
@@ -153,20 +135,26 @@ interface FramePlayerOptions {
  * The player: draws the picture nearest what the scroll asked for on a canvas laid over the poster, and nothing until a
  * first picture has arrived, so the poster is what a visitor sees until then, and for good if the pictures never come.
  * Browser only. It writes and never reads, so the driver can call it in its write phase.
+ *
+ * Each picture is downloaded as a file and unpacked off the page's thread (`createImageBitmap` of the file), a window of
+ * them around where the film stands, so drawing one never waits for it. A browser that cannot (no `fetch` or
+ * `createImageBitmap`, or storage that refuses the download) plays from `<img>` pictures, as before: it works, and pays the
+ * unpacking on the page's thread.
  */
 declare class FramePlayer {
     private readonly el;
     private readonly sequence;
     private played;
-    private aim;
-    private motion;
-    private steppedAt;
-    private landingFrame;
     private readonly set;
     private readonly info;
-    private readonly images;
+    /** What a draw may use: an unpacked picture, or an `<img>` on a browser that plays from them. */
+    private readonly ready;
+    /** The downloaded files, unpacked when the film comes near them. */
+    private readonly files;
     private readonly order;
     private readonly host;
+    private readonly holdCount;
+    private fromFiles;
     private observer;
     private canvas;
     private context;
@@ -175,23 +163,29 @@ declare class FramePlayer {
     private loading;
     private started;
     private destroyed;
+    private held;
+    private readonly unpacked;
+    private readonly unpacking;
     private readonly pending;
+    private readonly downloads;
     constructor(el: HTMLElement, sequence: FrameSequence, options?: FramePlayerOptions);
     /**
-     * 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.
+     * Stand at `played` %, exactly. The film keeps no motion of its own: the scroll's glide, and the slowing at its end,
+     * are the caller's, so the film slows with the page and stops when it stops. Between two pictures it blends them.
      */
-    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;
+    seek(played: number): void;
     /** Whether a re-render took the canvas away with the markup it sat in. */
     get detached(): boolean;
     destroy(): void;
     private allowed;
     private start;
     private pump;
-    private load;
+    private loaded;
+    private download;
+    private loadImage;
+    /** Unpack the pictures around where the film stands, nearest first, and let go of the ones it has left. */
+    private hold;
+    private unpack;
     private draw;
     private ensureCanvas;
 }
@@ -477,5 +471,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, 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 };
+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, phoneFrameCount, 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.75.3",
+  "version": "5.76.1",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/media-core/frames.ts

@@ -111,23 +111,6 @@ 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';
 
-/**
- * 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;
 
@@ -152,59 +135,6 @@ 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 nearest where the scroll will stop, and stands there:
- * it never crawls through a dissolve, never stops between two pictures, and never steps back over a picture it reached
- * unless the scroll turns. `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;
-    // The picture nearest the stop, unless reaching it would show a step back: then the next whole one on the way.
-    const nearest = Math.round(stop);
-    const back = (motion.position - nearest) * direction > 1 / FRAME_BLEND_STEPS;
-    const goal = clamp(back ? (direction > 0 ? Math.ceil(motion.position) : Math.floor(motion.position)) : nearest);
-    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 a whole picture beside where the scroll stands. */
-export function filmLanded(motion: FilmMotion): boolean {
-    return Math.abs(motion.speed) < 0.01 && Number.isInteger(motion.position) && Math.abs(motion.position - motion.wanted) < 1;
-}
-
 /** The picture at `played` % of a set of `count`. */
 export function frameIndexAt(played: number, count: number): number {
     if (count <= 1) return 0;
@@ -242,6 +172,31 @@ export function nearestLoadedFrame(loaded: ReadonlyArray<unknown>, index: number
     return -1;
 }
 
+/**
+ * How much unpacked picture one player holds at once. A browser keeps few of 300 unpacked pictures (a wide set is 1.7 GB
+ * unpacked) and unpacked again on the page's own thread, at the moment of drawing, 22 ms a 1600×900 picture: longer than a
+ * whole frame, so the film and the page beside it skipped a beat for every new picture (Doron's recording, 2026-11-04).
+ */
+export const FRAMES_UNPACKED_BYTES = 96 * 1024 * 1024;
+const MIN_UNPACKED = 6;
+const MAX_UNPACKED = 24;
+
+/** How many pictures of `width`×`height` a player holds unpacked. */
+export function unpackedFrameCount(width: number, height: number): number {
+    return Math.min(MAX_UNPACKED, Math.max(MIN_UNPACKED, Math.floor(FRAMES_UNPACKED_BYTES / (width * height * 4))));
+}
+
+/** The `size` pictures to hold unpacked around `position`, nearest first, each side in turn starting ahead. */
+export function framesToHold(position: number, count: number, size: number): number[] {
+    const from = Math.min(count - 1, Math.max(0, Math.floor(position)));
+    const held: number[] = [from];
+    for (let distance = 1; held.length < Math.min(size, count); distance++) {
+        if (from + distance < count) held.push(from + distance);
+        if (from - distance >= 0 && held.length < size) held.push(from - distance);
+    }
+    return held;
+}
+
 export interface FrameSizes {
     width: number;
     height: number;
@@ -296,6 +251,7 @@ export enum FramesClass {
 }
 
 const LOAD_CONCURRENCY = 6;
+const UNPACK_CONCURRENCY = 4;
 const NEAR_MARGIN = '100% 0px';
 /** Under these the visitor keeps the poster: nobody on a metered 2G connection asked to download a film. */
 const SLOW_CONNECTIONS: ReadonlySet<string> = new Set(['slow-2g', '2g']);
@@ -318,18 +274,24 @@ export interface FramePlayerOptions {
  * The player: draws the picture nearest what the scroll asked for on a canvas laid over the poster, and nothing until a
  * first picture has arrived, so the poster is what a visitor sees until then, and for good if the pictures never come.
  * Browser only. It writes and never reads, so the driver can call it in its write phase.
+ *
+ * Each picture is downloaded as a file and unpacked off the page's thread (`createImageBitmap` of the file), a window of
+ * them around where the film stands, so drawing one never waits for it. A browser that cannot (no `fetch` or
+ * `createImageBitmap`, or storage that refuses the download) plays from `<img>` pictures, as before: it works, and pays the
+ * unpacking on the page's thread.
  */
 export class FramePlayer {
     private played: 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>;
+    /** What a draw may use: an unpacked picture, or an `<img>` on a browser that plays from them. */
+    private readonly ready: Array<CanvasImageSource | null>;
+    /** The downloaded files, unpacked when the film comes near them. */
+    private readonly files: Array<Blob | null>;
     private readonly order: number[];
     private readonly host: Window;
+    private readonly holdCount: number;
+    private fromFiles: boolean;
     private observer: IntersectionObserver | null = null;
     private canvas: HTMLCanvasElement | null = null;
     private context: CanvasRenderingContext2D | null = null;
@@ -338,15 +300,24 @@ export class FramePlayer {
     private loading = 0;
     private started = false;
     private destroyed = false;
+    private held = new Set<number>();
+    private readonly unpacked = new Map<number, ImageBitmap>();
+    private readonly unpacking = new Set<number>();
     private readonly pending = new Set<HTMLImageElement>();
+    private readonly downloads: AbortController | null;
 
     constructor(private readonly el: HTMLElement, private readonly sequence: FrameSequence, options: FramePlayerOptions = {}) {
         this.host = options.host ?? window;
         const { set, info } = frameSetFor(sequence, !!options.phone);
         this.set = set;
         this.info = info;
-        this.images = new Array(info.count).fill(null);
+        this.ready = new Array(info.count).fill(null);
+        this.files = new Array(info.count).fill(null);
         this.order = frameLoadOrder(info.count);
+        this.holdCount = unpackedFrameCount(info.width, info.height);
+        this.fromFiles = typeof this.host.fetch === 'function' && typeof this.host.createImageBitmap === 'function';
+        const Controller = (this.host as Window & { AbortController?: typeof AbortController }).AbortController;
+        this.downloads = this.fromFiles && Controller ? new Controller() : null;
         if (!this.allowed()) return;
         const Observer = (this.host as Window & { IntersectionObserver?: typeof IntersectionObserver }).IntersectionObserver;
         if (!Observer) {
@@ -360,33 +331,14 @@ export class FramePlayer {
     }
 
     /**
-     * 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.
+     * Stand at `played` %, exactly. The film keeps no motion of its own: the scroll's glide, and the slowing at its end,
+     * are the caller's, so the film slows with the page and stops when it stops. Between two pictures it blends them.
      */
-    seek(played: number, aim?: number, now?: number): void {
-        if (played === this.played && aim === this.aim) return;
+    seek(played: number): void {
+        if (played === this.played) return;
         this.played = played;
-        this.aim = aim;
-        this.step(now ?? this.host.performance?.now() ?? 0);
-    }
-
-    /** 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.hold();
         this.draw();
-        if (!filmLanded(this.motion) && this.landingFrame === null) this.landingFrame = this.host.requestAnimationFrame(time => {
-            this.landingFrame = null;
-            this.step(time);
-        });
-    }
-
-    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. */
@@ -396,16 +348,18 @@ export class FramePlayer {
 
     destroy(): void {
         this.destroyed = true;
-        this.stopLanding();
         this.el.removeAttribute(FRAMES_SHOWING_ATTRIBUTE);
         this.observer?.disconnect();
         this.observer = null;
+        this.downloads?.abort();
         for (const image of this.pending) {
             image.onload = null;
             image.onerror = null;
             image.src = '';
         }
         this.pending.clear();
+        for (const bitmap of this.unpacked.values()) bitmap.close();
+        this.unpacked.clear();
         this.canvas?.remove();
         this.canvas = null;
         this.context = null;
@@ -426,64 +380,134 @@ export class FramePlayer {
 
     private pump(): void {
         while (!this.destroyed && this.loading < LOAD_CONCURRENCY && this.nextToLoad < this.order.length) {
-            this.load(this.order[this.nextToLoad++]);
+            const index = this.order[this.nextToLoad++];
+            if (this.fromFiles) this.download(index);
+            else this.loadImage(index);
         }
     }
 
-    private load(index: number): void {
+    private loaded(arrived: boolean): void {
+        this.loading--;
+        if (this.destroyed) return;
+        if (arrived) this.draw();
+        this.pump();
+    }
+
+    private download(index: number): void {
+        this.loading++;
+        const url = frameUrl(this.sequence, this.set, index);
+        this.host.fetch(url, this.downloads ? { signal: this.downloads.signal } : undefined)
+            .then(response => (response.ok ? response.blob() : null))
+            .then(file => {
+                if (this.destroyed) return;
+                // A picture that failed is a gap: its neighbours stand in.
+                this.files[index] = file;
+                this.loading--;
+                this.hold();
+                this.pump();
+            }, () => {
+                if (this.destroyed) return;
+                // Storage that refuses a download from the page's address still serves an <img>: play from those.
+                this.fromFiles = false;
+                this.loading--;
+                this.loadImage(index);
+            });
+    }
+
+    private loadImage(index: number): void {
         const image = this.host.document.createElement('img');
         image.decoding = 'async';
         this.loading++;
         this.pending.add(image);
         const done = (arrived: boolean): void => {
             this.pending.delete(image);
-            this.loading--;
-            if (this.destroyed) return;
-            if (arrived) {
-                this.images[index] = image;
-                this.draw();
-            }
-            this.pump();
+            if (!this.destroyed && arrived) this.ready[index] = image;
+            this.loaded(arrived);
         };
-        // Decoded before it counts, or the first draw of each picture decodes on the driver's frame and the scroll stutters.
+        // Decoded before it counts, or its first draw decodes on the driver's frame.
         image.onload = () => {
             const decoded = image.decode?.();
             if (decoded) void decoded.then(() => done(true), () => done(true));
             else done(true);
         };
-        // A picture that failed is a gap: its neighbours stand in.
         image.onerror = () => done(false);
         image.src = frameUrl(this.sequence, this.set, index);
     }
 
+    /** Unpack the pictures around where the film stands, nearest first, and let go of the ones it has left. */
+    private hold(): void {
+        if (this.destroyed) return;
+        const wanted = framesToHold(framePosition(this.played ?? 0, this.info.count), this.info.count, this.holdCount);
+        this.held = new Set(wanted);
+        for (const [index, bitmap] of this.unpacked) {
+            if (this.held.has(index)) continue;
+            bitmap.close();
+            this.unpacked.delete(index);
+            this.ready[index] = null;
+        }
+        for (const index of wanted) {
+            if (this.unpacking.size >= UNPACK_CONCURRENCY) return;
+            if (this.files[index] && !this.ready[index] && !this.unpacking.has(index)) this.unpack(index);
+        }
+    }
+
+    private unpack(index: number): void {
+        this.unpacking.add(index);
+        this.host.createImageBitmap(this.files[index]!).then(bitmap => {
+            this.unpacking.delete(index);
+            if (this.destroyed || !this.held.has(index)) {
+                bitmap.close();
+            } else {
+                this.unpacked.set(index, bitmap);
+                this.ready[index] = bitmap;
+                this.draw();
+            }
+            this.hold();
+        }, () => {
+            // A file that will not unpack is a gap, like one that never came.
+            this.unpacking.delete(index);
+            this.files[index] = null;
+            this.hold();
+        });
+    }
+
     private draw(): void {
-        if (!this.motion) return;
-        const blend = frameBlendAt(this.images, this.motion.position);
+        if (this.destroyed || this.played === null) return;
+        const blend = frameBlendAt(this.ready, framePosition(this.played, this.info.count));
         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]!;
-        if (!this.ensureCanvas(image)) return;
+        const picture = this.ready[blend.from]!;
+        if (!this.ensureCanvas(picture)) return;
         const context = this.context!;
         const { width, height } = this.canvas!;
         context.clearRect(0, 0, width, height);
-        context.drawImage(image, 0, 0, width, height);
         if (blend.mix > 0) {
+            // A true mix, (1 − mix)·from + mix·to, even where a see-through film has nothing on one side. Drawing `to` over
+            // an opaque `from` kept `from`'s outline whole until the next picture, so the subject's edge jumped a picture at
+            // a time instead of moving.
+            context.globalCompositeOperation = 'lighter';
+            context.globalAlpha = 1 - blend.mix;
+            context.drawImage(picture, 0, 0, width, height);
             context.globalAlpha = blend.mix;
-            context.drawImage(this.images[blend.to]!, 0, 0, width, height);
+            context.drawImage(this.ready[blend.to]!, 0, 0, width, height);
             context.globalAlpha = 1;
+            context.globalCompositeOperation = 'source-over';
+        } else {
+            context.drawImage(picture, 0, 0, width, height);
         }
         // Over a transparent film the poster would show through: a second, stiller subject behind the moving one.
         if (!this.drawn) this.el.setAttribute(FRAMES_SHOWING_ATTRIBUTE, '');
         this.drawn = blend;
     }
 
-    private ensureCanvas(image: HTMLImageElement): boolean {
+    private ensureCanvas(picture: CanvasImageSource): boolean {
         if (this.canvas) return !!this.context;
+        const size = picture as { naturalWidth?: number; naturalHeight?: number; width?: number; height?: number };
         const canvas = this.host.document.createElement('canvas');
         canvas.className = FramesClass.Canvas;
         canvas.setAttribute('aria-hidden', 'true');
-        canvas.width = image.naturalWidth || this.info.width;
-        canvas.height = image.naturalHeight || this.info.height;
+        canvas.width = size.naturalWidth || Number(size.width) || this.info.width;
+        canvas.height = size.naturalHeight || Number(size.height) || this.info.height;
         this.context = canvas.getContext('2d');
         if (!this.context) return false;
         this.canvas = canvas;

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

@@ -19,7 +19,8 @@ import { LIGHT_UP_PIECE_CAP, SplitText, splitText } from './split-text';
  */
 
 export const SCENE_DAMPING = 9;
-const SETTLED = 0.0005;
+/** Page px from the scroll at which the damping stops and stands exactly on it: a step this small never shows. */
+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;
@@ -263,11 +264,12 @@ export class ScrollDriver {
         for (const { scene, local, target } of reads) {
             if (this.options.pin && scene.stage) scene.stage.style.setProperty('translate', `0 ${local}px`);
             const next = scene.fresh ? target : dampToward(scene.progress, target, seconds, this.options.damping);
-            const settled = Math.abs(next - target) < SETTLED;
+            // The step onto the scroll is what is left: taken once it is under SETTLED_PX, so it never shows.
+            const settled = scene.fresh || Math.abs(target - scene.progress) * Math.max(1, scene.travel) < SETTLED_PX;
             scene.progress = settled ? target : next;
             scene.target = target;
             scene.fresh = false;
-            this.write(scene, now);
+            this.write(scene);
             this.options.onFrame?.(scene.root, { target, progress: scene.progress });
             moving = moving || !settled;
         }
@@ -283,11 +285,11 @@ export class ScrollDriver {
         return { scene, local, target: progress };
     }
 
-    private write(scene: Scene, now: number): void {
+    private write(scene: Scene): 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), scenePlayed(tracks, scene.target), now);
+            this.writePlayed(layer, scene, scenePlayed(tracks, scene.progress));
             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 +307,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, aim: number | null, now: number): void {
+    private writePlayed(layer: Layer, scene: Scene, played: number | null): 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,8 +321,8 @@ export class ScrollDriver {
             layer.player = new FramePlayer(target, sequence, { phone: scene.phone, near: scene.root, host: this.host });
             layer.playerKey = key;
         }
-        // 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);
+        // The damped moment, like every other layer: the film slows with the page and stops when it stops.
+        layer.player.seek(played!);
     }
 
     /** One opacity per word, and a write only for the few the scroll actually changed. */