@design-edito/tools 0.5.2 → 0.5.3

package/components/UIModule/index.js

@@ -1,36 +1,33 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
 import { unknownToString } from '../../agnostic/errors/unknown-to-string/index.js';
 import { isNonNullObject } from '../../agnostic/objects/is-object/index.js';
 import { randomHash } from '../../agnostic/random/uuid/index.js';
-import { mergeClassNames } from '../utils/index.js';
+import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { uiModule as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
 /**
- * Dynamic UI module host component. Asynchronously imports an ES module by URL,
- * validates its exported interface, calls its `init` lifecycle to obtain a DOM
- * `Element`, and appends that element to its own root `<div>`. Handles loading,
- * error, and teardown states automatically.
+ * Dynamic UI module host. Asynchronously imports an ES module by URL, validates
+ * its exported interface, calls its `init` lifecycle to obtain a DOM `Element`,
+ * and appends that element to its own root `<div>`.
  *
  * The imported module is expected to conform to the {@link ModuleData} interface.
  * Any violation (missing exports, wrong types, `init` not returning an `Element`)
  * transitions the component into the `--error` state and logs to `console.error`.
  *
- * ### Root element modifiers
- * The root `<div>` receives the public class name defined by `uiModule` and
- * the following BEM-style modifier classes reflecting the current load lifecycle:
- * - `--loading` — the module fetch is in progress.
- * - `--no-module` — no module has been loaded yet (`src` is undefined or the
- * effect has not run).
- * - `--error` — the import, validation, or `init` call failed.
- * - `--loaded` — the module passed validation and `init` returned successfully.
- * - `--initialized` — the `Element` returned by `init` has been appended to the
- * host `<div>`.
+ * ### CSS modifiers
+ * Reflecting the current load lifecycle:
+ * - `loading` — the module fetch is in progress.
+ * - `no-module` — nothing has been loaded yet (`src` is undefined, or the
+ *   effect has not run).
+ * - `error` — the import, the validation, or the `init` call failed.
+ * - `loaded` — the module passed validation and `init` returned successfully.
+ * - `initialized` — the `Element` returned by `init` has been appended.
  *
  * ### Root element attributes
- * - `id` — a stable randomly generated ID (prefixed `f`) assigned once on mount.
- * Used to scope the module's `css` entries to this specific instance.
+ * - `id` — a stable generated id, assigned once on mount and used to scope the
+ * module's `css` entries to this specific instance.
  *
  * @param props - Component properties.
  * @see {@link Props}
@@ -38,107 +35,81 @@ import cssModule from './styles.module.css';
  * @returns A host `<div>` into which the module's root `Element` is appended,
  * along with any `<style>` blocks exported by the module.
  */
-export const UIModule = ({ src, props, stateHandlers, className }) => {
+export const UIModule = ({ src, props, onIdGenerated, onIsLoadingChanged, onLoadedModuleChanged, onModuleTargetChanged, className }) => {
     // State & refs
-    const [id] = useState(`f${randomHash(10)}`);
-    const [loading, setLoading] = useState(false);
-    const [loadedModule, _setLoadedModule] = useState(null);
-    const [moduleTarget, _setModuleTarget] = useState(null);
+    const [id] = useState(() => `f${randomHash(10)}`);
+    const [isLoading, setIsLoading] = useState(false);
+    const [loadedModule, setLoadedModule] = useState(null);
+    const [moduleTarget, setModuleTarget] = useState(null);
     const rootRef = useRef(null);
-    const loadedModuleRef = useRef(null);
-    const moduleTargetRef = useRef(null);
-    const setLoadedModule = (data) => {
-        loadedModuleRef.current = data;
-        _setLoadedModule(data);
-    };
-    const setModuleTarget = (data) => {
-        moduleTargetRef.current = data;
-        _setModuleTarget(data);
-    };
-    // State changes dispatch
-    useEffect(() => { stateHandlers?.idChanged?.(id); }, [id, stateHandlers]);
-    useEffect(() => { stateHandlers?.isLoadingChanged?.(loading); }, [loading, stateHandlers]);
-    useEffect(() => { stateHandlers?.loadedModuleChanged?.(loadedModule); }, [loadedModule, stateHandlers]);
-    useEffect(() => { stateHandlers?.moduleTargetChanged?.(moduleTarget); }, [moduleTarget, stateHandlers]);
-    // Fx dep. `src` - load & init module effect
+    // What the teardown needs, held outside state so the load effect can depend on
+    // `src` alone and still destroy whatever is actually live at cleanup time.
+    const liveInstanceRef = useRef(null);
+    // State dispatch
+    useChangeDispatch(isLoading, onIsLoadingChanged);
+    useChangeDispatch(loadedModule, onLoadedModuleChanged);
+    useChangeDispatch(moduleTarget, onModuleTargetChanged);
+    // Fx. no dep. - report the generated id, which never changes afterwards
+    useEffect(() => { onIdGenerated?.(id); }, []);
+    // Fx. dep. `src` - import, validate and initialize the module
     useEffect(() => {
         if (src === undefined)
             return;
-        try {
-            setLoading(true);
-            import(src)
-                .then(data => {
-                setLoading(false);
-                const errs = {
-                    notMod: new Error('Not a module'),
-                    initFunc: new Error('Module exported member `init` must be a function'),
-                    destroyFunc: new Error('Module exported member `destroy` must be a function'),
-                    cssStrArr: new Error('Module exported member `css` must be an array of strings'),
-                    updFunc: new Error('Module exported member `update` must be a function'),
-                    initRetElt: new Error('Module exported function `init` must return an Element'),
-                    initRetFirstElt: new Error('Module exported function `init` must return an array containing an Element in its first position')
-                };
-                if (!isNonNullObject(data))
-                    return setLoadedModule(errs.notMod);
-                if (!('init' in data))
-                    return setLoadedModule(errs.initFunc);
-                if (typeof data.init !== 'function')
-                    return setLoadedModule(errs.initFunc);
-                if (!('destroy' in data) || typeof data.destroy !== 'function')
-                    return setLoadedModule(errs.destroyFunc);
-                if ('css' in data) {
-                    if (!Array.isArray(data.css))
-                        return setLoadedModule(errs.cssStrArr);
-                    if (data.css.some(i => typeof i !== 'string'))
-                        return setLoadedModule(errs.cssStrArr);
-                }
-                if ('update' in data && typeof data.update !== 'function')
-                    return setLoadedModule(errs.updFunc);
-                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- shape fully validated by the checks above
-                const module = data;
-                setLoadedModule(module);
-                try {
-                    const target = module.init(props ?? {});
-                    if (!(target instanceof Element))
-                        return setLoadedModule(errs.initRetElt);
-                    setModuleTarget(target);
-                }
-                catch (err) {
-                    setModuleTarget(null);
-                    const e = err instanceof Error
-                        ? err
-                        : new Error(unknownToString(err));
-                    setLoadedModule(e);
-                }
-            }).catch((err) => {
-                setLoading(false);
-                setLoadedModule(err instanceof Error ? err : new Error(unknownToString(err)));
+        setIsLoading(true);
+        void import(src)
+            .then(data => {
+            setIsLoading(false);
+            if (!isNonNullObject(data))
+                return setLoadedModule(new Error('Not a module'));
+            if (!('init' in data) || typeof data.init !== 'function')
+                return setLoadedModule(new Error('Module exported member `init` must be a function'));
+            if (!('destroy' in data) || typeof data.destroy !== 'function')
+                return setLoadedModule(new Error('Module exported member `destroy` must be a function'));
+            if ('css' in data) {
+                if (!Array.isArray(data.css))
+                    return setLoadedModule(new Error('Module exported member `css` must be an array of strings'));
+                if (data.css.some(entry => typeof entry !== 'string'))
+                    return setLoadedModule(new Error('Module exported member `css` must be an array of strings'));
+            }
+            if ('update' in data && typeof data.update !== 'function')
+                return setLoadedModule(new Error('Module exported member `update` must be a function'));
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- shape fully validated by the checks above
+            const module = data;
+            setLoadedModule(module);
+            try {
+                const target = module.init(props ?? {});
+                if (!(target instanceof Element))
+                    return setLoadedModule(new Error('Module exported function `init` must return an Element'));
+                liveInstanceRef.current = { module, target };
+                setModuleTarget(target);
+            }
+            catch (err) {
+                liveInstanceRef.current = null;
                 setModuleTarget(null);
-            });
-        }
-        catch (err) {
-            if (err instanceof Error)
-                return setLoadedModule(err);
-            const errStr = unknownToString(err);
-            return setLoadedModule(new Error(errStr));
-        }
+                setLoadedModule(err instanceof Error ? err : new Error(unknownToString(err)));
+            }
+        })
+            .catch((err) => {
+            setIsLoading(false);
+            liveInstanceRef.current = null;
+            setLoadedModule(err instanceof Error ? err : new Error(unknownToString(err)));
+            setModuleTarget(null);
+        });
         return () => {
-            if (moduleTargetRef.current === null)
-                return;
-            if (loadedModuleRef.current instanceof Error)
-                return;
-            if (loadedModuleRef.current === null)
+            const liveInstance = liveInstanceRef.current;
+            if (liveInstance === null)
                 return;
-            loadedModuleRef.current.destroy(moduleTargetRef.current);
+            liveInstance.module.destroy(liveInstance.target);
+            liveInstanceRef.current = null;
         };
     }, [src]);
-    // Fx dep. `loadedModule` - log load errors
+    // Fx. dep. `loadedModule` - surface load errors
     useEffect(() => {
         // eslint-disable-next-line no-console
         if (loadedModule instanceof Error)
             console.error(loadedModule);
     }, [loadedModule]);
-    // Fx dep. `moduleTarget` - append the rendered module
+    // Fx. dep. `moduleTarget` - append the element the module built
     useEffect(() => {
         if (moduleTarget === null)
             return;
@@ -148,14 +119,14 @@ export const UIModule = ({ src, props, stateHandlers, className }) => {
     }, [moduleTarget]);
     // Rendering
     const c = clss(publicClassName, { cssModule });
+    const hasErrored = loadedModule instanceof Error;
     const rootClss = mergeClassNames(c(null, {
-        loading,
+        'loading': isLoading,
         'no-module': loadedModule === null,
-        'error': loadedModule instanceof Error,
-        'loaded': !loading && loadedModule !== null && !(loadedModule instanceof Error),
+        'error': hasErrored,
+        'loaded': !isLoading && loadedModule !== null && !hasErrored,
         'initialized': moduleTarget !== null
     }), className);
-    return _jsxs("div", { className: rootClss, ref: rootRef, id: id, children: [loadedModule === null && '', loadedModule !== null
-                && !(loadedModule instanceof Error)
-                && loadedModule.css?.map(css => _jsx("style", { children: `.${publicClassName}#${id} { ${css} }` }))] });
+    const moduleCss = hasErrored || loadedModule === null ? [] : loadedModule.css ?? [];
+    return _jsx("div", { className: rootClss, ref: rootRef, id: id, children: moduleCss.map((css, cssPos) => _jsx("style", { children: `.${publicClassName}#${id} { ${css} }` }, cssPos)) });
 };

package/components/Video/index.controlled.d.ts

@@ -1,4 +1,4 @@
-import { type FunctionComponent, type PropsWithChildren, type VideoHTMLAttributes, type ReactEventHandler } from 'react';
+import { type FunctionComponent, type PropsWithChildren, type VideoHTMLAttributes } from 'react';
 import type { WithClassName } from '../utils/types.js';
 import { type Props as SubsProps } from '../Subtitles/index.js';
 /**
@@ -27,47 +27,6 @@ type TrackData = {
     label?: string;
     default?: boolean;
 };
-/**
- * Callbacks for user actions on the video player controls.
- * Allows you to intercept user actions on the player's buttons and sliders.
- *
- * @property playButtonClick - Called when the play button is clicked. Receives the event, isPlaying state and HTMLVideoElement before any change happens. If the time is not controlled by parent (no currentTime given as props), the component will play to the target time right after.
- * @property pauseButtonClick - Called when the pause button is clicked. Receives the event, isPlaying state and HTMLVideoElement before any change happens. If the time is not controlled by parent (no currentTime given as props), the component will pause to the target time right after.
- * @property loudButtonClick - Called when the "loud" (unmute) button is clicked. Receives the event, isLoud state and HTMLVideoElement before any change happens.
- * @property muteButtonClick - Called when the mute button is clicked. Receives the event, isLoud state and HTMLVideoElement before any change happens.
- * @property volumeRangeChange - Called when the volume slider is changed. Receives the event, target volume (0 to 1), current volume (0 to 1) and HTMLVideoElement before any change happens.
- * @property fullscreenButtonClick - Called when the fullscreen button is clicked. Receives the event, isFullscreen state and HTMLVideoElement before any change happens.
- * @property rateRangeChange - Called when the playback rate slider is changed. Receives the event, target rate, current rate and HTMLVideoElement before any change happens.
- * @property timelineClick - Called when the timeline is clicked. Receives the event, target time (in seconds), current time (in seconds) and HTMLVideoElement before any change happens. If the time is not controlled by parent (no currentTime given as props), the component will update the video current time to the target time right after.
- */
-export type ActionHandlersProps = {
-    playButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isPlaying: boolean, video: HTMLVideoElement | null) => void;
-    pauseButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isPlaying: boolean, video: HTMLVideoElement | null) => void;
-    loudButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isLoud: boolean, video: HTMLVideoElement | null) => void;
-    muteButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isLoud: boolean, video: HTMLVideoElement | null) => void;
-    volumeRangeChange?: (e: React.ChangeEvent<HTMLInputElement>, targetVolumePercent: number, currentVolumePercent: number, video: HTMLVideoElement | null) => void;
-    fullscreenButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isFullscreen: boolean, video: HTMLVideoElement | null) => void;
-    rateRangeChange?: (e: React.ChangeEvent<HTMLInputElement>, targetRate: number, rate: number, video: HTMLVideoElement | null) => void;
-    timelineClick?: (e: React.MouseEvent<HTMLDivElement>, time: number, currentTime: number, video: HTMLVideoElement | null) => void;
-};
-/**
- * Callbacks to synchronize the internal player state with the outside.
- *
- * @property isPlaying - Called whenever the play/pause state changes.
- * @property isFullscreen - Called whenever the fullscreen state changes.
- * @property isLoud - Called whenever the mute/unmute state changes (true = unmuted, false = muted).
- * @property volume - Called whenever the volume changes (value between 0 and 1).
- * @property playbackRate - Called whenever the playback speed changes.
- * @property currentTime - Called on every change of the current time (in seconds).
- */
-export type StateHandlersProps = {
-    isPlaying?: (isPlaying: boolean) => void;
-    isFullscreen?: (isFullscreen: boolean) => void;
-    isLoud?: (isLoud: boolean) => void;
-    volume?: (volume: number) => void;
-    playbackRate?: (rate: number) => void;
-    currentTime?: (currentTime: number) => void;
-};
 /**
  * Props for the ControlledVideo component.
  *
@@ -84,11 +43,41 @@ export type StateHandlersProps = {
  * @property volume - External control of volume (0 to 1).
  * @property mute - External control of mute (true = muted).
  * @property playbackRate - External control of playback speed.
- * @property currentTimeMs - External control of current time (in ms). If given, the component considers the current time to be controlled by the parent, and will not attempt to update it internally on user interactions (play, timeline click, etc.), leaving it up to the parent to update this prop accordingly.
- * @property actionHandlers - Callbacks for user actions on the controls.
- * @property stateHandlers - Callbacks to synchronize internal state with the outside.
- * @property onFullscreenChange - Callback for native fullscreen mode changes.
- * @property _modifiers - Optional CSS modifiers for the root element.
+ * @property currentTimeMs - External control of current time (in ms). Providing
+ * it hands ownership of the time to the parent: the value is displayed as given,
+ * the element is seeked to it on every change, and user interactions that would
+ * otherwise move the time (timeline click) no longer do — the parent is expected
+ * to update the prop instead. Because a playing element advances the time by
+ * itself, a controlled time also implies a stopped video: `play` and `autoPlay`
+ * are ignored for as long as this prop is provided.
+ * @property onPlayButtonClicked - Called when the play button is clicked, before
+ * the component reacts, with the playback state as it was.
+ * @property onPauseButtonClicked - Called when the pause button is clicked, before
+ * the component reacts, with the playback state as it was.
+ * @property onLoudButtonClicked - Called when the unmute button is clicked, before
+ * the component reacts, with the mute state as it was (`true` = unmuted).
+ * @property onMuteButtonClicked - Called when the mute button is clicked, before
+ * the component reacts, with the mute state as it was (`true` = unmuted).
+ * @property onVolumeRangeChanged - Called when the volume slider moves, before the
+ * component reacts, with the target and current volumes (both `0` to `1`).
+ * @property onRateRangeChanged - Called when the playback rate slider moves, before
+ * the component reacts, with the target and current rates.
+ * @property onFullscreenButtonClicked - Called when the fullscreen button is
+ * clicked, before the component reacts, with the fullscreen state as it was.
+ * @property onTimelineClicked - Called when the timeline is clicked, before the
+ * component reacts, with the target and current times (in seconds). The component
+ * seeks to the target right after, unless the time is controlled.
+ * @property onIsPlayingChanged - Called once the playback state has changed.
+ * @property onIsFullscreenChanged - Called once the fullscreen state has changed.
+ * @property onIsLoudChanged - Called once the mute state has changed (`true` = unmuted).
+ * @property onVolumeChanged - Called once the volume has changed (`0` to `1`).
+ * @property onPlaybackRateChanged - Called once the playback rate has changed.
+ * @property onCurrentTimeMsChanged - Called once the current time has changed, in
+ * milliseconds, to match the `currentTimeMs` prop.
+ * @property onFullscreenChange - Called when the *browser* enters or leaves
+ * fullscreen on its own — pressing Escape, typically — with the new state. This is
+ * the signal a parent needs to update its `fullscreen` prop, and it is distinct
+ * from `onIsFullscreenChanged`, which merely echoes that prop back once changed.
  * @property className - Additional CSS class for the root element.
  * @property children - React content inserted into the <video> tag (fallback, etc).
  *
@@ -109,10 +98,21 @@ export type Props = PropsWithChildren<WithClassName<{
     mute?: boolean;
     playbackRate?: number;
     currentTimeMs?: number;
-    onFullscreenChange?: ReactEventHandler<HTMLVideoElement>;
-    actionHandlers?: ActionHandlersProps;
-    stateHandlers?: StateHandlersProps;
-    _modifiers?: Record<string, boolean>;
+    onPlayButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isPlaying: boolean, video: HTMLVideoElement | null) => void;
+    onPauseButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isPlaying: boolean, video: HTMLVideoElement | null) => void;
+    onLoudButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isLoud: boolean, video: HTMLVideoElement | null) => void;
+    onMuteButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isLoud: boolean, video: HTMLVideoElement | null) => void;
+    onVolumeRangeChanged?: (e: React.ChangeEvent<HTMLInputElement>, targetVolume: number, currentVolume: number, video: HTMLVideoElement | null) => void;
+    onRateRangeChanged?: (e: React.ChangeEvent<HTMLInputElement>, targetRate: number, currentRate: number, video: HTMLVideoElement | null) => void;
+    onFullscreenButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isFullscreen: boolean, video: HTMLVideoElement | null) => void;
+    onTimelineClicked?: (e: React.MouseEvent<HTMLDivElement>, targetTime: number, currentTime: number, video: HTMLVideoElement | null) => void;
+    onIsPlayingChanged?: (isPlaying: boolean) => void;
+    onIsFullscreenChanged?: (isFullscreen: boolean) => void;
+    onIsLoudChanged?: (isLoud: boolean) => void;
+    onVolumeChanged?: (volume: number) => void;
+    onPlaybackRateChanged?: (playbackRate: number) => void;
+    onCurrentTimeMsChanged?: (currentTimeMs: number) => void;
+    onFullscreenChange?: (isFullscreen: boolean) => void;
 }> & VideoHTMLAttributes<HTMLVideoElement>>;
 /**
  * Full-featured video player component. Wraps a native `<video>` element with

package/components/Video/index.controlled.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useRef, useState, useCallback, useEffect } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
-import { mergeClassNames } from '../utils/index.js';
+import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import cssModule from './styles.module.css';
 import { video as publicClassName } from '../public-classnames.js';
 import { Subtitles } from '../Subtitles/index.js';
@@ -41,79 +41,79 @@ import { forceExitFullscreen, forceFullscreen, forceLoud, forceMute, forcePause,
  * @returns A `<figure>` element containing the video, its controls, optional
  * subtitles.
  */
