npm - @scenar/embed - Versions diffs - 0.3.0 - Mend

@scenar/embed 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (43) hide show

package/src/mount.test.ts ADDED Viewed

@@ -0,0 +1,202 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { type EmbedAspectRatio, type EmbedMount, createEmbedMount } from "./mount.js";
+const SRC = "https://embed.example/tour/";
+const ORIGIN = "https://embed.example";
+/** Build a framed Scenar embed resize message (protocol v1). */
+function resizeMessage(widthPx: unknown, heightPx: unknown) {
+  return { source: "scenar-embed", v: 1, type: "resize", widthPx, heightPx };
+}
+/**
+ * Dispatch a window `message` event, attributed to a given origin and source
+ * window. The controller adopts a message only when both the origin matches the
+ * pinned embed origin and the source is the embed's own iframe window.
+ */
+function post(
+  data: unknown,
+  { origin = ORIGIN, source = null as MessageEventSource | null } = {},
+) {
+  const event = new MessageEvent("message", { data, origin });
+  Object.defineProperty(event, "source", { value: source, configurable: true });
+  window.dispatchEvent(event);
+}
+/**
+ * A detached iframe never navigates when its `src` is set (no browsing context),
+ * so tests can assert on `iframe.src` without jsdom navigation noise. We pin a
+ * unique sentinel as its `contentWindow` so the controller's per-frame
+ * `event.source` check is genuinely exercised.
+ */
+function makeIframe(): { iframe: HTMLIFrameElement; frame: MessageEventSource } {
+  const iframe = document.createElement("iframe");
+  // The controller posts commands to contentWindow (e.g. `destroy` on teardown),
+  // so the sentinel must carry a postMessage.
+  const frame = { postMessage: () => {} } as unknown as MessageEventSource;
+  Object.defineProperty(iframe, "contentWindow", { value: frame, configurable: true });
+  return { iframe, frame };
+}
+/** Let queued MutationObserver callbacks deliver. */
+function flushMicrotasks(): Promise<void> {
+  return new Promise((r) => setTimeout(r, 0));
+}
+let mounts: EmbedMount[] = [];
+function track(mount: EmbedMount): EmbedMount {
+  mounts.push(mount);
+  return mount;
+}
+beforeEach(() => {
+  document.documentElement.className = "";
+});
+afterEach(() => {
+  for (const mount of mounts) mount.destroy();
+  mounts = [];
+  document.documentElement.className = "";
+});
+describe("createEmbedMount — theme", () => {
+  it("applies ?theme=light by default (no dark class on <html>)", () => {
+    const { iframe } = makeIframe();
+    track(createEmbedMount(iframe, { src: SRC }));
+    expect(iframe.src).toBe("https://embed.example/tour/?theme=light");
+  });
+  it("applies ?theme=dark when the host is dark", () => {
+    document.documentElement.classList.add("dark");
+    const { iframe } = makeIframe();
+    track(createEmbedMount(iframe, { src: SRC }));
+    expect(iframe.src).toBe("https://embed.example/tour/?theme=dark");
+  });
+  it("pins a fixed theme regardless of the host (theme=dark)", () => {
+    const { iframe } = makeIframe();
+    track(createEmbedMount(iframe, { src: SRC, theme: "dark" }));
+    expect(iframe.src).toBe("https://embed.example/tour/?theme=dark");
+  });
+  it("reloads in the new theme when the host toggles dark mode (auto)", async () => {
+    const { iframe } = makeIframe();
+    track(createEmbedMount(iframe, { src: SRC, theme: "auto" }));
+    expect(iframe.src).toContain("theme=light");
+    document.documentElement.classList.add("dark");
+    await flushMicrotasks();
+    expect(iframe.src).toContain("theme=dark");
+    document.documentElement.classList.remove("dark");
+    await flushMicrotasks();
+    expect(iframe.src).toContain("theme=light");
+  });
+  it("does not observe the host when the theme is pinned", async () => {
+    const { iframe } = makeIframe();
+    track(createEmbedMount(iframe, { src: SRC, theme: "light" }));
+    document.documentElement.classList.add("dark");
+    await flushMicrotasks();
+    expect(iframe.src).toContain("theme=light");
+  });
+});
+describe("createEmbedMount — resize → aspect ratio", () => {
+  it("reports the exact size from a valid resize sent by its own frame", () => {
+    const ratios: EmbedAspectRatio[] = [];
+    const { iframe, frame } = makeIframe();
+    track(createEmbedMount(iframe, { src: SRC, onAspectRatio: (r) => ratios.push(r) }));
+    post(resizeMessage(900, 520), { source: frame });
+    expect(ratios).toEqual([{ widthPx: 900, heightPx: 520 }]);
+  });
+  it("routes each resize only to the frame that sent it (two embeds, one page)", () => {
+    const aRatios: EmbedAspectRatio[] = [];
+    const bRatios: EmbedAspectRatio[] = [];
+    const a = makeIframe();
+    const b = makeIframe();
+    track(createEmbedMount(a.iframe, { src: SRC, onAspectRatio: (r) => aRatios.push(r) }));
+    track(createEmbedMount(b.iframe, { src: SRC, onAspectRatio: (r) => bRatios.push(r) }));
+    post(resizeMessage(700, 400), { source: b.frame });
+    expect(bRatios).toEqual([{ widthPx: 700, heightPx: 400 }]);
+    expect(aRatios).toEqual([]);
+    post(resizeMessage(1000, 300), { source: a.frame });
+    expect(aRatios).toEqual([{ widthPx: 1000, heightPx: 300 }]);
+    expect(bRatios).toEqual([{ widthPx: 700, heightPx: 400 }]);
+  });
+});
+describe("createEmbedMount — ignores messages that do not match the contract", () => {
+  let iframe: HTMLIFrameElement;
+  let frame: MessageEventSource;
+  let onAspectRatio: ReturnType<typeof vi.fn>;
+  let onEvent: ReturnType<typeof vi.fn>;
+  beforeEach(() => {
+    ({ iframe, frame } = makeIframe());
+    onAspectRatio = vi.fn();
+    onEvent = vi.fn();
+    track(createEmbedMount(iframe, { src: SRC, onAspectRatio, onEvent }));
+  });
+  it("rejects a spoofed origin", () => {
+    post(resizeMessage(900, 520), { origin: "https://evil.example", source: frame });
+    expect(onAspectRatio).not.toHaveBeenCalled();
+  });
+  it("rejects a resize from a frame it does not own", () => {
+    post(resizeMessage(900, 520), { source: window });
+    expect(onAspectRatio).not.toHaveBeenCalled();
+  });
+  it("rejects a foreign source tag", () => {
+    post({ source: "other-widget", v: 1, type: "resize", widthPx: 9, heightPx: 5 }, { source: frame });
+    expect(onAspectRatio).not.toHaveBeenCalled();
+  });
+  it("rejects a mismatched protocol version", () => {
+    post({ source: "scenar-embed", v: 999, type: "resize", widthPx: 9, heightPx: 5 }, { source: frame });
+    expect(onAspectRatio).not.toHaveBeenCalled();
+  });
+  it("rejects a malformed payload", () => {
+    post(resizeMessage("huge", 520), { source: frame });
+    post(resizeMessage(900, Number.NaN), { source: frame });
+    post("not-an-object", { source: frame });
+    expect(onAspectRatio).not.toHaveBeenCalled();
+  });
+  it("still forwards non-resize events to onEvent without touching layout", () => {
+    post({ source: "scenar-embed", v: 1, type: "completed" }, { source: frame });
+    expect(onEvent).toHaveBeenCalledWith({ type: "completed" });
+    expect(onAspectRatio).not.toHaveBeenCalled();
+  });
+});
+describe("createEmbedMount — teardown", () => {
+  it("stops reacting to resizes after destroy", () => {
+    const ratios: EmbedAspectRatio[] = [];
+    const { iframe, frame } = makeIframe();
+    const mount = createEmbedMount(iframe, { src: SRC, onAspectRatio: (r) => ratios.push(r) });
+    mount.destroy();
+    post(resizeMessage(900, 520), { source: frame });
+    expect(ratios).toEqual([]);
+  });
+  it("stops observing host theme after destroy", async () => {
+    const { iframe } = makeIframe();
+    const mount = createEmbedMount(iframe, { src: SRC, theme: "auto" });
+    expect(iframe.src).toContain("theme=light");
+    mount.destroy();
+    document.documentElement.classList.add("dark");
+    await flushMicrotasks();
+    expect(iframe.src).toContain("theme=light");
+  });
+});

