@flamingo-stack/openframe-frontend-core 0.0.506 → 0.0.507

package/dist/utils/walkthrough-deep-link.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Walkthrough-video deep link — the ONE home for the query param that opens
+ * the floating walkthrough widget's theater full-screen (paused) on page
+ * load. Consumed by the widget itself (`FloatingWalkthroughVideo` defaults
+ * its `deepLinkParam` prop to this) and by hosts that MINT deep-link URLs
+ * (invitation emails) or carry the param across redirects (the hub's
+ * auth-wall proxy). Lives beside `dismissal-storage.ts` — the same
+ * widget-adjacent naming-layer altitude.
+ */
+/** `?walkthrough=1` — presence-based on the read side (any value counts);
+ *  `=1` is just the canonical value URL minters write. */
+export declare const WALKTHROUGH_OPEN_QUERY_PARAM = "walkthrough";
+/** Append the theater deep-link param to a URL (absolute or relative). */
+export declare function withWalkthroughOpenParam(url: string): string;
+//# sourceMappingURL=walkthrough-deep-link.d.ts.map

package/dist/utils/walkthrough-deep-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walkthrough-deep-link.d.ts","sourceRoot":"","sources":["../../src/utils/walkthrough-deep-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;0DAC0D;AAC1D,eAAO,MAAM,4BAA4B,gBAAgB,CAAC;AAE1D,0EAA0E;AAC1E,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.506",
+  "version": "0.0.507",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/features/.floating-walkthrough-video.md

