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

package/src/components/ui/tab-navigation.tsx

@@ -58,10 +58,17 @@ export interface TabItem {
   /**
    * 0..1. Set on the ACTIVE tab, the underline stops being a selection marker
    * and becomes a progress line: its width is this fraction of the tab, and it
-   * moves there linearly over `progressTransitionMs`. A timed, auto-advancing
+   * moves there linearly over `progressTransitionMs`. Start it above 0 (the
+   * first step of N is 1/N): at 0 the open tab has no underline at all. A timed, auto-advancing
    * strip (a looping demo) uses it; `0` snaps back with no animation.
    */
   progress?: number;
+  /**
+   * The tab's own colour (a CSS colour, such as the hex an agent's identity
+   * stores): its underline and its icon take it while the tab is open. Omitted,
+   * they are the platform's accent.
+   */
+  accent?: string;
 }
 
 export interface TabNavigationUrlSyncOptions {
@@ -334,7 +341,34 @@ const TabBar = memo(function TabBarImpl({
   // A tab that reports `progress` turns the underline into a progress line.
   const activeProgress = tabs.find(tab => tab.id === activeTab)?.progress;
   const hasProgress = typeof activeProgress === 'number';
-  const progress = hasProgress ? Math.max(0, Math.min(1, activeProgress)) : 1;
+  // A progress line always GROWS from the start of its tab. A run that starts
+  // over (another tab opened, by the rotation or by choice, or the same tab
+  // chosen again: its progress fell back) is first drawn EMPTY, with no
+  // transition, and only then let run to its value. Without that the line
+  // either slid across from the last tab, shrank back, or appeared already
+  // part-way and sat still until the next step.
+  const target = hasProgress ? Math.max(0, Math.min(1, activeProgress)) : 1;
+  // It starts on no tab at all, so the FIRST paint is a run starting over too:
+  // a page load, the rotation and a click all begin the line the same way.
+  const [run, setRun] = useState<{ tab: string | null; progress: number }>({ tab: null, progress: 0 });
+  const startsOver = hasProgress && (run.tab !== activeTab || target < run.progress);
+  // The same run moving forward: follow it (state derived from props during render).
+  if (hasProgress && !startsOver && run.progress !== target) setRun({ tab: activeTab, progress: target });
+  useEffect(() => {
+    if (!startsOver) return undefined;
+    // Two frames: the empty line has to be painted before it is let run.
+    let second = 0;
+    const first = requestAnimationFrame(() => {
+      second = requestAnimationFrame(() => setRun({ tab: activeTab, progress: target }));
+    });
+    return () => {
+      cancelAnimationFrame(first);
+      cancelAnimationFrame(second);
+    };
+  }, [startsOver, activeTab, target]);
+  const progress = startsOver ? 0 : target;
+  // The open tab's own colour, when it has one; else the platform's accent.
+  const activeAccent = tabs.find(tab => tab.id === activeTab)?.accent;
   const indicatorStyle: React.CSSProperties = {
     width: `${indicator.width * progress}px`,
     transform: `translateX(${indicator.left}px)`,
@@ -362,7 +396,7 @@ const TabBar = memo(function TabBarImpl({
           `relative` makes this the offsetParent the underline is measured against. */}
       <div
         ref={scrollRef}
-        className="scrollbar-hide relative flex h-full items-center justify-start gap-[var(--spacing-system-xxs)] overflow-x-auto overflow-y-hidden"
+        className="scrollbar-hide relative flex h-full items-center justify-start overflow-x-auto overflow-y-hidden"
       >
         {tabs.map(tab => {
           const isActive = activeTab === tab.id;
@@ -375,28 +409,19 @@ const TabBar = memo(function TabBarImpl({
               onClick={() => onTabChange(tab.id)}
               aria-label={tab.badge ? `${tab.label} (${tab.badge})` : undefined}
               className={cn(
-                'relative flex shrink-0 cursor-pointer items-center gap-[var(--spacing-system-xxs)] p-[var(--spacing-system-m)]',
+                'group relative flex shrink-0 cursor-pointer items-center gap-[var(--spacing-system-xxs)] p-[var(--spacing-system-m)]',
                 tabAlign === 'start' ? 'justify-start text-left' : 'justify-center',
                 // Named rather than `transition-all`: the only thing that moves
-                // here is colour. `all` also made the browser re-check every
-                // property each frame, including the background GRADIENT — which
-                // never animated anyway, since the inactive state has no
-                // background-image to interpolate from.
+                // here is colour.
                 'border-none bg-transparent outline-none transition-colors duration-200',
                 // `outline-none` above drops the browser's own focus ring, so
                 // put one back or the strip is un-navigable by keyboard — you
                 // can tab through it with nothing to show where you are. Inset,
-                // so it stays within the button instead of overlapping the tab
-                // sitting 4px away.
+                // so it stays within the button: the tabs touch.
                 'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ods-focus',
                 stretchTabs && 'flex-1',
                 tab.avatar && 'gap-[var(--spacing-system-xsf)]',
-                // Known limitation: ODS color vars hold hex values, so Tailwind
-                // alpha modifiers (to-ods-accent/10) silently produce no CSS.
-                // color-mix() accepts hex, so we derive the 10%-alpha stop from the token.
-                isActive
-                  ? 'bg-gradient-to-b from-transparent to-[color-mix(in_srgb,var(--color-accent-primary)_10%,transparent)]'
-                  : 'hover:bg-gradient-to-b hover:from-transparent hover:to-[color-mix(in_srgb,var(--color-accent-primary)_10%,transparent)]',
+                // The open tab is marked by the underline alone: no surface of its own.
               )}
             >
               {tab.avatar ? (
@@ -409,8 +434,11 @@ const TabBar = memo(function TabBarImpl({
                   <tab.icon
                     className={cn(
                       'h-4 w-4 transition-colors content-md:h-6 content-md:w-6',
-                      isActive ? 'text-ods-accent' : 'text-ods-text-secondary',
+                      isActive
+                        ? !tab.accent && 'text-ods-accent'
+                        : 'text-ods-text-secondary group-hover:text-ods-text-primary',
                     )}
+                    style={isActive && tab.accent ? { color: tab.accent } : undefined}
                   />
                   {tab.indicator && <StatusDot indicator={tab.indicator} className="absolute right-0 top-[-3px]" />}
                 </div>
@@ -425,7 +453,7 @@ const TabBar = memo(function TabBarImpl({
                   <span
                     className={cn(
                       'whitespace-nowrap transition-colors text-h4',
-                      isActive ? 'text-ods-text-primary' : 'text-ods-text-secondary',
+                      isActive ? 'text-ods-text-primary' : 'text-ods-text-secondary group-hover:text-ods-text-primary',
                     )}
                   >
                     {tab.label}
@@ -471,11 +499,11 @@ const TabBar = memo(function TabBarImpl({
           // tests) rather than incidental styling.
           data-testid="tab-navigation-underline"
           className={cn(
-            'pointer-events-none absolute bottom-0 left-0 bg-ods-accent motion-reduce:transition-none',
-            hasProgress ? 'h-0.5' : 'h-1',
+            'pointer-events-none absolute bottom-0 left-0 h-1 motion-reduce:transition-none',
+            !activeAccent && 'bg-ods-accent',
             !hasProgress && shouldAnimateIndicator && 'transition-[transform,width,opacity] duration-200 ease-out',
           )}
-          style={indicatorStyle}
+          style={activeAccent ? { ...indicatorStyle, backgroundColor: activeAccent } : indicatorStyle}
         />
       </div>
 

package/src/hooks/ui/use-autoplay.ts

@@ -1,59 +1,176 @@
 'use client';
 
-import { useEffect, useState } from 'react';
+import { useCallback, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import type { FocusEvent, PointerEvent } from 'react';
 import { usePrefersReducedMotionState } from './use-prefers-reduced-motion';
 
+/** 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;
 }
 
+/** Subscribes to `events` on `target` for as long as React keeps the subscription; one signal removes them all. */
+function listen(target: EventTarget, events: readonly string[], onChange: () => void): () => void {
+  const controller = new AbortController();
+  for (const event of events) target.addEventListener(event, onChange, { signal: controller.signal });
+  return () => controller.abort();
+}
+
+// The tab: hidden or not is the document's own state, read where it lives (never mirrored into React state).
+const subscribeToTab = (onChange: () => void) => {
+  const stopDocument = listen(document, ['visibilitychange'], onChange);
+  // `pageshow`: a page restored from the back/forward cache.
+  const stopWindow = listen(window, ['pageshow'], onChange);
+  return () => {
+    stopDocument();
+    stopWindow();
+  };
+};
+const tabIsHidden = () => document.visibilityState === 'hidden';
+
+const never = () => false;
+
+/** Every way a press can end. A drag the browser takes over (an image, selected text) ends in `dragend`, never `pointerup`. */
+const RELEASE_EVENTS = ['pointerup', 'pointercancel', 'mouseup', 'touchend', 'dragend', 'blur'] as const;
+
 /**
  * THE rule for anything that moves by itself (a looping demo, an
  * auto-advancing carousel): it plays while four plain facts hold, and nothing
  * 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 function useAutoplay(onScreen: boolean): UseAutoplayResult {
   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);
+
+  // The element the handlers are on: known from the first event it receives, so no ref has to be threaded to it.
+  const host = useRef<HTMLElement | null>(null);
+  // True from the moment focus comes in by keyboard until it leaves or the pointer is used.
+  const keyboardCameIn = useRef(false);
+  const subscribeToKeyboard = useCallback((onChange: () => void) => {
+    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<AutoplayHoldProps>(
+    () => ({
+      onPointerDown: event => {
+        host.current = event.currentTarget;
+        setPressed(true);
+        // One release ends it, wherever and however it happens; the same signal removes every listener.
+        const released = new AbortController();
+        const release = () => {
+          setPressed(false);
+          released.abort();
+        };
+        for (const type of RELEASE_EVENTS) window.addEventListener(type, release, { signal: released.signal });
+        // The net: a pointer that moves with no button down has been released, whatever was or was not reported.
+        window.addEventListener(
+          'pointermove',
+          (move: globalThis.PointerEvent) => {
+            if (move.buttons === 0) release();
+          },
+          { signal: released.signal },
+        );
+      },
+      onFocus: event => {
+        host.current = event.currentTarget;
+        // Only focus that arrives by keyboard holds it (the browser draws its ring as it comes in).
+        if (event.target.matches(':focus-visible')) keyboardCameIn.current = true;
+      },
+    }),
+    [],
+  );
+
+  // Bumped by `release`, so the keyboard store re-reads after it lets go.
+  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/src/hooks/ui/use-in-view.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useEffect, useState } from 'react';
 
 export interface UseInViewOptions {
   /**
@@ -43,49 +43,42 @@ const STEPS = Array.from({ length: 21 }, (_, i) => i / 20);
  * `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 function useInView<T extends Element = HTMLElement>({
   threshold = 0,
   rootMargin = '0px',
   initial = false,
 }: UseInViewOptions = {}): UseInViewResult<T> {
-  const [inView, setInView] = useState(initial);
-  const observerRef = useRef<IntersectionObserver | null>(null);
-
-  const disconnect = useCallback(() => {
-    observerRef.current?.disconnect();
-    observerRef.current = null;
-  }, []);
-
-  const ref = useCallback(
-    (node: T | null) => {
-      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],
-  );
+  // The element, as state: the effect below is keyed on it. `setNode` is the ref (stable).
+  const [node, setNode] = useState<T | null>(null);
+  const [seen, setSeen] = useState<{ node: T; inView: boolean } | null>(null);
 
-  useEffect(() => disconnect, [disconnect]);
+  useEffect(() => {
+    if (!node || typeof IntersectionObserver === 'undefined') return undefined;
+    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]);
 
-  return { ref, inView };
+  // No element: not in view. An element the observer has not reported on yet (or cannot be observed): `initial`.
+  const inView = !node ? false : seen?.node === node ? seen.inView : initial;
+  return { ref: setNode, inView };
 }

package/src/hooks/use-agent-identities.ts

@@ -8,6 +8,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. */

package/src/hooks/use-scenario-player.ts

@@ -1,11 +1,11 @@
 'use client';
 
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { useAutoplay } from './ui/use-autoplay';
+import { type AutoplayHoldProps, useAutoplay } from './ui/use-autoplay';
 
 /**
  * How soon the first step follows the moment the demo becomes playable (it
- * scrolled into view, the tab came back, play was pressed). A demo that sits
+ * scrolled into view, the tab came back, the visitor let go of it). A demo that sits
  * still for a whole step after it appears reads as broken; one that moves
  * within a third of a second reads as responding to you.
  */
@@ -32,6 +32,14 @@ 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 {
@@ -39,9 +47,16 @@ export interface UseScenarioPlayerResult {
   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. */
@@ -60,14 +75,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 function useScenarioPlayer({
   scenarioCount,
@@ -77,9 +93,10 @@ export function useScenarioPlayer({
   enabled = true,
   initialScenario = 0,
   startAtEnd = false,
+  emptyFirstStep = true,
 }: UseScenarioPlayerOptions): UseScenarioPlayerResult {
   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);
@@ -89,6 +106,9 @@ export function useScenarioPlayer({
   const step = reducedMotion ? lastStep : Math.min(rawStep, lastStep);
 
   const playing = auto.playing && scenarioCount > 0;
+  // Latched the first time it may play (state derived during render).
+  const [started, setStarted] = useState(false);
+  if (playing && !started) setStarted(true);
 
   // True from the moment it becomes playable until its first tick has been scheduled.
   const starting = useRef(false);
@@ -98,9 +118,12 @@ export function useScenarioPlayer({
     wasPlaying.current = playing;
     if (!playing) return undefined;
     const atEnd = rawStep >= lastStep;
-    // The first step after it becomes playable comes quickly. A finished
-    // scenario still holds its full time: it is there to be read.
-    const quickStart = starting.current && !atEnd;
+    // The first step comes quickly, both after it becomes playable and at the
+    // top of every scenario whose step 0 is the empty stage (the rotation
+    // moved on, or the visitor chose a tab): a stage that sits empty for a
+    // whole step after a tap reads as not responding. A finished scenario still
+    // holds its full time: it is there to be read.
+    const quickStart = emptyFirstStep && (starting.current || rawStep === 0) && !atEnd;
     starting.current = false;
     const timer = setTimeout(
       () => {
@@ -114,24 +137,25 @@ export 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]);
 
+  // A visitor's choice is an instruction to play from there: it lets go of any hold.
   const setStep = useCallback(
     (next: number) => {
       setRawStep(Math.max(0, Math.min(lastStep, next)));
-      setPaused(false);
+      release();
     },
-    [lastStep, setPaused],
+    [lastStep, release],
   );
 
   const go = useCallback(
     (next: number) => {
       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 };
 }

package/src/schemas/contact-schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 // Dropdown option constants — re-exported by `<ContactForm>` consumers
 // that want to surface their own custom Select widgets keyed on the

package/src/schemas/meeting-booking-schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod';
 
 /**
  * Meeting-booking wire contracts + validation factory.

package/src/styles/fonts.css

@@ -59,6 +59,32 @@
   src: url('./fonts/dm-sans-latin-700-normal.woff2') format('woff2');
 }
 
+/* Metric-matched fallbacks: what is drawn until the two files above arrive
+   (`font-display: swap`). A system font scaled to the web font's advance width
+   and line box, so the text keeps its line breaks and height when the swap
+   happens and nothing below it moves (layout shift). The figures are measured
+   from the files in ./fonts: Azeret Mono's advance is 0.65em against 0.60em
+   for the system monospaces, DM Sans averages 6% wider than Arial. The
+   overrides are the web font's own ascent and descent divided by the scale. */
+@font-face {
+  font-family: 'Azeret Mono Fallback';
+  src:
+    local('Menlo'), local('Monaco'), local('Courier New'), local('Liberation Mono'), local('DejaVu Sans Mono'),
+    local('Roboto Mono'), local('Droid Sans Mono');
+  size-adjust: 108.33%;
+  ascent-override: 86.5%;
+  descent-override: 21.2%;
+  line-gap-override: 0%;
+}
+@font-face {
+  font-family: 'DM Sans Fallback';
+  src: local('Arial'), local('Helvetica'), local('Liberation Sans'), local('Roboto');
+  size-adjust: 106%;
+  ascent-override: 93.6%;
+  descent-override: 29.2%;
+  line-gap-override: 0%;
+}
+
 :root {
   --font-azeret-mono: 'Azeret Mono';
   --font-dm-sans: 'DM Sans';

package/src/styles/ods-design-tokens.css

@@ -7,9 +7,11 @@
 
   /* Font Families */
   --font-family-heading:
-    'Azeret Mono', 'SF Mono', Monaco, Inconsolata, 'Roboto Mono', Consolas, 'Courier New', monospace;
+    'Azeret Mono', 'Azeret Mono Fallback', 'SF Mono', Monaco, Inconsolata, 'Roboto Mono', Consolas, 'Courier New',
+    monospace;
   --font-family-body:
-    'DM Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+    'DM Sans', 'DM Sans Fallback', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial,
+    sans-serif;
 
   /* Font Weights */
   --font-weight-medium: 500;

package/dist/aicpa-soc2-logo-icon-CJ5JRV6J.cjs

@@ -1,7 +0,0 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";
-
-
-var _chunkHVZBIXCZcjs = require('./chunk-HVZBIXCZ.cjs');
-
-
-exports.AicpaSoc2LogoIcon = _chunkHVZBIXCZcjs.AicpaSoc2LogoIcon;