@flamingo-stack/openframe-frontend-core 0.0.731 → 0.0.732

package/dist/hooks/index.cjs

@@ -60,7 +60,7 @@
 
 
 
-var _chunkBFHLGEJKcjs = require('../chunk-BFHLGEJK.cjs');
+var _chunkSJRR745Gcjs = require('../chunk-SJRR745G.cjs');
 
 
 
@@ -77,7 +77,7 @@ var _chunkA6P6DHEZcjs = require('../chunk-A6P6DHEZ.cjs');
 require('../chunk-MZ4KBSH7.cjs');
 
 
-var _chunkYJFN2W7Acjs = require('../chunk-YJFN2W7A.cjs');
+var _chunkRIXGLS5Ycjs = require('../chunk-RIXGLS5Y.cjs');
 
 
 
@@ -88,8 +88,8 @@ var _chunkYJFN2W7Acjs = require('../chunk-YJFN2W7A.cjs');
 
 
 
-var _chunkYUXRIR45cjs = require('../chunk-YUXRIR45.cjs');
-require('../chunk-2WXLQ5R5.cjs');
+var _chunkCC3LINHFcjs = require('../chunk-CC3LINHF.cjs');
+require('../chunk-HELVKMRG.cjs');
 require('../chunk-JKX2C3I2.cjs');
 require('../chunk-7DNL734S.cjs');
 require('../chunk-WWUSFOJ7.cjs');
@@ -105,7 +105,7 @@ var _chunkEAY6ZUEScjs = require('../chunk-EAY6ZUES.cjs');
 
 
 
-var _chunkLCTDHLDLcjs = require('../chunk-LCTDHLDL.cjs');
+var _chunkPX7FY655cjs = require('../chunk-PX7FY655.cjs');
 
 
 
@@ -243,4 +243,4 @@ require('../chunk-3ATAYP36.cjs');
 
 
 
