@vectoriox/iox-ui 5.76.1 → 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. */
@@ -109,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;
@@ -471,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, 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 { 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.1",
+  "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. */
@@ -206,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 {
@@ -229,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`. */

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;