/**
 * Feature Documentation: Background Terminal Buffering
 *
 * Demonstrates that terminal switching still works correctly after adding
 * buffer-and-replay for background terminals. Verifies that switching
 * between sessions shows terminal output and tab switching works.
 *
 * Run with: pnpm test:feature-docs background-terminal-buffering
 */
import { test, expect, resetApp } from '../_shared/electron-fixture'
import type { Page } from '@playwright/test'
import path from 'path'
import fs from 'fs'
import { fileURLToPath } from 'url'
import { screenshotElement, screenshotRegion } from '../_shared/screenshot-helpers'
import { generateFeaturePage, generateIndex, FeatureStep } from '../_shared/template'

const __filename = fileURLToPath(import.meta.url)
const __dirname = path.dirname(__filename)

const FEATURE_DIR = __dirname
const SCREENSHOTS = path.join(FEATURE_DIR, 'screenshots')
const FEATURES_ROOT = path.join(__dirname, '..')

let page: Page
const steps: FeatureStep[] = []

test.beforeAll(async () => {
  await fs.promises.mkdir(SCREENSHOTS, { recursive: true })
  ;({ page } = await resetApp())
})

test.afterAll(async () => {
  await generateFeaturePage(
    {
      title: 'Background Terminal Buffering',
      description:
        'When multiple agents run simultaneously, background terminals now buffer PTY data ' +
        'instead of writing to xterm.js in real-time. Data is replayed in a single batch when ' +
        'the terminal becomes visible. This walkthrough verifies that session switching and ' +
        'terminal tabs still work correctly with buffering enabled.',
      steps,
    },
    FEATURE_DIR,
  )
  await generateIndex(FEATURES_ROOT)
})

test.describe.serial('Feature: Background Terminal Buffering', () => {
  test('Step 1: Initial session has a visible terminal', async () => {
    const sidebar = page.locator('[data-panel-id="sidebar"]')
    await expect(sidebar).toBeVisible()

    // First session should be selected and terminal visible
    const terminalArea = page.locator('.xterm:visible').first()
    await expect(terminalArea).toBeVisible()

    await screenshotRegion(
      page,
      sidebar,
      terminalArea,
      path.join(SCREENSHOTS, '01-initial-session.png'),
    )
    steps.push({
      screenshotPath: 'screenshots/01-initial-session.png',
      caption: 'Initial state: first session selected with active terminal',
      description:
        'The active session\'s terminal receives PTY data directly (no buffering). ' +
        'Background sessions buffer data until they become visible.',
    })
  })

  test('Step 2: Switch to a different session', async () => {
    const backendSession = page.locator('.cursor-pointer:has-text("backend-api")')
    await backendSession.click()
    await expect(backendSession).toHaveClass(/bg-accent\/15/)

    // Terminal should be visible for the newly active session
    const terminalArea = page.locator('.xterm:visible').first()
    await expect(terminalArea).toBeVisible()

    const sidebar = page.locator('[data-panel-id="sidebar"]')
    await screenshotRegion(
      page,
      sidebar,
      terminalArea,
      path.join(SCREENSHOTS, '02-switched-session.png'),
    )
    steps.push({
      screenshotPath: 'screenshots/02-switched-session.png',
      caption: 'Switched to backend-api — its terminal is now active',
      description:
        'When switching sessions, the newly visible terminal flushes any buffered data ' +
        'and receives future PTY output directly. The previous session\'s terminal ' +
        'starts buffering.',
    })
  })

  test('Step 3: Switch back — terminal state preserved', async () => {
    const broomySession = page.locator('.cursor-pointer:has-text("broomy")')
    await broomySession.click()
    await expect(broomySession).toHaveClass(/bg-accent\/15/)

    const terminalArea = page.locator('.xterm:visible').first()
    await expect(terminalArea).toBeVisible()

    await screenshotElement(
      page,
      terminalArea,
      path.join(SCREENSHOTS, '03-back-to-first.png'),
    )
    steps.push({
      screenshotPath: 'screenshots/03-back-to-first.png',
      caption: 'Switching back preserves terminal content',
      description:
        'Any data that arrived while this terminal was in the background is replayed ' +
        'in a single batch write, which is dramatically cheaper than writing each chunk individually.',
    })
  })

  test('Step 4: Terminal tabs work within a session', async () => {
    // Add a user terminal tab
    const addTabButton = page.locator('[data-testid="add-terminal-tab"]')
    // The add tab button might have different selectors — look for it
    const tabBar = page.locator('.xterm:visible').first().locator('..')
    await expect(tabBar).toBeVisible()

    // Verify the Agent tab is visible
    const agentTab = page.getByText('Agent', { exact: true }).first()
    await expect(agentTab).toBeVisible()

    await screenshotElement(
      page,
      agentTab.locator('..').locator('..'),
      path.join(SCREENSHOTS, '04-terminal-tabs.png'),
    )
    steps.push({
      screenshotPath: 'screenshots/04-terminal-tabs.png',
      caption: 'Terminal tab bar with Agent tab',
      description:
        'The tab bar shows the Agent tab. Switching between terminal tabs within a session ' +
        'also triggers buffer flush — only the visible tab writes to xterm.js.',
    })
  })


})
