Add interactive tutorial system for calibration and device cards

Generic tutorial engine supports absolute (modal) and fixed (viewport)
positioning modes with spotlight backdrop, pulsing ring, and tooltip.
Calibration tutorial covers LED count, corner, direction, offset, span,
test, and toggle inputs. Device tutorial walks through card controls.
Auto-triggers on first calibration open and first device add.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

server/src/wled_controller/static/app.js

@@ -611,6 +611,7 @@ function createDeviceCard(device) {
                 </a>
                 ` : ''}
             </div>
+            <button class="card-tutorial-btn" onclick="startDeviceTutorial('${device.id}')" title="${t('device.tutorial.start')}">?</button>
         </div>
     `;
 }
@@ -933,7 +934,12 @@ async function handleAddDevice(event) {
             console.log('Device added successfully:', result);
             showToast('Device added successfully', 'success');
             closeAddDeviceModal();
-            loadDevices();
+            await loadDevices();
+            // Auto-start device tutorial on first device add
+            if (!localStorage.getItem('deviceTutorialSeen')) {
+                localStorage.setItem('deviceTutorialSeen', '1');
+                setTimeout(() => startDeviceTutorial(), 300);
+            }
         } else {
             const errorData = await response.json();
             console.error('Failed to add device:', errorData);
@@ -1090,7 +1096,14 @@ async function showCalibration(deviceId) {
 
         // Initialize span drag and render canvas after layout settles
         initSpanDrag();
-        requestAnimationFrame(() => renderCalibrationCanvas());
+        requestAnimationFrame(() => {
+            renderCalibrationCanvas();
+            // Auto-start tutorial on first open
+            if (!localStorage.getItem('calibrationTutorialSeen')) {
+                localStorage.setItem('calibrationTutorialSeen', '1');
+                startCalibrationTutorial();
+            }
+        });
 
         // Re-render on container resize (e.g. window resize changes aspect-ratio container)
         if (!window._calibrationResizeObserver) {
@@ -1121,6 +1134,7 @@ function isCalibrationDirty() {
 }
 
 function forceCloseCalibrationModal() {
+    closeTutorial();
     const deviceId = document.getElementById('calibration-device-id').value;
     if (deviceId) {
         clearTestMode(deviceId);
@@ -1828,6 +1842,7 @@ document.addEventListener('mousedown', (e) => {
 document.addEventListener('click', (e) => {
     if (!e.target.classList.contains('modal')) return;
     if (backdropMouseDownTarget !== e.target) return;
+    if (activeTutorial) return;
 
     const modalId = e.target.id;
 
@@ -1871,3 +1886,229 @@ window.addEventListener('beforeunload', () => {
         clearInterval(refreshInterval);
     }
 });
+
+// =============================================================================
+// Tutorial System (generic engine)
+// =============================================================================
+
+let activeTutorial = null;
+// Shape: { steps, overlay, mode, step, resolveTarget, container }
+// mode: 'absolute' (within a container) or 'fixed' (viewport-level)
+
+const calibrationTutorialSteps = [
+    { selector: '#cal-top-leds', textKey: 'calibration.tip.led_count', position: 'bottom' },
+    { selector: '.corner-bottom-left', textKey: 'calibration.tip.start_corner', position: 'right' },
+    { selector: '.direction-toggle', textKey: 'calibration.tip.direction', position: 'bottom' },
+    { selector: '.offset-control', textKey: 'calibration.tip.offset', position: 'bottom' },
+    { selector: '.edge-span-bar[data-edge="top"]', textKey: 'calibration.tip.span', position: 'bottom' },
+    { selector: '.toggle-top', textKey: 'calibration.tip.test', position: 'top' },
+    { selector: '.preview-screen-total', textKey: 'calibration.tip.toggle_inputs', position: 'bottom' }
+];
+
+const deviceTutorialSteps = [
+    { selector: '.card-subtitle', textKey: 'device.tip.metadata', position: 'bottom' },
+    { selector: '.brightness-control', textKey: 'device.tip.brightness', position: 'bottom' },
+    { selector: '.card-actions .btn:nth-child(1)', textKey: 'device.tip.start', position: 'top' },
+    { selector: '.card-actions .btn:nth-child(2)', textKey: 'device.tip.settings', position: 'top' },
+    { selector: '.card-actions .btn:nth-child(3)', textKey: 'device.tip.calibrate', position: 'top' },
+    { selector: '.card-actions .btn:nth-child(4)', textKey: 'device.tip.webui', position: 'top' }
+];
+
+function startTutorial(config) {
+    closeTutorial();
+    const overlay = document.getElementById(config.overlayId);
+    if (!overlay) return;
+
+    activeTutorial = {
+        steps: config.steps,
+        overlay: overlay,
+        mode: config.mode,
+        step: 0,
+        resolveTarget: config.resolveTarget,
+        container: config.container
+    };
+
+    overlay.classList.add('active');
+    document.addEventListener('keydown', handleTutorialKey);
+    showTutorialStep(0);
+}
+
+function startCalibrationTutorial() {
+    const container = document.querySelector('#calibration-modal .modal-body');
+    if (!container) return;
+    startTutorial({
+        steps: calibrationTutorialSteps,
+        overlayId: 'tutorial-overlay',
+        mode: 'absolute',
+        container: container,
+        resolveTarget: (step) => document.querySelector(step.selector)
+    });
+}
+
+function startDeviceTutorial(deviceId) {
+    // Resolve the device ID to target (don't capture card reference — it goes stale when loadDevices rebuilds DOM)
+    const selector = deviceId
+        ? `.card[data-device-id="${deviceId}"]`
+        : '.card[data-device-id]';
+    if (!document.querySelector(selector)) return;
+    startTutorial({
+        steps: deviceTutorialSteps,
+        overlayId: 'device-tutorial-overlay',
+        mode: 'fixed',
+        container: null,
+        resolveTarget: (step) => {
+            const card = document.querySelector(selector);
+            if (!card) return null;
+            return step.global
+                ? document.querySelector(step.selector)
+                : card.querySelector(step.selector);
+        }
+    });
+}
+
+function closeTutorial() {
+    if (!activeTutorial) return;
+    activeTutorial.overlay.classList.remove('active');
+    document.querySelectorAll('.tutorial-target').forEach(el => {
+        el.classList.remove('tutorial-target');
+        el.style.zIndex = '';
+    });
+    document.removeEventListener('keydown', handleTutorialKey);
+    activeTutorial = null;
+}
+
+function tutorialNext() {
+    if (!activeTutorial) return;
+    if (activeTutorial.step < activeTutorial.steps.length - 1) {
+        showTutorialStep(activeTutorial.step + 1);
+    } else {
+        closeTutorial();
+    }
+}
+
+function tutorialPrev() {
+    if (!activeTutorial) return;
+    if (activeTutorial.step > 0) {
+        showTutorialStep(activeTutorial.step - 1);
+    }
+}
+
+function showTutorialStep(index) {
+    if (!activeTutorial) return;
+    activeTutorial.step = index;
+    const step = activeTutorial.steps[index];
+    const overlay = activeTutorial.overlay;
+    const isFixed = activeTutorial.mode === 'fixed';
+
+    // Remove previous target highlight
+    document.querySelectorAll('.tutorial-target').forEach(el => {
+        el.classList.remove('tutorial-target');
+        el.style.zIndex = '';
+    });
+
+    // Find and highlight target
+    const target = activeTutorial.resolveTarget(step);
+    if (!target) return;
+    target.classList.add('tutorial-target');
+    // For fixed overlays, target must be above the z-index:10000 overlay
+    if (isFixed) target.style.zIndex = '10001';
+
+    const targetRect = target.getBoundingClientRect();
+    const pad = 6;
+    let x, y, w, h;
+
+    if (isFixed) {
+        // Fixed mode: coordinates are viewport-relative
+        x = targetRect.left - pad;
+        y = targetRect.top - pad;
+        w = targetRect.width + pad * 2;
+        h = targetRect.height + pad * 2;
+    } else {
+        // Absolute mode: coordinates relative to container
+        const containerRect = activeTutorial.container.getBoundingClientRect();
+        x = targetRect.left - containerRect.left - pad;
+        y = targetRect.top - containerRect.top - pad;
+        w = targetRect.width + pad * 2;
+        h = targetRect.height + pad * 2;
+    }
+
+    // Update backdrop clip-path (polygon with rectangular cutout)
+    const backdrop = overlay.querySelector('.tutorial-backdrop');
+    if (backdrop) {
+        backdrop.style.clipPath = `polygon(
+            0% 0%, 0% 100%,
+            ${x}px 100%, ${x}px ${y}px,
+            ${x + w}px ${y}px, ${x + w}px ${y + h}px,
+            ${x}px ${y + h}px, ${x}px 100%,
+            100% 100%, 100% 0%)`;
+    }
+
+    // Position ring around target
+    const ring = overlay.querySelector('.tutorial-ring');
+    if (ring) {
+        ring.style.left = x + 'px';
+        ring.style.top = y + 'px';
+        ring.style.width = w + 'px';
+        ring.style.height = h + 'px';
+    }
+
+    // Update tooltip content
+    const tooltip = overlay.querySelector('.tutorial-tooltip');
+    const textEl = overlay.querySelector('.tutorial-tooltip-text');
+    const counterEl = overlay.querySelector('.tutorial-step-counter');
+    if (textEl) textEl.textContent = t(step.textKey);
+    if (counterEl) counterEl.textContent = `${index + 1} / ${activeTutorial.steps.length}`;
+
+    // Enable/disable nav buttons
+    const prevBtn = overlay.querySelector('.tutorial-prev-btn');
+    const nextBtn = overlay.querySelector('.tutorial-next-btn');
+    if (prevBtn) prevBtn.disabled = (index === 0);
+    if (nextBtn) nextBtn.textContent = (index === activeTutorial.steps.length - 1) ? '\u2713' : '\u2192';
+
+    // Position tooltip
+    if (tooltip) {
+        positionTutorialTooltip(tooltip, x, y, w, h, step.position, isFixed);
+    }
+}
+
+function positionTutorialTooltip(tooltip, sx, sy, sw, sh, preferred, isFixed) {
+    const gap = 12;
+    const tooltipW = 260;
+    // Place offscreen to measure real height without visual flash
+    tooltip.setAttribute('style', 'left:-9999px;top:-9999px');
+    const tooltipH = tooltip.offsetHeight || 150;
+
+    const positions = {
+        top:    { x: sx + sw / 2 - tooltipW / 2, y: sy - tooltipH - gap },
+        bottom: { x: sx + sw / 2 - tooltipW / 2, y: sy + sh + gap },
+        left:   { x: sx - tooltipW - gap, y: sy + sh / 2 - tooltipH / 2 },
+        right:  { x: sx + sw + gap, y: sy + sh / 2 - tooltipH / 2 }
+    };
+
+    let pos = positions[preferred] || positions.bottom;
+
+    const cW = isFixed ? window.innerWidth : activeTutorial.container.clientWidth;
+    const cH = isFixed ? window.innerHeight : activeTutorial.container.clientHeight;
+
+    // If preferred position overflows, try opposite
+    if (pos.y + tooltipH > cH || pos.y < 0 || pos.x + tooltipW > cW || pos.x < 0) {
+        const opposite = { top: 'bottom', bottom: 'top', left: 'right', right: 'left' };
+        const alt = positions[opposite[preferred]];
+        if (alt && alt.y >= 0 && alt.y + tooltipH <= cH && alt.x >= 0 && alt.x + tooltipW <= cW) {
+            pos = alt;
+        }
+    }
+
+    pos.x = Math.max(8, Math.min(cW - tooltipW - 8, pos.x));
+    pos.y = Math.max(8, Math.min(cH - tooltipH - 8, pos.y));
+
+    // Force-set all positioning via setAttribute to avoid any style-setting quirks
+    tooltip.setAttribute('style', `left:${Math.round(pos.x)}px;top:${Math.round(pos.y)}px`);
+}
+
+function handleTutorialKey(e) {
+    if (!activeTutorial) return;
+    if (e.key === 'Escape') { closeTutorial(); e.stopPropagation(); }
+    else if (e.key === 'ArrowRight' || e.key === 'ArrowDown') { e.preventDefault(); tutorialNext(); }
+    else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') { e.preventDefault(); tutorialPrev(); }
+}

server/src/wled_controller/static/index.html

@@ -80,17 +80,11 @@
         <div class="modal-content" style="max-width: 700px;">
             <div class="modal-header">
                 <h2 data-i18n="calibration.title">📐 LED Calibration</h2>
+                <button class="tutorial-trigger-btn" onclick="startCalibrationTutorial()" data-i18n-title="calibration.tutorial.start" title="Start tutorial">?</button>
                 <button class="modal-close-btn" onclick="closeCalibrationModal()" title="Close">&#x2715;</button>
             </div>
             <div class="modal-body">
                 <input type="hidden" id="calibration-device-id">
-                <ul class="section-tip">
-                    <li data-i18n="calibration.tip.led_count">Enter LED count per edge</li>
-                    <li data-i18n="calibration.tip.start_corner">Click a corner to set the start position</li>
-                    <li data-i18n="calibration.tip.span">Drag green bars to adjust coverage span</li>
-                    <li data-i18n="calibration.tip.test">Click an edge to toggle test LEDs</li>
-                    <li data-i18n="calibration.tip.toggle_inputs">Click total LED count to toggle edge inputs</li>
-                </ul>
                 <!-- Interactive Preview with integrated LED inputs and test toggles -->
                 <div style="margin-bottom: 12px; padding: 0 24px;">
                     <div class="calibration-preview">
@@ -174,6 +168,23 @@
                 </div>
 
 
+                <!-- Tutorial Overlay -->
+                <div id="tutorial-overlay" class="tutorial-overlay">
+                    <div class="tutorial-backdrop"></div>
+                    <div class="tutorial-ring"></div>
+                    <div class="tutorial-tooltip">
+                        <div class="tutorial-tooltip-header">
+                            <span class="tutorial-step-counter"></span>
+                            <button class="tutorial-close-btn" onclick="closeTutorial()">&times;</button>
+                        </div>
+                        <p class="tutorial-tooltip-text"></p>
+                        <div class="tutorial-tooltip-nav">
+                            <button class="tutorial-prev-btn" onclick="tutorialPrev()">&#8592;</button>
+                            <button class="tutorial-next-btn" onclick="tutorialNext()">&#8594;</button>
+                        </div>
+                    </div>
+                </div>
+
                 <div id="calibration-error" class="error-message" style="display: none;"></div>
             </div>
             <div class="modal-footer">
@@ -310,6 +321,23 @@
     </div>
 
 
+    <!-- Device Tutorial Overlay (viewport-level) -->
+    <div id="device-tutorial-overlay" class="tutorial-overlay tutorial-overlay-fixed">
+        <div class="tutorial-backdrop"></div>
+        <div class="tutorial-ring"></div>
+        <div class="tutorial-tooltip">
+            <div class="tutorial-tooltip-header">
+                <span class="tutorial-step-counter"></span>
+                <button class="tutorial-close-btn" onclick="closeTutorial()">&times;</button>
+            </div>
+            <p class="tutorial-tooltip-text"></p>
+            <div class="tutorial-tooltip-nav">
+                <button class="tutorial-prev-btn" onclick="tutorialPrev()">&#8592;</button>
+                <button class="tutorial-next-btn" onclick="tutorialNext()">&#8594;</button>
+            </div>
+        </div>
+    </div>
+
     <script src="/static/app.js"></script>
     <script>
         // Initialize theme

server/src/wled_controller/static/locales/en.json

@@ -77,6 +77,14 @@
   "device.health.online": "WLED Online",
   "device.health.offline": "WLED Offline",
   "device.health.checking": "Checking...",
+  "device.tutorial.start": "Start tutorial",
+  "device.tip.metadata": "Device info (LED count, type, color channels) is auto-detected from WLED",
+  "device.tip.brightness": "Slide to adjust device brightness",
+  "device.tip.start": "Start or stop screen capture processing",
+  "device.tip.settings": "Configure device settings (display, FPS, health check)",
+  "device.tip.calibrate": "Calibrate LED positions, direction, and coverage",
+  "device.tip.webui": "Open WLED's built-in web interface for advanced configuration",
+  "device.tip.add": "Click here to add a new WLED device",
   "settings.title": "Device Settings",
   "settings.brightness": "Brightness:",
   "settings.brightness.hint": "Global brightness for this WLED device (0-100%)",
@@ -92,9 +100,12 @@
   "calibration.title": "LED Calibration",
   "calibration.tip.led_count": "Enter LED count per edge",
   "calibration.tip.start_corner": "Click a corner to set the start position",
+  "calibration.tip.direction": "Toggle LED strip direction (clockwise / counterclockwise)",
+  "calibration.tip.offset": "Set LED offset — distance from LED 0 to the start corner",
   "calibration.tip.span": "Drag green bars to adjust coverage span",
   "calibration.tip.test": "Click an edge to toggle test LEDs",
   "calibration.tip.toggle_inputs": "Click total LED count to toggle edge inputs",
+  "calibration.tutorial.start": "Start tutorial",
   "calibration.start_position": "Starting Position:",
   "calibration.position.bottom_left": "Bottom Left",
   "calibration.position.bottom_right": "Bottom Right",

server/src/wled_controller/static/locales/ru.json

@@ -77,6 +77,14 @@
   "device.health.online": "WLED Онлайн",
   "device.health.offline": "WLED Недоступен",
   "device.health.checking": "Проверка...",
+  "device.tutorial.start": "Начать обучение",
+  "device.tip.metadata": "Информация об устройстве (кол-во LED, тип, цветовые каналы) определяется автоматически из WLED",
+  "device.tip.brightness": "Перетащите для регулировки яркости",
+  "device.tip.start": "Запуск или остановка захвата экрана",
+  "device.tip.settings": "Настройки устройства (дисплей, FPS, интервал проверки)",
+  "device.tip.calibrate": "Калибровка позиций LED, направления и зоны покрытия",
+  "device.tip.webui": "Открыть встроенный веб-интерфейс WLED для расширенной настройки",
+  "device.tip.add": "Нажмите, чтобы добавить новое WLED устройство",
   "settings.title": "Настройки Устройства",
   "settings.brightness": "Яркость:",
   "settings.brightness.hint": "Общая яркость для этого WLED устройства (0-100%)",
@@ -92,9 +100,12 @@
   "calibration.title": "Калибровка Светодиодов",
   "calibration.tip.led_count": "Укажите количество LED на каждой стороне",
   "calibration.tip.start_corner": "Нажмите на угол для выбора стартовой позиции",
+  "calibration.tip.direction": "Переключение направления ленты (по часовой / против часовой)",
+  "calibration.tip.offset": "Смещение LED — расстояние от LED 0 до стартового угла",
   "calibration.tip.span": "Перетащите зелёные полосы для настройки зоны покрытия",
   "calibration.tip.test": "Нажмите на край для теста LED",
   "calibration.tip.toggle_inputs": "Нажмите на общее количество LED для скрытия боковых полей",
+  "calibration.tutorial.start": "Начать обучение",
   "calibration.start_position": "Начальная Позиция:",
   "calibration.position.bottom_left": "Нижний Левый",
   "calibration.position.bottom_right": "Нижний Правый",

server/src/wled_controller/static/style.css

@@ -206,7 +206,7 @@ section {
     background: var(--card-bg);
     border: 1px solid var(--border-color);
     border-radius: 8px;
-    padding: 20px;
+    padding: 12px 20px 20px;
     position: relative;
     transition: transform 0.2s, box-shadow 0.2s;
 }
@@ -215,6 +215,31 @@ section {
     box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
 }
 
+.card-tutorial-btn {
+    position: absolute;
+    bottom: 10px;
+    right: 10px;
+    background: none;
+    border: 1.5px solid var(--border-color);
+    color: var(--text-muted, #777);
+    font-size: 0.7rem;
+    font-weight: bold;
+    width: 20px;
+    height: 20px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    border-radius: 50%;
+    transition: color 0.2s, background 0.2s, border-color 0.2s;
+    padding: 0;
+}
+
+.card-tutorial-btn:hover {
+    border-color: var(--primary-color);
+    color: var(--primary-color);
+}
+
 .card-remove-btn {
     position: absolute;
     top: 10px;
@@ -242,7 +267,7 @@ section {
     display: flex;
     justify-content: space-between;
     align-items: center;
-    margin-bottom: 4px;
+    margin-bottom: 10px;
     padding-right: 30px;
 }
 
@@ -1368,3 +1393,202 @@ input:-webkit-autofill:focus {
     }
 }
 
+/* Tutorial System */
+.tutorial-trigger-btn {
+    width: 28px;
+    height: 28px;
+    border-radius: 50%;
+    border: 2px solid var(--primary-color);
+    background: transparent;
+    color: var(--primary-color);
+    font-size: 1rem;
+    font-weight: bold;
+    cursor: pointer;
+    transition: all 0.2s;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    margin-left: auto;
+    margin-right: 8px;
+    flex-shrink: 0;
+}
+
+.tutorial-trigger-btn:hover {
+    background: var(--primary-color);
+    color: white;
+}
+
+#calibration-modal .modal-body {
+    position: relative;
+}
+
+.tutorial-overlay {
+    display: none;
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    z-index: 100;
+    pointer-events: none;
+}
+
+.tutorial-overlay.active {
+    display: block;
+    pointer-events: auto;
+}
+
+.tutorial-backdrop {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background: rgba(0, 0, 0, 0.7);
+    transition: clip-path 0.3s ease;
+}
+
+.tutorial-ring {
+    position: absolute;
+    border: 2px solid var(--primary-color);
+    border-radius: 6px;
+    pointer-events: none;
+    transition: all 0.3s ease;
+    animation: tutorial-pulse 2s infinite;
+}
+
+@keyframes tutorial-pulse {
+    0%, 100% { box-shadow: 0 0 0 0 rgba(76, 175, 80, 0.6); }
+    50% { box-shadow: 0 0 0 6px rgba(76, 175, 80, 0); }
+}
+
+.tutorial-tooltip {
+    position: absolute;
+    width: 260px;
+    background: var(--card-bg);
+    border: 2px solid var(--primary-color);
+    border-radius: 8px;
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.5);
+    z-index: 102;
+    pointer-events: auto;
+    animation: tutorial-tooltip-in 0.25s ease-out;
+}
+
+@keyframes tutorial-tooltip-in {
+    from { opacity: 0; transform: translateY(-8px); }
+    to { opacity: 1; transform: translateY(0); }
+}
+
+.tutorial-tooltip-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 8px 12px;
+    border-bottom: 1px solid var(--border-color);
+}
+
+.tutorial-step-counter {
+    font-size: 0.8rem;
+    font-weight: 600;
+    color: var(--primary-color);
+}
+
+.tutorial-close-btn {
+    background: none;
+    border: none;
+    color: #777;
+    font-size: 1.3rem;
+    width: 24px;
+    height: 24px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    border-radius: 4px;
+    transition: color 0.2s, background 0.2s;
+    padding: 0;
+    line-height: 1;
+}
+
+.tutorial-close-btn:hover {
+    color: var(--text-color);
+    background: rgba(128, 128, 128, 0.15);
+}
+
+.tutorial-tooltip-text {
+    margin: 0;
+    padding: 12px;
+    line-height: 1.5;
+    color: var(--text-color);
+    font-size: 0.9rem;
+}
+
+.tutorial-tooltip-nav {
+    display: flex;
+    gap: 6px;
+    padding: 8px 12px;
+    border-top: 1px solid var(--border-color);
+}
+
+.tutorial-prev-btn,
+.tutorial-next-btn {
+    flex: 1;
+    padding: 6px;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+    font-size: 1rem;
+    font-weight: 600;
+    transition: opacity 0.2s;
+}
+
+.tutorial-prev-btn {
+    background: var(--border-color);
+    color: var(--text-color);
+}
+
+.tutorial-next-btn {
+    background: var(--primary-color);
+    color: white;
+}
+
+.tutorial-prev-btn:hover:not(:disabled),
+.tutorial-next-btn:hover:not(:disabled) {
+    opacity: 0.85;
+}
+
+.tutorial-prev-btn:disabled,
+.tutorial-next-btn:disabled {
+    opacity: 0.3;
+    cursor: not-allowed;
+}
+
+.tutorial-target {
+    position: relative;
+    z-index: 101 !important;
+}
+
+/* Fixed (viewport-level) tutorial overlay for device cards */
+.tutorial-overlay-fixed {
+    position: fixed;
+    z-index: 10000;
+}
+
+.tutorial-overlay-fixed .tutorial-backdrop {
+    position: fixed;
+}
+
+.tutorial-overlay-fixed .tutorial-ring {
+    position: fixed;
+}
+
+.tutorial-overlay-fixed .tutorial-tooltip {
+    position: absolute;
+    z-index: 10002;
+    animation: none;
+    opacity: 1;
+}
+
+/* target z-index for fixed overlay is set inline via JS (target is outside overlay DOM) */
+
+