@elizaos/ui 2.0.0-beta.2 → 2.0.3-beta.2

package/components/pages/tutorial/TutorialOverlay.js

@@ -0,0 +1,181 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { useBranding } from "../../../config/branding.js";
+import { dispatchTutorialChatControl } from "../../../events/index.js";
+import { setNavLock } from "../../../navigation/nav-lock.js";
+import { useApp } from "../../../state/index.js";
+import { useShellControllerContext } from "../../shell/ShellControllerContext.hooks.js";
+import { TutorialNarrator } from "./TutorialNarrator.js";
+import { TutorialSpotlight } from "./TutorialSpotlight.js";
+import { goToStep, stopTutorial, useTutorial } from "./tutorial-controller.js";
+import { buildTutorialSteps, } from "./tutorial-steps.js";
+/**
+ * The always-mounted interactive tour engine. When active it drives the real
+ * chat into a clean, known state at the start of each frame, narrates the line
+ * aloud through the app's real voice ({@link TutorialNarrator}), samples live UI
+ * state (chat detent, composer text, voice transcript, current tab), and
+ * auto-advances the instant the user performs the frame's action. The "ask to
+ * navigate" + voice frames complete the staged navigation for real on success.
+ * Mounted once in App.tsx, inside the shell controller provider.
+ */
+const LATE_SKIP_SEC = 14; // an unobtrusive "Skip" appears if a frame stalls
+const SUCCESS_BEAT_MS = 850; // brief "you did it" pause before advancing
+function readChatDetent() {
+    if (typeof document === "undefined")
+        return null;
+    const d = document
+        .querySelector('[data-testid="chat-sheet"]')
+        ?.getAttribute("data-detent");
+    return d === "pill" || d === "collapsed" || d === "half" || d === "full"
+        ? d
+        : null;
+}
+function readComposerText() {
+    if (typeof document === "undefined")
+        return "";
+    const el = document.querySelector('[data-testid="chat-composer-textarea"]');
+    return el instanceof HTMLTextAreaElement ? el.value : "";
+}
+export function TutorialOverlay() {
+    const { active, stepIndex } = useTutorial();
+    const { tab, setTab } = useApp();
+    const controller = useShellControllerContext();
+    // Brand the tour copy ("Meet Milady", "Hi, I'm Milady") with the app name.
+    const { appName } = useBranding();
+    const steps = React.useMemo(() => buildTutorialSteps(appName), [appName]);
+    const [beat, setBeat] = React.useState(1);
+    // The id of the step whose action has been completed. Tracked by id (not a
+    // lingering boolean) so a frame's success can't bleed into the NEXT frame
+    // during the advance render — which would fire the next frame's
+    // `navigateOnDone` before the user ever acts on it.
+    const [doneStepId, setDoneStepId] = React.useState(null);
+    // The late "Skip" only needs a single boolean flip once a frame stalls — not
+    // a per-tick seconds counter, which would re-render the overlay 5×/second.
+    const [lateSkip, setLateSkip] = React.useState(false);
+    const [muted, setMuted] = React.useState(false);
+    const step = active ? steps[stepIndex] : undefined;
+    // Live values read by the (closure-stable) sampling interval via refs, so it
+    // never captures a stale tab/transcript.
+    const tabRef = React.useRef(tab);
+    tabRef.current = tab;
+    const transcriptRef = React.useRef(controller?.transcript ?? "");
+    transcriptRef.current = controller?.transcript ?? "";
+    const stepStartRef = React.useRef(0);
+    const sawPrefillRef = React.useRef(false);
+    const advance = React.useCallback(() => {
+        if (stepIndex >= steps.length - 1)
+            stopTutorial();
+        else
+            goToStep(stepIndex + 1);
+    }, [stepIndex, steps.length]);
+    // Frame enter: reset per-frame state and drive the chat into the clean state
+    // this frame needs (pill / rest / expand) or pre-fill the staged command.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: stepIndex/active are the reset triggers
+    React.useEffect(() => {
+        setBeat(1);
+        setDoneStepId(null);
+        setLateSkip(false);
+        sawPrefillRef.current = false;
+        stepStartRef.current = Date.now();
+        if (!step)
+            return;
+        if (step.prefill != null) {
+            dispatchTutorialChatControl({ action: "prefill", text: step.prefill });
+        }
+        else if (step.enterChat) {
+            dispatchTutorialChatControl({ action: step.enterChat });
+        }
+    }, [stepIndex, active]);
+    // Capability lock: while the tour runs, restrict navigation to the tabs the
+    // current frame expects (its own tab + its staged target), so nothing — a
+    // stray control, a deep link, an agent action, the chat's own nav buttons —
+    // can drift the app into a state the tour doesn't expect. Cleared on exit.
+    React.useEffect(() => {
+        if (!active || !step) {
+            setNavLock(null);
+            return undefined;
+        }
+        setNavLock(step.lockTabs ?? ["chat"]);
+        return () => setNavLock(null);
+    }, [active, step]);
+    // When the tour ends — skip, complete, or unmount — restore the chat to a
+    // normal interactive state. A frame may have collapsed it to the pill, where
+    // the composer is `inert` (not clickable); without this reset, cancelling the
+    // tour on the "open chat" frame leaves the input dead until the pill is
+    // tapped. Fires on the active→inactive transition via the effect cleanup.
+    React.useEffect(() => {
+        if (!active)
+            return undefined;
+        return () => {
+            dispatchTutorialChatControl({ action: "reset" });
+        };
+    }, [active]);
+    // The tour never auto-launches. It only starts on an explicit user action —
+    // the home "Tutorial" tile or the launcher view (both call startTutorial()).
+    // Sample live UI state and auto-detect completion of the current beat.
+    React.useEffect(() => {
+        if (!active || !step || doneStepId === step.id)
+            return undefined;
+        const id = window.setInterval(() => {
+            const secs = (Date.now() - stepStartRef.current) / 1000;
+            // Reveal the late "Skip" once, when a frame stalls. setState bails out
+            // once it's already true, so this stops re-rendering after the first flip.
+            if (secs >= LATE_SKIP_SEC)
+                setLateSkip(true);
+            const composerText = readComposerText();
+            if (step.prefill && composerText === step.prefill) {
+                sawPrefillRef.current = true;
+            }
+            const obs = {
+                tab: tabRef.current,
+                detent: readChatDetent(),
+                composerText,
+                transcript: transcriptRef.current,
+                prefillSent: step.prefill != null &&
+                    sawPrefillRef.current &&
+                    composerText.trim() === "",
+                secondsOnStep: secs,
+            };
+            const check = beat === 2 && step.beat2 ? step.beat2.isDone : step.isDone;
+            if (check?.(obs)) {
+                if (beat === 1 && step.beat2) {
+                    setBeat(2);
+                    stepStartRef.current = Date.now();
+                }
+                else {
+                    setDoneStepId(step.id);
+                }
+            }
+        }, 200);
+        return () => window.clearInterval(id);
+    }, [active, step, doneStepId, beat]);
+    // On the CURRENT step's success: complete any staged navigation for real, then
+    // advance. Guarded by step identity so a prior frame's success can't trigger
+    // this frame's navigation during the advance render.
+    React.useEffect(() => {
+        if (!step || doneStepId !== step.id)
+            return undefined;
+        if (step.navigateOnDone)
+            setTab(step.navigateOnDone);
+        const t = window.setTimeout(advance, SUCCESS_BEAT_MS);
+        return () => window.clearTimeout(t);
+    }, [doneStepId, step, setTab, advance]);
+    if (!active || !step)
+        return null;
+    const succeeded = doneStepId === step.id;
+    const current = beat === 2 && step.beat2 ? step.beat2 : step;
+    const isLast = stepIndex >= steps.length - 1;
+    const showContinue = step.manualContinue || lateSkip;
+    const continueLabel = step.manualContinue
+        ? (step.continueLabel ?? "Continue")
+        : "Skip";
+    return (_jsxs(_Fragment, { children: [!muted && (_jsx(TutorialNarrator, { utteranceId: `tutorial-${step.id}-${beat}`, text: current.voiceLine, muted: muted })), _jsx(TutorialSpotlight, { targetSelector: step.targetSelector, dimOutside: !succeeded, title: step.title, body: succeeded ? (step.doneBody ?? current.body) : current.body, muted: muted, onToggleMute: () => {
+                    controller?.unlockAudio?.();
+                    setMuted((m) => !m);
+                }, onSkip: stopTutorial, onContinue: showContinue && !succeeded
+                    ? () => {
+                        controller?.unlockAudio?.();
+                        advance();
+                    }
+                    : undefined, continueLabel: isLast ? "Done" : continueLabel })] }));
+}

