remotion_service/docs/superpowers/plans/2026-04-04-subtitle-revision-workspace.md

# Subtitle Revision Workspace Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Redesign the subtitle-revision screen into a more cohesive editorial workspace while staying inside the current frontend design system.

**Architecture:** Keep the existing component boundaries and logic intact, then improve hierarchy through coordinated shell styling and small presentation-only markup changes. The work is isolated to the shared stepper chrome, the subtitle-revision step layout, the transcription editor surface, and the timeline dock so the redesign remains low-risk and easy to verify.

**Tech Stack:** Next.js 16, React, TypeScript, SCSS Modules, Vidstack, Lucide, Chrome DevTools MCP

---

## File Structure

- Modify: `cofee_frontend/src/shared/ui/Stepper/Stepper.module.scss`
  Purpose: Reduce stepper visual dominance and align it with the calmer workspace shell.
- Modify: `cofee_frontend/src/widgets/ProjectWizard/ProjectWizard.module.scss`
  Purpose: Introduce softer page-level spacing/canvas treatment around the active step content.
- Modify: `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.tsx`
  Purpose: Add minimal presentational structure for player/editor panel headers and shell grouping.
- Modify: `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.module.scss`
  Purpose: Build the unified editorial workspace shell and responsive balanced split behavior.
- Modify: `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.tsx`
  Purpose: Add small semantic wrappers for a stronger editor header and cleaner segment metadata grouping.
- Modify: `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.module.scss`
  Purpose: Redesign the editor surface, segment cards, and add-segment action within current tokens.
- Modify: `cofee_frontend/src/widgets/TimelinePanel/TimelinePanel.module.scss`
  Purpose: Make the timeline feel like a docked rail within the same workspace shell.

## Task 1: Soften the Stepper and Page Canvas

**Files:**
- Modify: `cofee_frontend/src/shared/ui/Stepper/Stepper.module.scss`
- Modify: `cofee_frontend/src/widgets/ProjectWizard/ProjectWizard.module.scss`
- Test: `cd cofee_frontend && bunx tsc --noEmit`

- [ ] **Step 1: Inspect the current stepper and wizard shell before editing**

Run:

```bash
sed -n '1,220p' cofee_frontend/src/shared/ui/Stepper/Stepper.module.scss
sed -n '1,220p' cofee_frontend/src/widgets/ProjectWizard/ProjectWizard.module.scss
```

Expected: confirm the current stepper uses a saturated active pill and the wizard root is mostly structural with minimal page-level styling.

- [ ] **Step 2: Update the stepper to feel quieter and more integrated**

Apply changes in `cofee_frontend/src/shared/ui/Stepper/Stepper.module.scss` so the active step is calmer and the bar reads as context instead of a hero element.

Use this shape for the key selectors:

```scss
.root {
	position: relative;
	background: linear-gradient(180deg, variables.$bg-default 0%, variables.$bg-surface 100%);
	border-bottom: 1px solid variables.$border-subtle;
}

.scrollContainer {
	gap: 10px;
	padding: 18px 28px 14px;
}

.step {
	padding: 8px 14px 8px 8px;
	border-radius: 999px;
	background: rgba(255, 255, 255, 0.42);
	border: 1px solid transparent;
}

.stepActive {
	background: variables.$bg-surface;
	border-color: rgba(139, 92, 246, 0.16);
	box-shadow: 0 10px 24px rgba(24, 24, 27, 0.06);
}

.stepCompleted {
	background: rgba(255, 255, 255, 0.28);
}
```

- [ ] **Step 3: Give the wizard a softer canvas around the active step**

Update `cofee_frontend/src/widgets/ProjectWizard/ProjectWizard.module.scss` so the content area gets breathing room without changing behavior.

Use this shape:

```scss
.root {
	display: flex;
	flex-direction: column;
	height: calc(100vh - var(--header-height));
	overflow: hidden;
	background: linear-gradient(180deg, variables.$bg-default 0%, rgba(255, 255, 255, 0.55) 100%);
}

.content {
	flex: 1;
	display: flex;
	flex-direction: column;
	overflow-y: auto;
	min-height: 0;
	padding: 18px 24px 24px;
}
```

- [ ] **Step 4: Run the frontend type-check after the shell changes**

Run:

```bash
cd cofee_frontend && bunx tsc --noEmit
```

Expected: exit code `0`.

- [ ] **Step 5: Commit the shell changes**

```bash
git add cofee_frontend/src/shared/ui/Stepper/Stepper.module.scss cofee_frontend/src/widgets/ProjectWizard/ProjectWizard.module.scss
git commit -m "feat: refine project wizard shell"
```

## Task 2: Build the Subtitle Revision Workspace Shell

