@ibgib/space-gib 0.0.34 → 0.0.36

package/src/client/ui/component/tutorial/tutorial-controller.mts

@@ -0,0 +1,622 @@
+/**
+ * @module tutorial-controller
+ *
+ * Controller managing the interactive spotlight tour, virtual mouse cursor animations,
+ * and tutorial overlay in Space-Gib.
+ */
+
+import { TutorialScript, TutorialStep, TutorialActionContext } from './tutorial-types.mjs';
+
+/**
+ * Deeply traverses the DOM tree, recursing into all ShadowRoots to locate an element
+ * by ID or CSS selector.
+ */
+export function findElementDeep(
+    idOrSelector: string,
+    root: Document | Element | ShadowRoot = document
+): HTMLElement | null {
+    if (!idOrSelector) return null;
+
+    const cleanId = idOrSelector.startsWith('#') ? idOrSelector.slice(1) : idOrSelector;
+
+    // 1. Direct getElementById if available on this root
+    if ('getElementById' in root) {
+        const el = (root as Document | ShadowRoot).getElementById(cleanId);
+        if (el) return el;
+    }
+
+    // 2. Direct querySelector
+    try {
+        const selector = idOrSelector.startsWith('#') || idOrSelector.startsWith('.')
+            ? idOrSelector
+            : `#${idOrSelector}`;
+        const el = root.querySelector(selector);
+        if (el) return el as HTMLElement;
+    } catch {
+        // Invalid selector, ignore
+    }
+
+    // 3. Search children with shadowRoots recursively
+    const searchRoot = root instanceof Document ? root.body || root.documentElement : root;
+    if (!searchRoot) return null;
+
+    const treeWalker = document.createTreeWalker(searchRoot, NodeFilter.SHOW_ELEMENT);
+    let currentNode = treeWalker.nextNode() as Element | null;
+    while (currentNode) {
+        if (currentNode.shadowRoot) {
+            const found = findElementDeep(idOrSelector, currentNode.shadowRoot);
+            if (found) return found;
+        }
+        currentNode = treeWalker.nextNode() as Element | null;
+    }
+
+    return null;
+}
+
+export class TutorialController {
+    private lc = '[TutorialController]';
+
+    private script?: TutorialScript;
+    private currentStepIndex = 0;
+    private shell: any;
+    private active = false;
+
+    // DOM Elements
+    private overlayContainer?: HTMLDivElement;
+    private backdrop?: HTMLDivElement;
+    private spotlightRing?: HTMLDivElement;
+    private beacon?: HTMLButtonElement;
+    private card?: HTMLDivElement;
+    private cursor?: HTMLDivElement;
+
+    // Virtual cursor position tracker
+    private cursorX = -9999;
+    private cursorY = -9999;
+
+    // Bound listeners for cleanup
+    private boundHandleResize = this.handleResize.bind(this);
+    private boundHandleKeydown = this.handleKeydown.bind(this);
+
+    public get isActive(): boolean {
+        return this.active;
+    }
+
+    public get currentStep(): TutorialStep | undefined {
+        return this.script?.steps[this.currentStepIndex];
+    }
+
+    /**
+     * Starts the specified tutorial script.
+     */
+    public async start(script: TutorialScript, shell: any): Promise<void> {
+        console.log(`${this.lc} [start] Starting tutorial script: "${script?.title}" with ${script?.steps?.length} steps.`);
+        if (!script || script.steps.length === 0) {
+            console.warn(`${this.lc} [start] Cannot start empty tutorial script.`);
+            return;
+        }
+
+        this.script = script;
+        this.shell = shell;
+        this.currentStepIndex = 0;
+        this.active = true;
+
+        this.mountOverlay();
+        window.addEventListener('resize', this.boundHandleResize);
+        window.addEventListener('keydown', this.boundHandleKeydown);
+
+        await this.renderStep(this.currentStepIndex);
+    }
+
+    /**
+     * Advances to the next step, executing any in-between transition actions,
+     * or closes the tour if on the final step.
+     */
+    public async next(): Promise<void> {
+        console.log(`${this.lc} [next] Current step index: ${this.currentStepIndex}, total: ${this.script?.steps.length}`);
+        if (!this.active || !this.script) return;
+
+        const currentStep = this.script.steps[this.currentStepIndex];
+
+        // 1. Check if current step has an in-between transition action
+        if (currentStep?.transitionAction) {
+            console.log(`${this.lc} [next] Executing transition action for step "${currentStep.id}"...`);
+            this.hideOverlayElements();
+            try {
+                const ctx: TutorialActionContext = {
+                    shell: this.shell,
+                    metaspace: this.shell?.metaspace,
+                    galaxyName: this.shell?.fileExplorerInstance?.getGalaxyName?.() || 'code-1',
+                    branchName: this.shell?.fileExplorerInstance?.getBranchName?.() || 'main',
+                };
+                await currentStep.transitionAction(ctx, this);
+                console.log(`${this.lc} [next] Transition action completed.`);
+            } catch (err) {
+                console.warn(`${this.lc} [next] Transition action failed:`, err);
+            } finally {
+                this.hideCursor();
+                this.showOverlayElements();
+            }
+        }
+
+        if (this.currentStepIndex < this.script.steps.length - 1) {
+            this.currentStepIndex++;
+            await this.renderStep(this.currentStepIndex);
+        } else {
+            console.log(`${this.lc} [next] Final step reached, stopping tour.`);
+            this.stop();
+        }
+    }
+
+    /**
+     * Goes back to the previous step.
+     */
+    public async prev(): Promise<void> {
+        console.log(`${this.lc} [prev] Current step index: ${this.currentStepIndex}`);
+        if (!this.active || !this.script) return;
+
+        if (this.currentStepIndex > 0) {
+            this.currentStepIndex--;
+            await this.renderStep(this.currentStepIndex);
+        }
+    }
+
+    /**
+     * Jumps directly to a specific step index.
+     */
+    public async goToStep(index: number): Promise<void> {
+        console.log(`${this.lc} [goToStep] Jumping to index: ${index}`);
+        if (!this.active || !this.script) return;
+        if (index >= 0 && index < this.script.steps.length) {
+            this.currentStepIndex = index;
+            await this.renderStep(this.currentStepIndex);
+        }
+    }
+
+    /**
+     * Stops and removes the tutorial overlay from the DOM.
+     */
+    public stop(): void {
+        console.log(`${this.lc} [stop] Closing and unmounting tutorial overlay.`);
+        this.active = false;
+        window.removeEventListener('resize', this.boundHandleResize);
+        window.removeEventListener('keydown', this.boundHandleKeydown);
+
+        if (this.overlayContainer && this.overlayContainer.parentNode) {
+            this.overlayContainer.parentNode.removeChild(this.overlayContainer);
+        }
+        this.overlayContainer = undefined;
+        this.backdrop = undefined;
+        this.spotlightRing = undefined;
+        this.beacon = undefined;
+        this.card = undefined;
+        this.cursor = undefined;
+        this.script = undefined;
+    }
+
+    /**
+     * Smoothly animates the virtual mouse cursor to a target element or coordinate,
+     * and performs a visual mouse-down / click-ripple effect.
+     */
+    public async animateMouseClick(
+        target: HTMLElement | { x: number; y: number },
+        options: {
+            durationMs?: number;
+            clickHoldMs?: number;
+            startPos?: { x: number; y: number };
+            hideAfterMs?: number;
+        } = {}
+    ): Promise<void> {
+        if (!this.cursor) return;
+
+        const duration = options.durationMs ?? 750;
+        const clickHold = options.clickHoldMs ?? 250;
+
+        let toX: number;
+        let toY: number;
+
+        if (target instanceof HTMLElement) {
+            const rect = target.getBoundingClientRect();
+            toX = rect.left + rect.width / 2;
+            toY = rect.top + rect.height / 2;
+        } else {
+            toX = target.x;
+            toY = target.y;
+        }
+
+        // Determine starting position
+        let fromX = this.cursorX;
+        let fromY = this.cursorY;
+
+        if (fromX < 0 || fromY < 0 || isNaN(fromX) || isNaN(fromY)) {
+            if (options.startPos) {
+                fromX = options.startPos.x;
+                fromY = options.startPos.y;
+            } else {
+                fromX = Math.min(window.innerWidth - 60, Math.max(20, toX + 160));
+                fromY = Math.min(window.innerHeight - 60, Math.max(20, toY + 140));
+            }
+        }
+
+        this.cursor.style.transform = `translate(${fromX}px, ${fromY}px)`;
+        this.cursor.classList.add('visible');
+        this.cursor.classList.remove('clicking');
+
+        // Animate smooth gliding trajectory using Web Animations API
+        const anim = this.cursor.animate([
+            { transform: `translate(${fromX}px, ${fromY}px)` },
+            { transform: `translate(${toX}px, ${toY}px)` }
+        ], {
+            duration,
+            easing: 'cubic-bezier(0.22, 1, 0.36, 1)',
+            fill: 'forwards'
+        });
+
+        await new Promise<void>(resolve => {
+            anim.onfinish = () => resolve();
+        });
+
+        this.cursorX = toX;
+        this.cursorY = toY;
+        this.cursor.style.transform = `translate(${toX}px, ${toY}px)`;
+
+        // Perform tactile click down animation (squash pointer + expand golden ripple)
+        this.cursor.classList.add('clicking');
+        await new Promise(r => setTimeout(r, clickHold));
+        this.cursor.classList.remove('clicking');
+
+        if (options.hideAfterMs !== undefined && options.hideAfterMs >= 0) {
+            setTimeout(() => {
+                this.hideCursor();
+            }, options.hideAfterMs);
+        }
+    }
+
+    /**
+     * Hides the virtual mouse cursor.
+     */
+    public hideCursor(): void {
+        if (!this.cursor) return;
+        this.cursor.classList.remove('visible', 'clicking');
+        this.cursorX = -9999;
+        this.cursorY = -9999;
+    }
+
+    /**
+     * Temporarily fades out overlay cards, beacons, and spotlights so the underlying app
+     * can run animations without visual clutter.
+     */
+    public hideOverlayElements(): void {
+        if (this.card) {
+            this.card.style.opacity = '0';
+            this.card.style.pointerEvents = 'none';
+        }
+        if (this.beacon) {
+            this.beacon.style.opacity = '0';
+            this.beacon.style.pointerEvents = 'none';
+        }
+        if (this.spotlightRing) {
+            this.spotlightRing.style.display = 'none';
+        }
+        if (this.backdrop) {
+            this.backdrop.classList.remove('backdrop-active');
+            this.backdrop.style.opacity = '0';
+        }
+    }
+
+    /**
+     * Restores overlay card and beacon visibility after transition actions complete.
+     */
+    public showOverlayElements(): void {
+        if (this.card) {
+            this.card.style.opacity = '1';
+            this.card.style.pointerEvents = 'auto';
+        }
+        if (this.beacon) {
+            this.beacon.style.opacity = '1';
+            this.beacon.style.pointerEvents = 'auto';
+        }
+    }
+
+    private mountOverlay(): void {
+        if (this.overlayContainer) return;
+        console.log(`${this.lc} [mountOverlay] Mounting DOM elements and fallback styles...`);
+
+        // Inject inline fallback styles if not already present
+        if (!document.getElementById('tutorial-inline-styles')) {
+            const style = document.createElement('style');
+            style.id = 'tutorial-inline-styles';
+            style.textContent = `
+                .tutorial-overlay-container { position: fixed; inset: 0; z-index: 10000; pointer-events: none; overflow: hidden; }
+                .tutorial-backdrop { position: absolute; inset: 0; background: rgba(8, 10, 15, 0.82); backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px); pointer-events: auto; opacity: 0; transition: opacity 0.3s ease; }
+                .tutorial-backdrop.backdrop-active { opacity: 1; }
+                .tutorial-spotlight-ring { position: absolute; border-radius: 8px; background: transparent !important; box-shadow: 0 0 0 9999px rgba(8, 10, 15, 0.82), 0 0 0 3px rgba(255, 204, 0, 0.85), 0 0 25px 6px rgba(255, 180, 0, 0.45); pointer-events: none; z-index: 10001; }
+                .tutorial-cursor { position: fixed; top: 0; left: 0; width: 32px; height: 32px; z-index: 10006; pointer-events: none; opacity: 0; transform: translate(-9999px, -9999px); transition: opacity 0.25s ease; }
+                .tutorial-cursor.visible { opacity: 1; }
+                .tutorial-cursor-pointer { filter: drop-shadow(0 3px 8px rgba(0, 0, 0, 0.7)); transition: transform 0.12s ease; transform-origin: 0 0; }
+                .tutorial-cursor.clicking .tutorial-cursor-pointer { transform: scale(0.82); }
+                .tutorial-cursor-ripple { position: absolute; top: 0; left: 0; width: 36px; height: 36px; border-radius: 50%; border: 2px solid #ffd700; background: rgba(255, 215, 0, 0.25); box-shadow: 0 0 16px rgba(255, 215, 0, 0.85); transform: translate(-18px, -18px) scale(0); opacity: 0; pointer-events: none; }
+                .tutorial-cursor.clicking .tutorial-cursor-ripple { animation: cursor-ripple-anim 0.55s cubic-bezier(0.1, 0.8, 0.3, 1) forwards; }
+                @keyframes cursor-ripple-anim { 0% { transform: translate(-18px, -18px) scale(0.2); opacity: 1; } 100% { transform: translate(-18px, -18px) scale(2.5); opacity: 0; } }
+                .tutorial-beacon { position: absolute; display: flex; align-items: center; gap: 8px; padding: 8px 18px; background: linear-gradient(135deg, #ffd700 0%, #ff9900 100%); color: #121212; font-size: 0.95rem; font-weight: 700; border: 2px solid rgba(255, 255, 255, 0.8); border-radius: 9999px; box-shadow: 0 4px 20px rgba(255, 180, 0, 0.65); cursor: pointer; pointer-events: auto; z-index: 10002; transition: top 0.35s ease, left 0.35s ease, transform 0.2s ease, opacity 0.25s ease; }
+                .tutorial-card { position: absolute; width: 440px; max-width: calc(100vw - 32px); background: rgba(18, 22, 34, 0.95); backdrop-filter: blur(16px); -webkit-backdrop-filter: blur(16px); border: 1px solid rgba(255, 215, 0, 0.35); border-radius: 14px; box-shadow: 0 16px 40px rgba(0, 0, 0, 0.75); padding: 22px 24px; color: #e2e8f0; pointer-events: auto; z-index: 10002; transition: top 0.35s ease, left 0.35s ease, opacity 0.25s ease; }
+                .tutorial-card.placement-center { top: 50% !important; left: 50% !important; transform: translate(-50%, -50%); width: 620px; }
+                .tutorial-card-header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 12px; }
+                .tutorial-step-badge { font-size: 0.75rem; font-weight: 700; text-transform: uppercase; color: #ffd700; background: rgba(255, 215, 0, 0.12); padding: 4px 10px; border-radius: 9999px; border: 1px solid rgba(255, 215, 0, 0.3); }
+                .tutorial-card-close { background: none; border: none; color: #94a3b8; font-size: 1.25rem; cursor: pointer; }
+                .tutorial-card-title { margin: 0 0 12px 0; font-size: 1.25rem; font-weight: 700; color: #ffffff; }
+                .tutorial-card-body { font-size: 0.92rem; line-height: 1.6; color: #cbd5e1; margin-bottom: 20px; max-height: 55vh; overflow-y: auto; }
+                .tutorial-card-footer { display: flex; align-items: center; justify-content: space-between; padding-top: 14px; border-top: 1px solid rgba(255, 255, 255, 0.08); }
+                .tutorial-progress-dots { display: flex; gap: 6px; }
+                .tutorial-dot { width: 8px; height: 8px; border-radius: 9999px; background: rgba(255, 255, 255, 0.2); }
+                .tutorial-dot.active { background: #ffd700; transform: scale(1.25); }
+                .tutorial-card-actions { display: flex; align-items: center; gap: 10px; }
+                .tutorial-btn-skip { background: none; border: none; color: #94a3b8; font-size: 0.85rem; cursor: pointer; }
+                .tutorial-btn-next { background: linear-gradient(135deg, #ffd700 0%, #ffaa00 100%); color: #0f172a; font-weight: 700; font-size: 0.9rem; padding: 8px 18px; border: none; border-radius: 8px; cursor: pointer; }
+            `;
+            document.head.appendChild(style);
+        }
+
+        const container = document.createElement('div');
+        container.className = 'tutorial-overlay-container';
+
+        const backdrop = document.createElement('div');
+        backdrop.className = 'tutorial-backdrop';
+        container.appendChild(backdrop);
+        this.backdrop = backdrop;
+
+        const spotlightRing = document.createElement('div');
+        spotlightRing.className = 'tutorial-spotlight-ring';
+        container.appendChild(spotlightRing);
+        this.spotlightRing = spotlightRing;
+
+        const beacon = document.createElement('button');
+        beacon.className = 'tutorial-beacon';
+        beacon.type = 'button';
+        beacon.addEventListener('click', (e) => {
+            e.stopPropagation();
+            console.log(`${this.lc} [beacon.click] Beacon clicked! Advancing...`);
+            this.next();
+        });
+        container.appendChild(beacon);
+        this.beacon = beacon;
+
+        const card = document.createElement('div');
+        card.className = 'tutorial-card';
+        container.appendChild(card);
+        this.card = card;
+
+        // Virtual mouse cursor element
+        const cursor = document.createElement('div');
+        cursor.className = 'tutorial-cursor';
+        cursor.id = 'tutorial-cursor';
+        cursor.innerHTML = `
+            <svg class="tutorial-cursor-pointer" viewBox="0 0 24 24" width="28" height="28" fill="none">
+                <path d="M5.5 3.21V20.8c0 .45.54.67.85.35l4.86-4.86a.5.5 0 0 1 .35-.15h6.87a.5.5 0 0 0 .35-.85L6.35 2.86a.5.5 0 0 0-.85.35z" fill="#ffd700" stroke="#0f172a" stroke-width="1.5" stroke-linejoin="round"/>
+            </svg>
+            <div class="tutorial-cursor-ripple"></div>
+        `;
+        container.appendChild(cursor);
+        this.cursor = cursor;
+
+        document.body.appendChild(container);
+        this.overlayContainer = container;
+        console.log(`${this.lc} [mountOverlay] Tutorial overlay successfully mounted to document.body.`);
+    }
+
+    private async renderStep(stepIndex: number): Promise<void> {
+        if (!this.script || !this.card || !this.beacon || !this.spotlightRing) return;
+
+        const step = this.script.steps[stepIndex];
+        const totalSteps = this.script.steps.length;
+        console.log(`${this.lc} [renderStep] Step ${stepIndex + 1}/${totalSteps}: "${step.title}", target=#${step.targetElementId || '(center)'}`);
+
+        // 1. Execute step programmatic action if defined
+        if (step.action) {
+            try {
+                console.log(`${this.lc} [renderStep] Executing step action...`);
+                const ctx: TutorialActionContext = {
+                    shell: this.shell,
+                    metaspace: this.shell?.metaspace,
+                    galaxyName: this.shell?.fileExplorerInstance?.getGalaxyName?.() || 'code-1',
+                    branchName: this.shell?.fileExplorerInstance?.getBranchName?.() || 'main',
+                };
+                await step.action(ctx);
+                console.log(`${this.lc} [renderStep] Step action completed.`);
+            } catch (err) {
+                console.warn(`${this.lc} [renderStep] Step action failed:`, err);
+            }
+        }
+
+        // 2. Populate Card Content
+        const isFinalStep = stepIndex === totalSteps - 1;
+        const buttonText = step.buttonText || (isFinalStep ? 'Finish Tour ✨' : 'Next ➔');
+
+        const dotsHtml = this.script.steps
+            .map((_, i) => `<span class="tutorial-dot ${i === stepIndex ? 'active' : ''}"></span>`)
+            .join('');
+
+        this.card.innerHTML = `
+            <div class="tutorial-card-header">
+                <span class="tutorial-step-badge">Step ${stepIndex + 1} of ${totalSteps}</span>
+                <button class="tutorial-card-close" title="Close Tour (Esc)">✕</button>
+            </div>
+            <h3 class="tutorial-card-title">${step.title}</h3>
+            <div class="tutorial-card-body">${step.narration}</div>
+            <div class="tutorial-card-footer">
+                <div class="tutorial-progress-dots">${dotsHtml}</div>
+                <div class="tutorial-card-actions">
+                    <button class="tutorial-btn-skip">Skip</button>
+                    <button class="tutorial-btn-next">${buttonText}</button>
+                </div>
+            </div>
+        `;
+
+        // Wire Card buttons
+        const btnClose = this.card.querySelector('.tutorial-card-close');
+        btnClose?.addEventListener('click', (e) => {
+            e.stopPropagation();
+            console.log(`${this.lc} [card.close] Close button clicked.`);
+            this.stop();
+        });
+
+        const btnSkip = this.card.querySelector('.tutorial-btn-skip');
+        btnSkip?.addEventListener('click', (e) => {
+            e.stopPropagation();
+            console.log(`${this.lc} [card.skip] Skip button clicked.`);
+            this.stop();
+        });
+
+        const btnNext = this.card.querySelector('.tutorial-btn-next');
+        btnNext?.addEventListener('click', (e) => {
+            e.stopPropagation();
+            console.log(`${this.lc} [card.next] Next button clicked.`);
+            this.next();
+        });
+
+        // 3. Populate Beacon Label
+        const beaconLabel = step.beaconLabel || (isFinalStep ? 'Invest 💰' : 'Next ✨');
+        this.beacon.innerHTML = `
+            <span class="tutorial-beacon-icon">✨</span>
+            <span class="tutorial-beacon-text">${beaconLabel}</span>
+        `;
+
+        // 4. Update Positions
+        this.showOverlayElements();
+        requestAnimationFrame(() => {
+            this.positionElements(step);
+        });
+    }
+
+    private positionElements(step: TutorialStep): void {
+        if (!this.card || !this.beacon || !this.spotlightRing || !this.backdrop) return;
+
+        const placement = step.placement || 'bottom';
+        console.log(`${this.lc} [positionElements] Calculating positions for target="#${step.targetElementId}", placement="${placement}"`);
+
+        if (placement === 'center' || !step.targetElementId) {
+            console.log(`${this.lc} [positionElements] Positioning in center of viewport.`);
+            this.card.className = 'tutorial-card placement-center';
+            this.card.style.top = '50%';
+            this.card.style.left = '50%';
+            this.card.style.transform = 'translate(-50%, -50%)';
+
+            this.spotlightRing.style.display = 'none';
+            this.backdrop.classList.add('backdrop-active');
+
+            this.beacon.style.top = 'calc(50% - 240px)';
+            this.beacon.style.left = '50%';
+            this.beacon.style.transform = 'translateX(-50%)';
+            return;
+        }
+
+        const targetEl = findElementDeep(step.targetElementId);
+        if (!targetEl) {
+            console.warn(`${this.lc} [positionElements] Target element #${step.targetElementId} not found in DOM! Falling back to center.`);
+            this.card.className = 'tutorial-card placement-center';
+            this.card.style.top = '50%';
+            this.card.style.left = '50%';
+            this.card.style.transform = 'translate(-50%, -50%)';
+            this.spotlightRing.style.display = 'none';
+            this.backdrop.classList.add('backdrop-active');
+            this.beacon.style.top = '30px';
+            this.beacon.style.left = '50%';
+            this.beacon.style.transform = 'translateX(-50%)';
+            return;
+        }
+
+        this.card.className = `tutorial-card placement-${placement}`;
+        this.card.style.transform = 'none';
+        this.spotlightRing.style.display = 'block';
+
+        // When spotlight is active, the spotlight ring's huge box-shadow creates the dark veil,
+        // so we deactivate the backdrop blur to keep the inside 100% crystal-clear and crisp!
+        this.backdrop.classList.remove('backdrop-active');
+
+        const rect = targetEl.getBoundingClientRect();
+        console.log(`${this.lc} [positionElements] Target #${step.targetElementId} rect:`, rect);
+        const pad = 6;
+
+        // Position Spotlight Ring around Target with 100% transparent cutout
+        this.spotlightRing.style.top = `${Math.max(0, rect.top - pad)}px`;
+        this.spotlightRing.style.left = `${Math.max(0, rect.left - pad)}px`;
+        this.spotlightRing.style.width = `${rect.width + pad * 2}px`;
+        this.spotlightRing.style.height = `${rect.height + pad * 2}px`;
+
+        // Position Beacon adjacent to target
+        const beaconTop = Math.max(10, rect.top + 8);
+        const beaconLeft = Math.min(window.innerWidth - 180, Math.max(10, rect.right - 140));
+        this.beacon.style.top = `${beaconTop}px`;
+        this.beacon.style.left = `${beaconLeft}px`;
+        this.beacon.style.transform = 'none';
+
+        // Position Card according to placement
+        const cardWidth = 440;
+        const cardGap = 16;
+        let cardTop = 0;
+        let cardLeft = 0;
+
+        switch (placement) {
+            case 'bottom':
+                cardTop = rect.bottom + cardGap;
+                cardLeft = Math.max(16, Math.min(window.innerWidth - cardWidth - 16, rect.left + (rect.width / 2) - (cardWidth / 2)));
+                break;
+            case 'top':
+                cardTop = Math.max(16, rect.top - 280 - cardGap);
+                cardLeft = Math.max(16, Math.min(window.innerWidth - cardWidth - 16, rect.left + (rect.width / 2) - (cardWidth / 2)));
+                break;
+            case 'right':
+                cardTop = Math.max(16, Math.min(window.innerHeight - 360, rect.top));
+                cardLeft = Math.min(window.innerWidth - cardWidth - 16, rect.right + cardGap);
+                break;
+            case 'left':
+                cardTop = Math.max(16, Math.min(window.innerHeight - 360, rect.top));
+                cardLeft = Math.max(16, rect.left - cardWidth - cardGap);
+                break;
+        }
+
+        // Clamp inside window boundaries
+        cardTop = Math.max(16, Math.min(window.innerHeight - 320, cardTop));
+        cardLeft = Math.max(16, Math.min(window.innerWidth - cardWidth - 16, cardLeft));
+
+        this.card.style.top = `${cardTop}px`;
+        this.card.style.left = `${cardLeft}px`;
+
+        console.log(`${this.lc} [positionElements] Successfully positioned: card=(${cardLeft}px, ${cardTop}px), beacon=(${beaconLeft}px, ${beaconTop}px)`);
+    }
+
+    private handleResize(): void {
+        if (!this.active || !this.script) return;
+        const step = this.script.steps[this.currentStepIndex];
+        if (step) {
+            this.positionElements(step);
+        }
+    }
+
+    private handleKeydown(e: KeyboardEvent): void {
+        if (!this.active) return;
+
+        if (e.key === 'Escape') {
+            console.log(`${this.lc} [keydown] Escape pressed -> stop()`);
+            e.preventDefault();
+            this.stop();
+        } else if (e.key === 'ArrowRight' || e.key === 'Enter') {
+            if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement) return;
+            console.log(`${this.lc} [keydown] ${e.key} pressed -> next()`);
+            e.preventDefault();
+            this.next();
+        } else if (e.key === 'ArrowLeft') {
+            console.log(`${this.lc} [keydown] ArrowLeft pressed -> prev()`);
+            e.preventDefault();
+            this.prev();
+        }
+    }
+}
+
+// Module-level singleton
+let _tutorialController: TutorialController | undefined;
+export function getTutorialController(): TutorialController {
+    if (!_tutorialController) {
+        _tutorialController = new TutorialController();
+    }
+    return _tutorialController;
+}