-export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pauseBtnContent, loudBtnContent, muteBtnContent, fullscreenBtnContent, play, fullscreen, mute, muted, volume = 1, playbackRate = 1, currentTimeMs: givenCurrentTimeMs, actionHandlers, stateHandlers, children, className, _modifiers, ...intrinsicVideoAttributes }) => {
+export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pauseBtnContent, loudBtnContent, muteBtnContent, fullscreenBtnContent, play, fullscreen, mute, muted, volume = 1, playbackRate = 1, currentTimeMs: givenCurrentTimeMs, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onTimelineClicked, onIsPlayingChanged, onIsFullscreenChanged, onIsLoudChanged, onVolumeChanged, onPlaybackRateChanged, onCurrentTimeMsChanged, onFullscreenChange, children, className, ...intrinsicVideoAttributes }) => {
     const videoRef = useRef(null);
     const [totalTime, setTotalTime] = useState(0);
     const totalTimeMs = useMemo(() => secondsToMs(totalTime), [totalTime]);
-    const [currentTimeMs, setCurrentTimeMs] = useState(0);
+    const [internalCurrentTimeMs, setInternalCurrentTimeMs] = useState(0);
+    const isTimeControlled = givenCurrentTimeMs !== undefined;
+    // The parent owns the time as soon as it provides one, so that is what gets
+    // displayed — not what the element reported one render later.
+    const currentTimeMs = givenCurrentTimeMs ?? internalCurrentTimeMs;
     const currentTime = useMemo(() => msToSeconds(currentTimeMs), [currentTimeMs]);
-    const isTimeControlled = useMemo(() => givenCurrentTimeMs !== undefined, [givenCurrentTimeMs]);
     const volumePercent = useMemo(() => volume * 100, [volume]);
+    // Every state item this component displays is read from its props, never from
+    // the element: it is the parent's job to keep them in sync.
+    const isPlaying = play ?? false;
+    const isLoud = !(mute ?? false);
+    const isFullscreen = fullscreen ?? false;
     // Intrinsic event handler
     const handleMetadataLoadEvent = useCallback((e) => {
         if (videoRef.current === null)
             return;
         const video = videoRef.current;
         setTotalTime(video.duration);
+        // A seek asked for before the metadata landed was silently dropped by the
+        // element — replay it now that it can be honoured.
+        if (givenCurrentTimeMs !== undefined)
+            video.currentTime = msToSeconds(givenCurrentTimeMs);
         intrinsicVideoAttributes.onLoadedMetadata?.(e);
-    }, [intrinsicVideoAttributes.onLoadedMetadata]);
+    }, [intrinsicVideoAttributes.onLoadedMetadata, givenCurrentTimeMs]);
     const handleOnTimeUpdateEvent = useCallback((e) => {
         const video = e.currentTarget;
         const newTimeMs = secondsToMs(video.currentTime);
-        setCurrentTimeMs(newTimeMs);
+        setInternalCurrentTimeMs(newTimeMs);
         if (intrinsicVideoAttributes.onTimeUpdate !== undefined)
             intrinsicVideoAttributes.onTimeUpdate(e);
     }, [intrinsicVideoAttributes.onTimeUpdate]);