**Files:**
- Modify: `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.tsx`
- Modify: `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.module.scss`
- Test: `cd cofee_frontend && bunx tsc --noEmit`

- [ ] **Step 1: Inspect the current subtitle-revision markup and styles**

Run:

```bash
sed -n '1,260p' cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.tsx
sed -n '1,260p' cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.module.scss
```

Expected: confirm the current main grid, timeline, and footer are separate blocks with minimal shared shell styling.

- [ ] **Step 2: Add panel headers and a single workspace shell in the TSX**

Update `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.tsx` so the player and editor live inside named panels.

Use this structure inside the `MediaPlayer` content:

```tsx
<div className={styles.workspaceShell}>
	<div className={styles.mainGrid}>
		<section className={styles.panel}>
			<div className={styles.panelHeader}>
				<div>
					<p className={styles.eyebrow}>Просмотр</p>
					<h3 className={styles.panelTitle}>Видео проекта</h3>
				</div>
			</div>
			<div className={styles.playerColumn}>...</div>
		</section>

		<section className={styles.panel}>
			<div className={styles.panelHeader}>
				<div>
					<p className={styles.eyebrow}>Редактор</p>
					<h3 className={styles.panelTitle}>Транскрипция</h3>
				</div>
			</div>
			<div className={styles.editorColumn}>...</div>
		</section>
	</div>

	<div className={styles.timelineWrapper}>...</div>
	<div className={styles.footer}>...</div>
</div>
```

- [ ] **Step 3: Style the workspace shell, balanced split, and responsive stack**

Update `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.module.scss` with a single rounded shell, two equal panels, and a docked lower rail.

Use this shape for the key selectors:

```scss
.workspaceShell {
	display: flex;
	flex-direction: column;
	flex: 1;
	min-height: 0;
	border: 1px solid rgba(24, 24, 27, 0.08);
	border-radius: variables.$radius-lg;
	background: linear-gradient(180deg, rgba(255, 255, 255, 0.72) 0%, variables.$bg-surface 100%);
	box-shadow: 0 18px 48px rgba(24, 24, 27, 0.08);
	overflow: hidden;
}

.mainGrid {
	display: grid;
	grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
	gap: 18px;
	padding: 20px;
	flex: 1;
	min-height: 0;
}

.panel {
	display: flex;
	flex-direction: column;
	min-height: 0;
	border: 1px solid rgba(24, 24, 27, 0.08);
	border-radius: variables.$radius-lg;
	background: rgba(255, 255, 255, 0.58);
	overflow: hidden;
}
```

Add responsive collapse:

```scss
@media (max-width: 1024px) {
	.mainGrid {
		grid-template-columns: 1fr;
	}
}
```

- [ ] **Step 4: Verify the layout still type-checks**

Run:

```bash
cd cofee_frontend && bunx tsc --noEmit
```

Expected: exit code `0`.

- [ ] **Step 5: Commit the workspace shell changes**

```bash
git add cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.tsx cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.module.scss
git commit -m "feat: redesign subtitle revision workspace shell"
```

## Task 3: Redesign the Transcription Editor Surface

**Files:**
- Modify: `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.tsx`
- Modify: `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.module.scss`
- Test: `cd cofee_frontend && bunx tsc --noEmit`

- [ ] **Step 1: Inspect the current transcription editor structure**

Run:

```bash
sed -n '1,320p' cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.tsx
sed -n '1,320p' cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.module.scss
```

Expected: confirm the current editor has a plain header, dense segment rows, and a dashed add button.

- [ ] **Step 2: Add semantic wrappers for a stronger header and cleaner metadata row**

Update `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.tsx` with small presentation-only wrappers.

Use this shape:

```tsx
<div className={styles.headerMeta}>
	<p className={styles.kicker}>Редактура</p>
	<h3 className={styles.title}>Редактор транскрипции</h3>
</div>

<div className={styles.segmentMetaRow}>
	<div className={styles.timesGroup}>...</div>
	<div className={styles.actionsGroup}>...</div>
</div>
```

For each timing field, wrap the label and input in a chip-like container:

```tsx
<label className={styles.timeChip}>
	<span className={styles.timeLabelText}>Начало</span>
	<input className={styles.timeInput} ... />
</label>
```

- [ ] **Step 3: Rework the editor styling into a calmer editorial surface**

Update `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.module.scss` so the editor looks less like a raw form and more like a reading/editing workspace.

Use this shape for the key selectors:

```scss
.root {
	display: flex;
	flex-direction: column;
	height: 100%;
	min-height: 0;
	background: transparent;
}

.header {
	display: flex;
	align-items: center;
	justify-content: space-between;
	padding: 18px 20px 14px;
	border-bottom: 1px solid rgba(24, 24, 27, 0.08);
	background: rgba(255, 255, 255, 0.68);
}

.segment {
	border: 1px solid rgba(24, 24, 27, 0.08);
	border-radius: variables.$radius-lg;
	padding: 14px;
	background: rgba(255, 255, 255, 0.82);
	box-shadow: 0 8px 24px rgba(24, 24, 27, 0.04);
}

.timeChip {
	display: inline-flex;
	align-items: center;
	gap: 8px;
	padding: 6px 10px;
	border-radius: 999px;
	background: variables.$bg-hover;
	border: 1px solid transparent;
}

.textArea {
	padding: 14px 16px;
	border-radius: variables.$radius-md;
	line-height: 1.65;
	background: rgba(244, 244, 245, 0.92);
}
```

Replace the dashed add button treatment with a quieter inset surface:

```scss
.addButton {
	margin: 0 20px 18px;
	padding: 12px 14px;
	border: 1px solid rgba(24, 24, 27, 0.08);
	border-radius: variables.$radius-md;
	background: rgba(255, 255, 255, 0.6);
}
```

- [ ] **Step 4: Run the frontend type-check after the editor redesign**

Run:

```bash
cd cofee_frontend && bunx tsc --noEmit
```

Expected: exit code `0`.

- [ ] **Step 5: Commit the editor redesign**

```bash
git add cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.tsx cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.module.scss
git commit -m "feat: refine transcription editor presentation"
```

## Task 4: Dock the Timeline and Verify in Chrome

**Files:**
- Modify: `cofee_frontend/src/widgets/TimelinePanel/TimelinePanel.module.scss`
- Test: `cd cofee_frontend && bunx tsc --noEmit`
- Verify: Chrome at `http://localhost:3000/projects/83eb1396-8217-4ceb-ae32-b3b63cd01982`

- [ ] **Step 1: Inspect the current timeline chrome**

Run:

```bash
sed -n '1,260p' cofee_frontend/src/widgets/TimelinePanel/TimelinePanel.module.scss
```

Expected: confirm the toolbar and label column are functional but visually flatter and less integrated with the workspace shell.

- [ ] **Step 2: Update the timeline dock styling to match the workspace**

Modify `cofee_frontend/src/widgets/TimelinePanel/TimelinePanel.module.scss` so the toolbar, labels column, and scroll area feel like a lower editing rail.

Use this shape:

```scss
.root {
	display: flex;
	flex-direction: column;
	align-self: stretch;
	height: 100%;
	min-width: 0;
	overflow: hidden;
	background: rgba(255, 255, 255, 0.56);
}

.toolbar {
	height: 40px;
	padding: 0 14px;
	border-bottom: 1px solid rgba(24, 24, 27, 0.08);
	background: rgba(255, 255, 255, 0.72);
}

.labelsColumn {
	width: 68px;
	background: rgba(255, 255, 255, 0.48);
}

.zoomBtn {
	width: 28px;
	height: 28px;
	border-radius: 999px;
}
```

- [ ] **Step 3: Run the frontend type-check before browser verification**

Run:

```bash
cd cofee_frontend && bunx tsc --noEmit
```

Expected: exit code `0`.

- [ ] **Step 4: Verify the redesigned screen in Chrome**

Check the route:

```text
http://localhost:3000/projects/83eb1396-8217-4ceb-ae32-b3b63cd01982
```

Verify all of the following:

- the stepper is still readable but less dominant
- the player and editor read as one shell
- the desktop split still feels balanced
- the transcription cards are calmer and easier to scan
- the timeline feels docked to the workspace
- the footer stays visually anchored
- the layout still holds together at a narrower viewport

- [ ] **Step 5: Commit the timeline and verification-backed finish**

```bash
git add cofee_frontend/src/widgets/TimelinePanel/TimelinePanel.module.scss
git commit -m "feat: align timeline dock with subtitle workspace"
```

## Self-Review

### Spec Coverage

- Quieter stepper: covered by Task 1
- Single workspace shell: covered by Task 2
- Stronger transcription editor hierarchy: covered by Task 3
- Docked timeline integration: covered by Task 4
- Responsive balanced split: covered by Task 2 and Task 4 browser verification
- Design-system constraint: enforced in every task by reusing existing tokens and limiting scope to SCSS/module presentation

### Placeholder Scan

- No `TODO`, `TBD`, or deferred implementation notes remain
- Each task lists exact files and commands
- Each styling task includes concrete selector/code shapes instead of abstract guidance

### Type Consistency

- `workspaceShell`, `panel`, `panelHeader`, `eyebrow`, and `panelTitle` are introduced in the step component only
- `headerMeta`, `kicker`, `segmentMetaRow`, and `timeChip` are introduced in the editor only
- No new logic APIs or renamed behavioral props are required