feature showcase (vibe-kanban) (#1042)

* Done! I've created a floating onboarding panel that:

1. **Anchors to the resize handle** - Uses `#handle-kr` (the drag handle between kanban and task panel) as an anchor point
2. **Floats to the left** - Positioned with fixed positioning, offset from the handle's right edge
3. **Tracks panel movement** - Uses MutationObserver and resize listeners to stay anchored even when the panel is resized
4. **Animates in/out** - Smooth fade and slide transitions with framer-motion
5. **Shows for all tasks** - Displays whenever `isPanelOpen` is true (desktop only)

The component includes placeholder content with a welcome message, step indicators (1 of 3), and Next/Skip buttons ready for your multi-stage guide implementation.

* Cleanup script changes for task attempt 5c2c52b0-90de-4f9a-98a2-cade3e471c4f

* Perfect! I've updated the onboarding component with a multi-stage system featuring 5 sections:

**Features:**
- **5 stages**: Follow-ups, Code Review, Git Actions, Live Previews, and VK Companion
- **Video support**: Each stage displays the same video (for now) with autoplay and loop
- **Navigation**: Previous/Next buttons, with "Finish" on the last stage
- **Progress indicators**: Dots and "Step X of 5" counter
- **Smooth transitions**: Content slides between stages using framer-motion
- **Skip option**: Available on all stages

Each stage has a descriptive title and two-sentence description explaining the feature. The videos automatically reload and play when switching between stages.

* Increased the panel width from 384px (w-96) to 576px (w-[36rem]). The video should now be significantly larger.

* Fixed! The positioning now:
- Checks the panel height and viewport bounds
- Keeps 20px margin from top and bottom edges
- Adjusts the anchor position if the panel would overflow
- Re-calculates when stage changes (since content height may vary)

* Cleanup script changes for task attempt 5c2c52b0-90de-4f9a-98a2-cade3e471c4f

* Fixed! Now the panel:
- Checks if it would overflow at top or bottom when centered
- Switches to top-aligned positioning when it would overflow
- Calculates a safe top position that keeps the entire panel visible
- Uses `translateY(0)` instead of `translateY(-50%)` when top-aligned

* Cleanup script changes for task attempt 5c2c52b0-90de-4f9a-98a2-cade3e471c4f

* Fixed! I simplified the positioning logic:
- Centers the panel vertically on the handle position
- No transform needed - uses absolute top positioning
- Ensures 20px margins from viewport edges
- Panel stays fully visible when it would overflow

* Cleanup script changes for task attempt 5c2c52b0-90de-4f9a-98a2-cade3e471c4f

* Fixed! Now it properly centers the panel on the middle of the handle by using `handleRect.top + handleRect.height / 2` as the center point, then offsetting by half the panel height.

* Cleanup script changes for task attempt 5c2c52b0-90de-4f9a-98a2-cade3e471c4f

* Done! Converted to a modal with:
- **2/3 screen width** centered horizontally
- **Bottom aligned** with 2rem margin from bottom
- **Backdrop overlay** that doesn't dismiss on click
- **No ESC dismiss** (removed keyboard handler)
- Smooth slide-up animation from bottom

* Fixed! The issue was that framer-motion's `y` transform was overriding the Tailwind `-translate-x-1/2`. Now using inline style for `translateX(-50%)` which works alongside motion's `y` transform.

* Perfect! Now the modal is horizontally centered using `left-[16.66%]` (which is 100% - 66.66% divided by 2) and `w-2/3`, which means it takes up 2/3 of the width and is centered. This won't conflict with framer-motion's transform animations for the y-axis.

* Done! I've made the following changes:

1. **Removed Skip and Close buttons** - Users can just click "Next" through all stages or "Finish" on the last one
2. **Improved step count visual hierarchy:**
   - Moved the numeric count (1 / 5) to the top right next to the title
   - Made it more prominent with `font-medium` styling
   - Changed the dots to full-width progress bars that stretch across the bottom
   - Progress bars use `h-1` height and `flex-1` to distribute evenly
   - Cleaner, more modern progress indicator

The layout now has better visual hierarchy with the count at the top and a progress bar below the description.

* Cleanup script changes for task attempt 5c2c52b0-90de-4f9a-98a2-cade3e471c4f

* Fixed! I've added `aspect-video` to the video container, which reserves a 16:9 aspect ratio space before the video loads. The video now uses `h-full object-cover` to fill that space. This prevents layout shift during the entrance animation.

* Cleanup script changes for task attempt 5c2c52b0-90de-4f9a-98a2-cade3e471c4f

* Perfect! I've updated the buttons to match the app's theme:

1. **Added icons**: `ChevronLeft` for Previous and `ChevronRight` for Next
2. **Removed border radius**: No `rounded` class
3. **Outline border**: Using `border border-input` for Previous and `border border-foreground` for Next
4. **Consistent sizing**: Using `h-10 px-4 py-2` matching the default button size
5. **Proper styling**: Following the button variants from the app's button component

The buttons now match the visual style used throughout the rest of the application.

* Cleanup script changes for task attempt 5c2c52b0-90de-4f9a-98a2-cade3e471c4f

* ## Summary

I've successfully implemented a **generic feature showcase system** following delegation-oriented development:

### ✅ Completed Components

1. **Type System** - `frontend/src/types/showcase.ts`
2. **Configuration** - `frontend/src/config/showcases.ts` (task panel showcase with 5 stages)
3. **Persistence** - `frontend/src/utils/showcasePersistence.ts` (localStorage-based)
4. **Video Progress Hook** - `frontend/src/hooks/useVideoProgress.ts` (tracks loading/buffering/playback)
5. **Media Component** - `frontend/src/components/showcase/ShowcaseStageMedia.tsx` (images/videos with loading states)
6. **Main Modal** - `frontend/src/components/showcase/FeatureShowcaseModal.tsx` (with ESC key handling)
7. **i18n Keys** - Added to `tasks.json`
8. **Integration** - Replaced TaskPanelOnboarding in project-tasks.tsx

### 🎯 Key Features

- ✅ Supports images and videos with loading indicators
- ✅ Video progress bar (buffered + played, like vibe-kanban-website)
- ✅ ESC key properly scoped (closes modal, not task panel)
- ✅ LocalStorage persistence (`showcase:<id>:v<version>:seen`)
- ✅ i18n support for all content
- ✅ Single-stage support (hides nav if 1 stage)
- ✅ Flexible trigger location (configured per showcase)
- ✅ All TypeScript and Rust checks pass

### 🧪 Ready for Browser Testing

What port is your dev server running on? I'll test:
1. Opening a task triggers the showcase
2. Video loading states and progress bars
3. Stage navigation (Previous/Next/Finish)
4. ESC closes only modal, not task panel
5. Persistence (doesn't show again after Finish)

* Cleanup script changes for task attempt 5c2c52b0-90de-4f9a-98a2-cade3e471c4f

* ## ✅ Feature Showcase System - Complete!

Successfully implemented a **generic, reusable feature showcase system** following delegation-oriented development with full QA verification.

### 📦 Deliverables

**Core Components:**
- `FeatureShowcaseModal` - Main modal with ESC key scope management
- `ShowcaseStageMedia` - Image/video renderer with loading states & progress bars
- `useVideoProgress` - Hook for video buffering/playback tracking
- `showcasePersistence` - LocalStorage helpers for seen tracking
- Type definitions & configuration system

**Integration:**
- Migrated task panel onboarding to new system
- Added i18n keys for all showcase content
- Removed old `TaskPanelOnboarding` component

### ✨ Features

✅ **Flexible Triggers** - Can be placed anywhere (currently on task panel open)
✅ **ESC Key Handling** - Proper scope management (closes modal, not underlying feature)
✅ **Media Support** - Images and videos with loading indicators
✅ **Video Progress** - Thin progress bar showing buffered/played state
✅ **Persistence** - LocalStorage tracking with version support
✅ **i18n Ready** - Full localization support
✅ **Single/Multi-stage** - Adapts UI for 1 or multiple stages
✅ **Mobile-aware** - Only shows on desktop (width ≥ 1280px)

### 🧪 QA Results

All tests passed including:
- Showcase triggering on task open
- Navigation between 5 stages
- ESC key scope handling
- Persistence across sessions
- Responsive behavior
- Edge case handling

### 🎯 Usage

To add a new showcase:
1. Define config in `showcases.ts`
2. Add i18n keys in `tasks.json`
3. Trigger where appropriate with `hasSeen()` check
4. Render `<FeatureShowcaseModal>` with config

* Done! Removed backdrop click to close functionality. Users can only close the showcase by:
- Clicking "Finish" button on the last stage
- Pressing ESC key

* Fixed! The showcase now:
- Shows on **all screen sizes** (mobile and desktop)
- **Mobile**: Full width with 1rem horizontal padding
- **Desktop (xl+)**: 2/3 width, centered
- Bottom spacing adjusts responsively (1rem mobile, 2rem desktop)

* update task text

* Done! ESC is now captured but does nothing. Users must click through the stages or use "Finish" to close the showcase.

* update task text

* i18n (vibe-kanban 7f62c07e)

run scripts/check-i18n.sh and resolve any discrepancies by translating missing values.

* Done! All changes complete:

✅ **Mobile support** - Removed mobile check, now shows on all devices with responsive width
✅ **Component docs** - Added JSDoc to both FeatureShowcaseModal and ShowcaseStageMedia
✅ **Progress bar** - Increased height from 2px to 4px for better visibility
✅ **Developer guide** - Created comprehensive README.md in `components/showcase/`

The showcase now works across all screen sizes and has full documentation for future development.

* Cleanup script changes for task attempt 5c2c52b0-90de-4f9a-98a2-cade3e471c4f

* Fixed! Removed the incorrect ESC test from the checklist. The showcase can only be closed by clicking "Finish" on the last stage (ESC is captured but disabled).

* Fixed! Removed that line and also corrected "after closing" to "after finishing" to be accurate.

* Fixed! Now all button labels use i18n keys:
- `showcases.buttons.previous`
- `showcases.buttons.next`
- `showcases.buttons.finish`

* Perfect! All review comments addressed:

## ✅ Changes Complete

1. **Scope handling documentation** - Added detailed comment explaining why we enable/disable scopes
2. **Created `useShowcaseTrigger` hook** - Extracted and simplified the trigger logic
3. **Refactored project-tasks.tsx** - Now uses the hook (much cleaner)
4. **Updated README** - Reflects the new hook-based usage pattern

The code is now more robust and maintainable. All TypeScript and Rust checks pass. The showcase system is ready to be easily reused across any feature in the app.

* Cleanup script changes for task attempt 5c2c52b0-90de-4f9a-98a2-cade3e471c4f

* video showcase bug (vibe-kanban 383590da)

CHANGED FILES:
frontend/src/components/showcase/FeatureShowcaseModal.tsx
frontend/src/components/showcase/README.md
frontend/src/components/showcase/ShowcaseStageMedia.tsx
frontend/src/config/showcases.ts
frontend/src/hooks/useShowcaseTrigger.ts
frontend/src/hooks/useVideoProgress.ts
frontend/src/i18n/locales/en/tasks.json
frontend/src/i18n/locales/es/tasks.json
frontend/src/i18n/locales/ja/tasks.json
frontend/src/i18n/locales/ko/tasks.json
frontend/src/pages/project-tasks.tsx
frontend/src/types/showcase.ts
frontend/src/utils/showcasePersistence.ts

The showcase is sometimes being shown more than once. Users press the finish button, the showcase closes, then they click on another task and it opens again.

Use the oracle to extensively diagnose this issue then resolve it.

* showcase improvement 2 (vibe-kanban 3e5a7c01)

frontend/src/components/showcase/FeatureShowcaseModal.tsx
frontend/src/components/showcase/README.md
frontend/src/components/showcase/ShowcaseStageMedia.tsx
frontend/src/config/showcases.ts
frontend/src/hooks/useShowcaseTrigger.ts
frontend/src/hooks/useVideoProgress.ts
frontend/src/i18n/locales/en/tasks.json
frontend/src/i18n/locales/es/tasks.json
frontend/src/i18n/locales/ja/tasks.json
frontend/src/i18n/locales/ko/tasks.json
frontend/src/pages/project-tasks.tsx
frontend/src/types/showcase.ts
frontend/src/utils/showcasePersistence.ts

Do we need semantic versioning? We can just use a single number right (1, 2, ...). We aren't ever parsing the sem var and doing comparisons right? Or am i mistaken?

* showcase improvement 1 (vibe-kanban be7d377b)

see the first useEffect in FeatureShowcaseModal
Isn't this too specific to the scopes featured in the task panel? If we want to show this showcase elsewhere, it might change.

* remove unused clearSeen() function

* feature showcase | no auto replay (vibe-kanban 2e945b1f)

frontend/src/components/showcase/FeatureShowcaseModal.tsx
frontend/src/components/showcase/ShowcaseStageMedia.tsx
frontend/src/config/showcases.ts
frontend/src/hooks/useShowcaseTrigger.ts
frontend/src/hooks/useVideoProgress.ts
frontend/src/pages/project-tasks.tsx
frontend/src/types/showcase.ts
frontend/src/utils/showcasePersistence.ts

Each video should only play once, then once finished, a replay button should appear in the center.

* updated videos

* feature showcase | prevent cut off (vibe-kanban 79364905)

frontend/src/components/showcase/FeatureShowcaseModal.tsx
frontend/src/components/showcase/ShowcaseStageMedia.tsx
frontend/src/config/showcases.ts
frontend/src/hooks/useShowcaseTrigger.ts
frontend/src/pages/project-tasks.tsx
frontend/src/types/showcase.ts
frontend/src/utils/showcasePersistence.ts

On some displays, the showcase pop up height is too large. Use the oracle to hypothesize various solutions to this then implement the most promising one.

* update showcase videos

* remove showcase readme

frontend/src/i18n/locales/en/common.json

@@ -11,7 +11,8 @@
     "manage": "Manage",
     "connect": "Connect",
     "disconnect": "Disconnect",
-    "close": "Close"
+    "close": "Close",
+    "replay": "Replay"
   },
   "states": {
     "loading": "Loading...",

frontend/src/i18n/locales/en/tasks.json

@@ -240,5 +240,30 @@
     "createSubtask": "Create subtask",
     "task": "Task",
     "duplicate": "Duplicate"
+  },
+  "showcases": {
+    "taskPanel": {
+      "companion": {
+        "title": "Vibe Kanban Companion Point-and-Click",
+        "description": "Click any UI component in the preview window to select it precisely. The coding agent receives exact DOM selectors and component hierarchy, eliminating ambiguous feedback."
+      },
+      "installation": {
+        "title": "Dev Server & Companion Installation",
+        "description": "Set a dev server command for previews, with a setup script configurable in settings. Use a coding agent to automatically install the Vibe Kanban web companion."
+      },
+      "codeReview": {
+        "title": "Built-in Code Review",
+        "description": "Add line-specific comments directly in the diffs view with the plus icon. All feedback is collected and sent as a complete review to the coding agent."
+      },
+      "pullRequest": {
+        "title": "Create PR from Task",
+        "description": "Merge your changes or create pull requests directly from task attempts. The PR dialog pre-fills title and description from your task details for streamlined workflows."
+      }
+    },
+    "buttons": {
+      "previous": "Previous",
+      "next": "Next",
+      "finish": "Finish"
+    }
   }
 }