-    const handleOnPlayEvent = useCallback((e) => {
-        /* We must never play a video that has controlled time */
-        if (isTimeControlled) {
-            videoRef.current?.pause();
-            return;
-        }
-        intrinsicVideoAttributes.onPlay?.(e);
-    }, [isTimeControlled, intrinsicVideoAttributes.onPlay]);
     // Custom action handlers
     const handlePlayButtonClick = useCallback((e) => {
-        const isPlaying = videoRef.current !== null ? videoRef.current.paused : false;
-        actionHandlers?.playButtonClick?.(e, isPlaying, videoRef.current);
-    }, [actionHandlers?.playButtonClick]);
+        const wasPlaying = videoRef.current?.paused === false;
+        onPlayButtonClicked?.(e, wasPlaying, videoRef.current);
+    }, [onPlayButtonClicked]);
     const handlePauseButtonClick = useCallback((e) => {
-        const isPlaying = videoRef.current !== null ? videoRef.current.paused : false;
-        actionHandlers?.pauseButtonClick?.(e, isPlaying, videoRef.current);
-    }, [actionHandlers?.pauseButtonClick]);
+        const wasPlaying = videoRef.current?.paused === false;
+        onPauseButtonClicked?.(e, wasPlaying, videoRef.current);
+    }, [onPauseButtonClicked]);
     const handleLoudButtonClick = useCallback((e) => {
-        const isLoud = mute !== undefined ? !mute : false;
-        actionHandlers?.loudButtonClick?.(e, isLoud, videoRef.current);
-    }, [actionHandlers?.loudButtonClick, mute]);
+        onLoudButtonClicked?.(e, isLoud, videoRef.current);
+    }, [onLoudButtonClicked, isLoud]);
     const handleMuteButtonClick = useCallback((e) => {
-        const isLoud = mute !== undefined ? !mute : false;
-        actionHandlers?.muteButtonClick?.(e, isLoud, videoRef.current);
-    }, [actionHandlers?.muteButtonClick, mute]);
+        onMuteButtonClicked?.(e, isLoud, videoRef.current);
+    }, [onMuteButtonClicked, isLoud]);
     const handleFullscreenButtonClick = useCallback((e) => {
-        actionHandlers?.fullscreenButtonClick?.(e, fullscreen ?? false, videoRef.current);
-    }, [actionHandlers?.fullscreenButtonClick, fullscreen]);
+        onFullscreenButtonClicked?.(e, isFullscreen, videoRef.current);
+    }, [onFullscreenButtonClicked, isFullscreen]);
     const handleVolumeRangeChange = useCallback((e) => {
         const targetVolume = Number(e.currentTarget.value) / 100;
-        actionHandlers?.volumeRangeChange?.(e, targetVolume, volume, videoRef.current);
-    }, [actionHandlers?.volumeRangeChange, volume]);
+        onVolumeRangeChanged?.(e, targetVolume, volume, videoRef.current);
+    }, [onVolumeRangeChanged, volume]);
     const handleRateRangeChange = useCallback((e) => {
-        actionHandlers?.rateRangeChange?.(e, Number(e.currentTarget.value), playbackRate, videoRef.current);
-    }, [actionHandlers?.rateRangeChange, playbackRate]);
+        onRateRangeChanged?.(e, Number(e.currentTarget.value), playbackRate, videoRef.current);
+    }, [onRateRangeChanged, playbackRate]);
     const handleTimelineClick = useCallback((e) => {
         if (videoRef.current === null)
             return;
-        const progress = getTimelineClickProgress(e, e.currentTarget, videoRef.current);
+        const progress = getTimelineClickProgress(e);
         const targetTime = progress * totalTime;
-        actionHandlers?.timelineClick?.(e, targetTime, currentTime, videoRef.current);
-        /* If we are given a currentTimeMs prop, we consider that the current time is controlled by the parent component, and we should not attempt to set it here on timeline click, as it would create conflicts. The parent comp should update the currentTimeMs prop itself */
+        onTimelineClicked?.(e, targetTime, currentTime, videoRef.current);
+        // A controlled time is the parent's to move: it is expected to update the
+        // prop in response to this very handler.
         if (!isTimeControlled) {
             videoRef.current.currentTime = targetTime;
         }
-    }, [actionHandlers?.timelineClick, totalTime, currentTime, isTimeControlled]);
+    }, [onTimelineClicked, totalTime, currentTime, isTimeControlled]);
     // Rendering