package/src/client/ui/component/tutorial/tutorial-types.mts

@@ -0,0 +1,45 @@
+/**
+ * @module tutorial-types
+ *
+ * Type definitions for the generic Space-Gib Tutorial Runner.
+ */
+
+export interface TutorialActionContext {
+    shell: any;
+    metaspace?: any;
+    space?: any;
+    galaxyName: string;
+    branchName: string;
+}
+
+export type TutorialPlacement = 'top' | 'bottom' | 'left' | 'right' | 'center';
+
+export interface TutorialStep {
+    /** Unique step identifier */
+    id: string;
+    /** Header title displayed on the narration card */
+    title: string;
+    /** Formatted HTML / Markdown narration content */
+    narration: string;
+    /** Target DOM element ID to spotlight and anchor to */
+    targetElementId?: string;
+    /** Placement of the card relative to the target element */
+    placement?: TutorialPlacement;
+    /** Text for the action / advance button */
+    buttonText?: string;
+    /** Label for the golden beacon */
+    beaconLabel?: string;
+    /** Optional async action executed when step becomes active */
+    action?: (context: TutorialActionContext) => Promise<void>;
+    /**
+     * Optional async in-between transition action executed when advancing from this step to the next.
+     * The overlay card, beacon, and spotlight are hidden while this action executes so the screen is clear.
+     */
+    transitionAction?: (context: TutorialActionContext, controller: any) => Promise<void>;
+}
+
+export interface TutorialScript {
+    id: string;
+    title: string;
+    steps: TutorialStep[];
+}