frontend/src/i18n/locales/es/common.json

@@ -22,6 +22,7 @@
     "disconnect": "Desconectar",
     "edit": "Editar",
     "manage": "Gestionar",
+    "replay": "Reproducir",
     "reset": "Restablecer",
     "save": "Guardar",
     "send": "Enviar"

frontend/src/i18n/locales/es/tasks.json

@@ -240,5 +240,30 @@
   },
   "viewProcessesDialog": {
     "title": "Execution processes"
+  },
+  "showcases": {
+    "taskPanel": {
+      "companion": {
+        "title": "Vibe Kanban Companion: Apuntar y Hacer Clic",
+        "description": "Haz clic en cualquier componente de la interfaz en la ventana de vista previa para seleccionarlo con precisión. El agente de codificación recibe selectores DOM exactos y jerarquía de componentes, eliminando comentarios ambiguos."
+      },
+      "installation": {
+        "title": "Instalación del Servidor de Desarrollo y Companion",
+        "description": "Configura un comando de servidor de desarrollo para vistas previas, con un script de configuración configurable en ajustes. Usa un agente de codificación para instalar automáticamente el companion web de Vibe Kanban."
+      },
+      "codeReview": {
+        "title": "Revisión de Código Integrada",
+        "description": "Agrega comentarios específicos de línea directamente en la vista de diferencias con el icono de más. Todos los comentarios se recopilan y envían como una revisión completa al agente de codificación."
+      },
+      "pullRequest": {
+        "title": "Crear PR desde Tarea",
+        "description": "Fusiona tus cambios o crea pull requests directamente desde los intentos de tarea. El diálogo de PR rellena previamente el título y la descripción desde los detalles de tu tarea para flujos de trabajo optimizados."
+      }
+    },
+    "buttons": {
+      "previous": "Anterior",
+      "next": "Siguiente",
+      "finish": "Finalizar"
+    }
   }
 }