package/components/pages/tutorial/TutorialSpotlight.d.ts

@@ -0,0 +1,25 @@
+import * as React from "react";
+export interface SpotlightCardProps {
+    title: string;
+    body: string;
+    /** Narration muted — toggles the speaker control. */
+    muted: boolean;
+    onToggleMute: () => void;
+    onSkip: () => void;
+    /** Optional manual-advance button (centered cards, or a stalled frame). */
+    onContinue?: () => void;
+    continueLabel?: string;
+}
+export interface TutorialSpotlightProps extends SpotlightCardProps {
+    /** CSS selector for the element to spotlight, or null for a centered card. */
+    targetSelector: string | null;
+    /**
+     * Dim the screen around the target while the step is in progress. PURELY
+     * VISUAL — the dim never captures pointer events, so the real UI underneath
+     * (the chat input, the mic, every control) always stays tappable. Only the
+     * instruction card is interactive.
+     */
+    dimOutside: boolean;
+}
+export declare function TutorialSpotlight({ targetSelector, dimOutside, ...card }: TutorialSpotlightProps): React.ReactPortal | null;
+//# sourceMappingURL=TutorialSpotlight.d.ts.map

package/components/pages/tutorial/TutorialSpotlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TutorialSpotlight.d.ts","sourceRoot":"","sources":["../../../../../../../src/components/pages/tutorial/TutorialSpotlight.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAgB/B,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,8EAA8E;IAC9E,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;;OAKG;IACH,UAAU,EAAE,OAAO,CAAC;CACrB;AAkBD,wBAAgB,iBAAiB,CAAC,EAChC,cAAc,EACd,UAAU,EACV,GAAG,IAAI,EACR,EAAE,sBAAsB,GAAG,KAAK,CAAC,WAAW,GAAG,IAAI,CA0GnD"}

