Ready2Blob/.planning/PROJECT.md

# Ready2Blob

## What This Is

Ready2Blob is a pure-frontend web app that helps IT professionals deploy rclone onto end-user Windows PCs. A step-by-step wizard collects backend credentials (18 backends: Azure Blob, S3, S3-compatible, OneDrive, SFTP, GCS, Backblaze B2, Google Drive, Dropbox, Box, pCloud, FTP, WebDAV, SMB, HTTP, Seafile, Yandex Disk, Koofr) and deployment preferences, then generates rclone config files and PowerShell scripts ready to push via Intune or any RMM tool — all client-side, no server required.

## Core Value

An IT pro can go from zero to a deployable rclone setup in minutes — without needing to know rclone's config syntax or PowerShell deployment conventions.

## Current State

**Shipped:** v1.3 — 2026-04-16
**Backends:** 18 (Azure Blob, S3, S3-compatible, OneDrive, SFTP, GCS, Backblaze B2, Google Drive, Dropbox, Box, pCloud, FTP, WebDAV, SMB, HTTP, Seafile, Yandex Disk, Koofr)
**Tech stack:** Vite 6, React 18, TypeScript 5, Tailwind v4, react-hook-form 7, Zod 4, Vitest 4, JSZip
**Test coverage:** 165+ tests across all test files — all GREEN
**Total milestones:** 3 shipped (v1.0 + v1.1 + v1.2 + v1.3), 13 phases, 40 plans

## Requirements

### Validated

- ✓ Backend Schema Registry as single source of truth for form rendering, Zod validation, config generation — v1.0
- ✓ 4-step wizard (backend selection → config → deployment → review/download) with back-navigation — v1.0
- ✓ Review + download layer: live preview, security gate, individual downloads, ZIP bundle, clipboard copy — v1.0
- ✓ Registry-driven BackendSelectionStep, scriptTargets filtering, ReviewStep Back button, dead export cleanup, act() fix — v1.1
- ✓ 4 new backends (OneDrive, SFTP, GCS, B2), SftpAuthToggle, inline field validation, contextual tooltips — v1.1
- ✓ **THEME-01**: MD3 color token system (CSS custom properties), all components use semantic classes — v1.2
- ✓ **THEME-02**: System/Light/Dark theme toggle, persisted in localStorage, zero FOUC — v1.2
- ✓ **COMP-01**: MD3 outlined text fields with CSS-only floating labels — v1.2
- ✓ **COMP-02**: MD3 button hierarchy (filled/outlined/text) across all wizard steps — v1.2
- ✓ **COMP-03**: Backend cards and output blocks with MD3 elevation and tonal surface tint — v1.2
- ✓ **COMP-04**: StepIndicator with numbered circles, connectors, checkmarks — v1.2
- ✓ **DEBT-01**: FieldRenderer consistent `aria-label` across text/select branches — v1.2
- ✓ **UX-01**: Intro section explaining Ready2Blob with CTA to start wizard — v1.2
- ✓ **UX-02**: Remote name field with example, help text, live config preview — v1.2
- ✓ **UX-03**: 1-2 sentence step descriptions on all 4 wizard steps — v1.2
- ✓ **UX-04**: Contextual help text on all backend credential fields — v1.2
- ✓ **POLISH-01**: Mobile-responsive layout (stacking cards, full-width fields, stretch buttons) — v1.2
- ✓ **POLISH-02**: MD3 `focus-visible` ring-3 indicators on all interactive elements — v1.2
- ✓ **POLISH-03**: Step fade/slide transition with `prefers-reduced-motion` guard — v1.2
- ✓ **POLISH-04**: Auto-scroll to first validation error on form submission — v1.2
- ✓ **DARK-01**: All wizard step h2 headings readable in dark mode — v1.2
- ✓ **DARK-02**: DeploymentStep native form controls visible with semantic tokens in dark mode — v1.2
- ✓ **DARK-03**: FieldRenderer select has proper bg/text color in dark mode — v1.2
- ✓ **REMOTE-01**: BACKEND_REGISTRY with 18 backends, correct rclone fields, displayName, description, category — v1.3
- ✓ **REMOTE-02**: BackendType derived from `keyof typeof BACKEND_REGISTRY` — no manual union — v1.3
- ✓ **REMOTE-03**: BackendSelectionStep with category groups, instant search, inline SVG icons — v1.3
- ✓ **REMOTE-04**: OAuthInstructions collapsible component with backend-specific `rclone authorize` — v1.3
- ✓ **REMOTE-05**: RemoteConfigStep renders correct form for all 18 backends including GdriveAuthToggle — v1.3
- ✓ **REMOTE-06**: buildRcloneConf produces valid rclone.conf for all 18 backends — v1.3

### Active

*(No active requirements — planning next milestone)*

### Out of Scope