package/src/mount.ts ADDED Viewed

@@ -0,0 +1,113 @@
+import {
+  type ScenarEmbedEvent,
+  type ScenarEmbedHostController,
+  createEmbedHostController,
+} from "@scenar/core";
+import {
+  type ScenarEmbedTheme,
+  applyThemeToSrc,
+  originFromSrc,
+  resolveTheme,
+} from "./resolve.js";
+/** The embed's exact rendered size, reported over the `resize` event. */
+export interface EmbedAspectRatio {
+  readonly widthPx: number;
+  readonly heightPx: number;
+}
+/** Options for {@link createEmbedMount}. */
+export interface EmbedMountOptions {
+  /** The absolute embed URL, without a theme query (the mount adds it). */
+  readonly src: string;
+  /** Theme strategy (default `auto`). */
+  readonly theme?: ScenarEmbedTheme;
+  /** Called whenever the embed reports a new rendered size, for host layout. */
+  readonly onAspectRatio?: (ratio: EmbedAspectRatio) => void;
+  /** Called for every well-formed event from the pinned embed. */
+  readonly onEvent?: (event: ScenarEmbedEvent) => void;
+}
+/** A live mount: the host controller plus a teardown for all listeners. */
+export interface EmbedMount {
+  /** Imperative transport (play/pause/seek/setMuted/setVolume) over the bridge. */
+  readonly controller: ScenarEmbedHostController;
+  /** Disconnect the theme observer and the controller's message listener. */
+  destroy(): void;
+}
+/** Whether the host page is in dark mode (the `dark` class on `<html>`). */
+function hostPrefersDark(): boolean {
+  return (
+    typeof document !== "undefined" &&
+    document.documentElement.classList.contains("dark")
+  );
+}
+/**
+ * Wire an existing iframe to a hosted Scenar tour: set its themed `src`, pin the
+ * embed origin, adopt the embed's reported aspect ratio, and (for `theme:auto`)
+ * track the host's dark mode.
+ *
+ * This is the one place the loader's behavior lives. The `<scenar-embed>`
+ * element and the React `<ScenarEmbed>` are thin adapters that create the iframe
+ * + own layout, then hand it here — so neither re-implements the bridge, exactly
+ * as {@link createEmbedHostController} is shared by the console and this loader.
+ *
+ * The caller owns the iframe element (and removes it for full teardown); this
+ * function owns only the listeners it adds, all released by {@link EmbedMount.destroy}.
+ */
+export function createEmbedMount(
+  iframe: HTMLIFrameElement,
+  options: EmbedMountOptions,
+): EmbedMount {
+  const { src, theme = "auto", onAspectRatio, onEvent } = options;
+  const origin = originFromSrc(src);
+  // Track the last applied theme so an unrelated `<html>` class mutation never
+  // triggers a needless reload — only a real light/dark flip reassigns `src`.
+  let appliedTheme: "light" | "dark" | null = null;
+  const applyTheme = (): void => {
+    const resolved = resolveTheme(theme, hostPrefersDark());
+    if (resolved === appliedTheme) return;
+    appliedTheme = resolved;
+    iframe.src = applyThemeToSrc(src, resolved);
+  };
+  const controller = createEmbedHostController(
+    { iframe, origin },
+    {
+      onEvent: (event) => {
+        if (event.type === "resize") {
+          onAspectRatio?.({ widthPx: event.widthPx, heightPx: event.heightPx });
+        }
+        onEvent?.(event);
+      },
+    },
+  );
+  let observer: MutationObserver | undefined;
+  if (
+    theme === "auto" &&
+    typeof MutationObserver !== "undefined" &&
+    typeof document !== "undefined"
+  ) {
+    observer = new MutationObserver(applyTheme);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["class"],
+    });
+  }
+  // Assign the initial themed src last, so the controller's listener is already
+  // attached when the frame begins loading.
+  applyTheme();
+  return {
+    controller,
+    destroy() {
+      observer?.disconnect();
+      controller.destroy();
+    },
+  };
+}