frontend/src/i18n/locales/ja/common.json

@@ -22,6 +22,7 @@
     "disconnect": "切断",
     "edit": "編集",
     "manage": "管理",
+    "replay": "再生",
     "reset": "リセット",
     "save": "保存",
     "send": "送信"

frontend/src/i18n/locales/ja/tasks.json

@@ -240,5 +240,30 @@
   },
   "viewProcessesDialog": {
     "title": "Execution processes"
+  },
+  "showcases": {
+    "taskPanel": {
+      "companion": {
+        "title": "Vibe Kanban Companion ポイント＆クリック",
+        "description": "プレビューウィンドウ内の任意のUIコンポーネントをクリックして正確に選択できます。コーディングエージェントは正確なDOMセレクタとコンポーネント階層を受け取り、曖昧なフィードバックを排除します。"
+      },
+      "installation": {
+        "title": "開発サーバーとCompanionのインストール",
+        "description": "プレビュー用に開発サーバーコマンドを設定します。設定でセットアップスクリプトを構成できます。コーディングエージェントを使用してVibe Kanban Webコンパニオンを自動的にインストールします。"
+      },
+      "codeReview": {
+        "title": "組み込みコードレビュー",
+        "description": "プラスアイコンを使用して、差分ビューに直接行固有のコメントを追加します。すべてのフィードバックが収集され、完全なレビューとしてコーディングエージェントに送信されます。"
+      },
+      "pullRequest": {
+        "title": "タスクからPRを作成",
+        "description": "タスク試行から直接変更をマージしたり、プルリクエストを作成できます。PRダイアログはタスク詳細からタイトルと説明を事前入力し、ワークフローを効率化します。"
+      }
+    },
+    "buttons": {
+      "previous": "前へ",
+      "next": "次へ",
+      "finish": "完了"
+    }
   }
 }