package/components/pages/tutorial/TutorialSpotlight.js

@@ -0,0 +1,139 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Volume2, VolumeX } from "lucide-react";
+import * as React from "react";
+import { createPortal } from "react-dom";
+/**
+ * The tour spotlight: a full-screen overlay that
+ *  - draws a breathing orange glow ring around the target (the indicator that
+ *    points at the next control);
+ *  - floats a small instruction card near the target (auto-flips above/below);
+ *  - for a centered card (welcome / finish) dims the whole screen instead.
+ *
+ * Brand orange (#FF5800) is the only accent; resting→hover stays orange→darker.
+ */
+const BRAND = "#FF5800";
+const PAD = 8; // glow ring inset around the target
+function measure(selector) {
+    if (!selector || typeof document === "undefined")
+        return null;
+    const el = document.querySelector(selector);
+    if (!el)
+        return null;
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0)
+        return null;
+    return { top: r.top, left: r.left, width: r.width, height: r.height };
+}
+export function TutorialSpotlight({ targetSelector, dimOutside, ...card }) {
+    const [rect, setRect] = React.useState(() => measure(targetSelector));
+    // Follow the target as it moves/resizes/scrolls (rAF loop is the simplest
+    // reliable tracker across layout shifts, animations, and the chat expanding).
+    React.useEffect(() => {
+        if (!targetSelector) {
+            setRect(null);
+            return;
+        }
+        let raf = 0;
+        let prev = "";
+        const tick = () => {
+            const next = measure(targetSelector);
+            const sig = next
+                ? `${Math.round(next.top)},${Math.round(next.left)},${Math.round(next.width)},${Math.round(next.height)}`
+                : "";
+            if (sig !== prev) {
+                prev = sig;
+                setRect(next);
+            }
+            raf = requestAnimationFrame(tick);
+        };
+        raf = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(raf);
+    }, [targetSelector]);
+    if (typeof document === "undefined")
+        return null;
+    const hole = rect
+        ? {
+            top: Math.max(0, rect.top - PAD),
+            left: Math.max(0, rect.left - PAD),
+            width: rect.width + PAD * 2,
+            height: rect.height + PAD * 2,
+        }
+        : null;
+    // Card placement: centered when there's no target. For a target in the BOTTOM
+    // of the screen (e.g. the chat — which also expands upward), pin the card near
+    // the TOP so it never covers the control or sits in the chat's expand path.
+    // Otherwise place it just below the target, or above when there's no room.
+    const vh = typeof window === "undefined" ? 800 : window.innerHeight;
+    const cardStyle = !hole
+        ? { top: "50%", left: "50%", transform: "translate(-50%, -50%)" }
+        : hole.top > vh * 0.55
+            ? {
+                top: Math.max(72, Math.round(vh * 0.12)),
+                left: "50%",
+                transform: "translateX(-50%)",
+            }
+            : hole.top + hole.height + 180 < vh
+                ? { top: hole.top + hole.height + 14, left: clampLeft(hole.left) }
+                : { top: Math.max(14, hole.top - 172), left: clampLeft(hole.left) };
+    return createPortal(_jsxs("div", { className: "fixed inset-0", 
+        // Inline z-index (not a Tailwind arbitrary class — that huge value isn't
+        // reliably generated) so the spotlight + card always sit ABOVE the chat
+        // overlay (z 9000), even when the chat is expanded full-screen while the
+        // user performs the instructed action. Clicks pass through except the card.
+        style: { pointerEvents: "none", zIndex: 2147483000 }, "aria-live": "polite", children: [_jsx("style", { children: SPOTLIGHT_KEYFRAMES }), dimOutside &&
+                (hole ? (_jsx(BackdropWithHole, { hole: hole })) : (_jsx("div", { className: "absolute inset-0 bg-black/55", style: { pointerEvents: "none" } }))), hole && (_jsx("div", { className: "absolute rounded-2xl", style: {
+                    top: hole.top,
+                    left: hole.left,
+                    width: hole.width,
+                    height: hole.height,
+                    pointerEvents: "none",
+                    boxShadow: "0 0 18px 5px rgba(255,88,0,0.5)",
+                    animation: "tutorial-glow 1.6s ease-in-out infinite",
+                } })), _jsx(SpotlightCard, { ...card, cardStyle: cardStyle })] }), document.body);
+}
+function clampLeft(left) {
+    const w = 320;
+    return Math.min(Math.max(14, left), window.innerWidth - w - 14);
+}
+/** Four dim rects framing the target hole — a purely visual cut-out so the
+ *  target pops. Every rect is pointer-events:none: nothing here blocks input,
+ *  so the whole UI underneath (including the chat textarea) stays tappable. */
+function BackdropWithHole({ hole }) {
+    const dim = "absolute bg-black/55";
+    const passThrough = { pointerEvents: "none" };
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: dim, style: { ...passThrough, top: 0, left: 0, right: 0, height: hole.top } }), _jsx("div", { className: dim, style: {
+                    ...passThrough,
+                    top: hole.top + hole.height,
+                    left: 0,
+                    right: 0,
+                    bottom: 0,
+                } }), _jsx("div", { className: dim, style: {
+                    ...passThrough,
+                    top: hole.top,
+                    left: 0,
+                    width: hole.left,
+                    height: hole.height,
+                } }), _jsx("div", { className: dim, style: {
+                    ...passThrough,
+                    top: hole.top,
+                    left: hole.left + hole.width,
+                    right: 0,
+                    height: hole.height,
+                } })] }));
+}
+function SpotlightCard({ title, body, muted, onToggleMute, onSkip, onContinue, continueLabel, cardStyle, }) {
+    return (_jsxs("div", { className: "absolute w-[300px] max-w-[calc(100vw-28px)] rounded-2xl border border-white/12 bg-neutral-950/95 p-4 text-white shadow-2xl backdrop-blur-md motion-safe:animate-[shell-overlay-in_220ms_ease-out]", style: { ...cardStyle, pointerEvents: "auto" }, "data-testid": "tutorial-card", role: "dialog", "aria-label": "Tour step", children: [_jsx("h3", { className: "text-[15px] font-semibold leading-snug", children: title }), _jsx("p", { className: "mt-1 whitespace-pre-line text-[13px] leading-relaxed text-white/75", children: body }), _jsxs("div", { className: "mt-3 flex items-center justify-between gap-2", children: [_jsxs("div", { className: "flex items-center gap-3", children: [_jsx("button", { type: "button", onClick: onToggleMute, "data-testid": "tutorial-mute", "aria-label": muted ? "Unmute narration" : "Mute narration", "aria-pressed": muted, className: "text-white/45 transition-colors hover:text-white/80", children: muted ? (_jsx(VolumeX, { className: "h-4 w-4", "aria-hidden": true })) : (_jsx(Volume2, { className: "h-4 w-4", "aria-hidden": true })) }), _jsx("button", { type: "button", onClick: onSkip, "data-testid": "tutorial-skip", className: "text-[12px] text-white/45 underline-offset-2 hover:text-white/70 hover:underline", children: "Skip tour" })] }), onContinue && (_jsx("button", { type: "button", onClick: onContinue, "data-testid": "tutorial-continue", className: "rounded-lg px-3 py-1.5 text-[13px] font-semibold text-white transition-colors", style: { backgroundColor: BRAND }, onMouseEnter: (e) => {
+                            e.currentTarget.style.backgroundColor = "#D44A00";
+                        }, onMouseLeave: (e) => {
+                            e.currentTarget.style.backgroundColor = BRAND;
+                        }, children: continueLabel ?? "Continue" }))] })] }));
+}
+const SPOTLIGHT_KEYFRAMES = `
+@keyframes tutorial-glow {
+  0%, 100% { box-shadow: 0 0 16px 4px rgba(255,88,0,0.45); }
+  50%      { box-shadow: 0 0 30px 11px rgba(255,88,0,0.8); }
+}
+@media (prefers-reduced-motion: reduce) {
+  [style*="tutorial-glow"] { animation: none !important; }
+}
+`;