-exports.AGENT_IDENTITIES_API_PATH = _chunkLCTDHLDLcjs.AGENT_IDENTITIES_API_PATH; exports.CONTENT_BREAKPOINTS = _chunk7DUXR4HLcjs.CONTENT_BREAKPOINTS; exports.ContentAreaWidthContext = _chunk7DUXR4HLcjs.ContentAreaWidthContext; exports.DRAG_AND_DROP_MEDIA_QUERY = _chunkGID62YENcjs.DRAG_AND_DROP_MEDIA_QUERY; exports.GraphQLIntrospector = _chunkBFHLGEJKcjs.GraphQLIntrospector; exports.NEAR_VIEWPORT_ROOT_MARGIN = _chunkCW3ML76Ucjs.NEAR_VIEWPORT_ROOT_MARGIN; exports.PREFERS_REDUCED_MOTION_QUERY = _chunkYUXRIR45cjs.PREFERS_REDUCED_MOTION_QUERY; exports.ViewportBreakpoints = _chunk7DUXR4HLcjs.ViewportBreakpoints; exports.batchFetchAuthenticatedImages = _chunkBFHLGEJKcjs.batchFetchAuthenticatedImages; exports.breakpoints = _chunkMANNIJ42cjs.breakpoints; exports.clearAuthedAssetCache = _chunkVOX4E6AXcjs.clearAuthedAssetCache; exports.clearAuthedImageCache = _chunkMANNIJ42cjs.clearAuthedImageCache; exports.clearVariablesParams = _chunkBFHLGEJKcjs.clearParams; exports.coerceValue = _chunkBFHLGEJKcjs.coerceValue; exports.completeFormRescue = _chunkBFHLGEJKcjs.completeFormRescue; exports.configureAuthenticatedImage = _chunkBFHLGEJKcjs.configureAuthenticatedImage; exports.configureBatchImageFetch = _chunkBFHLGEJKcjs.configureBatchImageFetch; exports.contentBreakpointFor = _chunk7DUXR4HLcjs.contentBreakpointFor; exports.createSearchParams = _chunkBLH2SFOOcjs.createSearchParams; exports.extractVariablesFromQuery = _chunkBFHLGEJKcjs.extractVariablesFromQuery; exports.flattenQueryVariables = _chunkBFHLGEJKcjs.flattenQueryVariables; exports.getArrayParams = _chunkBFHLGEJKcjs.getArrayParams; exports.getNestedValue = _chunkBFHLGEJKcjs.getNestedValue; exports.getRequiredParams = _chunkBFHLGEJKcjs.getRequiredParams; exports.introspector = _chunkBFHLGEJKcjs.introspector; exports.isInputObjectType = _chunkBFHLGEJKcjs.isInputObjectType; exports.isScalarType = _chunkBFHLGEJKcjs.isScalarType; exports.mergeDefaults = _chunkBFHLGEJKcjs.mergeDefaults; exports.mergeVariables = _chunkBFHLGEJKcjs.mergeVariables; exports.resetDownloadsStore = _chunkBFHLGEJKcjs.resetDownloadsStore; exports.resolveActiveSection = _chunkBFHLGEJKcjs.resolveActiveSection; exports.setNestedValue = _chunkBFHLGEJKcjs.setNestedValue; exports.shouldIncludeInUrl = _chunkBLH2SFOOcjs.shouldIncludeInUrl; exports.toast = _chunkBFHLGEJKcjs.toast; exports.urlParamsToVariables = _chunkBFHLGEJKcjs.urlParamsToVariables; exports.useAccessCodeIntegration = _chunkBFHLGEJKcjs.useAccessCodeIntegration; exports.useActiveSection = _chunkBFHLGEJKcjs.useActiveSection; exports.useAgentIdentities = _chunkLCTDHLDLcjs.useAgentIdentities; exports.useApiParams = _chunkBFHLGEJKcjs.useApiParams; exports.useAuthedAssetSrc = _chunkVOX4E6AXcjs.useAuthedAssetSrc; exports.useAuthedImageSrc = _chunkMANNIJ42cjs.useAuthedImageSrc; exports.useAuthenticatedImage = _chunkBFHLGEJKcjs.useAuthenticatedImage; exports.useAutoLimitTags = _chunkA6P6DHEZcjs.useAutoLimitTags; exports.useAutoplay = _chunkYUXRIR45cjs.useAutoplay; exports.useBatchImages = _chunkBFHLGEJKcjs.useBatchImages; exports.useClaudeMirrorSrc = _chunkBFHLGEJKcjs.useClaudeMirrorSrc; exports.useContactSubmission = _chunkBFHLGEJKcjs.useContactSubmission; exports.useContentBreakpoint = _chunk7DUXR4HLcjs.useContentBreakpoint; exports.useContentLgUp = _chunk7DUXR4HLcjs.useContentLgUp; exports.useContentMdUp = _chunk7DUXR4HLcjs.useContentMdUp; exports.useCopyToClipboard = _chunkBFHLGEJKcjs.useCopyToClipboard; exports.useCursorPaginationState = _chunkBFHLGEJKcjs.useCursorPaginationState; exports.useDebounce = _chunkYUXRIR45cjs.useDebounce; exports.useDeferredError = _chunkBFHLGEJKcjs.useDeferredError; exports.useDownloads = _chunkBFHLGEJKcjs.useDownloads; exports.useDragAndDropEnabled = _chunkGID62YENcjs.useDragAndDropEnabled; exports.useFocusTrap = _chunkBFHLGEJKcjs.useFocusTrap; exports.useFormRescue = _chunkBFHLGEJKcjs.useFormRescue; exports.useHeaderHeight = _chunk24I6RFVUcjs.useHeaderHeight; exports.useHorizontalScrollbar = _chunkGID62YENcjs.useHorizontalScrollbar; exports.useHumanitySignals = _chunkBFHLGEJKcjs.useHumanitySignals; exports.useImageEdgeColor = _chunkEAY6ZUEScjs.useImageEdgeColor; exports.useInView = _chunkYUXRIR45cjs.useInView; exports.useIsTruncated = _chunkMANNIJ42cjs.useIsTruncated; exports.useIsomorphicLayoutEffect = _chunkVOX4E6AXcjs.useIsomorphicLayoutEffect; exports.useKeyboardCollisionPadding = _chunkA6P6DHEZcjs.useKeyboardCollisionPadding; exports.useLgUp = _chunkMANNIJ42cjs.useLgUp; exports.useLocalStorage = _chunkGID62YENcjs.useLocalStorage; exports.useLocationHash = _chunkBFHLGEJKcjs.useLocationHash; exports.useMarqueeEngine = _chunkYUXRIR45cjs.useMarqueeEngine; exports.useMdUp = _chunkMANNIJ42cjs.useMdUp; exports.useMediaQuery = _chunkMANNIJ42cjs.useMediaQuery; exports.useMemoizedCallback = _chunkBFHLGEJKcjs.useMemoizedCallback; exports.useNatsClient = _chunkBFHLGEJKcjs.useNatsClient; exports.useNavMenus = _chunkBFHLGEJKcjs.useNavMenus; exports.useNearViewport = _chunkCW3ML76Ucjs.useNearViewport; exports.useNotificationPermission = _chunkBFHLGEJKcjs.useNotificationPermission; exports.useOgPlaceholderUrl = _chunkEAY6ZUEScjs.useOgPlaceholderUrl; exports.useOnboardingState = _chunkBFHLGEJKcjs.useOnboardingState; exports.usePlatformByValue = _chunkBFHLGEJKcjs.usePlatformByValue; exports.usePlatformConfig = _chunkBFHLGEJKcjs.usePlatformConfig; exports.usePrefersReducedMotion = _chunkYUXRIR45cjs.usePrefersReducedMotion; exports.usePrefersReducedMotionState = _chunkYUXRIR45cjs.usePrefersReducedMotionState; exports.usePreventScroll = _chunkBFHLGEJKcjs.usePreventScroll; exports.useQueryParams = _chunkBFHLGEJKcjs.useQueryParams; exports.useRescuedForm = _chunkBFHLGEJKcjs.useRescuedForm; exports.useResetOnPageHidden = _chunkYUXRIR45cjs.useResetOnPageHidden; exports.useScenarioPlayer = _chunkBFHLGEJKcjs.useScenarioPlayer; exports.useScrollToHash = _chunkBFHLGEJKcjs.useScrollToHash; exports.useSearch = _chunkBFHLGEJKcjs.useSearch; exports.useSmUp = _chunkMANNIJ42cjs.useSmUp; exports.useStickyToolbar = _chunkBFHLGEJKcjs.useStickyToolbar; exports.useSuppressCloneFocus = _chunkYUXRIR45cjs.useSuppressCloneFocus; exports.useTablePagination = _chunkBFHLGEJKcjs.useTablePagination; exports.useThrottle = _chunkBFHLGEJKcjs.useThrottle; exports.useToast = _chunkBFHLGEJKcjs.useToast; exports.useValidatePlatform = _chunkBFHLGEJKcjs.useValidatePlatform; exports.useVisitorDesktopDownload = _chunkBFHLGEJKcjs.useVisitorDesktopDownload; exports.useVisitorOs = _chunkYJFN2W7Acjs.useVisitorOs; exports.useWindowSize = _chunkBFHLGEJKcjs.useWindowSize; exports.validateSchema = _chunkBFHLGEJKcjs.validateSchema; exports.validateVariables = _chunkBFHLGEJKcjs.validateVariables; exports.variablesToUrlParams = _chunkBFHLGEJKcjs.variablesToUrlParams;
+exports.AGENT_IDENTITIES_API_PATH = _chunkPX7FY655cjs.AGENT_IDENTITIES_API_PATH; exports.CONTENT_BREAKPOINTS = _chunk7DUXR4HLcjs.CONTENT_BREAKPOINTS; exports.ContentAreaWidthContext = _chunk7DUXR4HLcjs.ContentAreaWidthContext; exports.DRAG_AND_DROP_MEDIA_QUERY = _chunkGID62YENcjs.DRAG_AND_DROP_MEDIA_QUERY; exports.GraphQLIntrospector = _chunkSJRR745Gcjs.GraphQLIntrospector; exports.NEAR_VIEWPORT_ROOT_MARGIN = _chunkCW3ML76Ucjs.NEAR_VIEWPORT_ROOT_MARGIN; exports.PREFERS_REDUCED_MOTION_QUERY = _chunkCC3LINHFcjs.PREFERS_REDUCED_MOTION_QUERY; exports.ViewportBreakpoints = _chunk7DUXR4HLcjs.ViewportBreakpoints; exports.batchFetchAuthenticatedImages = _chunkSJRR745Gcjs.batchFetchAuthenticatedImages; exports.breakpoints = _chunkMANNIJ42cjs.breakpoints; exports.clearAuthedAssetCache = _chunkVOX4E6AXcjs.clearAuthedAssetCache; exports.clearAuthedImageCache = _chunkMANNIJ42cjs.clearAuthedImageCache; exports.clearVariablesParams = _chunkSJRR745Gcjs.clearParams; exports.coerceValue = _chunkSJRR745Gcjs.coerceValue; exports.completeFormRescue = _chunkSJRR745Gcjs.completeFormRescue; exports.configureAuthenticatedImage = _chunkSJRR745Gcjs.configureAuthenticatedImage; exports.configureBatchImageFetch = _chunkSJRR745Gcjs.configureBatchImageFetch; exports.contentBreakpointFor = _chunk7DUXR4HLcjs.contentBreakpointFor; exports.createSearchParams = _chunkBLH2SFOOcjs.createSearchParams; exports.extractVariablesFromQuery = _chunkSJRR745Gcjs.extractVariablesFromQuery; exports.flattenQueryVariables = _chunkSJRR745Gcjs.flattenQueryVariables; exports.getArrayParams = _chunkSJRR745Gcjs.getArrayParams; exports.getNestedValue = _chunkSJRR745Gcjs.getNestedValue; exports.getRequiredParams = _chunkSJRR745Gcjs.getRequiredParams; exports.introspector = _chunkSJRR745Gcjs.introspector; exports.isInputObjectType = _chunkSJRR745Gcjs.isInputObjectType; exports.isScalarType = _chunkSJRR745Gcjs.isScalarType; exports.mergeDefaults = _chunkSJRR745Gcjs.mergeDefaults; exports.mergeVariables = _chunkSJRR745Gcjs.mergeVariables; exports.resetDownloadsStore = _chunkSJRR745Gcjs.resetDownloadsStore; exports.resolveActiveSection = _chunkSJRR745Gcjs.resolveActiveSection; exports.setNestedValue = _chunkSJRR745Gcjs.setNestedValue; exports.shouldIncludeInUrl = _chunkBLH2SFOOcjs.shouldIncludeInUrl; exports.toast = _chunkSJRR745Gcjs.toast; exports.urlParamsToVariables = _chunkSJRR745Gcjs.urlParamsToVariables; exports.useAccessCodeIntegration = _chunkSJRR745Gcjs.useAccessCodeIntegration; exports.useActiveSection = _chunkSJRR745Gcjs.useActiveSection; exports.useAgentIdentities = _chunkPX7FY655cjs.useAgentIdentities; exports.useApiParams = _chunkSJRR745Gcjs.useApiParams; exports.useAuthedAssetSrc = _chunkVOX4E6AXcjs.useAuthedAssetSrc; exports.useAuthedImageSrc = _chunkMANNIJ42cjs.useAuthedImageSrc; exports.useAuthenticatedImage = _chunkSJRR745Gcjs.useAuthenticatedImage; exports.useAutoLimitTags = _chunkA6P6DHEZcjs.useAutoLimitTags; exports.useAutoplay = _chunkCC3LINHFcjs.useAutoplay; exports.useBatchImages = _chunkSJRR745Gcjs.useBatchImages; exports.useClaudeMirrorSrc = _chunkSJRR745Gcjs.useClaudeMirrorSrc; exports.useContactSubmission = _chunkSJRR745Gcjs.useContactSubmission; exports.useContentBreakpoint = _chunk7DUXR4HLcjs.useContentBreakpoint; exports.useContentLgUp = _chunk7DUXR4HLcjs.useContentLgUp; exports.useContentMdUp = _chunk7DUXR4HLcjs.useContentMdUp; exports.useCopyToClipboard = _chunkSJRR745Gcjs.useCopyToClipboard; exports.useCursorPaginationState = _chunkSJRR745Gcjs.useCursorPaginationState; exports.useDebounce = _chunkCC3LINHFcjs.useDebounce; exports.useDeferredError = _chunkSJRR745Gcjs.useDeferredError; exports.useDownloads = _chunkSJRR745Gcjs.useDownloads; exports.useDragAndDropEnabled = _chunkGID62YENcjs.useDragAndDropEnabled; exports.useFocusTrap = _chunkSJRR745Gcjs.useFocusTrap; exports.useFormRescue = _chunkSJRR745Gcjs.useFormRescue; exports.useHeaderHeight = _chunk24I6RFVUcjs.useHeaderHeight; exports.useHorizontalScrollbar = _chunkGID62YENcjs.useHorizontalScrollbar; exports.useHumanitySignals = _chunkSJRR745Gcjs.useHumanitySignals; exports.useImageEdgeColor = _chunkEAY6ZUEScjs.useImageEdgeColor; exports.useInView = _chunkCC3LINHFcjs.useInView; exports.useIsTruncated = _chunkMANNIJ42cjs.useIsTruncated; exports.useIsomorphicLayoutEffect = _chunkVOX4E6AXcjs.useIsomorphicLayoutEffect; exports.useKeyboardCollisionPadding = _chunkA6P6DHEZcjs.useKeyboardCollisionPadding; exports.useLgUp = _chunkMANNIJ42cjs.useLgUp; exports.useLocalStorage = _chunkGID62YENcjs.useLocalStorage; exports.useLocationHash = _chunkSJRR745Gcjs.useLocationHash; exports.useMarqueeEngine = _chunkCC3LINHFcjs.useMarqueeEngine; exports.useMdUp = _chunkMANNIJ42cjs.useMdUp; exports.useMediaQuery = _chunkMANNIJ42cjs.useMediaQuery; exports.useMemoizedCallback = _chunkSJRR745Gcjs.useMemoizedCallback; exports.useNatsClient = _chunkSJRR745Gcjs.useNatsClient; exports.useNavMenus = _chunkSJRR745Gcjs.useNavMenus; exports.useNearViewport = _chunkCW3ML76Ucjs.useNearViewport; exports.useNotificationPermission = _chunkSJRR745Gcjs.useNotificationPermission; exports.useOgPlaceholderUrl = _chunkEAY6ZUEScjs.useOgPlaceholderUrl; exports.useOnboardingState = _chunkSJRR745Gcjs.useOnboardingState; exports.usePlatformByValue = _chunkSJRR745Gcjs.usePlatformByValue; exports.usePlatformConfig = _chunkSJRR745Gcjs.usePlatformConfig; exports.usePrefersReducedMotion = _chunkCC3LINHFcjs.usePrefersReducedMotion; exports.usePrefersReducedMotionState = _chunkCC3LINHFcjs.usePrefersReducedMotionState; exports.usePreventScroll = _chunkSJRR745Gcjs.usePreventScroll; exports.useQueryParams = _chunkSJRR745Gcjs.useQueryParams; exports.useRescuedForm = _chunkSJRR745Gcjs.useRescuedForm; exports.useResetOnPageHidden = _chunkCC3LINHFcjs.useResetOnPageHidden; exports.useScenarioPlayer = _chunkSJRR745Gcjs.useScenarioPlayer; exports.useScrollToHash = _chunkSJRR745Gcjs.useScrollToHash; exports.useSearch = _chunkSJRR745Gcjs.useSearch; exports.useSmUp = _chunkMANNIJ42cjs.useSmUp; exports.useStickyToolbar = _chunkSJRR745Gcjs.useStickyToolbar; exports.useSuppressCloneFocus = _chunkCC3LINHFcjs.useSuppressCloneFocus; exports.useTablePagination = _chunkSJRR745Gcjs.useTablePagination; exports.useThrottle = _chunkSJRR745Gcjs.useThrottle; exports.useToast = _chunkSJRR745Gcjs.useToast; exports.useValidatePlatform = _chunkSJRR745Gcjs.useValidatePlatform; exports.useVisitorDesktopDownload = _chunkSJRR745Gcjs.useVisitorDesktopDownload; exports.useVisitorOs = _chunkRIXGLS5Ycjs.useVisitorOs; exports.useWindowSize = _chunkSJRR745Gcjs.useWindowSize; exports.validateSchema = _chunkSJRR745Gcjs.validateSchema; exports.validateVariables = _chunkSJRR745Gcjs.validateVariables; exports.variablesToUrlParams = _chunkSJRR745Gcjs.variablesToUrlParams;