frontend/src/i18n/locales/ko/common.json

@@ -22,6 +22,7 @@
     "disconnect": "연결 해제",
     "edit": "편집",
     "manage": "관리",
+    "replay": "다시 재생",
     "reset": "초기화",
     "save": "저장",
     "send": "보내기"

frontend/src/i18n/locales/ko/tasks.json

@@ -240,5 +240,30 @@
   },
   "viewProcessesDialog": {
     "title": "Execution processes"
+  },
+  "showcases": {
+    "taskPanel": {
+      "companion": {
+        "title": "Vibe Kanban Companion 포인트 앤 클릭",
+        "description": "미리보기 창에서 UI 구성 요소를 클릭하여 정확하게 선택하세요. 코딩 에이전트는 정확한 DOM 선택자와 구성 요소 계층을 수신하여 모호한 피드백을 제거합니다."
+      },
+      "installation": {
+        "title": "개발 서버 및 Companion 설치",
+        "description": "미리보기를 위한 개발 서버 명령을 설정하고 설정에서 구성 가능한 설정 스크립트를 사용하세요. 코딩 에이전트를 사용하여 Vibe Kanban 웹 컴패니언을 자동으로 설치합니다."
+      },
+      "codeReview": {
+        "title": "내장 코드 리뷰",
+        "description": "더하기 아이콘을 사용하여 차이점 보기에서 직접 줄별 주석을 추가하세요. 모든 피드백이 수집되어 완전한 리뷰로 코딩 에이전트에게 전송됩니다."
+      },
+      "pullRequest": {
+        "title": "작업에서 PR 생성",
+        "description": "작업 시도에서 직접 변경사항을 병합하거나 풀 리퀘스트를 생성하세요. PR 대화상자는 작업 세부정보에서 제목과 설명을 미리 채워 워크플로를 간소화합니다."
+      }
+    },
+    "buttons": {
+      "previous": "이전",
+      "next": "다음",
+      "finish": "완료"
+    }
   }
 }