@vectoriox/iox-ui 5.72.0 → 5.73.0

package/index.d.ts

@@ -954,6 +954,8 @@ declare class IoxVideoComponent implements AfterViewInit, OnDestroy {
     get captionsLang(): unknown;
     set consentCategory(v: unknown);
     get consentCategory(): unknown;
+    set frames(v: unknown);
+    get frames(): unknown;
     private root?;
     plan: VideoPlan;
     attrs: Record<string, string>;
@@ -969,7 +971,7 @@ declare class IoxVideoComponent implements AfterViewInit, OnDestroy {
     private render;
     private attach;
     static ɵfac: i0.ɵɵFactoryDeclaration<IoxVideoComponent, [null, null, { optional: true; }]>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<IoxVideoComponent, "iox-video", never, { "nodeId": { "alias": "nodeId"; "required": false; }; "videoSource": { "alias": "videoSource"; "required": false; }; "src": { "alias": "src"; "required": false; }; "poster": { "alias": "poster"; "required": false; }; "mode": { "alias": "mode"; "required": false; }; "autoplay": { "alias": "autoplay"; "required": false; }; "title": { "alias": "title"; "required": false; }; "captions": { "alias": "captions"; "required": false; }; "captionsLang": { "alias": "captionsLang"; "required": false; }; "consentCategory": { "alias": "consentCategory"; "required": false; }; }, {}, never, never, false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<IoxVideoComponent, "iox-video", never, { "nodeId": { "alias": "nodeId"; "required": false; }; "videoSource": { "alias": "videoSource"; "required": false; }; "src": { "alias": "src"; "required": false; }; "poster": { "alias": "poster"; "required": false; }; "mode": { "alias": "mode"; "required": false; }; "autoplay": { "alias": "autoplay"; "required": false; }; "title": { "alias": "title"; "required": false; }; "captions": { "alias": "captions"; "required": false; }; "captionsLang": { "alias": "captionsLang"; "required": false; }; "consentCategory": { "alias": "consentCategory"; "required": false; }; "frames": { "alias": "frames"; "required": false; }; }, {}, never, never, false, never>;
 }
 
 /** What the visitor actually types into. Chosen by a trait; it also implies a validation rule. */

package/media-core/index.d.ts

@@ -1,5 +1,138 @@
 import { ConsentCategory, ConsentDecision } from '@vectoriox/iox-ui/consent-core';
 
+/**
+ * A video played by the scroll, as pictures (premium sites SC4). Every source, a video file or a folder of rendered frames,
+ * becomes the same numbered set of pictures, prepared once in the author's browser, one set for wide screens and a lighter
+ * one for phones. So there is one player and it is the same on every browser: a `<video>` seeked by the scroll needs a
+ * dense-keyframe encode no pod here can run, and on an iPhone it accepts seeks it never answers.
+ *
+ * The saved value is a small description, never a list of addresses: a page holding 300 URLs would ship them in its HTML.
+ */
+declare enum FrameSet {
+    Wide = "w",
+    Phone = "p"
+}
+interface FrameSetInfo {
+    count: number;
+    width: number;
+    height: number;
+}
+interface FrameSequence {
+    /** Where the numbered pictures live: `<base>/<set>/0001.<ext>`. */
+    base: string;
+    ext: FrameExtension;
+    wide: FrameSetInfo;
+    /** Absent = phones play the wide set. */
+    phone?: FrameSetInfo;
+    /** What the sequence weighs in storage, both sets. Shown to the author. */
+    bytes?: number;
+}
+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 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. */
+declare const FRAME_SEQUENCE_ID: RegExp;
+/** The sequence a saved value really describes, or null. Never throws on what a page document holds. */
+declare function normalizeFrameSequence(raw: unknown): FrameSequence | null;
+/** The name a picture is stored under: its place in the set, from 1. */
+declare function frameFileName(index: number, ext: FrameExtension): string;
+/** Picture `index` (from 0) of a set. */
+declare function frameUrl(sequence: FrameSequence, set: FrameSet, index: number): string;
+/** The first picture of each set, for a poster's `srcset`; '' when there is only one set. */
+declare function phoneFrameSrcset(sequence: FrameSequence): string;
+/** Which set plays: the phone's on a phone, when there is one. */
+declare function frameSetFor(sequence: FrameSequence, phone: boolean): {
+    set: FrameSet;
+    info: FrameSetInfo;
+};
+/** The picture at `played` % of a set of `count`. */
+declare function frameIndexAt(played: number, count: number): number;
+/**
+ * The order to fetch a set in: the two ends, then every 16th, every 8th and so on down to all of them. Any scroll position
+ * then has a near picture almost at once, and the movement sharpens as the rest arrive. Fetching in sequence would leave a
+ * visitor who scrolls fast looking at the first frames.
+ */
+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;
+interface FrameSizes {
+    width: number;
+    height: number;
+}
+/** The longest side of a wide picture and of a phone picture. A phone's is not its width: a landscape video covers a
+ *  tall stage by its height, so a picture sized to the phone's width would be enlarged five times. */
+declare const WIDE_LONG_SIDE = 1600;
+declare const PHONE_LONG_SIDE = 1100;
+/** `width`×`height` fitted inside `longSide`, never enlarged. */
+declare function fittedFrameSize(width: number, height: number, longSide: number): FrameSizes;
+/** How many pictures a video of `seconds` becomes. */
+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;
+}>(files: ReadonlyArray<T>): T[];
+/** A sequence's weight, for the author. */
+declare function frameSummary(sequence: FrameSequence): {
+    frames: number;
+    megabytes: number | null;
+};
+declare enum FramesClass {
+    Canvas = "iox-video__frames"
+}
+interface FramePlayerOptions {
+    /** Play the phone's set. */
+    phone?: boolean;
+    /** Start fetching when this comes near the screen. Not the layer itself: a layer clipped shut intersects nothing. */
+    near?: Element;
+    /** The window, for a test. */
+    host?: Window;
+}
+/**
+ * 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.
+ */
+declare class FramePlayer {
+    private readonly el;
+    private readonly sequence;
+    private readonly set;
+    private readonly info;
+    private readonly images;
+    private readonly order;
+    private readonly host;
+    private observer;
+    private canvas;
+    private context;
+    private wanted;
+    private drawn;
+    private nextToLoad;
+    private loading;
+    private started;
+    private destroyed;
+    private readonly pending;
+    constructor(el: HTMLElement, sequence: FrameSequence, options?: FramePlayerOptions);
+    /** Stand at `played` %. */
+    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 draw;
+    private ensureCanvas;
+}
+
 /**
  * VIDEO (CC3 — complex-components plan §7b, board 5). A LEAF type with two sources:
  * - an uploaded FILE renders as a real `<video>` (poster, `preload="metadata"`, captions, controls);
@@ -34,7 +167,9 @@ declare enum VideoTrait {
     Title = "title",
     Captions = "captions",
     CaptionsLang = "captionsLang",
-    Consent = "consentCategory"
+    Consent = "consentCategory",
+    /** Pictures the scroll plays (SC4): a `FrameSequence`. Written by the Scene panel, never typed. */
+    Frames = "frames"
 }
 /** What a plan renders. */
 declare enum VideoKind {
@@ -43,7 +178,9 @@ declare enum VideoKind {
     /** YouTube / Vimeo: poster + play, the player loaded on a click after consent. */
     Facade = "facade",
     /** No address yet: the poster blank (DS3) and nothing to play. */
-    Empty = "empty"
+    Empty = "empty",
+    /** Pictures the scroll plays: the poster, and the driver's canvas over it. No player, no controls. */
+    Frames = "frames"
 }
 /** A recognised embed: which provider, its video id and (Vimeo, unlisted) its privacy hash. */
 interface VideoRef {
@@ -114,6 +251,8 @@ interface VideoPlan {
     embedUrl: string | null;
     /** "YouTube" / "Vimeo" ('' for a file). */
     providerLabel: string;
+    /** Pictures the scroll plays (Frames). */
+    frames: FrameSequence | null;
 }
 /**
  * The ONE decision for a Video node and a visitor's consent (null = none recorded — the server always passes null,
@@ -181,7 +320,9 @@ declare enum VideoAttribute {
     /** The player is loaded (after the click and the grant). */
     Playing = "data-iox-video-playing",
     /** The consent prompt is showing. */
-    Asking = "data-iox-video-asking"
+    Asking = "data-iox-video-asking",
+    /** The pictures the scroll plays, as JSON: what the driver reads, so it needs no node tree. */
+    Frames = "data-iox-video-frames"
 }
 declare enum VideoIcon {
     Play = "ph-fill ph-play",
@@ -273,5 +414,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, VIDEO_EMBED_ORIGINS, VIDEO_NODE_TYPE, VIDEO_PROVIDER_COMPANY, VIDEO_PROVIDER_LABEL, VIDEO_WORDS, VideoAttribute, VideoClass, VideoIcon, VideoKind, VideoMode, VideoRuntime, VideoSource, VideoTrait, attachVideoAt, attachVideos, documentConsentTransport, isThirdPartyPoster, parseVideoUrl, planVideo, readConsentRecord, serializeVideoAttributes, videoConsentCategory, videoEmbedUrl, videoInnerHtml, videoPlayLabel, videoPosterFileName, videoProp, videoRefOf, videoRootAttributes, videoRuntimeOf, videoSourceOf, videoThumbnailRequest, videoWords };
-export type { ConsentGrantDetail, ConsentTransport, VideoMarkupOptions, VideoNodeLike, VideoPlan, VideoRef, VideoRuntimeOptions, VideoThumbnailRequest, VideoWords };
+export { CONSENT_GRANT_EVENT, CONSENT_PREFERENCES_EVENT, 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, frameFileName, frameIndexAt, frameLoadOrder, 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, FramePlayerOptions, FrameSequence, FrameSetInfo, FrameSizes, VideoMarkupOptions, VideoNodeLike, VideoPlan, VideoRef, VideoRuntimeOptions, VideoThumbnailRequest, VideoWords };

package/package.json

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

package/scene-core/index.d.ts

@@ -23,6 +23,8 @@ declare enum SceneProp {
     Clip = "clip",
     /** How many of the layer's words are lit, in % (100 = all): the word-by-word light-up. Split in the browser only. */
     Words = "words",
+    /** How much of a Video layer's pictures have played, in % (100 = the last picture). */
+    Play = "play",
     /** The layer's background colour. */
     Ground = "ground",
     /** The layer's text colour. */
@@ -102,6 +104,8 @@ declare function sceneFrame(tracks: ReadonlyArray<SceneTrack>, p: number, option
 declare const SCENE_WORD_DIM = 0.16;
 /** How many of a layer's words are lit at `p`, in %; null when it has no such track. */
 declare function sceneWordsLit(tracks: ReadonlyArray<SceneTrack>, p: number): number | null;
+/** How far a layer's pictures have played at `p`, in %; null when it has no such track. */
+declare function scenePlayed(tracks: ReadonlyArray<SceneTrack>, p: number): number | null;
 /** Word `index` of `count`, with `lit` % lit: words light one after the other, each easing in as the last finishes. */
 declare function sceneWordOpacity(index: number, count: number, lit: number): number;
 /** A frame as kebab-case style declarations, for a string renderer. */
@@ -161,6 +165,13 @@ declare function sceneRevealFromOf(tracks: ReadonlyArray<SceneTrack>): SceneReve
  * direction is kept and nothing on screen changes until the author sets a second key.
  */
 declare function withSceneRevealFrom(tracks: ReadonlyArray<SceneTrack>, from: SceneRevealFrom, p: number): SceneTrack[];
+/**
+ * A layer's pictures playing across the whole Scene: the start of playing them. Keys the author has set are kept, so
+ * replacing the pictures keeps the timing.
+ */
+declare function withScenePlayback(tracks: ReadonlyArray<SceneTrack>): SceneTrack[];
+/** Stop playing a layer's pictures. */
+declare function withoutScenePlayback(tracks: ReadonlyArray<SceneTrack>): SceneTrack[];
 /**
  * Set a key at `p`, in the author's units. A number is clamped to its bounds; a colour that is no colour changes nothing,
  * because `normalizeTracks` would drop it anyway and the author's other keys must survive.
@@ -319,6 +330,7 @@ declare class ScrollDriver {
     /** Read a root's stage and layers from its DOM: its own Scene's only, never a nested one's. */
     private readScene;
     private letGo;
+    private stopPlayer;
     private restoreWords;
     private readLayer;
     private remeasureAll;
@@ -326,6 +338,11 @@ declare class ScrollDriver {
     private readonly tick;
     private read;
     private write;
+    /**
+     * 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;
     /** One opacity per word, and a write only for the few the scroll actually changed. */
     private writeWords;
 }
@@ -382,5 +399,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, sceneRevealFromOf, sceneRootOnPath, sceneScreensOf, sceneScrollState, sceneTrackDef, sceneTrackSpan, sceneWordOpacity, sceneWordsLit, scenesIn, splitText, syncSceneAttributes, textPieces, valueAt, withSceneKey, withSceneRevealFrom, withoutSceneKey };
+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 };

package/src/generation-core/node-baselines.generated.ts

@@ -4912,6 +4912,7 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
       "videoSource": "youtube",
       "src": "",
       "poster": "",
+      "frames": null,
       "mode": "inline",
       "autoplay": false,
       "title": "",
@@ -4976,6 +4977,7 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
       "videoSource",
       "src",
       "poster",
+      "frames",
       "__behaviourLabel",
       "mode",
       "autoplay",

package/src/media-core/frames.ts

@@ -0,0 +1,339 @@
+/**
+ * A video played by the scroll, as pictures (premium sites SC4). Every source, a video file or a folder of rendered frames,
+ * becomes the same numbered set of pictures, prepared once in the author's browser, one set for wide screens and a lighter
+ * one for phones. So there is one player and it is the same on every browser: a `<video>` seeked by the scroll needs a
+ * dense-keyframe encode no pod here can run, and on an iPhone it accepts seeks it never answers.
+ *
+ * The saved value is a small description, never a list of addresses: a page holding 300 URLs would ship them in its HTML.
+ */
+
+export enum FrameSet {
+    Wide = 'w',
+    Phone = 'p',
+}
+
+export interface FrameSetInfo {
+    count: number;
+    width: number;
+    height: number;
+}
+
+export interface FrameSequence {
+    /** Where the numbered pictures live: `<base>/<set>/0001.<ext>`. */
+    base: string;
+    ext: FrameExtension;
+    wide: FrameSetInfo;
+    /** Absent = phones play the wide set. */
+    phone?: FrameSetInfo;
+    /** What the sequence weighs in storage, both sets. Shown to the author. */
+    bytes?: number;
+}
+
+export 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. */
+export const MAX_FRAMES = 300;
+/** 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. */
+export const FRAME_SEQUENCE_ID = /^[a-z0-9]{8,40}$/;
+
+const SAFE_BASE = /^https:\/\/[^\s"'<>\\]+$/;
+const PAD = 4;
+const ALL_EXTENSIONS: ReadonlySet<string> = new Set(Object.values(FrameExtension));
+
+function setInfo(raw: unknown): FrameSetInfo | null {
+    const { count, width, height } = (raw ?? {}) as Partial<FrameSetInfo>;
+    const valid = (v: unknown, max: number): v is number => Number.isInteger(v) && (v as number) > 0 && (v as number) <= max;
+    return valid(count, MAX_FRAMES) && valid(width, 8192) && valid(height, 8192) ? { count, width, height } : null;
+}
+
+/** The sequence a saved value really describes, or null. Never throws on what a page document holds. */
+export function normalizeFrameSequence(raw: unknown): FrameSequence | null {
+    const value = (typeof raw === 'string' ? parseJson(raw) : raw) as Partial<FrameSequence> | null;
+    if (!value || typeof value !== 'object') return null;
+    const wide = setInfo(value.wide);
+    if (!wide || typeof value.base !== 'string' || !SAFE_BASE.test(value.base) || !ALL_EXTENSIONS.has(String(value.ext))) return null;
+    const phone = setInfo(value.phone);
+    return {
+        base: value.base.replace(/\/+$/, ''),
+        ext: value.ext as FrameExtension,
+        wide,
+        ...(phone ? { phone } : {}),
+        ...(Number.isFinite(value.bytes) && (value.bytes as number) > 0 ? { bytes: value.bytes } : {}),
+    };
+}
+
+function parseJson(raw: string): unknown {
+    try { return JSON.parse(raw); } catch { return null; }
+}
+
+/** The name a picture is stored under: its place in the set, from 1. */
+export function frameFileName(index: number, ext: FrameExtension): string {
+    return `${String(index + 1).padStart(PAD, '0')}.${ext}`;
+}
+
+/** Picture `index` (from 0) of a set. */
+export function frameUrl(sequence: FrameSequence, set: FrameSet, index: number): string {
+    return `${sequence.base}/${set}/${frameFileName(index, sequence.ext)}`;
+}
+
+/** The first picture of each set, for a poster's `srcset`; '' when there is only one set. */
+export function phoneFrameSrcset(sequence: FrameSequence): string {
+    if (!sequence.phone) return '';
+    return `${frameUrl(sequence, FrameSet.Phone, 0)} ${sequence.phone.width}w, ${frameUrl(sequence, FrameSet.Wide, 0)} ${sequence.wide.width}w`;
+}
+
+/** Which set plays: the phone's on a phone, when there is one. */
+export function frameSetFor(sequence: FrameSequence, phone: boolean): { set: FrameSet; info: FrameSetInfo } {
+    return phone && sequence.phone ? { set: FrameSet.Phone, info: sequence.phone } : { set: FrameSet.Wide, info: sequence.wide };
+}
+
+/** The picture at `played` % of a set of `count`. */
+export function frameIndexAt(played: number, count: number): number {
+    if (count <= 1) return 0;
+    return Math.round((Math.min(100, Math.max(0, played)) / 100) * (count - 1));
+}
+
+/**
+ * The order to fetch a set in: the two ends, then every 16th, every 8th and so on down to all of them. Any scroll position
+ * then has a near picture almost at once, and the movement sharpens as the rest arrive. Fetching in sequence would leave a
+ * visitor who scrolls fast looking at the first frames.
+ */
+export function frameLoadOrder(count: number): number[] {
+    const order: number[] = [];
+    const seen = new Set<number>();
+    const add = (i: number): void => {
+        if (i >= 0 && i < count && !seen.has(i)) {
+            seen.add(i);
+            order.push(i);
+        }
+    };
+    add(0);
+    add(count - 1);
+    for (let stride = 16; stride >= 1; stride /= 2) {
+        for (let i = 0; i < count; i += stride) add(i);
+    }
+    return order;
+}
+
+/** The loaded picture nearest `index`, or -1 when none has arrived. Ties go backward: the picture already passed. */
+export function nearestLoadedFrame(loaded: ReadonlyArray<unknown>, index: number): number {
+    for (let distance = 0; distance < loaded.length; distance++) {
+        if (loaded[index - distance]) return index - distance;
+        if (loaded[index + distance]) return index + distance;
+    }
+    return -1;
+}
+
+export interface FrameSizes {
+    width: number;
+    height: number;
+}
+
+/** The longest side of a wide picture and of a phone picture. A phone's is not its width: a landscape video covers a
+ *  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;
+
+/** `width`×`height` fitted inside `longSide`, never enlarged. */
+export function fittedFrameSize(width: number, height: number, longSide: number): FrameSizes {
+    const scale = Math.min(1, longSide / Math.max(width, height));
+    return { width: Math.max(1, Math.round(width * scale)), height: Math.max(1, Math.round(height * scale)) };
+}
+
+/** How many pictures a video of `seconds` becomes. */
+export function videoFrameCount(seconds: number): number {
+    return Math.min(VIDEO_MAX_FRAMES, Math.max(2, Math.ceil(seconds * VIDEO_FRAMES_PER_SECOND)));
+}
+
+/** Which of `sourceCount` pictures make a set of `count`, spread evenly, first and last always in. */
+export function sampledFrameIndexes(sourceCount: number, count: number): number[] {
+    if (count >= sourceCount) return Array.from({ length: sourceCount }, (_, i) => i);
+    if (count <= 1) return [0];
+    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`. */
+export function sortFrameFiles<T extends { name: string }>(files: ReadonlyArray<T>): T[] {
+    return [...files].sort((a, b) => NATURAL.compare(a.name, b.name));
+}
+
+/** A sequence's weight, for the author. */
+export function frameSummary(sequence: FrameSequence): { frames: number; megabytes: number | null } {
+    return { frames: sequence.wide.count, megabytes: sequence.bytes ? Math.round((sequence.bytes / (1024 * 1024)) * 10) / 10 : null };
+}
+
+export enum FramesClass {
+    Canvas = 'iox-video__frames',
+}
+
+const LOAD_CONCURRENCY = 6;
+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']);
+
+interface NetworkInformationLike {
+    saveData?: boolean;
+    effectiveType?: string;
+}
+
+export interface FramePlayerOptions {
+    /** Play the phone's set. */
+    phone?: boolean;
+    /** Start fetching when this comes near the screen. Not the layer itself: a layer clipped shut intersects nothing. */
+    near?: Element;
+    /** The window, for a test. */
+    host?: Window;
+}
+
+/**
+ * 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.
+ */
+export class FramePlayer {
+    private readonly set: FrameSet;
+    private readonly info: FrameSetInfo;
+    private readonly images: Array<HTMLImageElement | null>;
+    private readonly order: number[];
+    private readonly host: Window;
+    private observer: IntersectionObserver | null = null;
+    private canvas: HTMLCanvasElement | null = null;
+    private context: CanvasRenderingContext2D | null = null;
+    private wanted = 0;
+    private drawn = -1;
+    private nextToLoad = 0;
+    private loading = 0;
+    private started = false;
+    private destroyed = false;
+    private readonly pending = new Set<HTMLImageElement>();
+
+    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.order = frameLoadOrder(info.count);
+        if (!this.allowed()) return;
+        const Observer = (this.host as Window & { IntersectionObserver?: typeof IntersectionObserver }).IntersectionObserver;
+        if (!Observer) {
+            this.start();
+            return;
+        }
+        this.observer = new Observer(entries => {
+            if (entries.some(entry => entry.isIntersecting)) this.start();
+        }, { rootMargin: NEAR_MARGIN });
+        this.observer.observe(options.near ?? el);
+    }
+
+    /** Stand at `played` %. */
+    seek(played: number): void {
+        this.wanted = frameIndexAt(played, this.info.count);
+        this.draw();
+    }
+
+    /** Whether a re-render took the canvas away with the markup it sat in. */
+    get detached(): boolean {
+        return !!this.canvas && !this.canvas.isConnected;
+    }
+
+    destroy(): void {
+        this.destroyed = true;
+        this.observer?.disconnect();
+        this.observer = null;
+        for (const image of this.pending) {
+            image.onload = null;
+            image.onerror = null;
+            image.src = '';
+        }
+        this.pending.clear();
+        this.canvas?.remove();
+        this.canvas = null;
+        this.context = null;
+    }
+
+    private allowed(): boolean {
+        const connection = (this.host.navigator as Navigator & { connection?: NetworkInformationLike } | undefined)?.connection;
+        return !connection?.saveData && !SLOW_CONNECTIONS.has(connection?.effectiveType ?? '');
+    }
+
+    private start(): void {
+        if (this.started) return;
+        this.started = true;
+        this.observer?.disconnect();
+        this.observer = null;
+        this.pump();
+    }
+
+    private pump(): void {
+        while (!this.destroyed && this.loading < LOAD_CONCURRENCY && this.nextToLoad < this.order.length) {
+            this.load(this.order[this.nextToLoad++]);
+        }
+    }
+
+    private load(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();
+        };
+        // Decoded before it counts, or the first draw of each picture decodes on the driver's frame and the scroll stutters.
+        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);
+    }
+
+    private draw(): void {
+        const index = nearestLoadedFrame(this.images, this.wanted);
+        if (index < 0 || index === this.drawn) return;
+        const image = this.images[index]!;
+        if (!this.ensureCanvas(image)) return;
+        this.context!.clearRect(0, 0, this.canvas!.width, this.canvas!.height);
+        this.context!.drawImage(image, 0, 0, this.canvas!.width, this.canvas!.height);
+        this.drawn = index;
+    }
+
+    private ensureCanvas(image: HTMLImageElement): boolean {
+        if (this.canvas) return !!this.context;
+        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;
+        this.context = canvas.getContext('2d');
+        if (!this.context) return false;
+        this.canvas = canvas;
+        this.el.appendChild(canvas);
+        return true;
+    }
+}

package/src/media-core/public-api.ts

@@ -5,5 +5,6 @@
  * fetch and store an embed's poster (the visitor never asks the provider for it).
  * ⚠️ Consumers wire the usual trio — ng-package raw-ts assets, jest moduleNameMapper, tsconfig paths.
  */
+export * from './frames';
 export * from './video';
 export * from './video-runtime';