package/dist/hooks/ui/use-autoplay.d.ts

@@ -1,9 +1,23 @@
+import type { FocusEvent, PointerEvent } from 'react';
+/** The handlers that hold a moving thing still while a visitor is on it. Spread them on its outer element. */
+export interface AutoplayHoldProps {
+    onPointerDown: (event: PointerEvent<HTMLElement>) => void;
+    onFocus: (event: FocusEvent<HTMLElement>) => void;
+}
 export interface UseAutoplayResult {
     /** True while the thing may move by itself. */
     playing: boolean;
-    /** The visitor stopped it with the pause control. */
-    paused: boolean;
-    setPaused: (paused: boolean) => void;
+    /** The visitor is holding it still: a finger or the mouse button is down on it, or the keyboard is inside it. */
+    held: boolean;
+    /** Spread on the element that moves: it is how a visitor stops it, with no control to find. */
+    holdProps: AutoplayHoldProps;
+    /**
+     * Lets go of every hold at once. Called when the visitor CHOOSES something on
+     * the thing itself (a tab, a step, an arrow): a choice is an instruction to
+     * play from there, and it must never depend on the browser reporting the end
+     * of the press or the focus that made it.
+     */
+    release: () => void;
     /** True once the system preference is known to be reduced motion. */
     reducedMotion: boolean;
 }