| Feature | Reason |
|---------|--------|
| User accounts / saved templates | No backend, no persistence |
| Server-side generation | Everything runs in the browser |
| Test connection / validate credentials | Requires backend proxy (CORS blocks direct cloud API calls) |
| rclone version management / auto-update on endpoints | Separate lifecycle problem |
| Non-Windows targets | Scripts target Windows endpoints only |
| Auto-push to Intune via Graph API | Requires Azure AD app registration, massive scope increase |
| Config credential encryption | rclone encrypted configs require interactive unlock, incompatible with unattended deployment |
| Multiple remotes in one config | Significant wizard UX complexity, defer to v2 |
| OAuth flow in browser | Requires backend proxy; paste pre-obtained token instead |
| MUI or Material Tailwind component library | Bundle bloat (~300KB+) for 4-step wizard; custom tokens + Tailwind lighter |
| Page-per-step routing (React Router) | Wizard state is ephemeral credentials in memory; refreshing loses context |
| Glassmorphism / neomorphism effects | CPU-intensive, low contrast accessibility issues |
| Arbitrary user-picked hex color | Breaks accessibility; curated presets cover 95% of personalization need |
| Custom checkbox/radio styling | High effort for few toggles; native inputs sufficient |

## Constraints

- **Architecture**: Pure static frontend — no backend, no server required
- **Target OS**: Windows endpoints only (scripts are PowerShell)
- **Secrets**: Plain text in generated files — UI must display a clear security warning before download

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Pure frontend (no backend) | Simpler hosting, no data retention risk with credentials | ✓ Good — static site deployable anywhere |
| BACKEND_REGISTRY as single source of truth | Drives form rendering, Zod schemas, and config generation from one definition | ✓ Good — zero duplication across phases |
| useReducer + Context API (no external state lib) | Zero dependencies, sufficient for 4-step wizard | ✓ Good — kept bundle lean |
| Wave 0 TDD (stubs RED before implementation) | Forces API contract before code, catches integration mismatches early | ✓ Good — caught several issues upfront |
| Support all rclone backends (not Azure-only) | Broader utility despite "Blob" in project name | ✓ Good — 18 backends shipped |
| Optional rclone install in scripts | Different orgs have different baseline images | ✓ Good — no friction for orgs that pre-install |
| Tailwind v4 via @tailwindcss/vite plugin | No postcss.config.js, no tailwind.config.js needed | ✓ Good — cleaner config |
| Zod v4 + @hookform/resolvers v5 together | v5 resolvers required for Zod v4 compatibility | ✓ Good — noted for future upgrades |
| AzureAuthToggle / SftpAuthToggle CSS hidden pattern | Preserves both auth fields in react-hook-form state when toggling | ✓ Good — extended to GdriveAuthToggle in v1.3 |
| FieldDef.validate + tooltipText extension | Additive interface change, non-breaking to existing backends | ✓ Good — clean composition |
| ThemeToggle via DOM class toggle, not React Context | Avoids re-render cascade on theme change | ✓ Good — instant theme switch |
| Two-layer CSS token pattern (@theme + @layer base) | Required for .dark cascade in Tailwind v4 | ✓ Good — only valid approach for v4 |
| vi.stubGlobal for localStorage/matchMedia in tests | Node v25 experimental WebStorage breaks standard Storage API in jsdom | ✓ Good — necessary workaround |
| TextFieldMD3 CSS-only floating label | `peer-[:not(:placeholder-shown)]` — no JS state | ✓ Good — simpler, animatable |
| DEBT-01 fix: aria-label directly on tooltip buttons | Prevents getByLabelText ambiguity with { selector: 'input' } guard | ✓ Good — consistent pattern |
| key={state.currentStep} on step wrapper | Forces React remount to trigger CSS animation from initial state | ✓ Good — cleanest animation approach |
| BackendType derived from `keyof typeof BACKEND_REGISTRY` | Eliminates manual union maintenance at 18+ backends | ✓ Good — adding a backend is one touch-point |
| BACKEND_SCHEMAS auto-generated via Object.fromEntries | No per-backend buildZodSchema call needed | ✓ Good — zero boilerplate |
| Registry `as const` (not Record<BackendType,…> cast) | Cast was circular when BackendType derived from registry | ✓ Good — necessary to break circularity |
| type=search for search input | Prevents getByRole('textbox') collision with remote name TextFieldMD3 | ✓ Good — test-selector discipline |
| renderBackendFields() switch vs nested ternaries | 7+ branches require readable structure | ✓ Good — extensible for future backends |
| OAuthInstructions step-prefix detection | Renders authorize command in `<code>` element; keeps test assertions compatible | ✓ Good — clean heuristic |
| BACKEND_ICONS as Partial<Record<BackendType, FC>> | Missing entries = no icon rendered (no error) | ✓ Good — graceful degradation |

<details>
<summary>Previous milestone context (v1.0 → v1.3 key decisions)</summary>

**v1.0 shipped:** 2026-03-27, 4 phases, 18 plans, ~2,746 LOC
**v1.1 shipped:** 2026-03-31, 3 phases, 11 plans, +7,311 lines
**v1.2 shipped:** 2026-04-01, 5 phases, 14 plans, +9,908 lines
**v1.3 shipped:** 2026-04-16, 1 phase, 4 plans, +3,753 lines

**v1.2 tech debt resolved in v1.3:**
- FieldRenderer aria inconsistency (DEBT-01) — resolved Phase 9

**v1.3 tech debt carried forward:**
- Test selectors risk if UI restyled heavily (131+ selectors, ongoing discipline required)
- No formal milestone audit run for v1.3

</details>

---
*Last updated: 2026-04-16 after v1.3 milestone*