package/components/pages/tutorial/TutorialView.d.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+/**
+ * The tour launcher — the view the home "Tutorial" tile opens. Pressing Start
+ * activates the global TutorialOverlay (the interactive tour) and drops the user
+ * back on the home base so the tour can spotlight the real chat. Eliza narrates
+ * each frame aloud; the tour can be muted from its card.
+ */
+export declare function TutorialView(): React.ReactElement;
+//# sourceMappingURL=TutorialView.d.ts.map

package/components/pages/tutorial/TutorialView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TutorialView.d.ts","sourceRoot":"","sources":["../../../../../../../src/components/pages/tutorial/TutorialView.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B;;;;;GAKG;AAEH,wBAAgB,YAAY,IAAI,KAAK,CAAC,YAAY,CAkDjD"}

package/components/pages/tutorial/TutorialView.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Sparkles } from "lucide-react";
+import * as React from "react";
+import { useAgentElement } from "../../../agent-surface/index.js";
+import { useApp } from "../../../state/index.js";
+import { Button } from "../../ui/button.js";
+import { startTutorial } from "./tutorial-controller.js";
+/**
+ * The tour launcher — the view the home "Tutorial" tile opens. Pressing Start
+ * activates the global TutorialOverlay (the interactive tour) and drops the user
+ * back on the home base so the tour can spotlight the real chat. Eliza narrates
+ * each frame aloud; the tour can be muted from its card.
+ */
+export function TutorialView() {
+    const { setTab } = useApp();
+    const begin = React.useCallback(() => {
+        startTutorial();
+        setTab("chat"); // return home so the tour overlays the real chat
+    }, [setTab]);
+    const start = useAgentElement({
+        id: "tutorial-start",
+        role: "button",
+        label: "Start quick tour",
+        description: "Launch the interactive walkthrough of the basics",
+        onActivate: begin,
+    });
+    return (_jsx("div", { className: "flex h-full w-full flex-col items-center justify-center overflow-y-auto px-6 py-10 text-center", "data-testid": "tutorial-launcher", children: _jsxs("div", { className: "flex max-w-sm flex-col items-center", children: [_jsx("div", { className: "mb-5 flex h-16 w-16 items-center justify-center rounded-2xl bg-accent-subtle", style: {
+                        boxShadow: "0 0 28px 4px color-mix(in srgb, var(--accent) 35%, transparent)",
+                    }, "aria-hidden": true, children: _jsx(Sparkles, { className: "h-7 w-7 text-accent" }) }), _jsx("h1", { className: "text-2xl font-semibold text-txt-strong", children: "Quick tour" }), _jsx("p", { className: "mt-2 text-[15px] leading-relaxed text-txt/70", children: "A hands-on walkthrough of the basics \u2014 about a minute." }), _jsx(Button, { ref: start.ref, ...start.agentProps, onClick: begin, "data-testid": "tutorial-start", size: "lg", className: "mt-7 text-[15px] font-semibold", children: "Start" })] }) }));
+}

