@vectoriox/iox-ui 5.76.0 → 5.77.0

package/media-core/index.d.ts

@@ -38,8 +38,12 @@ declare enum FrameExtension {
     Webp = "webp",
     Jpeg = "jpg"
 }
-/** The most pictures one set may hold. Past this a phone runs out of memory before the visitor runs out of scroll. */
-declare const MAX_FRAMES = 300;
+/**
+ * The most pictures one set may hold. A film's smoothness is its density, pictures per screen of scrolling: 210 over 18
+ * screens stepped on Doron's iPhone as a glide slowed, 1050 did not (2026-11-05). Memory is not what limits it: the player
+ * keeps the downloaded files (about 10 kB a phone picture) and only a window of them unpacked (`unpackedFrameCount`).
+ */
+declare const MAX_FRAMES = 1200;
 /** The most one picture may weigh when uploaded. */
 declare const MAX_FRAME_BYTES: number;
 /** A sequence's name in storage: what the browser generates and what the server accepts in a key. */
@@ -85,6 +89,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;
@@ -99,8 +113,6 @@ declare function fittedFrameSize(width: number, height: number, longSide: number
 declare function videoFrameCount(seconds: number): number;
 /** Which of `sourceCount` pictures make a set of `count`, spread evenly, first and last always in. */
 declare function sampledFrameIndexes(sourceCount: number, count: number): number[];
-/** A phone plays half the pictures: it has less memory, and half is plenty on a small screen. */
-declare function phoneFrameCount(wideCount: number): number;
 /** Rendered frames in their real order: `frame2` before `frame10`. */
 declare function sortFrameFiles<T extends {
     name: string;
@@ -125,6 +137,11 @@ 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;
@@ -132,9 +149,14 @@ declare class FramePlayer {
     private played;
     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;
@@ -143,7 +165,11 @@ 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` %, exactly. The film keeps no motion of its own: the scroll's glide, and the slowing at its end,
@@ -156,7 +182,12 @@ declare class FramePlayer {
     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;
 }
@@ -442,5 +473,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 { 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 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.76.0",
+  "version": "5.77.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/scene-core/index.d.ts

@@ -218,6 +218,23 @@ 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.
+ */
+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. */
+    perScreen: number;
+    /** The screens of scrolling the film plays over; where it holds still is not counted. */
+    screens: number;
+    smooth: boolean;
+}
+/**
+ * How densely a film of `count` pictures plays on a Scene of `screens`, by its Play track; null when nothing plays. A
+ * film's smoothness is its density, never the drawing: spread thin, a slowing glide holds each picture for many refreshes.
+ */
+declare function sceneFilmDensity(tracks: ReadonlyArray<SceneTrack> | null | undefined, screens: number | null, count: number): SceneFilmDensity | null;
 /** Motion v2 §3d's limits for scroll-linked work on one page. */
 declare const SCENE_BUDGET: {
     readonly heldSections: 1;
@@ -402,5 +419,5 @@ declare function revealStagger(groups: number, by: TextRevealBy): number;
  */
 declare function playTextReveal(el: HTMLElement, by: TextRevealBy, timing: KeyframeAnimationOptions): Animation | null;
 
-export { LIGHT_UP_PIECE_CAP, REVEAL_PIECE_CAP, SCENE_BUDGET, SCENE_DAMPING, SCENE_FLOW_RULES, SCENE_LENGTH, SCENE_MAX_SCREENS, SCENE_MIN_SCREENS, SCENE_PHONE_LENGTH, SCENE_PHONE_MAX_WIDTH, SCENE_REDUCED_MOTION_CSS, SCENE_REVEAL_DEFAULT, SCENE_STAGE_HEIGHT, SCENE_TRACK_DEFS, SCENE_WORDS, SCENE_WORD_DIM, SceneAttribute, SceneProp, SceneRevealFrom, ScrollDriver, TextRevealBy, applySceneFirstFrame, attachScenes, buildSceneRecipe, colourAt, dampToward, lineIndexes, movedSceneKey, normalizeTracks, playTextReveal, revealClipPath, revealStagger, sceneBudget, sceneColourKeyAt, sceneDisplayValue, sceneFirstFrame, sceneFrame, sceneFrameDeclarations, sceneHasKeyAt, sceneHeightForScreens, sceneKeyPosition, sceneLayersOf, sceneNodeAttributes, scenePlayed, sceneRevealFromOf, sceneRootOnPath, sceneScreensOf, sceneScrollState, sceneTrackDef, sceneTrackSpan, sceneWordOpacity, sceneWordsLit, scenesIn, splitText, syncSceneAttributes, textPieces, valueAt, withSceneKey, withScenePlayback, withSceneRevealFrom, withoutSceneKey, withoutScenePlayback };
-export type { SceneBudget, SceneFrame, SceneFrameOptions, SceneFrameState, SceneKey, SceneLayerNode, SceneNodeSource, SceneTrack, SceneTrackDef, SceneTreeNode, SceneWords, ScrollDriverOptions, SplitText, SplitTextOptions, TextPiece };
+export { LIGHT_UP_PIECE_CAP, REVEAL_PIECE_CAP, SCENE_BUDGET, SCENE_DAMPING, SCENE_FILM_SMOOTH, SCENE_FLOW_RULES, SCENE_LENGTH, SCENE_MAX_SCREENS, SCENE_MIN_SCREENS, SCENE_PHONE_LENGTH, SCENE_PHONE_MAX_WIDTH, SCENE_REDUCED_MOTION_CSS, SCENE_REVEAL_DEFAULT, SCENE_STAGE_HEIGHT, SCENE_TRACK_DEFS, SCENE_WORDS, SCENE_WORD_DIM, SceneAttribute, SceneProp, SceneRevealFrom, ScrollDriver, TextRevealBy, applySceneFirstFrame, attachScenes, buildSceneRecipe, colourAt, dampToward, lineIndexes, movedSceneKey, normalizeTracks, playTextReveal, revealClipPath, revealStagger, sceneBudget, sceneColourKeyAt, sceneDisplayValue, sceneFilmDensity, sceneFirstFrame, sceneFrame, sceneFrameDeclarations, sceneHasKeyAt, sceneHeightForScreens, sceneKeyPosition, sceneLayersOf, sceneNodeAttributes, scenePlayed, sceneRevealFromOf, sceneRootOnPath, sceneScreensOf, sceneScrollState, sceneTrackDef, sceneTrackSpan, sceneWordOpacity, sceneWordsLit, scenesIn, splitText, syncSceneAttributes, textPieces, valueAt, withSceneKey, withScenePlayback, withSceneRevealFrom, withoutSceneKey, withoutScenePlayback };
+export type { SceneBudget, SceneFilmDensity, SceneFrame, SceneFrameOptions, SceneFrameState, SceneKey, SceneLayerNode, SceneNodeSource, SceneTrack, SceneTrackDef, SceneTreeNode, SceneWords, ScrollDriverOptions, SplitText, SplitTextOptions, TextPiece };

package/src/media-core/frames.ts

@@ -42,8 +42,12 @@ export enum FrameExtension {
     Jpeg = 'jpg',
 }
 
-/** The most pictures one set may hold. Past this a phone runs out of memory before the visitor runs out of scroll. */
-export const MAX_FRAMES = 300;
+/**
+ * The most pictures one set may hold. A film's smoothness is its density, pictures per screen of scrolling: 210 over 18
+ * screens stepped on Doron's iPhone as a glide slowed, 1050 did not (2026-11-05). Memory is not what limits it: the player
+ * keeps the downloaded files (about 10 kB a phone picture) and only a window of them unpacked (`unpackedFrameCount`).
+ */
+export const MAX_FRAMES = 1200;
 /** The most one picture may weigh when uploaded. */
 export const MAX_FRAME_BYTES = 3 * 1024 * 1024;
 /** A sequence's name in storage: what the browser generates and what the server accepts in a key. */
@@ -172,6 +176,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;
@@ -181,10 +210,10 @@ export interface FrameSizes {
  *  tall stage by its height, so a picture sized to the phone's width would be enlarged five times. */
 export const WIDE_LONG_SIDE = 1600;
 export const PHONE_LONG_SIDE = 1100;
-/** How many pictures a second of video becomes, before the cap. */
-const VIDEO_FRAMES_PER_SECOND = 24;
-/** A video's cap: the pictures a scroll can show, at a weight a page can carry. A set of pictures is the author's own count. */
-const VIDEO_MAX_FRAMES = 180;
+/** How many pictures a second of video becomes, before the cap: what most recordings hold, so few are the same twice. */
+const VIDEO_FRAMES_PER_SECOND = 30;
+/** A video's cap: half a minute at that rate. A set of pictures is the author's own count, up to `MAX_FRAMES`. */
+const VIDEO_MAX_FRAMES = 900;
 
 /** `width`×`height` fitted inside `longSide`, never enlarged. */
 export function fittedFrameSize(width: number, height: number, longSide: number): FrameSizes {
@@ -204,11 +233,6 @@ export function sampledFrameIndexes(sourceCount: number, count: number): number[
     return Array.from({ length: count }, (_, i) => Math.round((i * (sourceCount - 1)) / (count - 1)));
 }
 
-/** A phone plays half the pictures: it has less memory, and half is plenty on a small screen. */
-export function phoneFrameCount(wideCount: number): number {
-    return Math.max(2, Math.ceil(wideCount / 2));
-}
-
 const NATURAL = new Intl.Collator('en', { numeric: true, sensitivity: 'base' });
 
 /** Rendered frames in their real order: `frame2` before `frame10`. */
@@ -226,6 +250,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']);
@@ -248,14 +273,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 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;
@@ -264,15 +299,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) {
@@ -292,6 +336,7 @@ export class FramePlayer {
     seek(played: number): void {
         if (played === this.played) return;
         this.played = played;
+        this.hold();
         this.draw();
     }
 
@@ -305,12 +350,15 @@ export class FramePlayer {
         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;
@@ -331,43 +379,104 @@ 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.destroyed || this.played === null) return;
-        const blend = frameBlendAt(this.images, framePosition(this.played, this.info.count));
+        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);
@@ -377,26 +486,27 @@ export class FramePlayer {
             // a time instead of moving.
             context.globalCompositeOperation = 'lighter';
             context.globalAlpha = 1 - blend.mix;
-            context.drawImage(image, 0, 0, width, height);
+            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(image, 0, 0, width, height);
+            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/scene-edit.ts

@@ -238,6 +238,41 @@ export function sceneHeightForScreens(screens: number): string {
     return `${roundTo((held + 1) * 100, 1)}vh`;
 }
 
+/**
+ * Pictures per screen of scrolling at which a played film stays smooth as a glide slows to a stop. Measured on Doron's
+ * iPhone (2026-11-05): Studio Alma's film at about 11 a screen stepped, at about 55 it did not.
+ */
+export const SCENE_FILM_SMOOTH = 40;
+
+export interface SceneFilmDensity {
+    /** Pictures per screen of scrolling over most of the play: half its scroll holds at least this many. */
+    perScreen: number;
+    /** The screens of scrolling the film plays over; where it holds still is not counted. */
+    screens: number;
+    smooth: boolean;
+}
+
+/**
+ * How densely a film of `count` pictures plays on a Scene of `screens`, by its Play track; null when nothing plays. A
+ * film's smoothness is its density, never the drawing: spread thin, a slowing glide holds each picture for many refreshes.
+ */
+export function sceneFilmDensity(tracks: ReadonlyArray<SceneTrack> | null | undefined, screens: number | null, count: number): SceneFilmDensity | null {
+    const keys = normalizeTracks(tracks).find(track => track.prop === SceneProp.Play)?.keys ?? [];
+    if (count < 2 || !screens || screens <= 0) return null;
+    const stretches: { perScreen: number; screens: number }[] = [];
+    for (let i = 1; i < keys.length; i++) {
+        const scrolled = (keys[i][0] - keys[i - 1][0]) * screens;
+        const played = Math.abs(Number(keys[i][1]) - Number(keys[i - 1][1]));
+        if (scrolled > 0 && played > 0) stretches.push({ perScreen: ((played / 100) * (count - 1)) / scrolled, screens: scrolled });
+    }
+    if (!stretches.length) return null;
+    stretches.sort((a, b) => a.perScreen - b.perScreen);
+    const total = stretches.reduce((sum, stretch) => sum + stretch.screens, 0);
+    let covered = 0;
+    const typical = stretches.find(stretch => (covered += stretch.screens) >= total / 2)!;
+    return { perScreen: Math.round(typical.perScreen), screens: roundTo(total, 1), smooth: typical.perScreen >= SCENE_FILM_SMOOTH };
+}
+
 /** Motion v2 §3d's limits for scroll-linked work on one page. */
 export const SCENE_BUDGET = { heldSections: 1, movingLayers: 8 } as const;