-    const isPlaying = play ?? false;
-    const isLoud = mute ?? false;
-    const isFullscreen = fullscreen ?? false;
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(null, {
         'play-on': isPlaying,
@@ -121,10 +121,11 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
         'fullscreen-on': isFullscreen,
         'fullscreen-off': !isFullscreen,
         'loud': isLoud,
-        'muted': !isLoud,
-        ..._modifiers
+        'muted': !isLoud
     }), className);
-    const appliedVolume = volume;
+    // Guarded: the duration is unknown until the metadata lands, and an unguarded
+    // division would expose the string 'NaN' on every render until then.
+    const currentTimeRatio = totalTime > 0 ? currentTime / totalTime : 0;
     const rootAttributes = {
         'data-play-on': isPlaying ? '' : undefined,
         'data-play-off': !isPlaying ? '' : undefined,
@@ -132,15 +133,15 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
         'data-fullscreen-off': !isFullscreen ? '' : undefined,
         'data-loud': isLoud ? '' : undefined,
         'data-muted': !isLoud ? '' : undefined,
-        'data-volume': appliedVolume.toFixed(8),
+        'data-volume': volume.toFixed(8),
         'data-volume-percent': volumePercent,
         'data-playback-rate': playbackRate,
         'data-current-time-ms': currentTimeMs.toFixed(2),
-        'data-current-time-ratio': (currentTime / totalTime).toFixed(8),
+        'data-current-time-ratio': currentTimeRatio.toFixed(8),
         'data-total-time-ms': totalTimeMs
     };
     const rootStyles = {
-        [`--${publicClassName}-current-time-ratio`]: (currentTime / totalTime).toFixed(8)
+        [`--${publicClassName}-current-time-ratio`]: currentTimeRatio.toFixed(8)
     };
     const parsedSources = useMemo(() => {
         if (sources === undefined)
@@ -201,8 +202,13 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
         };
     }, [fullscreen]);
     useEffect(() => {
-        if (isTimeControlled)
+        // A controlled time belongs to the parent, and a playing element advances
+        // the time on its own — so the two cannot coexist. Applied once, on entering
+        // the mode, rather than fought on every tick.
+        if (isTimeControlled) {
+            void forcePause(videoRef.current);
             return;
+        }
         if (play === true) {
             void forcePlay(videoRef.current);
         }
@@ -214,10 +220,9 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
         forceVolume(videoRef.current, volume);
     }, [volume]);
     useEffect(() => {
-        if (givenCurrentTimeMs !== undefined && videoRef.current !== null) {
-            void forcePause(videoRef.current);
-            videoRef.current.currentTime = msToSeconds(givenCurrentTimeMs);
-        }
+        if (givenCurrentTimeMs === undefined || videoRef.current === null)
+            return;
+        videoRef.current.currentTime = msToSeconds(givenCurrentTimeMs);
     }, [givenCurrentTimeMs]);
     useEffect(() => {
         if (mute === true) {
@@ -227,30 +232,28 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
             forceLoud(videoRef.current);
         }
     }, [mute]);