@@ -0,0 +1,38 @@
+<!-- source-hash: 47c31b34796bb8d1bc274d1012e9c9e3 -->
+Floating per-platform walkthrough/demo video widget. Renders a collapsed corner card (hover preview, transport controls, cookie dismissal) that opens a pure-theater dialog — a centered 16:9 stage on a dimmed backdrop. The host supplies the video data and the current pathname; the widget owns every playback state handoff between card, hover preview, and theater.
+
+## Key Components
+
+### Exports
+
+- **`FloatingWalkthroughVideo`** — The widget. Controlled (`open` + `onOpenChange`) or uncontrolled (`defaultOpen`) theater state.
+- **`WalkthroughVideoData`** — Wire-shape contract: `mainVideoUrl` / `youtubeUrl` (YouTube wins when both are set), `posterUrl`, `captionsUrl` (relative `/api/captions/...` path), `title`, `presenterAvatarUrl`, `position` (`'left' | 'right'` bottom-corner pin), `id` (drives id-match cookie dismissal — a new video re-shows a dismissed card).
+- **`FloatingWalkthroughVideoProps`** — See behaviors below for the non-obvious ones.
+
+### Key Behaviors
+
+- **Appear gate**: the collapsed card mounts after `appearDelayMs` (default 3000 ms) + an idle callback, and never renders when dismissed. The THEATER is deliberately NOT gated — a host `open={true}` or `defaultOpen` can force it before the card appears or after dismissal, which is what makes deep links work.
+- **`deepLinkParam`** — query-param NAME (defaults to `WALKTHROUGH_OPEN_QUERY_PARAM`, `'walkthrough'`, from `utils/walkthrough-deep-link.ts`; pass `''` to disable): when present in `window.location.search` at first client render, the theater opens immediately and PAUSED — `defaultOpen + defaultOpenPaused` decided inside the component, so hosts don't defer their first render to read the URL. Presence-based, read once (deep links arrive by full page load). SSR-safe: the server renders closed and the theater lives in a portal. URL minters (emails, redirects) use the sibling `withWalkthroughOpenParam(url)`.
+- **`defaultOpenPaused`** — with `defaultOpen`, the initial theater session starts PAUSED instead of autoplaying. For deep links (e.g. the hub's `?walkthrough=1`), where the open has no user gesture and unrequested audio/motion would be hostile. File player: both autoplay flags suppressed (MuxPlayer mounts paused on its poster). YouTube: `autoActivate` suppressed instead — the activated iframe hardcodes `autoplay=1`, so the click-to-play facade IS the paused presentation. The paused session is exactly the initial `defaultOpen` theater: it ends when the NEXT (gesture- or host-driven) open mounts a fresh theater, which autoplays as usual. It is deliberately NOT cleared on close — the closing player stays mounted through the dialog's exit animation, and a prop flip there would restart playback.
+- **Resume handoff**: closing the theater mid-play hands the timestamp + mute intent back to the card, which continues playback inline; reopening seeds the theater from the live card position. A finished video reopens at 0, not its own last frame.
+- **Dismissal**: cookie-based, id-matched (mirrors the announcement bar). `dismissal={false}` removes the X entirely; `dismissal.storageKey` is the per-platform cookie name (see `walkthroughDismissCookieName`).
+- **`pathname`**: route identity from the host — the lib can't observe navigation. Changing it re-queries the footer IntersectionObserver target (`hideNearSelector`, default `footer`) that fades the card out over the footer.
+
+## Usage Example
+
+```typescript
+// Host layout (hub: components/shared/global-walkthrough-video-client.tsx)
+<FloatingWalkthroughVideo
+  video={video}
+  pathname={pathname}
+  // Deep link (?walkthrough=1) is built in: `deepLinkParam` defaults to
+  // WALKTHROUGH_OPEN_QUERY_PARAM — theater opens immediately, PAUSED.
+  dismissal={{ storageKey: walkthroughDismissCookieName(platform) }}
+/>
+```
+
+> **Deep-link contract:** prefer `deepLinkParam` — the component reads the URL itself at the right moment. If a host drives `defaultOpen` manually instead, it is a load-time value: decide it BEFORE the component's first render, not by flipping a prop afterwards.
+
+## Source
+
+[`floating-walkthrough-video.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/openframe-frontend-core/src/components/features/floating-walkthrough-video.tsx)

package/src/components/features/floating-walkthrough-video.tsx

@@ -57,6 +57,7 @@ import {
   isWalkthroughDismissed,
   dismissWalkthrough,
 } from '../../utils/dismissal-storage';
+import { WALKTHROUGH_OPEN_QUERY_PARAM } from '../../utils/walkthrough-deep-link';
 
 /** Wire-shape data for the widget. Kept as the shared contract the hub DAL
  *  re-exports as `PublicWalkthroughVideo & { id }`. `mainVideoUrl`/`youtubeUrl`
@@ -82,6 +83,23 @@ export interface FloatingWalkthroughVideoProps {
   open?: boolean;
   onOpenChange?: (open: boolean) => void;
   defaultOpen?: boolean;
+  /** With `defaultOpen`: the initial theater starts PAUSED instead of
+   *  autoplaying — for deep links (`?walkthrough=1`), where the open has no
+   *  user gesture and unrequested audio/motion would be hostile. Applies to
+   *  the initial `defaultOpen` session only: it ends when the NEXT open —
+   *  gesture-driven (card click) or host-driven (`open` flipping true) —
+   *  mounts a fresh theater, which autoplays as usual. */
+  defaultOpenPaused?: boolean;
+  /** Query-param NAME that deep-links into the theater: when present in
+   *  `window.location.search` at first client render, the theater opens
+   *  immediately and PAUSED — `defaultOpen + defaultOpenPaused` decided
+   *  inside the component, so hosts don't defer their first render to read
+   *  the URL. Defaults to `WALKTHROUGH_OPEN_QUERY_PARAM` ('walkthrough');
+   *  pass '' to disable. Presence-based (any value counts), read ONCE at
+   *  mount (deep links arrive by full page load, not client navigation).
+   *  SSR-safe: the server renders closed, and the theater lives in a portal,
+   *  so the hydrated (non-portal) markup is identical either way. */
+  deepLinkParam?: string;
   label?: string;
   appearDelayMs?: number;
   /** Cookie-based dismissal (id-match, mirrors the announcement bar). `false`
@@ -111,6 +129,8 @@ export function FloatingWalkthroughVideo({
   open: openProp,
   onOpenChange,
   defaultOpen,
+  defaultOpenPaused,
+  deepLinkParam = WALKTHROUGH_OPEN_QUERY_PARAM,
   label = 'Play Demo Video',
   appearDelayMs = 3000,
   dismissal = {},
@@ -171,8 +191,29 @@ export function FloatingWalkthroughVideo({
   }, []);
 
   // --- controlled/uncontrolled open ---
-  const [openState, setOpenState] = useState(Boolean(defaultOpen));
+  // Deep link: read ONCE, synchronously, on the first client render — the
+  // theater's autoplay props are load-time, so the decision must exist before
+  // the render that mounts it (an effect would be one commit too late). The
+  // lazy initializer never re-runs, so client navigation can't re-trigger it.
+  const [deepLinkHit] = useState(() => {
+    if (!deepLinkParam || typeof window === 'undefined') return false;
+    try {
+      return new URLSearchParams(window.location.search).has(deepLinkParam);
+    } catch {
+      return false;
+    }
+  });
+  const [openState, setOpenState] = useState(Boolean(defaultOpen) || deepLinkHit);
   const open = openProp !== undefined ? openProp : openState;
+  // The paused deep-link session — see `defaultOpenPaused`. Load-time-safe:
+  // the theater player's autoplay props are read once at construction, and
+  // this is set before the first render that mounts it. Cleared on the next
+  // OPEN transition only (the prevOpen sync below), right before a fresh
+  // theater constructs — never on close, where the closing player is still
+  // mounted and a prop flip would restart it (see the sync's comment).
+  const [pausedOpenSession, setPausedOpenSession] = useState(
+    Boolean(defaultOpen && defaultOpenPaused) || deepLinkHit,
+  );
 
   // --- refs & continuation state ---
   const previewHandleRef = useRef<VideoPlayerHandle | null>(null);
@@ -400,6 +441,16 @@ export function FloatingWalkthroughVideo({
   const [prevOpen, setPrevOpen] = useState(open);
   if (open !== prevOpen) {
     setPrevOpen(open);
+    // RISING edge only: the paused deep-link session ends when the NEXT
+    // (gesture- or host-driven) open mounts a fresh theater — this re-render
+    // commits the cleared flag before that content constructs, so it
+    // autoplays as usual. NEVER clear on close: Radix keeps the closing
+    // theater mounted through its exit animation, and flipping the flag then
+    // flips `autoPlayUnmuted` false→true on the STILL-MOUNTED player, whose
+    // autoplay kick effect resurrects playback — audible after close and
+    // doubled against the card's resume player. Idempotent, so a
+    // discarded-and-retried render attempt decides the same way.
+    if (open && pausedOpenSession) setPausedOpenSession(false);
     // Compared, not cleared: React can discard and re-run a render attempt
     // (concurrent interruption, error retry, a host wrapping setOpen in
     // startTransition). A read-and-clear would decide differently on the
@@ -874,11 +925,15 @@ export function FloatingWalkthroughVideo({
               playerHandleRef={theaterHandleRef}
               // Muted still means PLAYING: without this a deliberately muted
               // card opened a paused theater, breaking parity with the
-              // unmuted path.
-              autoPlay={theaterStart.muted}
-              autoPlayUnmuted={!theaterStart.muted}
+              // unmuted path. EXCEPT the paused deep-link session, which
+              // starts fully stopped: no autoplay flag at all, and for
+              // YouTube no autoActivate either — the activated iframe
+              // hardcodes `autoplay=1`, so staying on the facade IS the
+              // paused presentation (clicking it activates and plays).
+              autoPlay={theaterStart.muted && !pausedOpenSession}
+              autoPlayUnmuted={!theaterStart.muted && !pausedOpenSession}
               startMuted={theaterStart.muted}
-              autoActivate
+              autoActivate={!pausedOpenSession}
               suspended={suspended}
               onMutedFallbackChange={st => { theaterForcedMuteRef.current = st.muted; }}
               onEnded={() => { endedLatchRef.current = true; }}

package/src/utils/index.ts

@@ -96,6 +96,8 @@ export * from './announcement-storage'
 // cookie id-match dismissal store (walkthrough video widget)
 export * from './dismiss-cookie'
 export * from './dismissal-storage'
+// walkthrough deep-link query param (widget default + host URL minters)
+export * from './walkthrough-deep-link'
 
 // Image-proxy URL builder (pure, runtime-configurable)
 export {

package/src/utils/walkthrough-deep-link.ts

@@ -0,0 +1,18 @@
+/**
+ * Walkthrough-video deep link — the ONE home for the query param that opens
+ * the floating walkthrough widget's theater full-screen (paused) on page
+ * load. Consumed by the widget itself (`FloatingWalkthroughVideo` defaults
+ * its `deepLinkParam` prop to this) and by hosts that MINT deep-link URLs
+ * (invitation emails) or carry the param across redirects (the hub's
+ * auth-wall proxy). Lives beside `dismissal-storage.ts` — the same
+ * widget-adjacent naming-layer altitude.
+ */
+
+/** `?walkthrough=1` — presence-based on the read side (any value counts);
+ *  `=1` is just the canonical value URL minters write. */
+export const WALKTHROUGH_OPEN_QUERY_PARAM = 'walkthrough';
+
+/** Append the theater deep-link param to a URL (absolute or relative). */
+export function withWalkthroughOpenParam(url: string): string {
+  return `${url}${url.includes('?') ? '&' : '?'}${WALKTHROUGH_OPEN_QUERY_PARAM}=1`;
+}