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/mount.js ADDED Viewed

@@ -0,0 +1,63 @@
+import { createEmbedHostController, } from "@scenar/core";
+import { applyThemeToSrc, originFromSrc, resolveTheme, } from "./resolve.js";
+/** Whether the host page is in dark mode (the `dark` class on `<html>`). */
+function hostPrefersDark() {
+    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, options) {
+    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 = null;
+    const applyTheme = () => {
+        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;
+    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();
+        },
+    };
+}
+//# sourceMappingURL=mount.js.map

package/mount.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"mount.js","sourceRoot":"","sources":["../src/mount.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,eAAe,EACf,aAAa,EACb,YAAY,GACb,MAAM,cAAc,CAAC;AA4BtB,4EAA4E;AAC5E,SAAS,eAAe;IACtB,OAAO,CACL,OAAO,QAAQ,KAAK,WAAW;QAC/B,QAAQ,CAAC,eAAe,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CACpD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAyB,EACzB,OAA0B;IAE1B,MAAM,EAAE,GAAG,EAAE,KAAK,GAAG,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAChE,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAElC,6EAA6E;IAC7E,4EAA4E;IAC5E,IAAI,YAAY,GAA4B,IAAI,CAAC;IACjD,MAAM,UAAU,GAAG,GAAS,EAAE;QAC5B,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,CAAC,CAAC;QACxD,IAAI,QAAQ,KAAK,YAAY;YAAE,OAAO;QACtC,YAAY,GAAG,QAAQ,CAAC;QACxB,MAAM,CAAC,GAAG,GAAG,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,yBAAyB,CAC1C,EAAE,MAAM,EAAE,MAAM,EAAE,EAClB;QACE,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YACjB,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC5B,aAAa,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;YACxE,CAAC;YACD,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC;KACF,CACF,CAAC;IAEF,IAAI,QAAsC,CAAC;IAC3C,IACE,KAAK,KAAK,MAAM;QAChB,OAAO,gBAAgB,KAAK,WAAW;QACvC,OAAO,QAAQ,KAAK,WAAW,EAC/B,CAAC;QACD,QAAQ,GAAG,IAAI,gBAAgB,CAAC,UAAU,CAAC,CAAC;QAC5C,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,eAAe,EAAE;YACzC,UAAU,EAAE,IAAI;YAChB,eAAe,EAAE,CAAC,OAAO,CAAC;SAC3B,CAAC,CAAC;IACL,CAAC;IAED,8EAA8E;IAC9E,0CAA0C;IAC1C,UAAU,EAAE,CAAC;IAEb,OAAO;QACL,UAAU;QACV,OAAO;YACL,QAAQ,EAAE,UAAU,EAAE,CAAC;YACvB,UAAU,CAAC,OAAO,EAAE,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json ADDED Viewed

@@ -0,0 +1,61 @@
+{
+  "name": "@scenar/embed",
+  "version": "0.3.0",
+  "description": "Drop-in host-side embedding for Scenar tours — a framework-agnostic <scenar-embed> web component and a matching React wrapper.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": [
+    "./dist/define.js",
+    "./dist/embed.global.js"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stigmer/scenar.git",
+    "directory": "packages/embed"
+  },
+  "keywords": [
+    "scenar",
+    "scenario",
+    "embed",
+    "iframe",
+    "web-component",
+    "react",
+    "demo",
+    "playback"
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./define": {
+      "types": "./define.d.ts",
+      "import": "./define.js",
+      "default": "./define.js"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "import": "./react.js",
+      "default": "./react.js"
+    },
+    "./loader": "./embed.global.js"
+  },
+  "dependencies": {
+    "@scenar/core": "0.3.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  }
+}

package/react.d.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import { type CSSProperties } from "react";
+import type { ScenarEmbedEvent } from "@scenar/core";
+import { type EmbedSource, type ScenarEmbedTheme } from "./resolve.js";
+/** 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 declare const ScenarEmbed: import("react").ForwardRefExoticComponent<ScenarEmbedProps & import("react").RefAttributes<ScenarEmbedHandle>>;
+//# sourceMappingURL=react.d.ts.map

package/react.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,aAAa,EAMnB,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,gBAAgB,EAItB,MAAM,cAAc,CAAC;AAKtB,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IAChC,IAAI,IAAI,IAAI,CAAC;IACb,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACrD,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,gHAiEvB,CAAC"}

package/react.js ADDED Viewed

@@ -0,0 +1,58 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef, useEffect, useImperativeHandle, useRef, useState, } from "react";
+import { createEmbedMount } from "./mount.js";
+import { 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";
+/**
+ * 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(function ScenarEmbed({ src, id, base, title, theme = "auto", onEvent, className, style }, ref) {
+    const iframeRef = useRef(null);
+    const mountRef = useRef(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 (_jsx("div", { className: className, style: { position: "relative", width: "100%", aspectRatio: ratio, ...style }, children: _jsx("iframe", { ref: iframeRef, title: title ?? DEFAULT_TITLE, loading: "lazy", allow: "autoplay; fullscreen", allowFullScreen: true, style: {
+                position: "absolute",
+                inset: 0,
+                width: "100%",
+                height: "100%",
+                border: 0,
+                borderRadius: "inherit",
+            } }) }));
+});
+//# sourceMappingURL=react.js.map

package/react.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"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"}

package/resolve.d.ts ADDED Viewed

@@ -0,0 +1,57 @@
+/**
+ * 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 declare const EMBED_BASE_ASPECT_WIDTH = 896;
+export declare 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 declare function resolveEmbedSrc(source: EmbedSource): string;
+/**
+ * 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 declare function resolveTheme(theme: ScenarEmbedTheme, isDark: boolean): "light" | "dark";
+/**
+ * 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 declare function applyThemeToSrc(src: string, theme: "light" | "dark"): string;
+/**
+ * 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 declare function originFromSrc(src: string): string;
+//# sourceMappingURL=resolve.d.ts.map

package/resolve.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAO3D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAIvF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAI5E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/resolve.js ADDED Viewed

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+/**
+ * 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;
+/**
+ * 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) {
+    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, isDark) {
+    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, theme) {
+    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) {
+    return new URL(src).origin;
+}
+//# sourceMappingURL=resolve.js.map

package/resolve.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAC3C,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAgB5C;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAmB;IACjD,IAAI,MAAM,CAAC,GAAG;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC;IAClC,IAAI,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,GAAG,CAAC;QACzE,OAAO,GAAG,IAAI,GAAG,MAAM,CAAC,EAAE,GAAG,CAAC;IAChC,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;AAC1E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAuB,EAAE,MAAe;IACnE,IAAI,KAAK,KAAK,OAAO;QAAE,OAAO,OAAO,CAAC;IACtC,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC;IACpC,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,KAAuB;IAClE,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;AAC7B,CAAC"}

package/src/define.ts ADDED Viewed

@@ -0,0 +1,8 @@
+/**
+ * Side-effecting entry: importing `@scenar/embed/define` registers the
+ * `<scenar-embed>` custom element. For bundler hosts that want the tag available
+ * without calling {@link defineScenarEmbed} themselves.
+ */
+import { defineScenarEmbed } from "./element.js";
+defineScenarEmbed();

package/src/element.test.ts ADDED Viewed

@@ -0,0 +1,108 @@
+import { describe, it, expect, beforeAll, afterEach } from "vitest";
+import {
+  type ScenarEmbedElement,
+  SCENAR_EMBED_TAG,
+  defineScenarEmbed,
+} from "./element.js";
+const SRC = "https://embed.example/tour/";
+const ORIGIN = "https://embed.example";
+beforeAll(() => {
+  defineScenarEmbed();
+});
+afterEach(() => {
+  document.body.innerHTML = "";
+  document.documentElement.className = "";
+});
+/**
+ * Create, configure, and connect a `<scenar-embed>`; return it, its iframe, and
+ * a sentinel `contentWindow` (with a no-op postMessage so the controller's
+ * teardown `destroy` command is harmless, and so the per-frame `event.source`
+ * check is genuinely exercised).
+ */
+function mountElement(
+  attrs: Record<string, string>,
+): { el: ScenarEmbedElement; iframe: HTMLIFrameElement; frame: MessageEventSource } {
+  const el = document.createElement(SCENAR_EMBED_TAG) as ScenarEmbedElement;
+  for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+  document.body.appendChild(el);
+  const iframe = el.querySelector("iframe") as HTMLIFrameElement;
+  const frame = { postMessage: () => {} } as unknown as MessageEventSource;
+  Object.defineProperty(iframe, "contentWindow", { value: frame, configurable: true });
+  return { el, iframe, frame };
+}
+function postResize(widthPx: number, heightPx: number, source: MessageEventSource): void {
+  const event = new MessageEvent("message", {
+    data: { source: "scenar-embed", v: 1, type: "resize", widthPx, heightPx },
+    origin: ORIGIN,
+  });
+  Object.defineProperty(event, "source", { value: source, configurable: true });
+  window.dispatchEvent(event);
+}
+describe("defineScenarEmbed", () => {
+  it("registers the tag once and is idempotent", () => {
+    defineScenarEmbed();
+    defineScenarEmbed();
+    expect(customElements.get(SCENAR_EMBED_TAG)).toBeTruthy();
+  });
+});
+describe("<scenar-embed>", () => {
+  it("renders a lazy, autoplay-capable iframe inside a responsive box", () => {
+    const { el, iframe } = mountElement({ src: SRC, title: "Welcome tour" });
+    expect(iframe).toBeTruthy();
+    expect(iframe.getAttribute("loading")).toBe("lazy");
+    expect(iframe.getAttribute("allow")).toBe("autoplay; fullscreen");
+    expect(iframe.hasAttribute("allowfullscreen")).toBe(true);
+    expect(iframe.getAttribute("title")).toBe("Welcome tour");
+    expect(el.style.position).toBe("relative");
+    expect(el.style.aspectRatio).toBe("896 / 480");
+  });
+  it("falls back to a generic accessible title", () => {
+    const { iframe } = mountElement({ src: SRC });
+    expect(iframe.getAttribute("title")).toBe("Interactive product tour");
+  });
+  it("frames the tour with the host theme baked into src", () => {
+    document.documentElement.classList.add("dark");
+    const { iframe } = mountElement({ src: SRC });
+    expect(iframe.src).toBe("https://embed.example/tour/?theme=dark");
+  });
+  it("updates the iframe title when the attribute changes (no reload)", () => {
+    const { el, iframe } = mountElement({ src: SRC, title: "First" });
+    const srcBefore = iframe.src;
+    el.setAttribute("title", "Second");
+    expect(iframe.getAttribute("title")).toBe("Second");
+    expect(iframe.src).toBe(srcBefore);
+  });
+  it("adopts the reported aspect ratio and re-dispatches embed events", () => {
+    const { el, frame } = mountElement({ src: SRC });
+    const seen: unknown[] = [];
+    el.addEventListener("scenar:resize", (e) => seen.push((e as CustomEvent).detail));
+    postResize(900, 520, frame);
+    expect(el.style.aspectRatio).toBe("900 / 520");
+    expect(seen).toEqual([{ type: "resize", widthPx: 900, heightPx: 520 }]);
+  });
+  it("tears down on disconnect", () => {
+    const { el, frame } = mountElement({ src: SRC });
+    postResize(900, 520, frame);
+    expect(el.style.aspectRatio).toBe("900 / 520");
+    el.remove();
+    postResize(640, 360, frame);
+    expect(el.style.aspectRatio).toBe("900 / 520");
+  });
+});

package/src/element.ts ADDED Viewed

@@ -0,0 +1,148 @@
+import { type EmbedMount, createEmbedMount } from "./mount.js";
+import {
+  type ScenarEmbedTheme,
+  EMBED_BASE_ASPECT_HEIGHT,
+  EMBED_BASE_ASPECT_WIDTH,
+} from "./resolve.js";
+/** The custom element tag name. */
+export const SCENAR_EMBED_TAG = "scenar-embed";
+/** Accessible iframe title when the host sets none. */
+const DEFAULT_TITLE = "Interactive product tour";
+/**
+ * SSR-safe base: subclassing `HTMLElement` evaluates at module load, which would
+ * throw in a non-DOM environment (server render). Fall back to a stub so this
+ * module can be imported anywhere; the element is only ever *registered* in a
+ * browser via {@link defineScenarEmbed}.
+ */
+const HTMLElementBase: typeof HTMLElement =
+  typeof HTMLElement !== "undefined"
+    ? HTMLElement
+    : (class {} as unknown as typeof HTMLElement);
+/**
+ * `<scenar-embed src="…">` — a framework-agnostic, drop-in embed for a hosted
+ * Scenar tour. It owns an internal iframe and its responsive box; all bridge
+ * behavior (origin pinning, theme sync, resize → aspect-ratio) comes from
+ * {@link createEmbedMount}, so the element holds no protocol logic of its own.
+ *
+ * Attributes:
+ * - `src` (required) — the absolute embed URL.
+ * - `title` — accessible iframe title (defaults to a generic label).
+ * - `theme` — `auto` (default) | `light` | `dark`.
+ *
+ * Events: re-dispatches every embed event as a DOM `CustomEvent` named
+ * `scenar:<type>` (e.g. `scenar:ready`, `scenar:completed`) with the event in
+ * `detail`, so a vanilla host can listen without touching `postMessage`.
+ *
+ * Imperative transport (`play`/`pause`/`seek`/`setMuted`/`setVolume`) delegates
+ * to the bridge; calls before the element has a `src` are no-ops.
+ */
+export class ScenarEmbedElement extends HTMLElementBase {
+  static get observedAttributes(): string[] {
+    return ["src", "title", "theme"];
+  }
+  private iframe: HTMLIFrameElement | null = null;
+  private mount: EmbedMount | null = null;
+  connectedCallback(): void {
+    if (!this.iframe) this.render();
+    this.attach();
+  }
+  disconnectedCallback(): void {
+    this.mount?.destroy();
+    this.mount = null;
+  }
+  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void {
+    if (oldValue === newValue) return;
+    if (name === "title") {
+      if (this.iframe) this.iframe.setAttribute("title", this.titleAttr());
+      return;
+    }
+    // A new src or theme rebuilds the bridge (and reloads the frame).
+    if (this.isConnected) this.attach();
+  }
+  play(): void {
+    this.mount?.controller.play();
+  }
+  pause(): void {
+    this.mount?.controller.pause();
+  }
+  seek(timeMs: number): void {
+    this.mount?.controller.seek(timeMs);
+  }
+  setMuted(muted: boolean): void {
+    this.mount?.controller.setMuted(muted);
+  }
+  setVolume(volume: number): void {
+    this.mount?.controller.setVolume(volume);
+  }
+  private titleAttr(): string {
+    return this.getAttribute("title") ?? DEFAULT_TITLE;
+  }
+  private themeAttr(): ScenarEmbedTheme {
+    const theme = this.getAttribute("theme");
+    return theme === "light" || theme === "dark" ? theme : "auto";
+  }
+  private setAspectRatio(width: number, height: number): void {
+    this.style.aspectRatio = `${width} / ${height}`;
+  }
+  /** Build the host box + the internal iframe (once). */
+  private render(): void {
+    this.style.display = "block";
+    this.style.position = "relative";
+    this.style.width = "100%";
+    this.setAspectRatio(EMBED_BASE_ASPECT_WIDTH, EMBED_BASE_ASPECT_HEIGHT);
+    const iframe = document.createElement("iframe");
+    iframe.setAttribute("title", this.titleAttr());
+    iframe.setAttribute("loading", "lazy");
+    iframe.setAttribute("allow", "autoplay; fullscreen");
+    iframe.setAttribute("allowfullscreen", "");
+    iframe.style.cssText =
+      "position:absolute;inset:0;width:100%;height:100%;border:0;border-radius:inherit";
+    this.appendChild(iframe);
+    this.iframe = iframe;
+  }
+  /** (Re)create the bridge for the current `src`/`theme`. */
+  private attach(): void {
+    const src = this.getAttribute("src");
+    if (!src || !this.iframe) return;
+    this.mount?.destroy();
+    this.mount = createEmbedMount(this.iframe, {
+      src,
+      theme: this.themeAttr(),
+      onAspectRatio: ({ widthPx, heightPx }) => this.setAspectRatio(widthPx, heightPx),
+      onEvent: (event) =>
+        this.dispatchEvent(new CustomEvent(`scenar:${event.type}`, { detail: event })),
+    });
+  }
+}
+/**
+ * Register `<scenar-embed>` (idempotent and SSR-safe). Pass a custom tag name to
+ * register under a different element name. A no-op when the registry is absent
+ * (server) or the tag is already defined.
+ */
+export function defineScenarEmbed(tagName: string = SCENAR_EMBED_TAG): void {
+  if (typeof customElements === "undefined") return;
+  if (customElements.get(tagName)) return;
+  customElements.define(tagName, ScenarEmbedElement);
+}

package/src/global.ts ADDED Viewed

@@ -0,0 +1,11 @@
+/**
+ * The IIFE entry, bundled to `dist/embed.global.js` (see vite.config.ts) — the
+ * single pasteable `<script>` for no-bundler hosts. It auto-registers
+ * `<scenar-embed>` on load and also exposes the registrar on `window.ScenarEmbed`
+ * for hosts that register under a custom tag.
+ */
+import { ScenarEmbedElement, defineScenarEmbed } from "./element.js";
+defineScenarEmbed();
+export { ScenarEmbedElement, defineScenarEmbed };

package/src/index.ts ADDED Viewed

@@ -0,0 +1,25 @@
+// @scenar/embed — public API
+// Drop-in host-side embedding for hosted Scenar tours. Importing this entry has
+// no side effects (it does not register the element); call `defineScenarEmbed()`
+// or import `@scenar/embed/define` to register `<scenar-embed>`.
+// Custom element + registrar
+export { ScenarEmbedElement, defineScenarEmbed, SCENAR_EMBED_TAG } from "./element.js";
+// Framework-free mount (the shared core both adapters build on)
+export { createEmbedMount } from "./mount.js";
+export type { EmbedMount, EmbedMountOptions, EmbedAspectRatio } from "./mount.js";
+// Pure resolution helpers + baseline constants
+export {
+  resolveEmbedSrc,
+  resolveTheme,
+  applyThemeToSrc,
+  originFromSrc,
+  EMBED_BASE_ASPECT_WIDTH,
+  EMBED_BASE_ASPECT_HEIGHT,
+} from "./resolve.js";
+export type { ScenarEmbedTheme, EmbedSource } from "./resolve.js";
+// The embed event/command types for host consumers (re-exported from @scenar/core)
+export type { ScenarEmbedEvent, ScenarEmbedCommand } from "@scenar/core";