package/src/react.test.tsx ADDED Viewed

@@ -0,0 +1,89 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { createRef } from "react";
+import { render, screen, act, cleanup } from "@testing-library/react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { ScenarEmbed, type ScenarEmbedHandle } from "./react.js";
+const SRC = "https://embed.example/tour/";
+const ORIGIN = "https://embed.example";
+afterEach(() => {
+  cleanup();
+  document.documentElement.className = "";
+});
+/** Pin a sentinel window (with a spyable postMessage) as the iframe's frame. */
+function stubFrame(iframe: HTMLIFrameElement): { postMessage: ReturnType<typeof vi.fn> } {
+  const postMessage = vi.fn();
+  const frame = { postMessage } as unknown as MessageEventSource;
+  Object.defineProperty(iframe, "contentWindow", { value: frame, configurable: true });
+  return { postMessage };
+}
+function postResize(iframe: HTMLIFrameElement, widthPx: number, heightPx: number): void {
+  const event = new MessageEvent("message", {
+    data: { source: "scenar-embed", v: 1, type: "resize", widthPx, heightPx },
+    origin: ORIGIN,
+  });
+  Object.defineProperty(event, "source", { value: iframe.contentWindow, configurable: true });
+  act(() => {
+    window.dispatchEvent(event);
+  });
+}
+describe("ScenarEmbed (React)", () => {
+  it("renders a responsive, lazy iframe and assigns the themed src after mount", () => {
+    render(<ScenarEmbed src={SRC} title="Welcome tour" />);
+    const iframe = screen.getByTitle("Welcome tour") as HTMLIFrameElement;
+    stubFrame(iframe);
+    expect(iframe.getAttribute("loading")).toBe("lazy");
+    expect(iframe.getAttribute("allow")).toBe("autoplay; fullscreen");
+    expect(iframe.src).toBe("https://embed.example/tour/?theme=light");
+    const wrapper = iframe.parentElement as HTMLElement;
+    expect(wrapper.style.aspectRatio).toBe("896 / 480");
+  });
+  it("resolves id + base into the embed src", () => {
+    render(<ScenarEmbed id="welcome" base="https://embed.example/demos" title="t" />);
+    const iframe = screen.getByTitle("t") as HTMLIFrameElement;
+    stubFrame(iframe);
+    expect(iframe.src).toBe("https://embed.example/demos/welcome/?theme=light");
+  });
+  it("does not render a src on the server (SSR-safe, no hydration mismatch)", () => {
+    const markup = renderToStaticMarkup(<ScenarEmbed src={SRC} title="t" />);
+    expect(markup).toContain("<iframe");
+    expect(markup).not.toContain("src=");
+  });
+  it("adopts the reported aspect ratio and forwards events", () => {
+    const onEvent = vi.fn();
+    render(<ScenarEmbed src={SRC} title="t" onEvent={onEvent} />);
+    const iframe = screen.getByTitle("t") as HTMLIFrameElement;
+    stubFrame(iframe);
+    postResize(iframe, 900, 520);
+    const wrapper = iframe.parentElement as HTMLElement;
+    expect(wrapper.style.aspectRatio).toBe("900 / 520");
+    expect(onEvent).toHaveBeenCalledWith({ type: "resize", widthPx: 900, heightPx: 520 });
+  });
+  it("drives transport through the ref handle", () => {
+    const ref = createRef<ScenarEmbedHandle>();
+    render(<ScenarEmbed ref={ref} src={SRC} title="t" />);
+    const iframe = screen.getByTitle("t") as HTMLIFrameElement;
+    const { postMessage } = stubFrame(iframe);
+    act(() => {
+      ref.current?.play();
+    });
+    expect(postMessage).toHaveBeenCalledWith(
+      { source: "scenar-embed", v: 1, type: "play" },
+      ORIGIN,
+    );
+  });
+});

