browsertrack 0.1.2 → 0.2.0

package/packages/client/src/notes/inspector.ts

@@ -12,15 +12,22 @@ export interface InspectorOptions {
   onNoteCreated?: (note: Partial<VisualNote>) => void;
 }
 
+export interface ActiveScenarioState {
+  id: string;
+  title: string;
+  stepNumber: number;
+}
+
 /**
- * Isolated Visual Note Inspector rendering in Shadow DOM.
+ * Isolated Visual Note & Multi-Step Scenario Inspector rendering in Shadow DOM.
  * Supports:
  * 1. Element selection (hover highlight & click)
  * 2. Region / Area selection (drag-and-drop rectangle on screen with cancel banner)
  * 3. Whole page note
- * 4. Real-time Saved Note Markers (pins on elements/regions when page loads or syncs)
- * 5. Interactive Note Detail Card (view message, target, resolve/delete actions)
- * 6. Floating quick dock / toolbar in bottom-right corner with Notes count toggle
+ * 4. Multi-Step Flow / Scenario Recording (sequential 'Save & Next Step' continuous capture)
+ * 5. Real-time Saved Note & Step Markers (pins with step sequencing numbers)
+ * 6. Interactive Note & Step Detail Card (with previous/next step walk-through navigation)
+ * 7. Floating quick dock / toolbar in bottom-right corner with Notes count and Flow controls
  */
 export class NoteInspector {
   private transport: WebSocketTransport;
@@ -37,8 +44,10 @@ export class NoteInspector {
   private toolbarElement: HTMLDivElement | null = null;
   private modalOverlay: HTMLDivElement | null = null;
   private cardOverlay: HTMLDivElement | null = null;
+  private toastContainer: HTMLDivElement | null = null;
 
   private activeMode: NoteInspectMode = 'idle';
+  private activeScenario: ActiveScenarioState | null = null;
   private hoveredElement: HTMLElement | null = null;
   private selectedElement: HTMLElement | null = null;
   private selectedRegion: RegionContext | null = null;
@@ -90,6 +99,46 @@ export class NoteInspector {
     this.renderMarkers();
   }
 
+  public showToast(message: string, icon = '✨', durationMs = 2500): void {
+    if (typeof document === 'undefined') return;
+    const root = this.ensureContainer();
+    if (!root || !this.toastContainer) return;
+
+    const toast = document.createElement('div');
+    toast.className = 'bt-toast';
+    toast.innerHTML = `<span>${icon}</span> <span>${message}</span>`;
+    this.toastContainer.appendChild(toast);
+
+    setTimeout(() => {
+      toast.classList.add('bt-toast-fadeout');
+      setTimeout(() => {
+        if (toast.parentElement) {
+          toast.parentElement.removeChild(toast);
+        }
+      }, 250);
+    }, durationMs);
+  }
+
+  public startScenario(title?: string): void {
+    const defaultTitle = title || `Scenario ${new Date().toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}`;
+    this.activeScenario = {
+      id: `scen_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`,
+      title: defaultTitle,
+      stepNumber: 1,
+    };
+    this.updateToolbarState();
+    this.setMode('element');
+    this.showToast(`Started flow: "${defaultTitle}"`, '🎬');
+  }
+
+  public finishScenario(): void {
+    const title = this.activeScenario?.title;
+    this.activeScenario = null;
+    this.updateToolbarState();
+    this.setMode('idle');
+    this.showToast(title ? `Finished flow: "${title}"` : 'Flow recording finished', '✓');
+  }
+
   public setMode(mode: NoteInspectMode): void {
     this.activeMode = mode;
     this.updateToolbarState();
@@ -276,6 +325,12 @@ export class NoteInspector {
           z-index: 2147483641;
         }
 
+        .bt-note-marker-step {
+          background: linear-gradient(135deg, #f59e0b, #d97706);
+          border-color: #fef3c7;
+          box-shadow: 0 4px 14px rgba(245, 158, 11, 0.4), 0 0 0 1px rgba(217, 119, 6, 0.5);
+        }
+
         @keyframes bt-pop-in {
           0% { transform: scale(0.6); opacity: 0; }
           100% { transform: scale(1); opacity: 1; }
@@ -286,6 +341,10 @@ export class NoteInspector {
           box-shadow: 0 8px 20px rgba(37,99,235,0.6), 0 0 0 2px #60a5fa;
         }
 
+        .bt-note-marker-step:hover {
+          box-shadow: 0 8px 20px rgba(245, 158, 11, 0.7), 0 0 0 2px #fde68a;
+        }
+
         .bt-marker-resolved {
           background: linear-gradient(135deg, #475569, #334155);
           border-color: #94a3b8;
@@ -382,6 +441,19 @@ export class NoteInspector {
           box-shadow: 0 2px 6px rgba(37, 99, 235, 0.35);
         }
 
+        .bt-toolbar-btn.active-scenario {
+          background: linear-gradient(135deg, #f59e0b, #d97706);
+          color: #ffffff;
+          font-weight: 700;
+          box-shadow: 0 2px 8px rgba(245, 158, 11, 0.4);
+          animation: bt-pulse 2s infinite;
+        }
+
+        @keyframes bt-pulse {
+          0%, 100% { opacity: 1; }
+          50% { opacity: 0.85; }
+        }
+
         .bt-count-pill {
           background: rgba(255, 255, 255, 0.2);
           color: #ffffff;
@@ -429,7 +501,7 @@ export class NoteInspector {
           border: 1px solid #334155;
           border-radius: 14px;
           padding: 20px;
-          width: 450px;
+          width: 470px;
           max-width: 92vw;
           box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.8), 0 0 0 1px rgba(255, 255, 255, 0.05);
           display: flex;
@@ -452,6 +524,7 @@ export class NoteInspector {
           align-items: center;
           gap: 8px;
           color: #f8fafc;
+          flex-wrap: wrap;
         }
 
         .bt-mode-badge {
@@ -481,6 +554,12 @@ export class NoteInspector {
           border: 1px solid rgba(168, 85, 247, 0.4);
         }
 
+        .bt-badge-step {
+          background: rgba(245, 158, 11, 0.15);
+          color: #fbbf24;
+          border: 1px solid rgba(245, 158, 11, 0.4);
+        }
+
         .bt-badge-status-open {
           background: rgba(16, 185, 129, 0.15);
           color: #34d399;
@@ -532,6 +611,43 @@ export class NoteInspector {
           color: #cbd5e1;
         }
 
+        .bt-scenario-stepper {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          background: #090d16;
+          border: 1px solid #1e293b;
+          border-radius: 8px;
+          padding: 6px 10px;
+          font-size: 12px;
+          font-weight: 600;
+          color: #f59e0b;
+        }
+
+        .bt-step-nav-btn {
+          background: #1e293b;
+          color: #f8fafc;
+          border: 1px solid #334155;
+          padding: 4px 10px;
+          border-radius: 6px;
+          cursor: pointer;
+          font-size: 11px;
+          font-weight: 600;
+          transition: all 0.12s ease;
+          font-family: inherit;
+        }
+
+        .bt-step-nav-btn:hover:not(:disabled) {
+          background: #2563eb;
+          border-color: #3b82f6;
+          color: #ffffff;
+        }
+
+        .bt-step-nav-btn:disabled {
+          opacity: 0.3;
+          cursor: not-allowed;
+        }
+
         .bt-note-message-box {
           background: #090d16;
           border: 1px solid #1e293b;
@@ -576,8 +692,9 @@ export class NoteInspector {
           display: flex;
           justify-content: space-between;
           align-items: center;
-          gap: 12px;
+          gap: 10px;
           margin-top: 2px;
+          flex-wrap: wrap;
         }
 
         .bt-kbd-hint {
@@ -605,12 +722,13 @@ export class NoteInspector {
           justify-content: flex-end;
           align-items: center;
           gap: 8px;
+          flex-wrap: wrap;
         }
 
         .bt-btn {
-          padding: 8px 16px;
+          padding: 7px 14px;
           border-radius: 7px;
-          font-size: 12.5px;
+          font-size: 12px;
           font-weight: 600;
           cursor: pointer;
           border: 1px solid transparent;
@@ -619,7 +737,7 @@ export class NoteInspector {
           display: inline-flex;
           align-items: center;
           justify-content: center;
-          gap: 6px;
+          gap: 5px;
         }
 
         .bt-btn-cancel {
@@ -641,6 +759,25 @@ export class NoteInspector {
           box-shadow: 0 4px 10px rgba(37, 99, 235, 0.45);
         }
 
+        .bt-btn-next-step {
+          background: linear-gradient(135deg, #6366f1, #4f46e5);
+          color: #ffffff;
+          box-shadow: 0 2px 8px rgba(99, 102, 241, 0.4);
+        }
+        .bt-btn-next-step:hover {
+          background: linear-gradient(135deg, #4f46e5, #4338ca);
+          box-shadow: 0 4px 12px rgba(99, 102, 241, 0.55);
+        }
+
+        .bt-btn-finish-flow {
+          background: linear-gradient(135deg, #10b981, #059669);
+          color: #ffffff;
+          box-shadow: 0 2px 8px rgba(16, 185, 129, 0.35);
+        }
+        .bt-btn-finish-flow:hover {
+          background: linear-gradient(135deg, #059669, #047857);
+        }
+
         .bt-btn-resolve {
           background: rgba(16, 185, 129, 0.15);
           color: #6ee7b7;
@@ -660,6 +797,47 @@ export class NoteInspector {
           background: rgba(239, 68, 68, 0.3);
           color: #ffffff;
         }
+
+        /* 6. Toast Notifications */
+        .bt-toast-container {
+          position: fixed;
+          bottom: 74px;
+          right: 24px;
+          display: flex;
+          flex-direction: column;
+          gap: 8px;
+          pointer-events: none;
+          z-index: 2147483647;
+          align-items: flex-end;
+        }
+
+        .bt-toast {
+          background: #0f172a;
+          color: #f8fafc;
+          border: 1px solid #334155;
+          border-radius: 30px;
+          padding: 8px 16px;
+          font-size: 12.5px;
+          font-weight: 500;
+          display: inline-flex;
+          align-items: center;
+          gap: 8px;
+          box-shadow: 0 10px 25px -3px rgba(0, 0, 0, 0.6), 0 4px 6px -4px rgba(0, 0, 0, 0.4);
+          pointer-events: auto;
+          animation: bt-toast-in 0.2s cubic-bezier(0.16, 1, 0.3, 1);
+          transition: opacity 0.25s ease, transform 0.25s ease;
+          user-select: none;
+        }
+
+        .bt-toast-fadeout {
+          opacity: 0;
+          transform: translateY(6px);
+        }
+
+        @keyframes bt-toast-in {
+          from { opacity: 0; transform: translateY(8px) scale(0.95); }
+          to { opacity: 1; transform: translateY(0) scale(1); }
+        }
       `;
 
       this.shadowRoot.appendChild(style);
@@ -675,6 +853,11 @@ export class NoteInspector {
       this.markersContainer.className = 'bt-markers-layer';
       this.shadowRoot.appendChild(this.markersContainer);
 
+      // Toast container layer
+      this.toastContainer = document.createElement('div');
+      this.toastContainer.className = 'bt-toast-container';
+      this.shadowRoot.appendChild(this.toastContainer);
+
       // Floating Toolbar
       if (this.options.showToolbar) {
         this.createToolbar();
@@ -707,6 +890,10 @@ export class NoteInspector {
         <span>📄</span> Page
       </button>
       <div class="bt-toolbar-divider"></div>
+      <button class="bt-toolbar-btn" id="bt-mode-flow" title="Record multi-step reproduction flow">
+        <span>🎬</span> Flow
+      </button>
+      <div class="bt-toolbar-divider"></div>
       <button class="bt-toolbar-btn active" id="bt-toggle-notes" title="Toggle visible note markers on screen">
         <span>📌</span> Notes <span class="bt-count-pill" id="bt-notes-count">0</span>
       </button>
@@ -715,6 +902,7 @@ export class NoteInspector {
     const btnElement = this.toolbarElement.querySelector('#bt-mode-element') as HTMLButtonElement;
     const btnRegion = this.toolbarElement.querySelector('#bt-mode-region') as HTMLButtonElement;
     const btnPage = this.toolbarElement.querySelector('#bt-mode-page') as HTMLButtonElement;
+    const btnFlow = this.toolbarElement.querySelector('#bt-mode-flow') as HTMLButtonElement;
     const btnToggleNotes = this.toolbarElement.querySelector('#bt-toggle-notes') as HTMLButtonElement;
 
     btnElement.onclick = (e: MouseEvent) => {
@@ -732,6 +920,15 @@ export class NoteInspector {
       this.setMode('page');
     };
 
+    btnFlow.onclick = (e: MouseEvent) => {
+      e.stopPropagation();
+      if (this.activeScenario) {
+        this.finishScenario();
+      } else {
+        this.startScenario();
+      }
+    };
+
     btnToggleNotes.onclick = (e: MouseEvent) => {
       e.stopPropagation();
       this.showMarkers = !this.showMarkers;
@@ -748,10 +945,23 @@ export class NoteInspector {
     const btnElement = this.toolbarElement.querySelector('#bt-mode-element');
     const btnRegion = this.toolbarElement.querySelector('#bt-mode-region');
     const btnPage = this.toolbarElement.querySelector('#bt-mode-page');
+    const btnFlow = this.toolbarElement.querySelector('#bt-mode-flow');
 
     btnElement?.classList.toggle('active', this.activeMode === 'element');
     btnRegion?.classList.toggle('active', this.activeMode === 'region');
     btnPage?.classList.toggle('active', this.activeMode === 'page');
+
+    if (btnFlow) {
+      if (this.activeScenario) {
+        btnFlow.className = 'bt-toolbar-btn active-scenario';
+        btnFlow.innerHTML = `<span>🎬</span> Step ${this.activeScenario.stepNumber} (Finish)`;
+        btnFlow.setAttribute('title', `Click to finish recording "${this.activeScenario.title}"`);
+      } else {
+        btnFlow.className = 'bt-toolbar-btn';
+        btnFlow.innerHTML = `<span>🎬</span> Flow`;
+        btnFlow.setAttribute('title', 'Record multi-step reproduction flow');
+      }
+    }
   }
 
   private updateToolbarCount(): void {
@@ -784,6 +994,10 @@ export class NoteInspector {
         return;
       }
 
+      const isStep = !!note.scenarioId && note.stepNumber != null;
+      const stepLabel = isStep ? `🎬 Step ${note.stepNumber}` : `#${index + 1}`;
+      const markerClass = `bt-note-marker ${isStep ? 'bt-note-marker-step' : ''}`;
+
       if (note.type === 'region' && note.region) {
         // Region box
         const regBox = document.createElement('div');
@@ -796,11 +1010,11 @@ export class NoteInspector {
 
         // Pin on top-left of region
         const pin = document.createElement('div');
-        pin.className = 'bt-note-marker';
+        pin.className = markerClass;
         pin.style.left = `${Math.max(4, note.region.x - 12)}px`;
         pin.style.top = `${Math.max(4, note.region.y - 12)}px`;
-        pin.title = note.message;
-        pin.innerHTML = `<span>📐</span> <span>#${index + 1}</span>`;
+        pin.title = isStep ? `[${note.scenarioTitle || 'Scenario'}] Step ${note.stepNumber}: ${note.message}` : note.message;
+        pin.innerHTML = `<span>${isStep ? '🎬' : '📐'}</span> <span>${stepLabel}</span>`;
         pin.onclick = (e) => {
           e.stopPropagation();
           this.openNoteCard(note);
@@ -820,12 +1034,12 @@ export class NoteInspector {
       const rect = targetEl ? targetEl.getBoundingClientRect() : note.target?.boundingRect;
       if (rect) {
         const pin = document.createElement('div');
-        pin.className = 'bt-note-marker';
+        pin.className = markerClass;
         pin.setAttribute('data-note-id', note.id);
-        pin.title = note.message;
+        pin.title = isStep ? `[${note.scenarioTitle || 'Scenario'}] Step ${note.stepNumber}: ${note.message}` : note.message;
         pin.style.left = `${Math.max(4, rect.left - 10)}px`;
         pin.style.top = `${Math.max(4, rect.top - 12)}px`;
-        pin.innerHTML = `<span>📝</span> <span>#${index + 1}</span>`;
+        pin.innerHTML = `<span>${isStep ? '🎬' : '📝'}</span> <span>${stepLabel}</span>`;
 
         pin.onclick = (e) => {
           e.stopPropagation();
@@ -845,10 +1059,11 @@ export class NoteInspector {
     if (pageNotes.length > 0) {
       const pageDock = document.createElement('div');
       pageDock.className = 'bt-page-notes-dock';
-      pageNotes.forEach((pNote, idx) => {
+      pageNotes.forEach((pNote) => {
         const pill = document.createElement('div');
         pill.className = 'bt-page-note-pill';
-        pill.innerHTML = `<span>📄</span> <span>Page Note (${truncate(pNote.message, 25)})</span>`;
+        const label = pNote.scenarioId && pNote.stepNumber ? `Step ${pNote.stepNumber}: ` : '';
+        pill.innerHTML = `<span>📄</span> <span>${label}${truncate(pNote.message, 25)}</span>`;
         pill.onclick = (e) => {
           e.stopPropagation();
           this.openNoteCard(pNote);
@@ -889,17 +1104,45 @@ export class NoteInspector {
 
     const formattedDate = new Date(note.createdAt).toLocaleString();
 
+    // Scenario flow steps navigation
+    let scenarioStepsHtml = '';
+    let scenarioSteps: VisualNote[] = [];
+    if (note.scenarioId) {
+      scenarioSteps = this.savedNotes
+        .filter((n) => n.scenarioId === note.scenarioId)
+        .sort((a, b) => (a.stepNumber || 0) - (b.stepNumber || 0));
+
+      const currentIndex = scenarioSteps.findIndex((s) => s.id === note.id);
+      const prevStep = currentIndex > 0 ? scenarioSteps[currentIndex - 1] : null;
+      const nextStep = currentIndex >= 0 && currentIndex < scenarioSteps.length - 1 ? scenarioSteps[currentIndex + 1] : null;
+
+      scenarioStepsHtml = `
+        <div class="bt-scenario-stepper">
+          <button class="bt-step-nav-btn" id="btn-prev-step" ${!prevStep ? 'disabled' : ''}>
+            ◀ Step ${prevStep ? prevStep.stepNumber : ''}
+          </button>
+          <span>🎬 Step ${note.stepNumber || 1} of ${scenarioSteps.length}</span>
+          <button class="bt-step-nav-btn" id="btn-next-step-card" ${!nextStep ? 'disabled' : ''}>
+            Step ${nextStep ? nextStep.stepNumber : ''} ▶
+          </button>
+        </div>
+      `;
+    }
+
     backdrop.innerHTML = `
       <div class="bt-modal">
         <div class="bt-modal-header">
           <div class="bt-modal-title">
-            <span>${icon} Visual Note Details</span>
+            <span>${note.scenarioId ? '🎬 ' + (note.scenarioTitle || 'Scenario Flow') : icon + ' Visual Note Details'}</span>
             <span class="bt-mode-badge ${badgeClass}">${note.type.toUpperCase()}</span>
+            ${note.scenarioId && note.stepNumber ? `<span class="bt-mode-badge bt-badge-step">STEP ${note.stepNumber}</span>` : ''}
             <span class="bt-mode-badge ${statusClass}">${note.status}</span>
           </div>
           <button class="bt-close-btn" id="btn-card-close" title="Close (Esc)">✕</button>
         </div>
 
+        ${scenarioStepsHtml}
+
         <div class="bt-target-pill" title="${contextText}">
           <span>🏷️</span>
           <span class="bt-pill-content">${contextText}</span>
@@ -913,9 +1156,18 @@ export class NoteInspector {
         </div>
 
         <div class="bt-modal-footer">
-          <button class="bt-btn bt-btn-delete" id="btn-card-delete" title="Delete this note">
-            <span>🗑️</span> Delete
-          </button>
+          <div style="display: flex; gap: 6px;">
+            <button class="bt-btn bt-btn-delete" id="btn-card-delete" title="Delete this note">
+              <span>🗑️</span> Delete
+            </button>
+            ${
+              note.scenarioId
+                ? `<button class="bt-btn bt-btn-delete" id="btn-card-delete-flow" title="Delete entire scenario flow">
+                    <span>🗑️</span> Delete Flow
+                  </button>`
+                : ''
+            }
+          </div>
           <div class="bt-modal-actions">
             <button class="bt-btn bt-btn-cancel" id="btn-card-dismiss">Close</button>
             <button class="bt-btn ${note.status === 'OPEN' ? 'bt-btn-resolve' : 'bt-btn-save'}" id="btn-card-resolve">
@@ -930,6 +1182,9 @@ export class NoteInspector {
     const btnDismiss = backdrop.querySelector('#btn-card-dismiss') as HTMLButtonElement;
     const btnResolve = backdrop.querySelector('#btn-card-resolve') as HTMLButtonElement;
     const btnDelete = backdrop.querySelector('#btn-card-delete') as HTMLButtonElement;
+    const btnDeleteFlow = backdrop.querySelector('#btn-card-delete-flow') as HTMLButtonElement | null;
+    const btnPrevStep = backdrop.querySelector('#btn-prev-step') as HTMLButtonElement | null;
+    const btnNextStepCard = backdrop.querySelector('#btn-next-step-card') as HTMLButtonElement | null;
 
     const closeCard = () => {
       if (this.cardOverlay) {
@@ -945,20 +1200,49 @@ export class NoteInspector {
       if (e.target === backdrop) closeCard();
     };
 
+    if (btnPrevStep && scenarioSteps.length > 0) {
+      const currentIndex = scenarioSteps.findIndex((s) => s.id === note.id);
+      if (currentIndex > 0) {
+        btnPrevStep.onclick = () => {
+          this.openNoteCard(scenarioSteps[currentIndex - 1]);
+        };
+      }
+    }
+
+    if (btnNextStepCard && scenarioSteps.length > 0) {
+      const currentIndex = scenarioSteps.findIndex((s) => s.id === note.id);
+      if (currentIndex >= 0 && currentIndex < scenarioSteps.length - 1) {
+        btnNextStepCard.onclick = () => {
+          this.openNoteCard(scenarioSteps[currentIndex + 1]);
+        };
+      }
+    }
+
     btnResolve.onclick = () => {
       if (note.status === 'OPEN') {
         this.transport.send({ type: 'resolve_note', noteId: note.id });
+        this.showToast('Note marked as resolved', '✅');
       } else {
         this.transport.send({ type: 'reopen_note', noteId: note.id });
+        this.showToast('Note reopened', '↺');
       }
       closeCard();
     };
 
     btnDelete.onclick = () => {
       this.transport.send({ type: 'delete_note', noteId: note.id });
+      this.showToast('Note deleted', '🗑️');
       closeCard();
     };
 
+    if (btnDeleteFlow && note.scenarioId) {
+      btnDeleteFlow.onclick = () => {
+        this.transport.send({ type: 'delete_scenario', scenarioId: note.scenarioId });
+        this.showToast('Scenario flow deleted', '🗑️');
+        closeCard();
+      };
+    }
+
     root.appendChild(backdrop);
   }
 
@@ -1008,7 +1292,7 @@ export class NoteInspector {
         if (target && target !== this.container && !this.container?.contains(target)) {
           this.selectedElement = target;
           this.openNoteEditor(target, 'element');
-          if (this.activeMode === 'element') {
+          if (this.activeMode === 'element' && !this.activeScenario) {
             this.setMode('idle');
           }
         }
@@ -1022,7 +1306,9 @@ export class NoteInspector {
           this.shadowRoot.removeChild(this.cardOverlay);
           this.cardOverlay = null;
         } else if (this.activeMode === 'region' || this.activeMode === 'element') {
-          this.setMode('idle');
+          if (!this.activeScenario) {
+            this.setMode('idle');
+          }
         }
       }
     };
@@ -1153,31 +1439,30 @@ export class NoteInspector {
             width: Math.round(width),
             height: Math.round(height),
           };
-          this.hideRegionOverlay();
-          this.setMode('idle');
           this.openRegionNoteEditor(this.selectedRegion);
-        } else {
-          this.hideRegionOverlay();
+        }
+
+        if (this.regionBox) {
+          this.regionBox.style.display = 'none';
+        }
+        if (!this.activeScenario) {
           this.setMode('idle');
         }
       };
-    }
 
-    // Always ensure regionOverlay is mounted before toolbar so toolbar is interactable
-    if (this.toolbarElement && this.toolbarElement.parentNode === root) {
-      root.insertBefore(this.regionOverlay, this.toolbarElement);
-    } else {
       root.appendChild(this.regionOverlay);
+    } else {
+      this.regionOverlay.style.display = 'block';
     }
   }
 
   private hideRegionOverlay(): void {
-    this.isDraggingRegion = false;
-    if (this.regionOverlay && this.regionOverlay.parentNode) {
-      this.regionOverlay.parentNode.removeChild(this.regionOverlay);
-    }
-    if (this.regionBox) {
-      this.regionBox.style.display = 'none';
+    if (this.regionOverlay) {
+      this.regionOverlay.style.display = 'none';
+      this.isDraggingRegion = false;
+      if (this.regionBox) {
+        this.regionBox.style.display = 'none';
+      }
     }
   }
 
@@ -1187,21 +1472,21 @@ export class NoteInspector {
 
     const rect = el.getBoundingClientRect();
     this.highlightOverlay.style.display = 'block';
-    this.highlightOverlay.style.top = `${rect.top}px`;
     this.highlightOverlay.style.left = `${rect.left}px`;
+    this.highlightOverlay.style.top = `${rect.top}px`;
     this.highlightOverlay.style.width = `${rect.width}px`;
     this.highlightOverlay.style.height = `${rect.height}px`;
 
-    const selector = getSemanticSelector(el);
-    const badgeText = `${selector} · ${Math.round(rect.width)}×${Math.round(rect.height)}`;
-
     let badge = this.highlightOverlay.querySelector('.bt-badge') as HTMLDivElement | null;
     if (!badge) {
       badge = document.createElement('div');
       badge.className = 'bt-badge';
       this.highlightOverlay.appendChild(badge);
     }
-    badge.textContent = badgeText;
+
+    const selector = getSemanticSelector(el);
+    const label = this.activeScenario ? `🎬 Step ${this.activeScenario.stepNumber} · ${selector}` : selector;
+    badge.textContent = `${label} (${Math.round(rect.width)} × ${Math.round(rect.height)} px)`;
   }
 
   private hideHighlight(): void {
@@ -1221,25 +1506,73 @@ export class NoteInspector {
     }
 
     this.renderNoteModal({
-      title: 'Add Visual Note',
-      modeBadge: noteType.toUpperCase(),
+      title: this.activeScenario
+        ? `Step ${this.activeScenario.stepNumber}: ${this.activeScenario.title}`
+        : 'Add Visual Note',
+      modeBadge: this.activeScenario ? `STEP ${this.activeScenario.stepNumber}` : noteType.toUpperCase(),
       pillText:
         noteType === 'page'
           ? `Page Viewport: ${window.innerWidth} × ${window.innerHeight} px`
           : `${getSemanticSelector(targetEl)} (${Math.round(targetEl.getBoundingClientRect().width)}×${Math.round(targetEl.getBoundingClientRect().height)}) · Viewport: ${window.innerWidth}×${window.innerHeight}`,
-      onSave: async (message) => {
-        await this.saveVisualNote(targetEl, message, noteType);
+      onSave: async (message, action) => {
+        let scenarioParam: { scenarioId?: string; stepNumber?: number; scenarioTitle?: string } | undefined;
+
+        if (action === 'next_step' && !this.activeScenario) {
+          this.startScenario();
+        }
+
+        if (this.activeScenario) {
+          scenarioParam = {
+            scenarioId: this.activeScenario.id,
+            stepNumber: this.activeScenario.stepNumber,
+            scenarioTitle: this.activeScenario.title,
+          };
+        }
+
+        await this.saveVisualNote(targetEl, message, noteType, scenarioParam);
+
+        if (action === 'next_step' && this.activeScenario) {
+          this.activeScenario.stepNumber++;
+          this.updateToolbarState();
+          this.setMode('element');
+        } else if (action === 'finish_flow' && this.activeScenario) {
+          this.finishScenario();
+        }
       },
     });
   }
 
   public openRegionNoteEditor(region: RegionContext): void {
     this.renderNoteModal({
-      title: 'Add Region Note',
-      modeBadge: 'REGION',
+      title: this.activeScenario
+        ? `Step ${this.activeScenario.stepNumber}: ${this.activeScenario.title}`
+        : 'Add Region Note',
+      modeBadge: this.activeScenario ? `STEP ${this.activeScenario.stepNumber}` : 'REGION',
       pillText: `Selected Area: x:${region.x}, y:${region.y} (${region.width} × ${region.height} px)`,
-      onSave: async (message) => {
-        await this.saveRegionVisualNote(region, message);
+      onSave: async (message, action) => {
+        let scenarioParam: { scenarioId?: string; stepNumber?: number; scenarioTitle?: string } | undefined;
+
+        if (action === 'next_step' && !this.activeScenario) {
+          this.startScenario();
+        }
+
+        if (this.activeScenario) {
+          scenarioParam = {
+            scenarioId: this.activeScenario.id,
+            stepNumber: this.activeScenario.stepNumber,
+            scenarioTitle: this.activeScenario.title,
+          };
+        }
+
+        await this.saveRegionVisualNote(region, message, scenarioParam);
+
+        if (action === 'next_step' && this.activeScenario) {
+          this.activeScenario.stepNumber++;
+          this.updateToolbarState();
+          this.setMode('element');
+        } else if (action === 'finish_flow' && this.activeScenario) {
+          this.finishScenario();
+        }
       },
     });
   }
@@ -1248,7 +1581,7 @@ export class NoteInspector {
     title: string;
     modeBadge: string;
     pillText: string;
-    onSave: (message: string) => Promise<void>;
+    onSave: (message: string, action: 'save' | 'next_step' | 'finish_flow') => Promise<void>;
   }): void {
     const root = this.ensureContainer();
     if (!root) return;
@@ -1263,15 +1596,16 @@ export class NoteInspector {
     backdrop.className = 'bt-modal-backdrop';
     this.modalOverlay = backdrop;
 
-    const badgeClass = `bt-badge-${options.modeBadge.toLowerCase()}`;
-    const icon = options.modeBadge === 'REGION' ? '📐' : options.modeBadge === 'PAGE' ? '📄' : '🎯';
+    const isStep = options.modeBadge.startsWith('STEP');
+    const badgeClass = isStep ? 'bt-badge-step' : `bt-badge-${options.modeBadge.toLowerCase()}`;
+    const icon = isStep ? '🎬' : options.modeBadge === 'REGION' ? '📐' : options.modeBadge === 'PAGE' ? '📄' : '🎯';
     const isMac = typeof navigator !== 'undefined' && /Mac|iPod|iPhone|iPad/.test(navigator.platform);
 
     backdrop.innerHTML = `
       <div class="bt-modal">
         <div class="bt-modal-header">
           <div class="bt-modal-title">
-            <span>📝 ${options.title}</span>
+            <span>${icon} ${options.title}</span>
             <span class="bt-mode-badge ${badgeClass}">${options.modeBadge}</span>
           </div>
           <button class="bt-close-btn" id="btn-close" title="Close (Esc)">✕</button>
@@ -1280,14 +1614,23 @@ export class NoteInspector {
           <span>${icon}</span>
           <span class="bt-pill-content">${options.pillText}</span>
         </div>
-        <textarea class="bt-textarea" placeholder="Describe the layout issue, styling bug, or note for AI agent..." autofocus></textarea>
+        <textarea class="bt-textarea" placeholder="Describe the layout issue, user action, or note for AI agent..." autofocus></textarea>
         <div class="bt-modal-footer">
           <div class="bt-kbd-hint">
             <kbd>${isMac ? '⌘' : 'Ctrl'}+Enter</kbd> save · <kbd>Esc</kbd> cancel
           </div>
           <div class="bt-modal-actions">
             <button class="bt-btn bt-btn-cancel" id="btn-cancel">Cancel</button>
-            <button class="bt-btn bt-btn-save" id="btn-save">Save Note</button>
+            <button class="bt-btn bt-btn-next-step" id="btn-next-step" title="Save this step and immediately select the next element">
+              <span>➡️</span> ${this.activeScenario ? 'Save & Next Step' : 'Save as Step 1 (Flow)'}
+            </button>
+            ${
+              this.activeScenario
+                ? `<button class="bt-btn bt-btn-finish-flow" id="btn-finish-flow" title="Save final step and complete scenario">
+                    <span>✓</span> Save & Finish Flow
+                  </button>`
+                : `<button class="bt-btn bt-btn-save" id="btn-save">Save Note</button>`
+            }
           </div>
         </div>
       </div>
@@ -1296,7 +1639,9 @@ export class NoteInspector {
     const textarea = backdrop.querySelector('textarea') as HTMLTextAreaElement;
     const btnClose = backdrop.querySelector('#btn-close') as HTMLButtonElement;
     const btnCancel = backdrop.querySelector('#btn-cancel') as HTMLButtonElement;
-    const btnSave = backdrop.querySelector('#btn-save') as HTMLButtonElement;
+    const btnSave = backdrop.querySelector('#btn-save') as HTMLButtonElement | null;
+    const btnNextStep = backdrop.querySelector('#btn-next-step') as HTMLButtonElement;
+    const btnFinishFlow = backdrop.querySelector('#btn-finish-flow') as HTMLButtonElement | null;
 
     const closeModal = () => {
       if (this.modalOverlay) {
@@ -1316,26 +1661,33 @@ export class NoteInspector {
       }
     };
 
-    const submitNote = async () => {
+    const handleAction = async (action: 'save' | 'next_step' | 'finish_flow') => {
       const message = textarea.value.trim();
       if (!message) return;
 
-      btnSave.textContent = 'Saving...';
-      btnSave.disabled = true;
+      btnNextStep.disabled = true;
+      if (btnSave) btnSave.disabled = true;
+      if (btnFinishFlow) btnFinishFlow.disabled = true;
 
       try {
-        await options.onSave(message);
+        await options.onSave(message, action);
       } finally {
         closeModal();
       }
     };
 
-    btnSave.onclick = submitNote;
+    if (btnSave) {
+      btnSave.onclick = () => handleAction('save');
+    }
+    btnNextStep.onclick = () => handleAction('next_step');
+    if (btnFinishFlow) {
+      btnFinishFlow.onclick = () => handleAction('finish_flow');
+    }
 
     textarea.onkeydown = (e: KeyboardEvent) => {
-      if (e.key === 'Enter' && (e.metaKey || e.ctrlKey || !e.shiftKey)) {
+      if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
         e.preventDefault();
-        submitNote();
+        handleAction(this.activeScenario ? 'next_step' : 'save');
       }
       if (e.key === 'Escape') {
         closeModal();
@@ -1346,7 +1698,12 @@ export class NoteInspector {
     setTimeout(() => textarea?.focus(), 50);
   }
 
-  public async saveVisualNote(targetEl: HTMLElement, message: string, noteType: 'element' | 'page' = 'element'): Promise<void> {
+  public async saveVisualNote(
+    targetEl: HTMLElement,
+    message: string,
+    noteType: 'element' | 'page' = 'element',
+    scenario?: { scenarioId?: string; stepNumber?: number; scenarioTitle?: string }
+  ): Promise<void> {
     const rect = targetEl.getBoundingClientRect();
     const selector = noteType === 'page' ? 'body' : getSemanticSelector(targetEl);
 
@@ -1381,25 +1738,30 @@ export class NoteInspector {
       confidence: selector.startsWith('[data-test') ? 'high' : selector.startsWith('#') ? 'medium' : 'low',
     };
 
+    const route = typeof window !== 'undefined' ? window.location.pathname + window.location.search : '/';
+    const url = typeof window !== 'undefined' ? window.location.href : 'http://localhost/';
+    const viewport = typeof window !== 'undefined'
+      ? { width: window.innerWidth, height: window.innerHeight, devicePixelRatio: window.devicePixelRatio || 1 }
+      : { width: 1280, height: 800, devicePixelRatio: 1 };
+    const scroll = typeof window !== 'undefined'
+      ? { scrollX: window.scrollX, scrollY: window.scrollY }
+      : { scrollX: 0, scrollY: 0 };
+
     const notePayload = {
       type: 'create_note',
       sessionId: this.transport.getSessionId() || '',
       noteType,
       message,
-      route: window.location.pathname + window.location.search,
-      url: window.location.href,
-      viewport: {
-        width: window.innerWidth,
-        height: window.innerHeight,
-        devicePixelRatio: window.devicePixelRatio || 1,
-      },
-      scroll: {
-        scrollX: window.scrollX,
-        scrollY: window.scrollY,
-      },
+      route,
+      url,
+      viewport,
+      scroll,
       target,
       elementContext,
       screenshot: screenshotDataUrl,
+      scenarioId: scenario?.scenarioId,
+      stepNumber: scenario?.stepNumber,
+      scenarioTitle: scenario?.scenarioTitle,
       timestamp: Date.now(),
     };
 
@@ -1407,9 +1769,19 @@ export class NoteInspector {
     if (this.options.onNoteCreated) {
       this.options.onNoteCreated(notePayload as any);
     }
+
+    if (scenario?.scenarioId) {
+      this.showToast(`Step ${scenario.stepNumber || 1} recorded`, '🎬');
+    } else {
+      this.showToast('Visual note saved', '✨');
+    }
   }
 
-  public async saveRegionVisualNote(region: RegionContext, message: string): Promise<void> {
+  public async saveRegionVisualNote(
+    region: RegionContext,
+    message: string,
+    scenario?: { scenarioId?: string; stepNumber?: number; scenarioTitle?: string }
+  ): Promise<void> {
     // 1. Capture full page screenshot and crop to region
     let screenshotDataUrl: string | undefined;
     try {
@@ -1421,24 +1793,29 @@ export class NoteInspector {
       // Defensive
     }
 
+    const route = typeof window !== 'undefined' ? window.location.pathname + window.location.search : '/';
+    const url = typeof window !== 'undefined' ? window.location.href : 'http://localhost/';
+    const viewport = typeof window !== 'undefined'
+      ? { width: window.innerWidth, height: window.innerHeight, devicePixelRatio: window.devicePixelRatio || 1 }
+      : { width: 1280, height: 800, devicePixelRatio: 1 };
+    const scroll = typeof window !== 'undefined'
+      ? { scrollX: window.scrollX, scrollY: window.scrollY }
+      : { scrollX: 0, scrollY: 0 };
+
     const notePayload = {
       type: 'create_note',
       sessionId: this.transport.getSessionId() || '',
       noteType: 'region',
       message,
-      route: window.location.pathname + window.location.search,
-      url: window.location.href,
-      viewport: {
-        width: window.innerWidth,
-        height: window.innerHeight,
-        devicePixelRatio: window.devicePixelRatio || 1,
-      },
-      scroll: {
-        scrollX: window.scrollX,
-        scrollY: window.scrollY,
-      },
+      route,
+      url,
+      viewport,
+      scroll,
       region,
       screenshot: screenshotDataUrl,
+      scenarioId: scenario?.scenarioId,
+      stepNumber: scenario?.stepNumber,
+      scenarioTitle: scenario?.scenarioTitle,
       timestamp: Date.now(),
     };
 
@@ -1446,108 +1823,103 @@ export class NoteInspector {
     if (this.options.onNoteCreated) {
       this.options.onNoteCreated(notePayload as any);
     }
-  }
 
-  private async cropDataUrl(dataUrl: string, region: RegionContext): Promise<string> {
-    return new Promise((resolve) => {
-      const img = new Image();
-      img.onload = () => {
-        try {
-          const canvas = document.createElement('canvas');
-          canvas.width = region.width;
-          canvas.height = region.height;
-          const ctx = canvas.getContext('2d');
-          if (!ctx) {
-            resolve(dataUrl);
-            return;
-          }
-
-          const dpr = window.devicePixelRatio || 1;
-          ctx.drawImage(
-            img,
-            region.x * dpr,
-            region.y * dpr,
-            region.width * dpr,
-            region.height * dpr,
-            0,
-            0,
-            region.width,
-            region.height
-          );
-          resolve(canvas.toDataURL('image/webp', 0.9));
-        } catch {
-          resolve(dataUrl);
-        }
-      };
-      img.onerror = () => resolve(dataUrl);
-      img.src = dataUrl;
-    });
+    if (scenario?.scenarioId) {
+      this.showToast(`Step ${scenario.stepNumber || 1} region recorded`, '🎬');
+    } else {
+      this.showToast('Region note saved', '📐');
+    }
   }
 
   private extractElementContext(el: HTMLElement): ElementContext {
     const selector = getSemanticSelector(el);
-    const tag = el.tagName.toLowerCase();
-
-    // Attributes (sanitize passwords/tokens)
     const attributes: Record<string, string> = {};
+
     for (let i = 0; i < el.attributes.length; i++) {
       const attr = el.attributes[i];
-      if (attr.name === 'value' && (el as HTMLInputElement).type === 'password') {
+      if (
+        this.options.maskSelectors?.some((mask) => {
+          try {
+            return el.matches(mask);
+          } catch {
+            return false;
+          }
+        }) &&
+        (attr.name === 'value' || attr.name === 'data-secret')
+      ) {
         attributes[attr.name] = '[REDACTED]';
       } else {
         attributes[attr.name] = attr.value;
       }
     }
 
-    // Clone element to sanitize inner sensitive fields
-    let outerHTML = '';
-    try {
-      const clone = el.cloneNode(true) as HTMLElement;
-      for (const passInput of Array.from(clone.querySelectorAll('input[type="password"]'))) {
-        passInput.setAttribute('value', '[REDACTED]');
-      }
-      outerHTML = truncate(clone.outerHTML, 10240); // 10 KB max
-    } catch {
-      outerHTML = truncate(el.outerHTML, 10240);
+    let outerHTML = el.outerHTML;
+    if (outerHTML && outerHTML.length > 1000) {
+      outerHTML = truncate(outerHTML, 1000);
     }
 
-    let parent: { selector: string; tag: string } | undefined;
-    if (el.parentElement && el.parentElement !== document.body) {
-      parent = {
-        selector: getSemanticSelector(el.parentElement),
-        tag: el.parentElement.tagName.toLowerCase(),
-      };
+    let innerText = el.innerText || el.textContent || '';
+    if (innerText && innerText.length > 200) {
+      innerText = truncate(innerText, 200);
     }
 
     return {
       selector,
-      tag,
+      tag: el.tagName.toLowerCase(),
       attributes,
       outerHTML,
-      innerText: truncate(el.textContent?.trim(), 200),
-      parent,
+      innerText,
+      parent: el.parentElement
+        ? {
+            selector: getSemanticSelector(el.parentElement),
+            tag: el.parentElement.tagName.toLowerCase(),
+          }
+        : undefined,
     };
   }
 
+  private async cropDataUrl(dataUrl: string, region: RegionContext): Promise<string> {
+    return new Promise((resolve) => {
+      const img = new Image();
+      img.onload = () => {
+        const canvas = document.createElement('canvas');
+        canvas.width = region.width;
+        canvas.height = region.height;
+        const ctx = canvas.getContext('2d');
+        if (!ctx) {
+          resolve(dataUrl);
+          return;
+        }
+
+        const dpr = window.devicePixelRatio || 1;
+        ctx.drawImage(
+          img,
+          region.x * dpr,
+          region.y * dpr,
+          region.width * dpr,
+          region.height * dpr,
+          0,
+          0,
+          region.width,
+          region.height
+        );
+        resolve(canvas.toDataURL('image/png'));
+      };
+      img.onerror = () => resolve(dataUrl);
+      img.src = dataUrl;
+    });
+  }
+
   public destroy(): void {
     for (const cleanup of this.cleanups) {
-      try {
-        cleanup();
-      } catch {}
+      cleanup();
     }
     this.cleanups = [];
 
-    if (this.container && this.container.parentElement) {
-      this.container.parentElement.removeChild(this.container);
+    if (this.container && this.container.parentNode) {
+      this.container.parentNode.removeChild(this.container);
+      this.container = null;
+      this.shadowRoot = null;
     }
-    this.container = null;
-    this.shadowRoot = null;
-    this.toolbarElement = null;
-    this.regionOverlay = null;
-    this.regionBox = null;
-    this.regionBanner = null;
-    this.markersContainer = null;
-    this.modalOverlay = null;
-    this.cardOverlay = null;
   }
 }