diff --git a/CLAUDE.md b/CLAUDE.md
index 5a94b42..bfc4958 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -182,6 +182,15 @@ For range sliders, display the current value **inside the label** (not in a sepa
Do **not** use a `range-with-value` wrapper div.
+### Tutorials
+
+The app has an interactive tutorial system (`static/js/features/tutorials.js`) with a generic engine, spotlight overlay, tooltip positioning, and keyboard navigation. Tutorials exist for:
+- **Getting started** (header-level walkthrough of all tabs and controls)
+- **Per-tab tutorials** (Dashboard, Targets, Sources, Profiles) triggered by `?` buttons
+- **Device card tutorial** and **Calibration tutorial** (context-specific)
+
+When adding **new tabs, sections, or major UI elements**, update the corresponding tutorial step array in `tutorials.js` and add `tour.*` i18n keys to all 3 locale files (`en.json`, `ru.json`, `zh.json`).
+
## General Guidelines
- Always test changes before marking as complete
diff --git a/server/src/wled_controller/static/css/cards.css b/server/src/wled_controller/static/css/cards.css
index 624fc2b..b58058e 100644
--- a/server/src/wled_controller/static/css/cards.css
+++ b/server/src/wled_controller/static/css/cards.css
@@ -69,7 +69,7 @@ section {
/* ── Card entrance animation ── */
@keyframes cardEnter {
from { opacity: 0; transform: translateY(12px); }
- to { opacity: 1; transform: translateY(0); }
+ to { transform: translateY(0); }
}
.card-enter {
diff --git a/server/src/wled_controller/static/js/app.js b/server/src/wled_controller/static/js/app.js
index 2cbde51..ec39a2e 100644
--- a/server/src/wled_controller/static/js/app.js
+++ b/server/src/wled_controller/static/js/app.js
@@ -23,6 +23,7 @@ import {
} from './features/displays.js';
import {
startCalibrationTutorial, startDeviceTutorial, startGettingStartedTutorial,
+ startDashboardTutorial, startTargetsTutorial, startSourcesTutorial, startProfilesTutorial,
closeTutorial, tutorialNext, tutorialPrev,
} from './features/tutorials.js';
@@ -79,6 +80,7 @@ import {
loadProfiles, openProfileEditor, closeProfileEditorModal,
saveProfileEditor, addProfileCondition,
toggleProfileEnabled, toggleProfileTargets, deleteProfile,
+ expandAllProfileSections, collapseAllProfileSections,
} from './features/profiles.js';
// Layer 5: device-discovery, targets
@@ -175,6 +177,10 @@ Object.assign(window, {
startCalibrationTutorial,
startDeviceTutorial,
startGettingStartedTutorial,
+ startDashboardTutorial,
+ startTargetsTutorial,
+ startSourcesTutorial,
+ startProfilesTutorial,
closeTutorial,
tutorialNext,
tutorialPrev,
@@ -298,6 +304,8 @@ Object.assign(window, {
toggleProfileEnabled,
toggleProfileTargets,
deleteProfile,
+ expandAllProfileSections,
+ collapseAllProfileSections,
// device-discovery
onDeviceTypeChanged,
diff --git a/server/src/wled_controller/static/js/features/dashboard.js b/server/src/wled_controller/static/js/features/dashboard.js
index b617f63..f8fdfef 100644
--- a/server/src/wled_controller/static/js/features/dashboard.js
+++ b/server/src/wled_controller/static/js/features/dashboard.js
@@ -274,7 +274,7 @@ function _updateProfilesInPlace(profiles) {
function _renderPollIntervalSelect() {
const sec = Math.round(dashboardPollInterval / 1000);
- return `${sec}s`;
+ return `${sec}s`;
}
let _pollDebounce = null;
@@ -518,9 +518,10 @@ export async function loadDashboard(forceFullRender = false) {
// First load: build everything in one innerHTML to avoid flicker
const isFirstLoad = !container.querySelector('.dashboard-perf-persistent');
const pollSelect = _renderPollIntervalSelect();
+ const toolbar = `
${pollSelect}
`;
if (isFirstLoad) {
- container.innerHTML = `
- ${_sectionHeader('perf', t('dashboard.section.performance'), '', pollSelect)}
+ container.innerHTML = `${toolbar}
+ ${_sectionHeader('perf', t('dashboard.section.performance'), '')}
${_sectionContent('perf', renderPerfSection())}
${dynamicHtml}
`;
diff --git a/server/src/wled_controller/static/js/features/profiles.js b/server/src/wled_controller/static/js/features/profiles.js
index a405b77..9f16b58 100644
--- a/server/src/wled_controller/static/js/features/profiles.js
+++ b/server/src/wled_controller/static/js/features/profiles.js
@@ -76,11 +76,20 @@ export async function loadProfiles() {
}
}
+export function expandAllProfileSections() {
+ CardSection.expandAll([csProfiles]);
+}
+
+export function collapseAllProfileSections() {
+ CardSection.collapseAll([csProfiles]);
+}
+
function renderProfiles(profiles, runningTargetIds = new Set()) {
const container = document.getElementById('profiles-content');
const items = csProfiles.applySortOrder(profiles.map(p => ({ key: p.id, html: createProfileCard(p, runningTargetIds) })));
- container.innerHTML = csProfiles.render(items);
+ const toolbar = `
`;
+ container.innerHTML = toolbar + csProfiles.render(items);
csProfiles.bind();
// Localize data-i18n elements within the profiles container only
diff --git a/server/src/wled_controller/static/js/features/streams.js b/server/src/wled_controller/static/js/features/streams.js
index d295bef..341b2e2 100644
--- a/server/src/wled_controller/static/js/features/streams.js
+++ b/server/src/wled_controller/static/js/features/streams.js
@@ -1301,7 +1301,7 @@ function renderPictureSourcesList(streams) {
const tabBar = `
${tabs.map(tab =>
``
- ).join('')}
`;
+ ).join('')}
`;
const renderAudioSourceCard = (src) => {
const isMono = src.source_type === 'mono';
diff --git a/server/src/wled_controller/static/js/features/targets.js b/server/src/wled_controller/static/js/features/targets.js
index d33e3e5..1d38dd0 100644
--- a/server/src/wled_controller/static/js/features/targets.js
+++ b/server/src/wled_controller/static/js/features/targets.js
@@ -576,7 +576,7 @@ export async function loadTargetsTab() {
const tabBar = `${subTabs.map(tab =>
``
- ).join('')}
`;
+ ).join('')}`;
// Use window.createPatternTemplateCard to avoid circular import
const createPatternTemplateCard = window.createPatternTemplateCard || (() => '');
diff --git a/server/src/wled_controller/static/js/features/tutorials.js b/server/src/wled_controller/static/js/features/tutorials.js
index 8c19c3d..e7ab459 100644
--- a/server/src/wled_controller/static/js/features/tutorials.js
+++ b/server/src/wled_controller/static/js/features/tutorials.js
@@ -33,6 +33,44 @@ const gettingStartedSteps = [
{ selector: '#locale-select', textKey: 'tour.language', position: 'bottom' }
];
+const dashboardTutorialSteps = [
+ { selector: '[data-dashboard-section="perf"]', textKey: 'tour.dash.perf', position: 'bottom' },
+ { selector: '[data-dashboard-section="running"]', textKey: 'tour.dash.running', position: 'bottom' },
+ { selector: '[data-dashboard-section="stopped"]', textKey: 'tour.dash.stopped', position: 'bottom' },
+ { selector: '[data-dashboard-section="profiles"]', textKey: 'tour.dash.profiles', position: 'bottom' }
+];
+
+const targetsTutorialSteps = [
+ { selector: '[data-target-sub-tab="led"]', textKey: 'tour.tgt.led_tab', position: 'bottom' },
+ { selector: '[data-card-section="led-devices"]', textKey: 'tour.tgt.devices', position: 'bottom' },
+ { selector: '[data-card-section="led-css"]', textKey: 'tour.tgt.css', position: 'bottom' },
+ { selector: '[data-card-section="led-targets"]', textKey: 'tour.tgt.targets', position: 'bottom' },
+ { selector: '[data-target-sub-tab="key_colors"]', textKey: 'tour.tgt.kc_tab', position: 'bottom' }
+];
+
+const sourcesTourSteps = [
+ { selector: '[data-stream-tab="raw"]', textKey: 'tour.src.raw', position: 'bottom' },
+ { selector: '[data-card-section="raw-templates"]', textKey: 'tour.src.templates', position: 'bottom' },
+ { selector: '[data-stream-tab="static_image"]', textKey: 'tour.src.static', position: 'bottom' },
+ { selector: '[data-stream-tab="processed"]', textKey: 'tour.src.processed', position: 'bottom' },
+ { selector: '[data-stream-tab="audio"]', textKey: 'tour.src.audio', position: 'bottom' },
+ { selector: '[data-stream-tab="value"]', textKey: 'tour.src.value', position: 'bottom' }
+];
+
+const profilesTutorialSteps = [
+ { selector: '[data-card-section="profiles"]', textKey: 'tour.prof.list', position: 'bottom' },
+ { selector: '[data-cs-add="profiles"]', textKey: 'tour.prof.add', position: 'bottom' },
+ { selector: '.card[data-profile-id]', textKey: 'tour.prof.card', position: 'bottom' }
+];
+
+const _fixedResolve = (step) => {
+ const el = document.querySelector(step.selector);
+ if (!el) return null;
+ // offsetParent is null when element or any ancestor has display:none
+ if (!el.offsetParent) return null;
+ return el;
+};
+
const deviceTutorialSteps = [
{ selector: '.card-subtitle', textKey: 'device.tip.metadata', position: 'bottom' },
{ selector: '.brightness-control', textKey: 'device.tip.brightness', position: 'bottom' },
@@ -112,6 +150,46 @@ export function startGettingStartedTutorial() {
});
}
+export function startDashboardTutorial() {
+ startTutorial({
+ steps: dashboardTutorialSteps,
+ overlayId: 'getting-started-overlay',
+ mode: 'fixed',
+ container: null,
+ resolveTarget: _fixedResolve
+ });
+}
+
+export function startTargetsTutorial() {
+ startTutorial({
+ steps: targetsTutorialSteps,
+ overlayId: 'getting-started-overlay',
+ mode: 'fixed',
+ container: null,
+ resolveTarget: _fixedResolve
+ });
+}
+
+export function startSourcesTutorial() {
+ startTutorial({
+ steps: sourcesTourSteps,
+ overlayId: 'getting-started-overlay',
+ mode: 'fixed',
+ container: null,
+ resolveTarget: _fixedResolve
+ });
+}
+
+export function startProfilesTutorial() {
+ startTutorial({
+ steps: profilesTutorialSteps,
+ overlayId: 'getting-started-overlay',
+ mode: 'fixed',
+ container: null,
+ resolveTarget: _fixedResolve
+ });
+}
+
export function closeTutorial() {
if (!activeTutorial) return;
const onClose = activeTutorial.onClose;
diff --git a/server/src/wled_controller/static/locales/en.json b/server/src/wled_controller/static/locales/en.json
index 9e8addf..9c65afc 100644
--- a/server/src/wled_controller/static/locales/en.json
+++ b/server/src/wled_controller/static/locales/en.json
@@ -224,6 +224,24 @@
"tour.theme": "Theme — switch between dark and light mode.",
"tour.language": "Language — choose your preferred interface language.",
"tour.restart": "Restart tutorial",
+ "tour.dash.perf": "Performance — real-time FPS charts, latency metrics, and poll interval control.",
+ "tour.dash.running": "Running targets — live streaming metrics and quick stop control.",
+ "tour.dash.stopped": "Stopped targets — ready to start with one click.",
+ "tour.dash.profiles": "Profiles — active profile status and quick enable/disable toggle.",
+ "tour.tgt.led_tab": "LED tab — standard LED strip targets with device and color strip configuration.",
+ "tour.tgt.devices": "Devices — your WLED controllers discovered on the network.",
+ "tour.tgt.css": "Color Strips — define how screen regions map to LED segments.",
+ "tour.tgt.targets": "LED Targets — combine a device, color strip, and capture source for streaming.",
+ "tour.tgt.kc_tab": "Key Colors — alternative target type using color-matching instead of pixel mapping.",
+ "tour.src.raw": "Raw — live screen capture sources from your displays.",
+ "tour.src.templates": "Capture Templates — reusable capture configurations (resolution, FPS, crop).",
+ "tour.src.static": "Static Image — test your setup with image files instead of live capture.",
+ "tour.src.processed": "Processed — apply post-processing effects like blur, brightness, or color correction.",
+ "tour.src.audio": "Audio — analyze microphone or system audio for reactive LED effects.",
+ "tour.src.value": "Value — numeric data sources used as conditions in profile automation.",
+ "tour.prof.list": "Profiles — automate target control based on time, audio, or value conditions.",
+ "tour.prof.add": "Click + to create a new profile with targets and activation conditions.",
+ "tour.prof.card": "Each card shows profile status, conditions, and quick controls to edit or toggle.",
"calibration.tutorial.start": "Start tutorial",
"calibration.overlay_toggle": "Overlay",
"calibration.start_position": "Starting Position:",
diff --git a/server/src/wled_controller/static/locales/ru.json b/server/src/wled_controller/static/locales/ru.json
index d050133..d4232c6 100644
--- a/server/src/wled_controller/static/locales/ru.json
+++ b/server/src/wled_controller/static/locales/ru.json
@@ -224,6 +224,24 @@
"tour.theme": "Тема — переключение между тёмной и светлой темой.",
"tour.language": "Язык — выберите предпочитаемый язык интерфейса.",
"tour.restart": "Запустить тур заново",
+ "tour.dash.perf": "Производительность — графики FPS в реальном времени, метрики задержки и интервал опроса.",
+ "tour.dash.running": "Запущенные цели — метрики стриминга и быстрая остановка.",
+ "tour.dash.stopped": "Остановленные цели — готовы к запуску одним нажатием.",
+ "tour.dash.profiles": "Профили — статус активных профилей и быстрое включение/выключение.",
+ "tour.tgt.led_tab": "LED — стандартные LED-цели с настройкой устройств и цветовых полос.",
+ "tour.tgt.devices": "Устройства — ваши WLED-контроллеры, найденные в сети.",
+ "tour.tgt.css": "Цветовые полосы — определите, как области экрана соответствуют сегментам LED.",
+ "tour.tgt.targets": "LED-цели — объедините устройство, цветовую полосу и источник захвата для стриминга.",
+ "tour.tgt.kc_tab": "Key Colors — альтернативный тип цели с подбором цветов вместо пиксельного маппинга.",
+ "tour.src.raw": "Raw — источники захвата экрана с ваших дисплеев.",
+ "tour.src.templates": "Шаблоны захвата — переиспользуемые конфигурации (разрешение, FPS, обрезка).",
+ "tour.src.static": "Статичные изображения — тестируйте настройку с файлами изображений.",
+ "tour.src.processed": "Обработка — применяйте эффекты: размытие, яркость, цветокоррекция.",
+ "tour.src.audio": "Аудио — анализ микрофона или системного звука для реактивных LED-эффектов.",
+ "tour.src.value": "Значения — числовые источники данных для условий автоматизации профилей.",
+ "tour.prof.list": "Профили — автоматизируйте управление целями по времени, звуку или значениям.",
+ "tour.prof.add": "Нажмите + для создания нового профиля с целями и условиями активации.",
+ "tour.prof.card": "Каждая карточка показывает статус профиля, условия и кнопки управления.",
"calibration.tutorial.start": "Начать обучение",
"calibration.overlay_toggle": "Оверлей",
"calibration.start_position": "Начальная Позиция:",
diff --git a/server/src/wled_controller/static/locales/zh.json b/server/src/wled_controller/static/locales/zh.json
index 6f6ce4d..50caaa8 100644
--- a/server/src/wled_controller/static/locales/zh.json
+++ b/server/src/wled_controller/static/locales/zh.json
@@ -224,6 +224,24 @@
"tour.theme": "主题 — 在深色和浅色模式之间切换。",
"tour.language": "语言 — 选择您偏好的界面语言。",
"tour.restart": "重新开始导览",
+ "tour.dash.perf": "性能 — 实时 FPS 图表、延迟指标和轮询间隔控制。",
+ "tour.dash.running": "运行中的目标 — 实时流媒体指标和快速停止控制。",
+ "tour.dash.stopped": "已停止的目标 — 一键启动。",
+ "tour.dash.profiles": "配置文件 — 活动配置文件状态和快速启用/禁用切换。",
+ "tour.tgt.led_tab": "LED 标签 — 标准 LED 灯带目标,包含设备和色带配置。",
+ "tour.tgt.devices": "设备 — 在网络中发现的 WLED 控制器。",
+ "tour.tgt.css": "色带 — 定义屏幕区域如何映射到 LED 段。",
+ "tour.tgt.targets": "LED 目标 — 将设备、色带和捕获源组合进行流式传输。",
+ "tour.tgt.kc_tab": "Key Colors — 使用颜色匹配代替像素映射的替代目标类型。",
+ "tour.src.raw": "原始 — 来自显示器的实时屏幕捕获源。",
+ "tour.src.templates": "捕获模板 — 可复用的捕获配置(分辨率、FPS、裁剪)。",
+ "tour.src.static": "静态图片 — 使用图片文件测试您的设置。",
+ "tour.src.processed": "处理 — 应用后处理效果,如模糊、亮度或色彩校正。",
+ "tour.src.audio": "音频 — 分析麦克风或系统音频以实现响应式 LED 效果。",
+ "tour.src.value": "数值 — 用于配置文件自动化条件的数字数据源。",
+ "tour.prof.list": "配置文件 — 基于时间、音频或数值条件自动控制目标。",
+ "tour.prof.add": "点击 + 创建包含目标和激活条件的新配置文件。",
+ "tour.prof.card": "每张卡片显示配置文件状态、条件和快速编辑/切换控制。",
"calibration.tutorial.start": "开始教程",
"calibration.overlay_toggle": "叠加层",
"calibration.start_position": "起始位置:",