package/src/react.tsx ADDED Viewed

@@ -0,0 +1,121 @@
+"use client";
+import {
+  type CSSProperties,
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from "react";
+import type { ScenarEmbedEvent } from "@scenar/core";
+import { type EmbedMount, createEmbedMount } from "./mount.js";
+import {
+  type EmbedSource,
+  type ScenarEmbedTheme,
+  EMBED_BASE_ASPECT_HEIGHT,
+  EMBED_BASE_ASPECT_WIDTH,
+  resolveEmbedSrc,
+} from "./resolve.js";
+/** Accessible iframe title when the host passes none. */
+const DEFAULT_TITLE = "Interactive product tour";
+/** Imperative transport exposed through a ref, driving the bridge. */
+export interface ScenarEmbedHandle {
+  play(): void;
+  pause(): void;
+  seek(timeMs: number): void;
+  setMuted(muted: boolean): void;
+  setVolume(volume: number): void;
+}
+export interface ScenarEmbedProps extends EmbedSource {
+  /** Accessible iframe title (defaults to a generic label). */
+  readonly title?: string;
+  /** Theme strategy (default `auto`: track the host's `dark` class). */
+  readonly theme?: ScenarEmbedTheme;
+  /** Receive every well-formed event from the embed (ready/progress/etc.). */
+  readonly onEvent?: (event: ScenarEmbedEvent) => void;
+  /** Class applied to the responsive wrapper. */
+  readonly className?: string;
+  /** Extra styles merged onto the responsive wrapper. */
+  readonly style?: CSSProperties;
+}
+/**
+ * Embed a hosted Scenar tour as a responsive, theme-synced iframe — the React
+ * sibling of `<scenar-embed>`. It is a thin adapter over {@link createEmbedMount}
+ * (it does not render the custom element), so it carries no protocol logic and
+ * stays free of web-component-in-React SSR/typing friction.
+ *
+ * SSR-safe: the iframe renders without a `src` on the server and on the first
+ * client render, so hydration never mismatches; the effect then assigns the
+ * themed `src` and adopts the embed's reported aspect ratio.
+ */
+export const ScenarEmbed = forwardRef<ScenarEmbedHandle, ScenarEmbedProps>(
+  function ScenarEmbed({ src, id, base, title, theme = "auto", onEvent, className, style }, ref) {
+    const iframeRef = useRef<HTMLIFrameElement>(null);
+    const mountRef = useRef<EmbedMount | null>(null);
+    const [ratio, setRatio] = useState(
+      `${EMBED_BASE_ASPECT_WIDTH} / ${EMBED_BASE_ASPECT_HEIGHT}`,
+    );
+    // Latest onEvent without forcing a re-mount when the callback identity changes.
+    const onEventRef = useRef(onEvent);
+    onEventRef.current = onEvent;
+    const resolvedSrc = resolveEmbedSrc({ src, id, base });
+    useEffect(() => {
+      const iframe = iframeRef.current;
+      if (!iframe) return;
+      const mount = createEmbedMount(iframe, {
+        src: resolvedSrc,
+        theme,
+        onAspectRatio: ({ widthPx, heightPx }) => setRatio(`${widthPx} / ${heightPx}`),
+        onEvent: (event) => onEventRef.current?.(event),
+      });
+      mountRef.current = mount;
+      return () => {
+        mount.destroy();
+        mountRef.current = null;
+      };
+    }, [resolvedSrc, theme]);
+    useImperativeHandle(
+      ref,
+      () => ({
+        play: () => mountRef.current?.controller.play(),
+        pause: () => mountRef.current?.controller.pause(),
+        seek: (timeMs) => mountRef.current?.controller.seek(timeMs),
+        setMuted: (muted) => mountRef.current?.controller.setMuted(muted),
+        setVolume: (volume) => mountRef.current?.controller.setVolume(volume),
+      }),
+      [],
+    );
+    return (
+      <div
+        className={className}
+        style={{ position: "relative", width: "100%", aspectRatio: ratio, ...style }}
+      >
+        <iframe
+          ref={iframeRef}
+          title={title ?? DEFAULT_TITLE}
+          loading="lazy"
+          allow="autoplay; fullscreen"
+          allowFullScreen
+          style={{
+            position: "absolute",
+            inset: 0,
+            width: "100%",
+            height: "100%",
+            border: 0,
+            borderRadius: "inherit",
+          }}
+        />
+      </div>
+    );
+  },
+);

package/src/resolve.test.ts ADDED Viewed

@@ -0,0 +1,77 @@
+import { describe, it, expect } from "vitest";
+import {
+  applyThemeToSrc,
+  originFromSrc,
+  resolveEmbedSrc,
+  resolveTheme,
+} from "./resolve.js";
+describe("resolveEmbedSrc", () => {
+  it("returns an explicit src verbatim", () => {
+    expect(resolveEmbedSrc({ src: "https://e.example/tour/" })).toBe("https://e.example/tour/");
+  });
+  it("prefers src over id+base when both are given", () => {
+    expect(
+      resolveEmbedSrc({ src: "https://e.example/a/", id: "b", base: "https://e.example" }),
+    ).toBe("https://e.example/a/");
+  });
+  it("joins base + id with a single trailing slash (base without slash)", () => {
+    expect(resolveEmbedSrc({ id: "welcome", base: "https://e.example/demos" })).toBe(
+      "https://e.example/demos/welcome/",
+    );
+  });
+  it("joins base + id without doubling the slash (base with slash)", () => {
+    expect(resolveEmbedSrc({ id: "welcome", base: "https://e.example/demos/" })).toBe(
+      "https://e.example/demos/welcome/",
+    );
+  });
+  it("throws an actionable error when neither src nor id+base is provided", () => {
+    expect(() => resolveEmbedSrc({})).toThrowError(/provide `src`, or both `id` and `base`/);
+    expect(() => resolveEmbedSrc({ id: "welcome" })).toThrowError(/id` and `base`/);
+  });
+});
+describe("resolveTheme", () => {
+  it("pins light and dark regardless of host state", () => {
+    expect(resolveTheme("light", true)).toBe("light");
+    expect(resolveTheme("light", false)).toBe("light");
+    expect(resolveTheme("dark", false)).toBe("dark");
+    expect(resolveTheme("dark", true)).toBe("dark");
+  });
+  it("defers to the host's resolved state under auto", () => {
+    expect(resolveTheme("auto", true)).toBe("dark");
+    expect(resolveTheme("auto", false)).toBe("light");
+  });
+});
+describe("applyThemeToSrc", () => {
+  it("adds the theme query when absent", () => {
+    expect(applyThemeToSrc("https://e.example/tour/", "dark")).toBe(
+      "https://e.example/tour/?theme=dark",
+    );
+  });
+  it("replaces an existing theme query rather than appending", () => {
+    expect(applyThemeToSrc("https://e.example/tour/?theme=dark", "light")).toBe(
+      "https://e.example/tour/?theme=light",
+    );
+  });
+  it("preserves other query params", () => {
+    expect(applyThemeToSrc("https://e.example/tour/?a=1", "dark")).toBe(
+      "https://e.example/tour/?a=1&theme=dark",
+    );
+  });
+});
+describe("originFromSrc", () => {
+  it("returns scheme + host + port with no path", () => {
+    expect(originFromSrc("https://e.example/tour/?theme=dark")).toBe("https://e.example");
+    expect(originFromSrc("http://localhost:4173/")).toBe("http://localhost:4173");
+  });
+});

package/src/resolve.ts ADDED Viewed

@@ -0,0 +1,80 @@
+/**
+ * Pure, DOM-free helpers shared by every adapter (the `<scenar-embed>` element,
+ * the React wrapper, and the IIFE global). Keeping URL/theme/origin resolution
+ * here — with zero DOM access — makes each rule unit-testable in isolation and
+ * guarantees the element and the React component resolve identically.
+ */
+/**
+ * How the embed's color theme is chosen.
+ *
+ * - `auto` (default) — track the host page's `dark` class on `<html>`.
+ * - `light` / `dark` — pin the theme regardless of the host.
+ */
+export type ScenarEmbedTheme = "auto" | "light" | "dark";
+/**
+ * The tour's recorded canonical viewport (mirrors `DEFAULT_VIEWPORT` in
+ * `@scenar/cli`). Used as the pre-handshake aspect-ratio baseline, before the
+ * embed reports its exact rendered size over the `resize` event.
+ */
+export const EMBED_BASE_ASPECT_WIDTH = 896;
+export const EMBED_BASE_ASPECT_HEIGHT = 480;
+/**
+ * Where a tour is served from. Pass `src` (the full embed URL) directly, or a
+ * `base` + `id` pair that resolves to `<base>/<id>/` — the convenience the React
+ * wrapper offers so docs can reference tours by slug.
+ */
+export interface EmbedSource {
+  /** The full embed URL (absolute). Takes precedence over `id` + `base`. */
+  readonly src?: string;
+  /** The published tour slug, resolved against `base`. */
+  readonly id?: string;
+  /** The base URL the `id` is resolved under (e.g. a GitHub Pages repo root). */
+  readonly base?: string;
+}
+/**
+ * Resolve an {@link EmbedSource} to a single absolute embed URL (without the
+ * theme query — that is layered on at mount time). Throws a developer-actionable
+ * error if neither form is supplied.
+ */
+export function resolveEmbedSrc(source: EmbedSource): string {
+  if (source.src) return source.src;
+  if (source.id && source.base) {
+    const base = source.base.endsWith("/") ? source.base : `${source.base}/`;
+    return `${base}${source.id}/`;
+  }
+  throw new Error("ScenarEmbed: provide `src`, or both `id` and `base`.");
+}
+/**
+ * Collapse a {@link ScenarEmbedTheme} to the concrete `light`/`dark` the embed
+ * understands. `auto` defers to `isDark` (the host's resolved state), which the
+ * caller reads from the DOM — this function stays pure.
+ */
+export function resolveTheme(theme: ScenarEmbedTheme, isDark: boolean): "light" | "dark" {
+  if (theme === "light") return "light";
+  if (theme === "dark") return "dark";
+  return isDark ? "dark" : "light";
+}
+/**
+ * Stamp the resolved theme onto an embed URL as `?theme=…`. The packed embed
+ * reads this query at load to apply its palette; changing it reloads the frame
+ * in the new theme (acceptable for an autoplay demo).
+ */
+export function applyThemeToSrc(src: string, theme: "light" | "dark"): string {
+  const url = new URL(src);
+  url.searchParams.set("theme", theme);
+  return url.toString();
+}
+/**
+ * The embed's exact origin (scheme + host + port, no path) — used to pin both
+ * inbound events and outbound commands. Derived from the embed URL.
+ */
+export function originFromSrc(src: string): string {
+  return new URL(src).origin;
+}