-    // State handlers
-    useEffect(() => {
-        if (stateHandlers?.currentTime !== undefined) {
-            stateHandlers.currentTime(msToSeconds(currentTimeMs));
-        }
-    }, [currentTimeMs, stateHandlers?.currentTime]);
-    useEffect(() => {
-        stateHandlers?.isPlaying?.(isPlaying);
-    }, [isPlaying, stateHandlers?.isPlaying]);
-    useEffect(() => {
-        stateHandlers?.isFullscreen?.(isFullscreen);
-    }, [isFullscreen, stateHandlers?.isFullscreen]);
+    // The browser can leave fullscreen without going through our button — Escape,
+    // or the platform's own exit gesture. Nothing in React reports it, so the real
+    // event is the only way for a parent to keep its `fullscreen` prop truthful.
     useEffect(() => {
-        stateHandlers?.isLoud?.(isLoud);
-    }, [isLoud, stateHandlers?.isLoud]);
-    useEffect(() => {
-        stateHandlers?.volume?.(volume);
-    }, [volume, stateHandlers?.volume]);
-    useEffect(() => {
-        stateHandlers?.playbackRate?.(playbackRate);
-    }, [playbackRate, stateHandlers?.playbackRate]);
-    return _jsxs("figure", { className: rootClss, style: rootStyles, ...rootAttributes, children: [_jsxs("video", { ref: videoRef, className: videoClss, ...intrinsicVideoAttributes, onLoadedMetadata: handleMetadataLoadEvent, onPlay: handleOnPlayEvent, onTimeUpdate: handleOnTimeUpdateEvent, children: [parsedSources.map((source, index) => typeof source === 'string'
+        if (onFullscreenChange === undefined)
+            return;
+        const onDocumentFullscreenChange = () => {
+            onFullscreenChange(document.fullscreenElement !== null);
+        };
+        document.addEventListener('fullscreenchange', onDocumentFullscreenChange);
+        return () => { document.removeEventListener('fullscreenchange', onDocumentFullscreenChange); };
+    }, [onFullscreenChange]);
+    // State handlers
+    useChangeDispatch(currentTimeMs, onCurrentTimeMsChanged);
+    useChangeDispatch(isPlaying, onIsPlayingChanged);
+    useChangeDispatch(isFullscreen, onIsFullscreenChanged);
+    useChangeDispatch(isLoud, onIsLoudChanged);
+    useChangeDispatch(volume, onVolumeChanged);
+    useChangeDispatch(playbackRate, onPlaybackRateChanged);
+    return _jsxs("figure", { className: rootClss, style: rootStyles, ...rootAttributes, children: [_jsxs("video", { ref: videoRef, className: videoClss, ...intrinsicVideoAttributes, autoPlay: isTimeControlled ? false : intrinsicVideoAttributes.autoPlay, onLoadedMetadata: handleMetadataLoadEvent, onTimeUpdate: handleOnTimeUpdateEvent, children: [parsedSources.map((source, index) => typeof source === 'string'
                         ? _jsx("source", { src: source }, index)
                         : _jsx("source", { src: source.src, type: source.type }, index)), parsedTracks.map((track, index) => typeof track === 'string'
                         ? _jsx("track", { src: track }, index)
-                        : _jsx("track", { src: track.src, kind: track.kind, srcLang: track.srclang, label: track.label, default: track.default }, index)), children] }), _jsxs("div", { className: videoControlsClss, children: [_jsx("button", { className: playBtnClss, onClick: handlePlayButtonClick, children: playBtnContent }), _jsx("button", { className: pauseBtnClss, onClick: handlePauseButtonClick, children: pauseBtnContent }), _jsx("button", { className: loudBtnClss, onClick: handleLoudButtonClick, children: loudBtnContent }), _jsx("button", { className: muteBtnClss, onClick: handleMuteButtonClick, children: muteBtnContent }), _jsx("input", { type: "range", className: volumeRangeClss, value: volumePercent, onChange: handleVolumeRangeChange, min: 0, max: 100, step: 1 }), _jsx("span", { className: volumePcntClss, children: Math.round(volumePercent) }), _jsx("button", { className: fullscreenBtnClss, onClick: handleFullscreenButtonClick, children: fullscreenBtnContent }), _jsx("input", { type: "range", className: playbackRateRangeClss, value: playbackRate, onChange: handleRateRangeChange, min: 0.25, max: 4, step: 0.25 }), _jsx("span", { className: playbackRateClss, children: playbackRate })] }), _jsxs("div", { className: timeControlsClss, children: [_jsx("span", { className: currentTimeClss, children: formatTime(currentTimeMs, 'mm:ss:ms') }), _jsx("span", { className: totalTimeClss, children: formatTime(totalTimeMs, 'mm:ss:ms') }), _jsx("div", { className: timelineClss, onClick: handleTimelineClick })] }), subtitles !== undefined && _jsx(Subtitles, { ...subtitles, timecodeMs: currentTimeMs })] });
+                        : _jsx("track", { src: track.src, kind: track.kind, srcLang: track.srclang, label: track.label, default: track.default }, index)), children] }), _jsxs("div", { className: videoControlsClss, children: [_jsx("button", { className: playBtnClss, onClick: handlePlayButtonClick, children: playBtnContent }), _jsx("button", { className: pauseBtnClss, onClick: handlePauseButtonClick, children: pauseBtnContent }), _jsx("button", { className: loudBtnClss, onClick: handleLoudButtonClick, children: loudBtnContent }), _jsx("button", { className: muteBtnClss, onClick: handleMuteButtonClick, children: muteBtnContent }), _jsx("input", { type: 'range', className: volumeRangeClss, value: volumePercent, onChange: handleVolumeRangeChange, min: 0, max: 100, step: 1 }), _jsx("span", { className: volumePcntClss, children: Math.round(volumePercent) }), _jsx("button", { className: fullscreenBtnClss, onClick: handleFullscreenButtonClick, children: fullscreenBtnContent }), _jsx("input", { type: 'range', className: playbackRateRangeClss, value: playbackRate, onChange: handleRateRangeChange, min: 0.25, max: 4, step: 0.25 }), _jsx("span", { className: playbackRateClss, children: playbackRate })] }), _jsxs("div", { className: timeControlsClss, children: [_jsx("span", { className: currentTimeClss, children: formatTime(currentTimeMs, 'mm:ss:ms') }), _jsx("span", { className: totalTimeClss, children: formatTime(totalTimeMs, 'mm:ss:ms') }), _jsx("div", { className: timelineClss, onClick: handleTimelineClick })] }), subtitles !== undefined && _jsx(Subtitles, { ...subtitles, timecodeMs: currentTimeMs })] });
 };