package/components/pages/tutorial/tutorial-controller.d.ts

@@ -0,0 +1,10 @@
+export interface TutorialState {
+    active: boolean;
+    stepIndex: number;
+}
+export declare function startTutorial(): void;
+/** Stop + mark complete so it never nags again (but stays re-runnable from the tile). */
+export declare function stopTutorial(): void;
+export declare function goToStep(index: number): void;
+export declare function useTutorial(): TutorialState;
+//# sourceMappingURL=tutorial-controller.d.ts.map

package/components/pages/tutorial/tutorial-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutorial-controller.d.ts","sourceRoot":"","sources":["../../../../../../../src/components/pages/tutorial/tutorial-controller.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AA0BD,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED,yFAAyF;AACzF,wBAAgB,YAAY,IAAI,IAAI,CAOnC;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED,wBAAgB,WAAW,IAAI,aAAa,CAU3C"}

package/components/pages/tutorial/tutorial-controller.js

@@ -0,0 +1,54 @@
+import * as React from "react";
+/**
+ * Global tutorial controller. The interactive tour is a persistent OVERLAY (not
+ * a tab view) because it navigates the user around the real app — to Settings,
+ * back home — and must survive those navigations. The home "Tutorial" tile and
+ * the launcher view call `startTutorial()`; the always-mounted `TutorialOverlay`
+ * (in App.tsx) subscribes and renders the spotlight + step engine when active.
+ *
+ * Module-level store (shared via globalThis so a single instance survives HMR
+ * and is reachable from the tile handler outside React) + useSyncExternalStore.
+ */
+const COMPLETED_KEY = "eliza:tutorial-completed";
+function store() {
+    const g = globalThis;
+    const k = Symbol.for("elizaos.ui.tutorial-controller");
+    const existing = g[k];
+    if (existing)
+        return existing;
+    const created = {
+        state: { active: false, stepIndex: 0 },
+        listeners: new Set(),
+    };
+    g[k] = created;
+    return created;
+}
+function set(next) {
+    const s = store();
+    s.state = { ...s.state, ...next };
+    for (const l of s.listeners)
+        l();
+}
+export function startTutorial() {
+    set({ active: true, stepIndex: 0 });
+}
+/** Stop + mark complete so it never nags again (but stays re-runnable from the tile). */
+export function stopTutorial() {
+    set({ active: false, stepIndex: 0 });
+    try {
+        localStorage.setItem(COMPLETED_KEY, "1");
+    }
+    catch {
+        /* storage unavailable — fine */
+    }
+}
+export function goToStep(index) {
+    set({ stepIndex: Math.max(0, index) });
+}
+export function useTutorial() {
+    const s = store();
+    return React.useSyncExternalStore((l) => {
+        s.listeners.add(l);
+        return () => s.listeners.delete(l);
+    }, () => s.state, () => s.state);
+}

