@vectoriox/iox-ui 5.73.3 → 5.74.0

package/media-core/index.d.ts

@@ -24,9 +24,16 @@ interface FrameSequence {
     wide: FrameSetInfo;
     /** Absent = phones play the wide set. */
     phone?: FrameSetInfo;
+    /**
+     * A phone film of its own, framed for a tall screen, lives under its own name: a replacement that fails half way leaves
+     * the one playing untouched. Absent = the phone set is the wide film made smaller, under `base`.
+     */
+    phoneBase?: string;
     /** What the sequence weighs in storage, both sets. Shown to the author. */
     bytes?: number;
 }
+/** At or under this width a screen is a phone. Scene's own limit says the same: scene-core reads media-core, never the reverse. */
+declare const FRAMES_PHONE_MAX_WIDTH = 767;
 declare enum FrameExtension {
     Webp = "webp",
     Jpeg = "jpg"
@@ -50,6 +57,22 @@ declare function frameSetFor(sequence: FrameSequence, phone: boolean): {
     set: FrameSet;
     info: FrameSetInfo;
 };
+/** Where `played` % stands in a set of `count`: 2.5 is half way from the third picture to the fourth. */
+declare function framePosition(played: number, count: number): number;
+/** 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. */
+interface FrameBlend {
+    from: number;
+    to: number;
+    mix: number;
+}
+/**
+ * The moment between two pictures. A long Scene gives a picture 50px of scroll or more, so a slow scroll would otherwise
+ * show the film stepping. Blending the two neighbours keeps it moving under the finger, at the cost of one more drawImage.
+ * 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;
 /** The picture at `played` % of a set of `count`. */
 declare function frameIndexAt(played: number, count: number): number;
 /**
@@ -112,7 +135,7 @@ declare class FramePlayer {
     private observer;
     private canvas;
     private context;
-    private wanted;
+    private position;
     private drawn;
     private nextToLoad;
     private loading;
@@ -414,5 +437,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, 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 };
+export { CONSENT_GRANT_EVENT, CONSENT_PREFERENCES_EVENT, FRAMES_PHONE_MAX_WIDTH, FRAME_BLEND_STEPS, FRAME_SEQUENCE_ID, FrameExtension, FramePlayer, FrameSet, FramesClass, MAX_FRAMES, MAX_FRAME_BYTES, PHONE_LONG_SIDE, VIDEO_EMBED_ORIGINS, VIDEO_NODE_TYPE, VIDEO_PROVIDER_COMPANY, VIDEO_PROVIDER_LABEL, VIDEO_WORDS, VideoAttribute, VideoClass, VideoIcon, VideoKind, VideoMode, VideoRuntime, VideoSource, VideoTrait, WIDE_LONG_SIDE, attachVideoAt, attachVideos, documentConsentTransport, fittedFrameSize, frameBlendAt, frameFileName, frameIndexAt, frameLoadOrder, framePosition, frameSetFor, frameSummary, frameUrl, isThirdPartyPoster, nearestLoadedFrame, normalizeFrameSequence, parseVideoUrl, phoneFrameCount, phoneFrameSrcset, planVideo, readConsentRecord, sampledFrameIndexes, serializeVideoAttributes, sortFrameFiles, videoConsentCategory, videoEmbedUrl, videoFrameCount, videoInnerHtml, videoPlayLabel, videoPosterFileName, videoProp, videoRefOf, videoRootAttributes, videoRuntimeOf, videoSourceOf, videoThumbnailRequest, videoWords };
+export type { ConsentGrantDetail, ConsentTransport, FrameBlend, FramePlayerOptions, FrameSequence, FrameSetInfo, FrameSizes, VideoMarkupOptions, VideoNodeLike, VideoPlan, VideoRef, VideoRuntimeOptions, VideoThumbnailRequest, VideoWords };

package/package.json

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

package/scene-core/index.d.ts

@@ -85,7 +85,7 @@ declare function normalizeTracks(tracks: unknown): SceneTrack[];
  */
 declare function revealClipPath(showing: number, from?: SceneRevealFrom, inlineSign?: 1 | -1): string;
 /** A numeric track's value at progress `p`. */
-declare function valueAt(keys: ReadonlyArray<SceneKey>, p: number): number;
+declare function valueAt(keys: ReadonlyArray<SceneKey>, p: number, ease?: (t: number) => number): number;
 /**
  * A colour track's value at progress `p`. Mixed by the browser, never computed here, so a design token stays a live
  * reference (a re-theme reaches a Scene, as it reaches every saved page) and the path is perceptual.
@@ -104,7 +104,10 @@ 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. */
+/**
+ * How far a layer's pictures have played at `p`, in %; null when it has no such track. A film runs straight between its
+ * keys, where everything else eases: eased over a 20-screen Scene it would crawl for its first screens and rush the middle.
+ */
 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;
@@ -130,7 +133,7 @@ declare function applySceneFirstFrame(el: HTMLElement | null | undefined, node:
  */
 declare const SCENE_FLOW_RULES: string;
 /** Under reduced motion the driver never starts, so the same rules hold for the whole visit. */
-declare const SCENE_REDUCED_MOTION_CSS = "@media (prefers-reduced-motion: reduce){.iox-role-scene{height:auto!important}.iox-role-scene-stage{position:relative!important;top:auto!important;height:auto!important;overflow:visible!important;container-type:normal!important}[data-iox-tracks]{transform:none!important;opacity:1!important;clip-path:none!important;pointer-events:auto!important}[data-iox-video-frames]{height:auto!important}[data-iox-video-frames]>.iox-video__poster{position:static!important;height:auto!important}}";
+declare const SCENE_REDUCED_MOTION_CSS = "@media (prefers-reduced-motion: reduce){.iox-role-scene{height:auto!important}.iox-role-scene-stage{position:relative!important;top:auto!important;height:auto!important;overflow:visible!important;container-type:normal!important}[data-iox-tracks]{transform:none!important;opacity:1!important;clip-path:none!important;pointer-events:auto!important}[data-iox-video-frames]{height:auto!important}[data-iox-video-frames]>.iox-video__poster,[data-iox-video-frames]>picture>.iox-video__poster{position:static!important;height:auto!important}}";
 
 declare function sceneKeyPosition(p: number): number;
 interface SceneTrackDef {

package/src/media-core/frames.ts

@@ -25,10 +25,18 @@ export interface FrameSequence {
     wide: FrameSetInfo;
     /** Absent = phones play the wide set. */
     phone?: FrameSetInfo;
+    /**
+     * A phone film of its own, framed for a tall screen, lives under its own name: a replacement that fails half way leaves
+     * the one playing untouched. Absent = the phone set is the wide film made smaller, under `base`.
+     */
+    phoneBase?: string;
     /** What the sequence weighs in storage, both sets. Shown to the author. */
     bytes?: number;
 }
 
+/** At or under this width a screen is a phone. Scene's own limit says the same: scene-core reads media-core, never the reverse. */
+export const FRAMES_PHONE_MAX_WIDTH = 767;
+
 export enum FrameExtension {
     Webp = 'webp',
     Jpeg = 'jpg',
@@ -58,11 +66,13 @@ export function normalizeFrameSequence(raw: unknown): FrameSequence | 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);
+    const phoneBase = phone && typeof value.phoneBase === 'string' && SAFE_BASE.test(value.phoneBase) ? value.phoneBase.replace(/\/+$/, '') : '';
     return {
         base: value.base.replace(/\/+$/, ''),
         ext: value.ext as FrameExtension,
         wide,
         ...(phone ? { phone } : {}),
+        ...(phoneBase ? { phoneBase } : {}),
         ...(Number.isFinite(value.bytes) && (value.bytes as number) > 0 ? { bytes: value.bytes } : {}),
     };
 }
@@ -78,7 +88,8 @@ export function frameFileName(index: number, ext: FrameExtension): string {
 
 /** 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)}`;
+    const base = set === FrameSet.Phone && sequence.phoneBase ? sequence.phoneBase : sequence.base;
+    return `${base}/${set}/${frameFileName(index, sequence.ext)}`;
 }
 
 /** The first picture of each set, for a poster's `srcset`; '' when there is only one set. */
@@ -92,6 +103,35 @@ export function frameSetFor(sequence: FrameSequence, phone: boolean): { set: Fra
     return phone && sequence.phone ? { set: FrameSet.Phone, info: sequence.phone } : { set: FrameSet.Wide, info: sequence.wide };
 }
 
+/** Where `played` % stands in a set of `count`: 2.5 is half way from the third picture to the fourth. */
+export function framePosition(played: number, count: number): number {
+    return (Math.min(100, Math.max(0, played)) / 100) * (count - 1);
+}
+
+/** 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;
+
+/** What to draw: picture `from`, with `to` over it at `mix` when the moment falls between two that have arrived. */
+export interface FrameBlend {
+    from: number;
+    to: number;
+    mix: number;
+}
+
+/**
+ * The moment between two pictures. A long Scene gives a picture 50px of scroll or more, so a slow scroll would otherwise
+ * show the film stepping. Blending the two neighbours keeps it moving under the finger, at the cost of one more drawImage.
+ * A neighbour still loading never blends: the nearest arrived picture stands in, and null means none has.
+ */
+export function frameBlendAt(loaded: ReadonlyArray<unknown>, position: number): FrameBlend | null {
+    const from = Math.floor(position);
+    const to = from + 1;
+    const mix = Math.round((position - from) * FRAME_BLEND_STEPS) / FRAME_BLEND_STEPS;
+    if (mix > 0 && mix < 1 && loaded[from] && loaded[to]) return { from, to, mix };
+    const nearest = nearestLoadedFrame(loaded, Math.round(position));
+    return nearest < 0 ? null : { from: nearest, to: nearest, mix: 0 };
+}
+
 /** The picture at `played` % of a set of `count`. */
 export function frameIndexAt(played: number, count: number): number {
     if (count <= 1) return 0;
@@ -215,8 +255,8 @@ export class FramePlayer {
     private observer: IntersectionObserver | null = null;
     private canvas: HTMLCanvasElement | null = null;
     private context: CanvasRenderingContext2D | null = null;
-    private wanted = 0;
-    private drawn = -1;
+    private position = 0;
+    private drawn: FrameBlend | null = null;
     private nextToLoad = 0;
     private loading = 0;
     private started = false;
@@ -244,7 +284,7 @@ export class FramePlayer {
 
     /** Stand at `played` %. */
     seek(played: number): void {
-        this.wanted = frameIndexAt(played, this.info.count);
+        this.position = framePosition(played, this.info.count);
         this.draw();
     }
 
@@ -314,13 +354,21 @@ export class FramePlayer {
     }
 
     private draw(): void {
-        const index = nearestLoadedFrame(this.images, this.wanted);
-        if (index < 0 || index === this.drawn) return;
-        const image = this.images[index]!;
+        const blend = frameBlendAt(this.images, this.position);
+        const last = this.drawn;
+        if (!blend || (last && last.from === blend.from && last.to === blend.to && last.mix === blend.mix)) return;
+        const image = this.images[blend.from]!;
         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;
+        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) {
+            context.globalAlpha = blend.mix;
+            context.drawImage(this.images[blend.to]!, 0, 0, width, height);
+            context.globalAlpha = 1;
+        }
+        this.drawn = blend;
     }
 
     private ensureCanvas(image: HTMLImageElement): boolean {

package/src/media-core/video.ts

@@ -1,6 +1,6 @@
 import { ConsentCategory, ConsentDecision, hasConsent } from '@vectoriox/iox-ui/consent-core';
 
-import { FrameSequence, FrameSet, frameUrl, normalizeFrameSequence, phoneFrameSrcset } from './frames';
+import { FRAMES_PHONE_MAX_WIDTH, FrameSequence, FrameSet, frameUrl, normalizeFrameSequence, phoneFrameSrcset } from './frames';
 
 /**
  * VIDEO (CC3 — complex-components plan §7b, board 5). A LEAF type with two sources:
@@ -441,7 +441,13 @@ export function videoInnerHtml(plan: VideoPlan, options: VideoMarkupOptions): st
         const srcset = own ? phoneFrameSrcset(plan.frames!) : '';
         // Its real size, so where a Scene flows (reduced motion, no script) the picture holds its height before it loads.
         const size = own ? ` width="${plan.frames!.wide.width}" height="${plan.frames!.wide.height}"` : '';
-        return `<img class="${VideoClass.Poster}" src="${esc(plan.poster)}"${srcset ? ` srcset="${esc(srcset)}" sizes="100vw"` : ''}${size} alt="${esc(plan.title)}" decoding="async">`;
+        const image = (attrs: string): string => `<img class="${VideoClass.Poster}" src="${esc(plan.poster)}"${attrs} alt="${esc(plan.title)}" decoding="async">`;
+        // A phone film is framed for a tall screen, so it is chosen by the screen, never by the pixels a high-density phone asks for.
+        if (own && plan.frames!.phoneBase) {
+            const { width, height } = plan.frames!.phone!;
+            return `<picture><source media="(max-width: ${FRAMES_PHONE_MAX_WIDTH}px)" srcset="${esc(frameUrl(plan.frames!, FrameSet.Phone, 0))}" width="${width}" height="${height}">${image(size)}</picture>`;
+        }
+        return image(`${srcset ? ` srcset="${esc(srcset)}" sizes="100vw"` : ''}${size}`);
     }
     const poster = plan.poster ? `<img class="${VideoClass.Poster}" src="${esc(plan.poster)}" alt="" loading="lazy" decoding="async">` : '';
     const label = esc(videoPlayLabel(plan, words));

package/src/scene-core/scene.ts

@@ -1,5 +1,5 @@
 import { SceneRole } from '@vectoriox/iox-ui/composite-core';
-import { VideoAttribute, VideoClass } from '@vectoriox/iox-ui/media-core';
+import { FRAMES_PHONE_MAX_WIDTH, VideoAttribute, VideoClass } from '@vectoriox/iox-ui/media-core';
 
 /**
  * A Scene's data and maths (premium-sites plan §5b). A Scene is a recipe of ordinary nodes — a tall Section, a pinned
@@ -83,7 +83,7 @@ export enum SceneAttribute {
 }
 
 /** At or under this stage width a layer plays its phone tracks. The `mobile` breakpoint's width. */
-export const SCENE_PHONE_MAX_WIDTH = 767;
+export const SCENE_PHONE_MAX_WIDTH = FRAMES_PHONE_MAX_WIDTH;
 
 const DECIMALS = 10000;
 const round = (v: number): number => Math.round(v * DECIMALS) / DECIMALS;
@@ -150,8 +150,10 @@ export function revealClipPath(showing: number, from: SceneRevealFrom = SCENE_RE
     }
 }
 
-/** The two keys around `p` and how far between them it eases. */
-function span(keys: ReadonlyArray<SceneKey>, p: number): { a: SceneKey; b: SceneKey; f: number } {
+const linear = (t: number): number => t;
+
+/** The two keys around `p` and how far between them it has come. */
+function span(keys: ReadonlyArray<SceneKey>, p: number, ease: (t: number) => number = smoothstep): { a: SceneKey; b: SceneKey; f: number } {
     const at = clamp01(p);
     if (at <= keys[0][0]) return { a: keys[0], b: keys[0], f: 0 };
     for (let i = 1; i < keys.length; i++) {
@@ -159,7 +161,7 @@ function span(keys: ReadonlyArray<SceneKey>, p: number): { a: SceneKey; b: Scene
             const a = keys[i - 1];
             const b = keys[i];
             const width = b[0] - a[0];
-            return { a, b, f: width > 0 ? smoothstep((at - a[0]) / width) : 1 };
+            return { a, b, f: width > 0 ? ease((at - a[0]) / width) : 1 };
         }
     }
     const last = keys[keys.length - 1];
@@ -167,9 +169,9 @@ function span(keys: ReadonlyArray<SceneKey>, p: number): { a: SceneKey; b: Scene
 }
 
 /** A numeric track's value at progress `p`. */
-export function valueAt(keys: ReadonlyArray<SceneKey>, p: number): number {
+export function valueAt(keys: ReadonlyArray<SceneKey>, p: number, ease?: (t: number) => number): number {
     if (!keys.length) return 0;
-    const { a, b, f } = span(keys, p);
+    const { a, b, f } = span(keys, p, ease);
     const from = Number(a[1]);
     return round(from + (Number(b[1]) - from) * f);
 }
@@ -229,10 +231,13 @@ export function sceneWordsLit(tracks: ReadonlyArray<SceneTrack>, p: number): num
     return track ? clampPercent(valueAt(track.keys, p)) : null;
 }
 
-/** How far a layer's pictures have played at `p`, in %; null when it has no such track. */
+/**
+ * How far a layer's pictures have played at `p`, in %; null when it has no such track. A film runs straight between its
+ * keys, where everything else eases: eased over a 20-screen Scene it would crawl for its first screens and rush the middle.
+ */
 export function scenePlayed(tracks: ReadonlyArray<SceneTrack>, p: number): number | null {
     const track = tracks.find(t => t.prop === SceneProp.Play);
-    return track ? clampPercent(valueAt(track.keys, p)) : null;
+    return track ? clampPercent(valueAt(track.keys, p, linear)) : null;
 }
 
 /** Word `index` of `count`, with `lit` % lit: words light one after the other, each easing in as the last finishes. */
@@ -307,7 +312,7 @@ export const SCENE_FLOW_RULES = `.iox-role-scene{height:auto!important}`
     + `[${SceneAttribute.Tracks}]{transform:none!important;opacity:1!important;clip-path:none!important;pointer-events:auto!important}`
     // A Video the scroll plays stands as its poster, at the poster's own height: a percent of a stage that now flows is nothing.
     + `[${VideoAttribute.Frames}]{height:auto!important}`
-    + `[${VideoAttribute.Frames}]>.${VideoClass.Poster}{position:static!important;height:auto!important}`;
+    + `[${VideoAttribute.Frames}]>.${VideoClass.Poster},[${VideoAttribute.Frames}]>picture>.${VideoClass.Poster}{position:static!important;height:auto!important}`;
 
 /** Under reduced motion the driver never starts, so the same rules hold for the whole visit. */
 export const SCENE_REDUCED_MOTION_CSS = `@media (prefers-reduced-motion: reduce){${SCENE_FLOW_RULES}}`;

package/styles/iox-design.css

@@ -348,12 +348,17 @@ dialog[data-iox-dialog]:not([open]) {
   container-type: inline-size;
 }
 /* The poster blank (DS3): no poster yet = the token fill, never a request to the provider. */
+/* A Video the scroll plays, given a height: without its own width, a 16 / 9 ratio would work its width out from that height
+   and run off the stage. Zero specificity, so the node's own width wins. */
+:where(.iox-video[data-iox-video-frames]) { width: 100%; }
 .iox-video[data-iox-video-poster-empty]:not([data-iox-video-playing]) { background-color: var(--iox-surface-2); }
 .iox-video[data-iox-video-playing] { background-color: var(--iox-inverse-bg); }
-.iox-video > :is(.iox-video__poster, .iox-video__media, .iox-video__frame, .iox-video__frames) {
+.iox-video > picture { display: contents; }
+.iox-video > :is(.iox-video__poster, .iox-video__media, .iox-video__frame, .iox-video__frames),
+.iox-video > picture > .iox-video__poster {
   position: absolute; inset: 0; width: 100%; height: 100%; border: 0; margin: 0; display: block; object-fit: cover;
 }
-.iox-video > .iox-video__poster { z-index: -1; }
+.iox-video > .iox-video__poster, .iox-video > picture > .iox-video__poster { z-index: -1; }
 .iox-video > .iox-video__media { object-fit: contain; background-color: var(--iox-inverse-bg); }
 .iox-video[data-iox-video-mode='background'] > .iox-video__media { object-fit: cover; }
 .iox-video__play {