@@ -13,20 +27,43 @@ export interface UseAutoplayResult {
  * else decides it.
  *
  *   1. it is on screen (`onScreen`, the caller's `useInView`);
- *   2. the browser tab is visible (`visibilitychange`, and `pageshow` for a
- *      page restored from the back/forward cache);
- *   3. the visitor has not pressed pause (`setPaused`: the stop control
+ *   2. the browser tab is visible;
+ *   3. the visitor is not holding it (`holdProps`: the way to stop it that
  *      WCAG 2.2.2 asks of anything that moves for more than five seconds);
  *   4. motion is allowed (never under reduced motion, and not before the
  *      preference is known).
  *
- * Every one of those has a way back that needs nothing particular from the
- * visitor: scroll back, return to the tab, press play. It deliberately does
- * NOT stop on hover, on keyboard focus, on a wheel event or on a touch.
- * Each was tried: a browser re-reports focus when its window is re-activated,
- * and a wheel or a touch is what scrolling the PAGE past the thing produces,
- * so those rules stopped it for reasons the visitor could not see, with no
- * visible way to start it again.
+ * There is NO pause button. A visitor holds it by PRESSING on it (a finger or
+ * the mouse button down, as a story is held) or by having KEYBOARD focus inside
+ * it. Each ends by itself (the press is released, wherever that happens; focus
+ * moves on), so it can never be left stopped with no visible way to start it again.
+ *
+ * HOW it knows, which is what keeps it from sticking. Each hold has more than
+ * one way to end, and every one of them is checked:
+ *   - a PRESS ends on its release, listened for on the WINDOW (a drag that
+ *     leaves the element still ends it), by ANY of the events a release can
+ *     arrive as (`RELEASE_EVENTS`: a native drag ends in `dragend`, not
+ *     `pointerup`), and, as the net under those, by the first pointer movement
+ *     that reports no button down;
+ *   - the KEYBOARD holds it only when focus ARRIVED by keyboard (the browser
+ *     drew a ring for it as it came in), and only until focus leaves the
+ *     element or the visitor reaches for the pointer. "Is `:focus-visible`
+ *     inside" alone is not the test: a browser turns the ring on for a control
+ *     that was CLICKED as soon as any key is pressed, which held the demo for a
+ *     visitor who clicked a tab and then scrolled with the space bar;
+ *   - a CHOICE made on the thing itself (`release`, called by whoever handles
+ *     the tab, the step or the arrow) lets go of everything: it plays from
+ *     there whatever the browser did or did not report;
+ *   - the tab is read from the document (`useSyncExternalStore`), never copied
+ *     into state.
+ *
+ * What does NOT hold it, each tried and removed:
+ *   - HOVER: a visitor watching a demo rests the mouse on it, so it stopped the
+ *     moment it had their attention and read as stuck;
+ *   - a WHEEL event or a passing touch: that is what scrolling the PAGE past
+ *     the thing produces (the browser cancels a press the moment it becomes a scroll);
+ *   - focus the browser shows no ring for: a browser re-reports focus when its
+ *     window is re-activated, and a mouse click on a control is not the keyboard.
  */
 export declare function useAutoplay(onScreen: boolean): UseAutoplayResult;
 //# sourceMappingURL=use-autoplay.d.ts.map

package/dist/hooks/ui/use-autoplay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-autoplay.d.ts","sourceRoot":"","sources":["../../../src/hooks/ui/use-autoplay.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,qEAAqE;IACrE,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,GAAG,iBAAiB,CAsBhE"}
+{"version":3,"file":"use-autoplay.d.ts","sourceRoot":"","sources":["../../../src/hooks/ui/use-autoplay.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAGtD,8GAA8G;AAC9G,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAC1D,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,iHAAiH;IACjH,IAAI,EAAE,OAAO,CAAC;IACd,+FAA+F;IAC/F,SAAS,EAAE,iBAAiB,CAAC;IAC7B;;;;;OAKG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,qEAAqE;IACrE,aAAa,EAAE,OAAO,CAAC;CACxB;AA0BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,GAAG,iBAAiB,CA6EhE"}

package/dist/hooks/ui/use-autoplay.js

@@ -1,24 +1,87 @@
 "use client";
-import { useEffect, useState } from "react";
+import { useCallback, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { usePrefersReducedMotionState } from "./use-prefers-reduced-motion.js";
+function listen(target, events, onChange) {
+  const controller = new AbortController();
+  for (const event of events) target.addEventListener(event, onChange, { signal: controller.signal });
+  return () => controller.abort();
+}
+const subscribeToTab = (onChange) => {
+  const stopDocument = listen(document, ["visibilitychange"], onChange);
+  const stopWindow = listen(window, ["pageshow"], onChange);
+  return () => {
+    stopDocument();
+    stopWindow();
+  };
+};
+const tabIsHidden = () => document.visibilityState === "hidden";
+const never = () => false;
+const RELEASE_EVENTS = ["pointerup", "pointercancel", "mouseup", "touchend", "dragend", "blur"];
 function useAutoplay(onScreen) {
   const reducedState = usePrefersReducedMotionState();
-  const [paused, setPaused] = useState(false);
-  const [tabHidden, setTabHidden] = useState(false);
-  useEffect(() => {
-    const sync = () => setTabHidden(document.visibilityState === "hidden");
-    sync();
-    document.addEventListener("visibilitychange", sync);
-    window.addEventListener("pageshow", sync);
+  const tabHidden = useSyncExternalStore(subscribeToTab, tabIsHidden, never);
+  const host = useRef(null);
+  const keyboardCameIn = useRef(false);
+  const subscribeToKeyboard = useCallback((onChange) => {
+    const usedPointer = () => {
+      keyboardCameIn.current = false;
+      onChange();
+    };
+    const stopFocus = listen(document, ["focusin", "focusout", "visibilitychange"], onChange);
+    const stopPointer = listen(document, ["pointerdown", "pointermove"], usedPointer);
+    const stopWindow = listen(window, ["focus", "blur"], onChange);
     return () => {
-      document.removeEventListener("visibilitychange", sync);
-      window.removeEventListener("pageshow", sync);
+      stopFocus();
+      stopPointer();
+      stopWindow();
     };
   }, []);
+  const keyboardIsInside = useCallback(() => {
+    if (!keyboardCameIn.current) return false;
+    const inside = !!host.current?.isConnected && host.current.contains(document.activeElement);
+    if (!inside) keyboardCameIn.current = false;
+    return inside;
+  }, []);
+  const focused = useSyncExternalStore(subscribeToKeyboard, keyboardIsInside, never);
+  const [pressed, setPressed] = useState(false);
+  const holdProps = useMemo(
+    () => ({
+      onPointerDown: (event) => {
+        host.current = event.currentTarget;
+        setPressed(true);
+        const released = new AbortController();
+        const release2 = () => {
+          setPressed(false);
+          released.abort();
+        };
+        for (const type of RELEASE_EVENTS) window.addEventListener(type, release2, { signal: released.signal });
+        window.addEventListener(
+          "pointermove",
+          (move) => {
+            if (move.buttons === 0) release2();
+          },
+          { signal: released.signal }
+        );
+      },
+      onFocus: (event) => {
+        host.current = event.currentTarget;
+        if (event.target.matches(":focus-visible")) keyboardCameIn.current = true;
+      }
+    }),
+    []
+  );
+  const [, setReleases] = useState(0);
+  const release = useCallback(() => {
+    keyboardCameIn.current = false;
+    setPressed(false);
+    setReleases((count) => count + 1);
+  }, []);
+  const held = pressed || focused;
   return {
-    playing: onScreen && !paused && !tabHidden && reducedState === false,
-    paused,
-    setPaused,
+    playing: onScreen && !held && !tabHidden && reducedState === false,
+    held,
+    holdProps,
+    release,
     reducedMotion: reducedState === true
   };
 }

package/dist/hooks/ui/use-in-view.d.ts

@@ -26,6 +26,14 @@ export interface UseInViewResult<T extends Element> {
  * `useNearViewport` is the fire-once sibling (mount a heavy thing when it gets
  * close, never unmount). This one is for things that should run only WHILE
  * visible, like an auto-advancing carousel or a looping demo.
+ *
+ * The observer LIVES IN AN EFFECT keyed on the element, never in the ref
+ * callback. An observer made in the callback and torn down by a separate
+ * effect is torn down every time React re-runs effects without re-attaching
+ * refs (a Fast Refresh, an Activity that hides and shows): nothing observed any
+ * more, and `inView` froze at its last value, so a demo that happened to be off
+ * screen at that moment never played again. An effect that owns it makes it
+ * again whenever it is torn down.
  */
 export declare function useInView<T extends Element = HTMLElement>({ threshold, rootMargin, initial, }?: UseInViewOptions): UseInViewResult<T>;
 //# sourceMappingURL=use-in-view.d.ts.map

package/dist/hooks/ui/use-in-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-in-view.d.ts","sourceRoot":"","sources":["../../../src/hooks/ui/use-in-view.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,OAAO;IAChD,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;IAC9B,mFAAmF;IACnF,MAAM,EAAE,OAAO,CAAC;CACjB;AAaD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,OAAO,GAAG,WAAW,EAAE,EACzD,SAAa,EACb,UAAkB,EAClB,OAAe,GAChB,GAAE,gBAAqB,GAAG,eAAe,CAAC,CAAC,CAAC,CAwC5C"}
+{"version":3,"file":"use-in-view.d.ts","sourceRoot":"","sources":["../../../src/hooks/ui/use-in-view.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,OAAO;IAChD,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;IAC9B,mFAAmF;IACnF,MAAM,EAAE,OAAO,CAAC;CACjB;AAaD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,OAAO,GAAG,WAAW,EAAE,EACzD,SAAa,EACb,UAAkB,EAClB,OAAe,GAChB,GAAE,gBAAqB,GAAG,eAAe,CAAC,CAAC,CAAC,CAyB5C"}

package/dist/hooks/ui/use-in-view.js

@@ -1,46 +1,31 @@
 "use client";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useEffect, useState } from "react";
 const STEPS = Array.from({ length: 21 }, (_, i) => i / 20);
 function useInView({
   threshold = 0,
   rootMargin = "0px",
   initial = false
 } = {}) {
-  const [inView, setInView] = useState(initial);
-  const observerRef = useRef(null);
-  const disconnect = useCallback(() => {
-    observerRef.current?.disconnect();
-    observerRef.current = null;
-  }, []);
-  const ref = useCallback(
-    (node) => {
-      disconnect();
-      if (!node) {
-        setInView(false);
-        return;
-      }
-      if (typeof IntersectionObserver === "undefined") {
-        setInView(initial);
-        return;
-      }
-      const observer = new IntersectionObserver(
-        (entries) => {
-          const entry = entries[entries.length - 1];
-          if (!entry) return;
-          const ofElement = entry.intersectionRatio >= threshold;
-          const viewportHeight = entry.rootBounds?.height ?? 0;
-          const ofViewport = viewportHeight > 0 && (entry.intersectionRect?.height ?? 0) >= viewportHeight * threshold;
-          setInView(entry.isIntersecting && (ofElement || ofViewport));
-        },
-        { threshold: STEPS, rootMargin }
-      );
-      observer.observe(node);
-      observerRef.current = observer;
-    },
-    [disconnect, threshold, rootMargin, initial]
-  );
-  useEffect(() => disconnect, [disconnect]);
-  return { ref, inView };
+  const [node, setNode] = useState(null);
+  const [seen, setSeen] = useState(null);
+  useEffect(() => {
+    if (!node || typeof IntersectionObserver === "undefined") return void 0;
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const entry = entries[entries.length - 1];
+        if (!entry) return;
+        const ofElement = entry.intersectionRatio >= threshold;
+        const viewportHeight = entry.rootBounds?.height ?? 0;
+        const ofViewport = viewportHeight > 0 && (entry.intersectionRect?.height ?? 0) >= viewportHeight * threshold;
+        setSeen({ node, inView: entry.isIntersecting && (ofElement || ofViewport) });
+      },
+      { threshold: STEPS, rootMargin }
+    );
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [node, threshold, rootMargin]);
+  const inView = !node ? false : seen?.node === node ? seen.inView : initial;
+  return { ref: setNode, inView };
 }
 export {
   useInView

package/dist/hooks/use-agent-identities.d.ts

@@ -3,6 +3,12 @@ export interface AgentIdentityIcon {
     name?: string | null;
     url?: string | null;
     props?: Record<string, unknown> | null;
+    /**
+     * The identity's accent, travelling with its icon: a hex colour (`#5efaf0`),
+     * as the server stores it. What is drawn in the agent's colour (its tab, the
+     * step it is on) reads it through `useAgentAccents`; unset, that is the platform's accent.
+     */
+    accent?: string | null;
 }
 /** Each agent's identity icon, keyed by the agent's slug. */
 export type AgentIdentityIcons = Readonly<Record<string, AgentIdentityIcon | null | undefined>>;

package/dist/hooks/use-agent-identities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-agent-identities.d.ts","sourceRoot":"","sources":["../../src/hooks/use-agent-identities.ts"],"names":[],"mappings":"AAKA,yGAAyG;AACzG,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACxC;AAED,6DAA6D;AAC7D,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC;AAEhG,gJAAgJ;AAChJ,eAAO,MAAM,yBAAyB,mBAAmB,CAAC;AAW1D;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,GAAE,MAAkC,EAC5C,OAAO,GAAE,OAAc,GACtB,kBAAkB,GAAG,SAAS,CAUhC"}
+{"version":3,"file":"use-agent-identities.d.ts","sourceRoot":"","sources":["../../src/hooks/use-agent-identities.ts"],"names":[],"mappings":"AAKA,yGAAyG;AACzG,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,6DAA6D;AAC7D,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC;AAEhG,gJAAgJ;AAChJ,eAAO,MAAM,yBAAyB,mBAAmB,CAAC;AAW1D;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,GAAE,MAAkC,EAC5C,OAAO,GAAE,OAAc,GACtB,kBAAkB,GAAG,SAAS,CAUhC"}

package/dist/hooks/use-scenario-player.d.ts

@@ -1,3 +1,4 @@
+import { type AutoplayHoldProps } from './ui/use-autoplay';
 export interface UseScenarioPlayerOptions {
     /** How many scenarios (tabs) the stage cycles through. */
     scenarioCount: number;
@@ -19,15 +20,30 @@ export interface UseScenarioPlayerOptions {
      * never gets to play (it is never scrolled into view) still reads complete.
      */
     startAtEnd?: boolean;
+    /**
+     * Whether step 0 of every scenario is an EMPTY stage, to be left at once
+     * (default true: a stage that sits empty for a whole step after a tap reads
+     * as not responding). False when step 0 already shows something to read:
+     * every step then lasts a whole `stepMs`, however the scenario was started
+     * (a page load, the rotation and a chosen tab all pace it the same).
+     */
+    emptyFirstStep?: boolean;
 }
 export interface UseScenarioPlayerResult {
     /** Index of the scenario being shown. */
     scenario: number;
     /** Current step, 0..lastStep. */
     step: number;
-    /** The visitor stopped it with the pause control. */
-    paused: boolean;
-    setPaused: (paused: boolean) => void;
+    /**
+     * False until it has been playable once (it has not been on screen yet).
+     * A progress line reads 0 until then, so it starts from empty when the
+     * visitor first reaches it, never part-way through a step nobody saw begin.
+     */
+    started: boolean;
+    /** The visitor is holding it still (pressing on it, or the keyboard is inside it). */
+    held: boolean;
+    /** Spread on the stage's outer element: how a visitor stops it (`useAutoplay`). */
+    holdProps: AutoplayHoldProps;
     /** Jump to a step in the current scenario (a visitor's tap, a stepper button). */
     setStep: (step: number) => void;
     /** Switch scenario and restart it from step 0. */
@@ -45,14 +61,15 @@ export interface UseScenarioPlayerResult {
  * line and the stage itself agree by construction.
  *
  * WHEN IT MOVES is `useAutoplay`'s rule: on screen (`enabled`), tab visible,
- * not paused, motion allowed. Under reduced motion it parks on the last step
+ * not held by the visitor, motion allowed. Under reduced motion it parks on the last step
  * of the current scenario, and every scenario can still be read by choosing it.
  *
- * The moment it becomes playable its first step follows within `START_MS`,
- * not a whole step later; from there every step takes `stepMs`.
+ * The moment it becomes playable, and at the top of every scenario (the
+ * rotation moved on, or a tab was chosen), its first step follows within
+ * `START_MS`, not a whole step later; from there every step takes `stepMs`.
  *
- * A visitor's own choice (`go`, `setStep`) moves the clock there and un-pauses
- * it; the rotation carries on from that point.
+ * A visitor's own choice (`go`, `setStep`) moves the clock there and lets go of
+ * any hold; the rotation carries on from that point.
  */
-export declare function useScenarioPlayer({ scenarioCount, lastStep: lastStepOption, stepMs, holdMs, enabled, initialScenario, startAtEnd, }: UseScenarioPlayerOptions): UseScenarioPlayerResult;
+export declare function useScenarioPlayer({ scenarioCount, lastStep: lastStepOption, stepMs, holdMs, enabled, initialScenario, startAtEnd, emptyFirstStep, }: UseScenarioPlayerOptions): UseScenarioPlayerResult;
 //# sourceMappingURL=use-scenario-player.d.ts.map

package/dist/hooks/use-scenario-player.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-scenario-player.d.ts","sourceRoot":"","sources":["../../src/hooks/use-scenario-player.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,wBAAwB;IACvC,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IAClD,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4BAA4B;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,kFAAkF;IAClF,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,kDAAkD;IAClD,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,qEAAqE;IACrE,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,aAAa,EACb,QAAQ,EAAE,cAAc,EACxB,MAAM,EACN,MAAM,EACN,OAAc,EACd,eAAmB,EACnB,UAAkB,GACnB,EAAE,wBAAwB,GAAG,uBAAuB,CAyDpD"}
+{"version":3,"file":"use-scenario-player.d.ts","sourceRoot":"","sources":["../../src/hooks/use-scenario-player.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,iBAAiB,EAAe,MAAM,mBAAmB,CAAC;AAUxE,MAAM,WAAW,wBAAwB;IACvC,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IAClD,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4BAA4B;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,sFAAsF;IACtF,IAAI,EAAE,OAAO,CAAC;IACd,mFAAmF;IACnF,SAAS,EAAE,iBAAiB,CAAC;IAC7B,kFAAkF;IAClF,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,kDAAkD;IAClD,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,qEAAqE;IACrE,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,aAAa,EACb,QAAQ,EAAE,cAAc,EACxB,MAAM,EACN,MAAM,EACN,OAAc,EACd,eAAmB,EACnB,UAAkB,EAClB,cAAqB,GACtB,EAAE,wBAAwB,GAAG,uBAAuB,CAgEpD"}

package/dist/hooks/use-scenario-player.js

@@ -9,15 +9,18 @@ function useScenarioPlayer({
   holdMs,
   enabled = true,
   initialScenario = 0,
-  startAtEnd = false
+  startAtEnd = false,
+  emptyFirstStep = true
 }) {
   const auto = useAutoplay(enabled);
-  const { reducedMotion, paused, setPaused } = auto;
+  const { reducedMotion, held, holdProps, release } = auto;
   const [scenario, setScenario] = useState(initialScenario);
   const [rawStep, setRawStep] = useState(startAtEnd ? Number.MAX_SAFE_INTEGER : 0);
   const lastStep = typeof lastStepOption === "function" ? lastStepOption(scenario) : lastStepOption;
   const step = reducedMotion ? lastStep : Math.min(rawStep, lastStep);
   const playing = auto.playing && scenarioCount > 0;
+  const [started, setStarted] = useState(false);
+  if (playing && !started) setStarted(true);
   const starting = useRef(false);
   const wasPlaying = useRef(false);
   useEffect(() => {
@@ -25,7 +28,7 @@ function useScenarioPlayer({
     wasPlaying.current = playing;
     if (!playing) return void 0;
     const atEnd = rawStep >= lastStep;
-    const quickStart = starting.current && !atEnd;
+    const quickStart = emptyFirstStep && (starting.current || rawStep === 0) && !atEnd;
     starting.current = false;
     const timer = setTimeout(
       () => {
@@ -39,23 +42,23 @@ function useScenarioPlayer({
       atEnd ? holdMs : quickStart ? Math.min(START_MS, stepMs) : stepMs
     );
     return () => clearTimeout(timer);
-  }, [playing, rawStep, lastStep, stepMs, holdMs, scenario, scenarioCount]);
+  }, [playing, rawStep, lastStep, stepMs, holdMs, scenario, scenarioCount, emptyFirstStep]);
   const setStep = useCallback(
     (next) => {
       setRawStep(Math.max(0, Math.min(lastStep, next)));
-      setPaused(false);
+      release();
     },
-    [lastStep, setPaused]
+    [lastStep, release]
   );
   const go = useCallback(
     (next) => {
       setScenario(next);
       setRawStep(0);
-      setPaused(false);
+      release();
     },
-    [setPaused]
+    [release]
   );
-  return { scenario, step, paused, setPaused, setStep, go, reducedMotion };
+  return { scenario, step, started: started || reducedMotion, held, holdProps, setStep, go, reducedMotion };
 }
 export {
   useScenarioPlayer