package/components/pages/tutorial/tutorial-steps.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The interactive tour script — six frames, each pointing a glowing spotlight at
+ * ONE real control. The engine (TutorialOverlay) drives the chat into a clean,
+ * known state when a frame begins, narrates the line aloud through the app's real
+ * voice, and auto-advances the instant the user actually performs the action.
+ *
+ * Frames teach the chat as the single remote control: open it, resize it, ask it
+ * to navigate (the tour pre-types the request and the user just taps send), and
+ * talk to it. Targets are stable test ids on the live UI (chat-pill,
+ * chat-sheet-grabber, chat-composer-action, chat-composer-mic) so the spotlight
+ * always lands on the genuine control.
+ */
+/** The chat's resting detent, read from the live `data-testid="chat-sheet"`. */
+export type ChatDetent = "pill" | "collapsed" | "half" | "full";
+/** Live UI state the engine samples each frame and feeds to `isDone`. */
+export interface TutorialObservable {
+    /** Current nav tab / view. */
+    tab: string;
+    /** The chat's detent (null when the chat isn't mounted yet). */
+    detent: ChatDetent | null;
+    /** Current composer draft text (read from the live textarea). */
+    composerText: string;
+    /** Live interim voice transcription ("" when not listening). */
+    transcript: string;
+    /**
+     * True once a frame's pre-filled command has been observed and then cleared —
+     * i.e. the user sent it. Used by the guided "ask to navigate" frame.
+     */
+    prefillSent: boolean;
+    /** Seconds elapsed on the current frame. */
+    secondsOnStep: number;
+}
+/** A single instruction within a frame (frames may have a second beat). */
+export interface TutorialBeat {
+    /** On-screen instruction. */
+    body: string;
+    /** Spoken instruction, narrated through the app's real voice. */
+    voiceLine: string;
+    /** Auto-advance when this becomes true. */
+    isDone?: (s: TutorialObservable) => boolean;
+}
+export interface TutorialStep extends TutorialBeat {
+    id: string;
+    title: string;
+    /** CSS selector for the control to spotlight, or null for a centered card. */
+    targetSelector: string | null;
+    /** Drive the chat into this state when the frame begins (clean per-frame state). */
+    enterChat?: "pill" | "rest" | "expand";
+    /** Pre-fill the composer with this command when the frame begins. */
+    prefill?: string;
+    /** A second instruction shown after the first beat completes (same target). */
+    beat2?: TutorialBeat;
+    /**
+     * On success, navigate here first so the action the tour staged actually
+     * completes for real (the "ask to navigate" + voice frames). Not set on frames
+     * where the user's own action already moved them.
+     */
+    navigateOnDone?: string;
+    /**
+     * The only tabs navigation may reach while this frame is showing — so nothing
+     * (a stray control, a deep link, an agent action) can drift the app off the
+     * guided path. Include the frame's own tab plus its `navigateOnDone` target.
+     * Defaults to the home base.
+     */
+    lockTabs?: string[];
+    /** A short line shown for a beat after success, before advancing. */
+    doneBody?: string;
+    /** Centered cards advance with this button instead of an action. */
+    manualContinue?: boolean;
+    continueLabel?: string;
+}
+/**
+ * Build the tour script for a given agent/app name so the copy reads "Meet
+ * Milady" / "Hi, I'm Milady" in a white-label app instead of the hardcoded
+ * "Eliza". Pass the branding appName (which is also the default agent's name).
+ */
+export declare function buildTutorialSteps(appName?: string): TutorialStep[];
+/**
+ * Default (canonical Eliza) tour script — kept for callers/tests that don't
+ * thread the app name. Branded callers use buildTutorialSteps(appName).
+ */
+export declare const TUTORIAL_STEPS: TutorialStep[];
+//# sourceMappingURL=tutorial-steps.d.ts.map

package/components/pages/tutorial/tutorial-steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutorial-steps.d.ts","sourceRoot":"","sources":["../../../../../../../src/components/pages/tutorial/tutorial-steps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhE,yEAAyE;AACzE,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAC7C;AAED,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IACvC,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAOD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,SAAU,GAAG,YAAY,EAAE,CAuEpE;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,YAAY,EAAyB,CAAC"}

package/components/pages/tutorial/tutorial-steps.js

@@ -0,0 +1,95 @@
+/**
+ * The interactive tour script — six frames, each pointing a glowing spotlight at
+ * ONE real control. The engine (TutorialOverlay) drives the chat into a clean,
+ * known state when a frame begins, narrates the line aloud through the app's real
+ * voice, and auto-advances the instant the user actually performs the action.
+ *
+ * Frames teach the chat as the single remote control: open it, resize it, ask it
+ * to navigate (the tour pre-types the request and the user just taps send), and
+ * talk to it. Targets are stable test ids on the live UI (chat-pill,
+ * chat-sheet-grabber, chat-composer-action, chat-composer-mic) so the spotlight
+ * always lands on the genuine control.
+ */
+const isExpanded = (d) => d === "half" || d === "full";
+const isShrunk = (d) => d === "collapsed" || d === "pill";
+/**
+ * Build the tour script for a given agent/app name so the copy reads "Meet
+ * Milady" / "Hi, I'm Milady" in a white-label app instead of the hardcoded
+ * "Eliza". Pass the branding appName (which is also the default agent's name).
+ */
+export function buildTutorialSteps(appName = "Eliza") {
+    const name = appName.trim() || "Eliza";
+    return [
+        {
+            id: "welcome",
+            title: `Meet ${name}`,
+            body: "Your AI agent. The chat runs everything — here's the quick version.",
+            voiceLine: `Hi, I'm ${name}, your A I agent. The chat runs everything — here's the quick version.`,
+            targetSelector: null,
+            manualContinue: true,
+            continueLabel: "Start",
+        },
+        {
+            id: "open-chat",
+            title: "Open the chat",
+            body: "Tap the pill to open it.",
+            voiceLine: "Tap the pill to open the chat.",
+            targetSelector: '[data-testid="chat-pill"]',
+            enterChat: "pill",
+            isDone: (s) => s.detent != null && s.detent !== "pill",
+        },
+        {
+            id: "resize-chat",
+            title: "Resize it",
+            body: "Drag the handle up to make the chat bigger.",
+            voiceLine: "Drag the handle up to make the chat bigger.",
+            targetSelector: '[data-testid="chat-sheet-grabber"]',
+            enterChat: "rest",
+            isDone: (s) => isExpanded(s.detent),
+            beat2: {
+                body: "Now drag it back down to tuck it away.",
+                voiceLine: "Now drag it back down to tuck it away.",
+                isDone: (s) => isShrunk(s.detent),
+            },
+        },
+        {
+            id: "ask-to-navigate",
+            title: "Just ask",
+            body: `You can ask ${name} to go anywhere. I've typed it for you — tap send.`,
+            voiceLine: `You can ask ${name} to go anywhere. I've typed it for you — tap send.`,
+            targetSelector: '[data-testid="chat-composer-action"]',
+            enterChat: "rest",
+            prefill: "open settings",
+            isDone: (s) => s.prefillSent,
+            navigateOnDone: "settings",
+            lockTabs: ["chat", "settings"],
+            doneBody: "Here's Settings.",
+        },
+        {
+            id: "use-voice",
+            title: "Talk to it",
+            body: "Tap the mic and say “go home”.",
+            voiceLine: "You can talk to me, too. Tap the mic and say: go home.",
+            targetSelector: '[data-testid="chat-composer-mic"]',
+            enterChat: "rest",
+            isDone: (s) => /\bhome\b/i.test(s.transcript),
+            navigateOnDone: "chat",
+            lockTabs: ["settings", "chat"],
+            doneBody: "Welcome home.",
+        },
+        {
+            id: "done",
+            title: "You're set",
+            body: "The chat is your remote — tap, drag, type, or talk. Re-run this tour anytime from the Tutorial tile.",
+            voiceLine: "That's it. The chat is your remote — tap, drag, type, or talk. Have fun.",
+            targetSelector: null,
+            manualContinue: true,
+            continueLabel: "Done",
+        },
+    ];
+}
+/**
+ * Default (canonical Eliza) tour script — kept for callers/tests that don't
+ * thread the app name. Branded callers use buildTutorialSteps(appName).
+ */
+export const TUTORIAL_STEPS = buildTutorialSteps();