Files

T

debont80 36699531cf Format code with Prettier (8 modified files from H1 decomposition)

Aligns with CC2 enforcement: ESLint + Prettier + noImplicitAny now enforced.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

2026-07-01 07:54:02 -04:00

136 KiB

Raw Blame History

Code Audit

Living checklist of audit findings for AeroFetch. Security & correctness were reviewed 2026-06-23 (all fixed — see Completed). The architectural review (2026-06-29) added the structural items; a second polish pass (2026-06-29) added the smaller inconsistencies. Items carry stable IDs so we can check them off as they land this session.

Severity = structural leverage / risk of future bugs, not "app is broken" (it isn't).

Session 2026-06-30 (correctness/safety/strictness pass): landed B3 B4 B5 B7 (checksum- filename match, newline-safe meta probe, canceled-event guards, cookie-login never-resolve), L88 L146 (queue/trim edge cases), L168 + L169 (noUncheckedIndexedAccess + noFallthroughCasesInSwitch now on — 0 errors after 8 real edge-case fixes), R5 (settings write failure handled), W1 W5 W6 (min window size, seeded folder picker, parented sign-in window), CL1 (shared stdout markers), L147 (dead macOS branches removed), M8 (StatusChip already unified the status→label map), M36 (Library selection only counts actionable rows), L11 (Queue header counts the live queue), L50 (no "saved" for 0 cookies), L156 + L57 (schedule picker min), L159 L15 L3 (dead-code/comment cleanup), package/builder metadata (L4 L41 L42 L43 L45 L58), user-facing copy (L66 L154; partial M37/SR9 jargon), doc reconciliation (M25 M26 L80 L81), and new unit tests (L35 isValidMediaItem, L36 compareVersions). All verified: typecheck + 234 tests + eslint + prettier green.

Session 2026-06-30 pass 2 (quality/format/UX polish): H5 (history re-download now stores formatId/formatHasAudio + strips compound quality labels; thumbnail also passed — L72), H6 (TerminalView log capped at 2000 lines), M21 (skip --audio-quality for lossless flac/wav), L166 (fmtEta hour rollover fixed in download.ts, store/downloads.ts, queueStats.ts — "2:00:00" not "120:00"), L165 (formatSpeed precision aligned with fmtBytes), L55 (QueueItem suppresses sizeLabel when already in probed-format quality label), L47 (probeMeta null sends empty meta event to clear "Resolving…"), L68 (notifiedBackground resets on window show), L76 (dup warning falls back to URL when title is placeholder), L91 (SettingsView unsafe tuple cast fixed), L98 (embed-chapters hint added), L108 (window title set), L37 (formatters extracted to lib/formatters.ts; fmtBytes/fmtEta/parseProgress unit-tested including NA paths), L38 (webm thumbnail exclusion test), L39 (CROP_SQUARE_PPA structural test), L40 (looksLikeUrl/looksLikeSingleVideo extracted to lib/urlHelpers.ts; test imports pure module directly). All verified: typecheck + 242 tests + eslint + prettier green.

Session 2026-06-30 pass 3 (reliability — B/R/L races & silent failures): L140 + L148 (the active-map teardown race — cancelDownload/pauseDownload release the concurrency slot synchronously and an identity-guarded releaseActive + per-spawn cookie jar make same-id retry/resume safe), L141 (renderer history capped at 500 + url de-dup to mirror main), R6 (writeJsonAtomic reports + logs write failures and keeps the data dirty for retry instead of an empty catch — log half; toast → CC8), R7 (encryptSecret warns before the plaintext fallback). All verified: typecheck + 243 tests + eslint green; the 5 touched files are prettier-clean. Deferred this pass (need UI/live-app or larger design): B2/B6 (cancel buttons + abort wiring), R4 (can't safely identify a download's .part files at cancel time — needs the yt-dlp "Destination" path tracked), L139 (needs a spawn↔auto-update interlock), L142 (multi-site IPC-return reconciliation, generalises M34), L157 (cross-store cancel-on-remove, ties to C2), R9 (clock-skew — "note for awareness").

Session 2026-06-30 pass 4 (Critical — store architecture): C1 (single source of truth for the preview mock + Settings defaults — DEFAULT_SETTINGS in @shared, one typed mockApi.ts, centralized isPreview) and C2 (broke the downloads ↔ sources circular import via a pure typed event bus, store/coordinator.ts — neither store imports the other now). All verified: typecheck + 243 tests + eslint green; the touched files are prettier-clean (3 pre-existing format violations in DownloadOptionsForm/LibraryView/SettingsView are untouched and out of scope).

Session 2026-07-01 (main-process structure — the H1-adjacent decompose batch): L2 (the ~200-line flat IPC block moved into one src/main/ipc.ts registerIpcHandlers(getMainWindow); index.ts is now lifecycle + window creation and imports the shared theme helpers from ipc.ts), L69 (path helpers split into src/main/paths.ts; settings.ts is now purely the electron-store layer), L10 (a main-process src/main/constants.ts centralizes the spawn timeouts, execFile buffers, stderr tail, and the three store caps — nine modules migrated off bare literals), CL2 (buildArgs → single BuildArgsInput object), CL3 (startDownload's stream/close/error/watchdog wiring extracted into wireChildProcess), and L1 (the scheduled-download promoter tick moved from store-module load into an App useEffect so a store import no longer starts a stray timer). All verified: typecheck (node+web) + 253 tests + eslint + production build green; the touched files are prettier-clean (the 8 remaining prettier warnings are all pre-existing, untouched files — DownloadOptionsForm/SettingsView/settings/*Card).

Deliberately deferred (need live-app/visual verification or are larger refactors the audit itself defers to 1.x): the wire-or-cut features (M5/M6/UX1), the god-file/store refactors (C1, C2, H1), the SIMP* helpers + shared-UI-token work, the CC* consolidations, PERF8 code-splitting, and the visual UI/UX polish long-tail. These are best done as their own PRs with the app running so the UI can actually be checked.

1.0 Release-Readiness Audit (lead-engineer synthesis)

A pre-release synthesis of the ~385 catalogued findings below — root causes, a release gate, and the consequential issues per dimension (severity · reasoning · fix · benefit). The detailed, ID'd backlog follows. No rewrite required; everything here is incremental.

Verdict

Not 1.0-ready as-is, but close — roughly 3–4 focused PRs away. The foundation is genuinely strong: disciplined security model (context isolation, sandbox, argv-injection defense, host-pinned signed-checksum updater), a clean pure/impure architecture, and good unit coverage of the pure logic. What blocks a commercial 1.0 is a thin layer of (a) real reliability bugs, (b) naive persistence, (c) built-but-unwired features, (d) first-run/perceived-quality gaps, and (e) the absence of enforcement/observability tooling. None require rearchitecting.

Root-cause themes (the 385 findings collapse to 8)

Built-but-unwired features — command preview (M5), incognito (M6), per-download options/extraArgs (UX1) are plumbed end-to-end with no UI; the ROADMAP even marks them ✅ (M25). Decide wire-or-cut.
"Two ways to do X" with no enforcement — persistence (M1), validation (CC9), async (CC5), errors (CC6), UI primitives (UI14/UI18/UI19), formatters (M9) — and no ESLint/Prettier to hold any line (CC2).
Renderer-optimistic state never reconciles + a store cycle — M34/L142 (settings show unsaved values), C2 (downloads↔sources circular import).
Naive JSON persistence — non-atomic writes (R1), corrupt→silent total data loss (R2), O(n²) full-file rewrites per completion (R3/PERF7), no cache.
Download-engine reliability gaps — no stall timeout (B1), reverse-order batches (M32), orphan .part on cancel (R4), retry-during-teardown race (L140).
First-run / perceived quality — light-default theme (SR1), nightly-default yt-dlp (SR2), placeholder icon (W14), stuck "Resolving…" (SR6), progress bar visibly restarting (SR7), unsigned build (SIGNING.md).
Accessibility & Windows-native feel — focus rings (UI28/29), no list keyboard nav (W7), title-bar theme (W3), text-field context menu (W4), no aria-live (W17), input labels (M28).
No enforcement / observability — no lint (CC2), noImplicitAny:false (M38), no logging (CC8/M29), no production source maps (L170).

Release gate

MUST fix before 1.0 (blockers) — correctness, data safety, security, trust: B1 · M32 · M35 · M34 · R1 · R2 · R3 · H7 · H8 · SR1 · SR6 · SR7 · W14 — all resolved as of this session. Code signing was dropped from the gate: it's a deliberate non-goal (no certificate will be purchased; the SmartScreen prompt on the unsigned build is accepted).

SHOULD fix for 1.0 (high): wire-or-cut the dead features (M5/M6/UX1) · a11y cluster (UI28/29, W4, W7, W17, M28) · W3 native theming · lint + noImplicitAny (CC2/M38) · dev-jargon copy (M37/SR9) · destructive confirmations (UX4) · PERF1/PERF2 (per-download redundant work).

DEFER to 1.x: the ~150 Low items · the simplification refactors (SIMP*, do incrementally) · the UI token system + shared primitives (UI/SIMP — high value, larger effort) · i18n · sqlite migration.

By dimension (severity · reasoning · fix · benefit)

Reliability

[Critical] No download stall timeout (B1). Reasoning: spawn has no timeout + no --socket-timeout; a dead connection hangs forever and permanently consumes a concurrency slot. Fix: --socket-timeout + an idle watchdog that kills+errors via the existing killTree. Benefit: downloads self-recover on flaky networks.
[Critical] Non-atomic writes + silent corruption→data-loss (R1/R2). Reasoning: writeFileSync isn't atomic; a crash mid-write corrupts the store and the next read returns [], silently wiping history/ sources. Fix: atomic write (temp+rename) + back up a corrupt file before resetting, in one jsonStore. Benefit: user data survives crashes; no silent loss.
[High] Reverse-order batch downloads (M32) & history duplicates (M35). Reasoning: addMany+pump promote highest-index first; redownload mints a new id defeating dedup. Fix: reverse the batch enqueue; dedup history by URL. Benefit: playlists download 1→N; clean history.
[High] Optimistic state never reconciles (M34). Reasoning: renderer keeps a value main rejected. Fix: apply the validated Settings the IPC returns. Benefit: the UI never lies about what's saved.

Performance

[High] O(n²) media-items rewrite (R3/PERF7). Reasoning: every completion re-reads+rewrites the whole (≤20k-item) file synchronously. Fix: in-memory cache + batched atomic writes (the same jsonStore). Benefit: channel downloads stop hitching the main process.
[Medium] Per-download redundant work (PERF1/PERF2). Reasoning: templates.json read + settings decrypt on every spawn even when unused. Fix: gate listTemplates() on the consent flag; cache decrypted settings. Benefit: lower latency/IO per download.
[Low] summarizeQueue/pump O(n) per tick (PERF3/PERF4). Fix: memoize + count-based pump. Benefit: scales to large queues.

Maintainability

[High] Triplicated Settings/Api + the preview mock (C1). Reasoning: a 4th touch-point per IPC method; drift-prone. Fix: DEFAULT_SETTINGS in @shared; one typed mockApi. Benefit: one place to change.
[High] Store circular dependency (C2). Fix: a coordinator/event bus. Benefit: removes a latent init crash.
[Medium] Duplicated persistence/validation/async/formatters (M1/CC9/CC5/M9). Fix: the lib/ helpers in SIMP1–SIMP5. Benefit: ~−500 LOC and fewer divergence bugs.
[Medium] God files (H1). Fix: SettingsView via <SettingsCard>/<ToggleField> (SIMP10). Benefit: 1104→~600 lines, reviewable.

Consistency

[Medium] Two ways to do X across persistence, status chips, segmented controls, buttons, errors (M1/UI18/UI14/UI15/CC6). Fix: one shared primitive/standard each (see "Recommended single style"). Benefit: the app reads as one product.
[Low] Naming/copy drift (CC1, L95/L150, separators L164). Fix: the conventions in CC1. Benefit: professional finish.

Readability

[Medium] Magic strings/numbers + long signatures + deep nesting (CL1/CL2/CL4, L10). Fix: constants.ts, options-objects, extracted helpers. Benefit: faster comprehension, fewer transpose bugs (CL2).

Polish (perceived quality)

[High] First-run defaults (SR1/SR2/SR3). Reasoning: light-on-dark first launch, nightly yt-dlp by default, auto-download-new on. Fix: theme:'system', ytdlpChannel:'stable', autoDownloadNew:false. Benefit: the first 10 seconds feel native and safe.
[High] Stuck "Resolving…" (SR6) & restarting progress bar (SR7). Fix: clear placeholder on error; weight the two merge phases. Benefit: nothing looks hung/glitchy.
[High] Placeholder icon (W14). Fixed: a designed mark (teal gradient square + top sheen, bold rounded download glyph over a landing shelf) replaces the flat placeholder; multi-size .ico regenerated. Benefit: brand credibility. (Unsigned build is a non-goal — no cert; the SmartScreen prompt is accepted.)

User experience

[High] Per-download options are unreachable (UX1). Reasoning: must change global settings to tweak one download. Fix: wire the existing DownloadOptionsForm into the bar (plumbing exists). Benefit: reclaims a whole feature.
[High] Destructive actions have no confirmation/undo (UX4). Fix: confirm Clear/Remove/Delete. Benefit: prevents data loss.
[Medium] Silent failures on Open/Show (UX6) and no global download status off the Downloads tab (UX9). Fix: surface errors; sidebar badge. Benefit: the app feels responsive and honest.

Accessibility & Windows-native (UX-critical for a Windows product)

[High] Fragmented/invisible focus + no list keyboard nav (UI28/29, W7). Fix: one focus-ring + roving list focus + Delete/Ctrl+A. Benefit: keyboard- and Narrator-usable.
[Medium] Title bar ignores in-app theme (W3); text fields have no context menu (W4); no aria-live (W17); inputs lack accessible names (M28). Fix: sync themeSource; add an editing context menu; live regions; aria-labels. Benefit: feels like a native, accessible Windows app.

Developer experience

[High] No enforcement tooling (CC2) + noImplicitAny:false (M38). Reasoning: style/type safety rely on discipline; implicit any is allowed. Fix: Prettier + typescript-eslint + CI; re-enable noImplicitAny. Benefit: the conventions stay true; regressions caught pre-merge.
[Medium] No logging + no prod source maps (CC8/M29/L170). Fix: one leveled file logger at every catch; hidden source maps. Benefit: field crashes become diagnosable instead of invisible.
[Low] Stale roadmap/docs (M25/M26, L80–L82); release checksum is manual (H8). Fix: reconcile docs; generate .sha256 in build:win. Benefit: trustworthy docs; updates don't silently fail to install.

Suggested PR sequence to 1.0

Correctness & data safety: B1, M32, M35, M34, and the cached/atomic jsonStore (R1/R2/R3/PERF7).
Security & trust: H7 (encrypt cookies), H8 (auto-generate checksums). (Code signing is a non-goal — no cert.)
First-run polish: SR1/SR2/SR3 defaults, SR6/SR7 status, W14 icon, W3 title-bar theme.
Wire-or-cut + a11y + tooling: UX1 (per-download panel) or remove M5/M6; focus/keyboard (UI28/29, W7, W4); Prettier+ESLint+noImplicitAny (CC2/M38).
Incremental cleanup (post-1.0): the SIMP refactors and the Low/UI/UX long tail, behind the new lint gate.

Critical

C1 — Single source of truth for the IPC mock + Settings defaults. const PREVIEW redeclared in 8 files; main.tsx reimplements the entire Api (~180 lines); the full Settings object is hand-maintained in 3 places (main/settings.ts DEFAULTS, renderer/store/settings.ts FALLBACK, main.tsx MOCK_SETTINGS). Add DEFAULT_SETTINGS to shared/ipc.ts, extract the preview mock into one mockApi.ts typed as Api, centralize isPreview. Fixed: DEFAULT_SETTINGS is now the canonical default in shared/ipc.ts; main's DEFAULTS, the renderer FALLBACK (store/settings.ts), and the preview MOCK_SETTINGS all derive from it (preview-only field tweaks layered on top) instead of three hand-kept copies. The whole browser mock moved into one mockApi.ts typed Window['api'] (so a missing/mistyped method is a compile error), and main.tsx shrank to window.api = mockApi. The PREVIEW check is single-sourced in isPreview.ts and imported (as PREVIEW) by all 8 sites.
C2 — Break the downloads ↔ sources store circular dependency. downloads.ts imports useSources; sources.ts imports useDownloads. Works only via lazy .getState(). Introduce a coordinator/event bus that owns cross-store reactions. Fixed: a tiny typed event bus store/coordinator.ts (no runtime deps — the AddEntry import is type-only) now owns the two cross-store reactions. sources emits enqueueDownloads (consumed by downloads.addMany); downloads emits downloadCompleted (consumed by sources.markDownloaded). Each store imports the bus, not the other, so the cycle is gone. Because downloads no longer pulls in sources, App now eagerly imports the sources store for side-effects (import './store/sources') so its startup load + scheduled- --sync kickoff and the downloadCompleted subscription still run at launch — robust even once the views are lazy-loaded (PERF8).

High

H1 — Decompose god files. SettingsView.tsx (1104, ~11 cards, ~30 selector subs + ~20 useState), DownloadBar.tsx (858, ~17 state hooks), store/downloads.ts (614). Done on refactor/h1-decompose-god-files: SettingsView → components/settings/*.tsx (one component per card + shared settingsStyles.ts), leaving a ~90-line shell (search box + display-toggle filter); each card still renders one <Card> DOM node so the filter is unchanged. DownloadBar → a downloadBar/useDownloadBar.ts hook (all state + handlers, wrapper handlers keep the preview-invalidation side-effects) + downloadBar/styles.ts + downloadBar/PlaylistPanel.tsx, leaving a render-only shell. store/downloads.ts → downloadTypes.ts (types, re-exported so importers are untouched) + downloadItem.ts (buildItem/titleFromUrl/RESOLVING) + downloadSeed.ts (preview seed), leaving the store + recordCompletion + wiring. Behaviour unchanged; full typecheck + lint + production build + 248 tests green.
H2 — Consolidate scattered utilities. youtubeId ×2; 4 YouTube-URL-parsing variants; byte/speed/eta/duration formatting across 4 modules. URL half: one canonical youtubeId now lives in urlHelpers.ts (the complete watch/shorts/embed/live/youtu.be parse); thumb.ts, queueStats.ts (sameVideo), and store/downloads.ts (titleFromUrl, which also fixes an old bug where any host with a ?v= param was mislabeled "YouTube video") all import it — the three ad-hoc reimplementations are gone. Formatter half (done with H4): fmtBytes/fmtSpeed/fmtEta now have a single home in @shared/format.ts imported by both sides; the main formatters module re-exports them and the renderer's three private copies (a byte formatter, an ETA formatter, and a speed string→number re-parser in queueStats) are deleted. Per-item and aggregate speed now use the same 1024-based scale (the old aggregate used 1000, a latent inconsistency). Unit-tested in test/clipboardLink.test.ts + test/download.test.ts + test/queueStats.test.ts.
H3 — Fix probe.ts → download.ts dependency direction (fmtBytes import); resolves with H2's shared formatter.
H4 — Carry raw numbers across the progress boundary. DownloadProgress ships formatted speed/eta strings; queueStats.ts re-parses them back to numbers. Fixed: DownloadProgress now carries speedBytesPerSec/etaSeconds as raw numbers (main's parseProgress no longer formats them); the renderer stores the raw numbers on DownloadItem, QueueItem formats them for display via @shared/format, and summarizeQueue sums/maxes the numbers directly — the lossy string→number→string round-trip (and queueStats' parseSpeed/parseEtaSeconds) is gone. Done together with the formatter half of H2.
H5 — History re-download silently changes quality. HistoryView.redownload passes the stored quality (for format-picker downloads this is a label like "720p · mp4 · 184 MB") back as quality with no formatId; buildArgs.videoFormat() has no matching case and falls back to bv*+ba/b (Best). The queued item shows "720p…" while actually fetching Best.
H6 — TerminalView log grows unbounded. setLines((ls) => [...ls, …]) with no cap; a verbose run (-F, --verbose) streams thousands of lines into React state. Every other log/list in the app is capped — cap this too (and/or virtualize).
H7 — cookies.txt written in plaintext with no restrictive perms. cookies.ts writeFileSync(getCookiesFilePath(), …) stores live auth/session cookies unencrypted under userData. In the portable build that's AeroFetch-data/ next to the exe (USB stick / shared Downloads folder), so anyone with folder access can read a logged-in session. Settings secrets are DPAPI-encrypted (settings.ts) but cookies are not. Encrypt at rest or document the exposure for the portable/shared-PC scenario the app explicitly targets.
H8 — Release checksum is a manual step the updater hard-requires. updater.ts sets REQUIRE_CHECKSUM = true and refuses any update lacking a <asset>.sha256, but build:win (electron-vite build && electron-builder --win) never generates one. Evidence in dist/: only 0.4.1 has .sha256 files (hand-made); the current 0.5.0 build does not. If a release is published without manually adding the checksum, every client's in-app update fails ("This release has no checksum … refusing to install"). Generate the .sha256 in the build/release script.

Medium

M1 — Unify JSON persistence. sources.ts has generic readJsonArray/writeJson; history.ts/errorlog.ts/templates.ts reimplement it inline.
M2 — Remove dead code: getDefaultFolder / download:default-folder (channel + preload + handler + mock, zero callers).
M3 — Remove duplicated completion side-effect in store/downloads.ts (history write + markDownloaded in both applyEvent('done') and the preview ticker). Subsumed by C2.
M4 — Decide queue persistence explicitly. Scheduler/queue is renderer-memory only; saved/scheduled items don't survive a quit. Persist or document as a non-goal in code.
M5 — Command-preview feature is fully built but unwired. CommandPreviewResult type + command:preview channel + previewCommand (download.ts) + formatCommandLine/ quoteForDisplay (buildArgs) + preload method all exist, but no renderer component calls window.api.previewCommand (only the main.tsx mock references it). Wire it into the DownloadBar Options panel, or remove the dead chain. Fixed: a "Show command / Hide command" toggle in DownloadBar.tsx calls window.api.previewCommand and renders the exact yt-dlp argv (monospace). The preview mirrors what download() spawns — probe-selected formatId/formatHasAudio, quality, per-download options, and trim — and is invalidated whenever any of those inputs (or the URL / a re-probe) changes, so the shown command never goes stale. Wired with M6/UX1 in the same panel.
M6 — Private/incognito mode is plumbed but unreachable. incognito flows through AddOptions → buildItem → history-skip → the QueueItem "Private" badge, but nothing in the UI ever sets incognito: true. Add the toggle or remove the dead plumbing. Fixed: an "Incognito mode (no logging, no history, no cookies)" checkbox in the DownloadBar Advanced panel sets incognito on the enqueued item (via AddOptions), lighting up the existing QueueItem "Private" badge. Reset to off after each download so it never silently carries over to the next.
M7 — newId() duplicated 3× (store/downloads.ts, TerminalView.tsx, TemplateManager.tsx) with divergent fallback prefixes (item-/t-/tpl-). Extract one helper. Fixed: one newId(prefix) helper; the three copies import it and pass their prefix. The fallback gained a monotonic counter so same-millisecond ids can't collide (subsumes L33/L70). Unit-tested in test/id.test.ts.
M8 — Two download-status→label maps. STATUS_BADGE (QueueItem) and STATUS_LABEL (LibraryView) independently map the same statuses (completed = "Completed" vs "Downloaded"). One shared map.
M9 — Three time formatters. relTime (LibraryView), formatWhen (HistoryView), fmtSchedule (QueueItem) — consolidate into a date util. Fixed: all three moved to datetime.ts and imported by their views; unit-tested in test/datetime.test.ts.
M10 — .url shortcut parsing duplicated — parseUrlFile (DownloadBar) vs readUrlShortcut (main/deeplink). Different URL= extractors for the same file format.
M11 — Inconsistent clipboard access. Reads use navigator.clipboard.readText (paste button) and window.api.readClipboard (suggestion watcher); writes use navigator.clipboard.writeText (copy report). Pick one strategy.
M12 — Shared errorText style. tokens.colorPaletteRedForeground1 is applied inline 12× across 5 files instead of one class. Partially fixed: added useErrorTextStyles (error / errorPre for pre-wrap multi-line output) and adopted it in SettingsView.tsx — the biggest offender — replacing all 6 inline style={{ color: … }} error spans + its local errorRowText class. The remaining red references live in per-component makeStyles classes (DownloadBar/LibraryView/QueueItem/TerminalView), not inline; migrate those to the shared hook incrementally.
M13 — Inconsistent secret-field masking. updateToken uses type="password"; proxy (may carry user:pass@) and youtubePoToken (a token) are plain-text Inputs.
M14 — Settings search mutates React-owned DOM. The search toggles each card's el.style.display directly; fragile (breaks if a card ever gets a conditional style) and matches on textContent incl. hidden text. Prefer state-driven filtering.
M15 — Nested interactive controls in role="button" (a11y). LibraryView's group header is a role="button" div containing <Button>s (All / Download) — invalid ARIA / keyboard semantics. Make the header a real element with sibling buttons.
M16 — No renderer error boundary. An exception in any view unmounts the whole shell to a blank window. Add a top-level boundary with a recover/reload affordance. Fixed: added ErrorBoundary wrapping <App/> in main.tsx. The fallback is dependency-free (no Fluent/theme provider — the crash may have come from that tree), logs via componentDidCatch, shows the error message, and offers a Reload button (window.location.reload(); persisted data lives in main, so nothing is lost).
M17 — statusByUrl collapses duplicate URLs. LibraryView maps URL→status into one Map; with "Download anyway" duplicates, a row can reflect the wrong item's state.
M18 — Audio "quality" presets hard-code MP3. QUALITY_OPTIONS.audio labels ("Best (MP3)", "320 kbps") are shown even when downloadOptions.audioFormat is opus/flac/wav, so the label contradicts the actual output format; --audio-quality is also meaningless for lossless.
M19 — Sidebar-collapsed pref uses localStorage while every other preference uses electron-store — won't back up/restore and is lost in the portable build across machines.
M20 — ProgressBar / native <select> accessibility. QueueItem/DownloadsView ProgressBars have no accessible name; several Selects carry both a <Field label> and an aria-label (double announcement).
M21 — --audio-quality always emitted. buildArgs passes --audio-quality even for lossless audioFormat (flac/wav), where it's meaningless; pair with M18's preset/format mismatch.
M22 — Backup export writes secrets in cleartext, silently. backup.ts exportBackup serializes the decrypted settings (proxy creds, PO token, update token) to a plain JSON file; the UI caption only says "Does not include download history" — no warning that the file contains credentials. Fixed: proxy/youtubePoToken/updateToken are stripped (set to '') before writing; SettingsView caption updated to say credentials are not included.
M23 — MAX_ITEMS truncation can silently drop a source's items. sources.ts replaceMediaItems does [...new, ...others].slice(0, 20000); once the global total exceeds the cap, the tail (another source's items) is dropped on write and only reappears when that source is re-indexed. Cap per-source, or surface it.
M24 — setSettings accepts unvalidated free strings. settings.ts stores rateLimit/proxy/defaultVideoQuality/defaultAudioQuality/youtubePlayerClient as any string. A bad rateLimit ("abc") only fails at download time; a defaultQuality not in QUALITY_OPTIONS leaves the Settings dropdown's controlled value blank. Fixed: VIDEO_QUALITY_OPTIONS / AUDIO_QUALITY_OPTIONS added to shared/ipc.ts and imported in both settings.ts (allowlist validation) and store/downloads.ts (single source of truth). rateLimit validated against yt-dlp rate format regex; youtubePlayerClient trimmed.
M25 — ROADMAP marks unwired features as ✅ shipped. ROADMAP.md Phase C ("Command preview … Surfaced as a Preview command button in the download bar") and Phase D ("Private / incognito mode — a download bar toggle") both carry [x], but neither is wired in the UI (corroborates M5/M6). The roadmap overstates completion — reconcile the docs or finish the wiring.
M26 — ROADMAP accent palette is wholesale stale. ROADMAP.md Phase E describes "four accent presets — Toffee (original), Slate, Evergreen, Lavender" with a default of Toffee; the shipped theme.ts is rose / coral / amber / teal ("Sunset-to-sea") with a default of teal. The whole section documents a palette that no longer exists.
M27 — Library batch-enqueue ignores per-item kind. sources.ts enqueueItems forces settings.defaultKind (+ its quality) for every item, so a channel can't be downloaded as audio without flipping the global default — inconsistent with the DownloadBar playlist panel, which offers a per-item video/audio toggle.
M28 — Primary text inputs have no accessible name. The URL field (DownloadBar), add-source (Library), search (History/Settings), and the Terminal args Textarea rely on placeholder only — which is not an accessible name. Add aria-label/<label> to each. (a11y; distinct from M20's Select/ProgressBar.)
M29 — Failures are swallowed everywhere. 29 .catch(() => {}) sites across 15 files: nearly every IPC write/read discards its error with no log, no user feedback, and no telemetry. A failed settings write, history add, or openPath simply vanishes. Fixed: a shared logError(op) helper replaces every swallowed renderer catch with one consistent console.error('[AeroFetch] <op> failed:', e) (settings, history, templates, errorlog, sources, App, DownloadBar drag-drop, SettingsView version reads, LibraryView scheduled-sync); main-process sites (ytdlp auto-update, cookies loadURL) log inline. Four genuinely-silent catches left intentionally: pauseDownload / cancelDownload (process kill, state already applied), unlink (cleanup), and clipboard.writeText (browser permission — no user action available). Scope note: this delivers the "log" half — failures are no longer silent. The user-facing toast + a persistent log sink (renderer console.error isn't captured in a packaged build) are deferred to CC8 (electron-log), which the audit already cross-references here.
M30 — A broken contextBridge degrades silently to mock mode. preload/index.ts only console.errors if exposeInMainWorld throws; the renderer then sees no window.electron, flips PREVIEW true, and runs the browser mock (no real IPC) with no visible error. A real bridge failure looks like "preview." Fixed: preload sends IpcChannels.preloadBridgeFailure on failure; main registers ipcMain.once(IpcChannels.preloadBridgeFailure, …) in registerIpcHandlers() (run before the window is created) and shows an error dialog + quits, so the failure is impossible to miss.
M31 — Default Electron menu (incl. Toggle DevTools/Reload) ships in production. No Menu.setApplicationMenu(null) is called; with autoHideMenuBar the default role menu is still Alt-accessible, exposing DevTools/reload to end users. Fixed: Menu.setApplicationMenu(null) called in app.whenReady() when !is.dev; dev builds keep the menu for DevTools access.
M32 — Playlist/channel batches download in reverse order. addMany prepends the whole batch in entry order ([entry1…entryN, …old]), but pump() promotes the highest-index queued item first (it reverses, assuming one-at-a-time prepends). So a selected playlist/channel downloads N → 1. Files are still named 001…NNN correctly (by playlistIndex), so a partial run leaves the last videos on disk — surprising. Enqueue batches in reverse, or have pump() respect insertion order.
M33 — Documented enqueue batch cap doesn't exist. ipc.ts:629 and ROADMAP-PINCHFLAT claim the queue pulls "a batch at a time (e.g. 50)" via MAX_ENQUEUE_BATCH so it "never holds the whole collection at once," but no such cap exists — enqueueItems addManys every selected item, so "Download all pending" on a 5,000-video channel puts 5,000 items in the store/queue at once. Implement the cap or fix the comment.
M34 — Optimistic settings updates never reconcile with main's validation. The settings store does set(partial) then setSettings(partial).catch(() => {}), discarding the validated Settings main returns. A value main rejects (e.g. an unsafe filenameTemplate, a clamped maxConcurrent, a malformed rateLimit) still shows as accepted in the UI until restart — the user believes a setting saved that didn't. Apply the returned authoritative state.
M35 — History re-download creates duplicate rows. redownload re-queues via addFromUrl, which mints a new id; on completion addHistory dedups by id (no match) and prepends a second row for the same video. Re-downloading from History accumulates duplicates. Dedup by URL, or reuse the entry id.
M36 — Library checkbox count ≠ "Download N selected". Every item row has a checkbox (LibraryView.tsx), but selectedActionable filters to pending/error/canceled only, so selecting 5 rows (incl. 2 already-downloaded) shows "Download 3 selected." The checkbox count and the button count silently disagree. Fix: only show checkboxes on actionable rows, or count all selected.
M37 — End-user hints leak developer/internal references. Settings hints surface dev-facing detail: "Requires aria2c.exe in resources/bin (see the README there)", "paste a read-only Gitea token", "sent via --extractor-args", "breaking downloads with 403 errors", "open a locked cookie database", and roadmap status ("automatic minting is planned"). These read as code comments, not product copy. Fix: rewrite for end users (hide repo/flag/HTTP-status jargon and roadmap notes).
M38 — noImplicitAny: false partially defeats strict. The inherited @electron-toolkit/tsconfig sets strict: true but explicitly "noImplicitAny": false", and neither project tsconfig re-enables it — so a parameter/variable with no inferrable type silently becomes any project-wide (the one real hole in an otherwise-strict setup; noUnusedLocals/ noUnusedParameters/noImplicitReturns are on, which is why dead locals don't accumulate). Fix: re-enable noImplicitAny in tsconfig.node.json/tsconfig.web.json.

Low

L1 — Module-load setInterval in store/downloads.ts runs on import (incl. tests/preview). Fixed: the scheduled-download promoter tick moved out of store-module scope into an App.tsx useEffect (interval SCHEDULE_TICK_MS, cleared on unmount). Importing the store in tests/preview no longer starts a stray never-cleared timer; the store keeps the promoteDueScheduled action, App owns the cadence. (The preview startFakeTicker interval is created on demand per launched item, not at load, so it was already fine.)
L2 — index.ts flat IPC registration (~150 lines) — let each main module export its own register(ipcMain). Fixed: the whole ~200-line handler block moved into one dedicated ipc.ts exporting registerIpcHandlers(getMainWindow) — the single place the renderer's IPC contract is wired. index.ts now imports it (plus the three shared theme helpers resolveBackgroundMode /applyNativeTheme/getSystemThemeInfo, also moved to ipc.ts) and shed ~50 imports it only needed for the handlers, leaving it as app-lifecycle + window creation. The window-coupled handlers (folder picker, theme-synced background, taskbar progress) take the live window via the getMainWindow accessor rather than a captured mainWindow.
L3 — Stale comments. getYtdlpVersion JSDoc still calls it the "Step-1 spike"; vitest.config.ts claims tests "only exercise buildArgs.ts" (9 test files now exist).
L4 — electron-builder.yml nits. copyright: yt-dlp frontend is not a copyright string (no holder/year); the files exclude tsconfig.tsbuildinfo never matches the real tsconfig.web.tsbuildinfo.
L5 — Inline style={{}} vs makeStyles (25× across 8 files; SettingsView 14×). Notably Sidebar's active-nav inset shadow and DownloadOptionsForm's hint caption use inline styles where a class exists elsewhere.
L6 — Control height mismatch. Select is a fixed 32px sitting beside size="large" (~40px) Input/Buttons in DownloadBar.
L7 — canceled and paused share the 'warning' badge color (QueueItem) — visually ambiguous.
L8 — Index/compound list keys. TerminalView keys log lines by array index; Settings Diagnostics keys by id + occurredAt while every other list keys by id alone.
L9 — Thumbnail box sizes not shared. Four hand-tuned 16:9 boxes (120×68, 108×64, 72×44, 60×34) with no shared aspect/size constant.
L10 — Scattered magic numbers. Timeouts/caps spread across modules (probe 60s, indexer 180s, probeMeta 30s, update-idle 60s; MAX_ENTRIES 500/200, MAX_TEMPLATES 100, MAX_ITEMS 20000). Consider a central constants module. Fixed: a main-process constants.ts now holds the process-spawn timeouts (VERSION_TIMEOUT_MS, META_PROBE_TIMEOUT_MS, PROBE_TIMEOUT_MS, INDEX_TIMEOUT_MS, YTDLP_UPDATE_TIMEOUT_MS, FEED_FETCH_TIMEOUT_MS, STALL_TIMEOUT_MS), the execFile maxBuffer sizes (META/PROBE/INDEX_MAX_BUFFER), STDERR_TAIL_BYTES, and the three hand-rolled store caps (ERRORLOG_MAX_ENTRIES, TEMPLATES_MAX, MEDIA_ITEMS_MAX). download/ffmpeg/indexer/probe/ytdlp/sync/ errorlog/templates/sources import from it instead of bare literals. Values already single-sourced in the shared contract (HISTORY_MAX_ENTRIES) and updater.ts's already-named local timeouts were left in place — they aren't scattered literals.
L11 — "Queue (N)" overcounts. DownloadsView's header count is items.length (includes completed/error/canceled), not the active queue.
L12 — Command palette polish. No scroll-into-view for keyboard selection in the 50vh list; role="dialog" without aria-modal/focus-trap; Esc handled only on the input.
L13 — Destructive actions lack confirmation. "Clear history", "Clear log", "Remove source" are one-click — inconsistent with the careful confirm on backup import.
L14 — base.css is bare — no global box-sizing, :focus-visible, or font-smoothing baseline, so custom native elements (Select, Hint, segmented controls) get inconsistent focus rings; box-sizing is then set ad hoc on the SettingsView swatch.
L15 — MediaThumb redundant ternary kind === 'audio' ? 'audio' : 'video' (kind is already that union).
L16 — relTime/formatWhen verbosity. relTime returns unbounded "N d ago"; History's formatWhen always appends the year, even for the current year.
L17 — TemplateManager regex not validated. An invalid urlPattern is accepted with no feedback and silently never matches (main's matchesUrl swallows the error).
L18 — Terminal nav item shown when custom commands are off — leads to a gated dead-end view; consider hiding/disabling it.
L19 — App.tsx focus hack — setTimeout(() => …focus(), 60) after a tab switch.
L20 — youtubePlayerClient is free text with no allowlist/validation; a typo passes straight to yt-dlp's --extractor-args.
L21 — Inconsistent in-component error handling. SettingsView funnels the app-update not-ok result into a dedicated appUpdError slot but keeps not-ok duals for version/update/export/import — two patterns in one file.
L22 — DownloadOptionsForm shows both audio + video controls regardless of the chosen kind in the per-download override panel (audio format shown for a video download, etc.).
L23 — Diagnostics shows first 20 errors with no "showing 20 of N" hint (the copied report includes all).
L24 — window.open(htmlUrl, '_blank') in SettingsView is the only window.open in the app (relies on the window-open handler); elsewhere external opens go through IPC/shell.
L25 — Taskbar effect over-fires. App.tsx subscribes to the whole downloads store and recomputes summarizeQueue + sends the taskbar IPC on every store change (each progress tick); throttle or dedupe by computed value.
L26 — Third URL-sniffing path. DownloadBar's drag-drop firstUrl is a separate "first http(s) line" extractor alongside useClipboardLink.looksLikeUrl and deeplink's scan.
L27 — DownloadBar Enter probes, not downloads. Enter in the URL field triggers fetchFormats; there's no keyboard path to actually start the download (LibraryView's Enter runs its primary action). Inconsistent.
L28 — Default kind/quality applied once. DownloadBar seeds from settings via a one-shot ref; changing the default in Settings while on the Downloads tab isn't reflected until reload.
L29 — UI constant in the store. QUALITY_OPTIONS lives in store/downloads.ts yet is a presentational constant imported by views — couples UI to the store module.
L30 — Redundant loading="lazy" on MediaThumb images already inside a virtualized list (the virtualizer only mounts visible rows).
L31 — Two theme switchers. Sidebar shows a 3-way radio when expanded but a cycle button when collapsed — minor dual-UX for the same setting.
L32 — paletteActions rebuilt every render in App.tsx (not memoized); harmless today, but it's passed straight into a child.
L33 — idCounter fallback resets per launch. The non-crypto newId fallback (item-${++idCounter}) restarts at 1 each run; the Date.now()-based fallbacks elsewhere can collide within a millisecond. Unify on one robust id helper (see M7). Fixed with M7: the single newId fallback is ${prefix}-${Date.now()}-${++counter}, so same-ms ids stay distinct.

Round 3 (2026-06-29) — tests, build metadata, error copy, edge cases:

L34 — Integration test off by default. real-download.integration.test.ts is describe.skipIf(!RUN); npm test never exercises a real download, so there's no automated regression for the actual yt-dlp argv path (only the pure builder).
L35 — isValidMediaItem has no test — the one persisted-JSON validator of six with no spec.
L36 — compareVersions differing-length components untested (e.g. 1.2 vs 1.2.0).
L37 — download.ts formatters untested (parseProgress/fmtBytes/fmtEta, incl. the NA paths).
L38 — buildArgs webm-thumbnail exclusion branch untested (embedThumbnail && container!=='webm').
L39 — CROP_SQUARE_PPA exact-string assertion is a change-detector test (breaks on harmless reformat).
L40 — clipboardLink.test.ts imports the zustand settings store to test two pure helpers (looksLikeUrl/looksLikeSingleVideo) — couples a pure-fn test to store init (see H2).
L41 — package.json homepage points at yt-dlp's GitHub, not AeroFetch — wrong product URL (surfaced by the NSIS installer).
L42 — package.json has no license field (ships LGPL ffmpeg + GPL aria2c).
L43 — package.json has no repository field (real repo is the Gitea instance).
L44 — Vestigial lint excludes. electron-builder.yml excludes .eslintrc/.prettierrc but there's no ESLint/Prettier config, script, or dependency — no enforced style tooling.
L45 — Three self-descriptions drift: pkg description "A yt-dlp frontend for Windows" vs builder copyright "yt-dlp frontend" vs Sidebar caption "yt-dlp frontend".
L46 — yt-dlp-missing error copy differs across 4 modules (download/ytdlp/probe/indexer): "Reinstall AeroFetch, or drop…" vs "Download it into resources/bin/…" vs "Drop it into resources/bin/."
L47 — probeMeta 30s timeout returns null silently — no surfaced message, unlike every other yt-dlp timeout ("Timed out …").
L48 — cleanError strips a leading error: for live failures, while raw ERROR: text shows elsewhere (errorlog seed / terminal) — inconsistent error normalization.
L49 — Newlines in user-facing error strings. download.ts missing-binary messages embed \n, which renders awkwardly in inline/Caption error spans.
L50 — "Cookies saved" shown for 0 cookies. Closing the sign-in window without logging in still writes the file and reports ok with cookieCount: 0.
L51 — Scheduled daily sync time hardcoded to 09:00 (schedule.ts) — on/off toggle only, no time picker.
L52 — Installer handoff is a fixed setTimeout(app.quit, 1500) (updater.ts) — a race on slow machines.
L53 — dialog.show*Dialog(win!, …) non-null assertions on a possibly-null window (chooseFolder, backup export/import) — can throw if the sender window is gone.
L54 — DownloadBar preview <img> has no onError fallback (inconsistent with MediaThumb's retry).
L55 — QueueItem meta line can show size twice — a probed-format quality label already contains the size, then sizeLabel is appended again.
L56 — SponsorBlock ON with zero categories silently no-ops (buildArgs guards on length > 0) with no UI warning.
L57 — Scheduling a past datetime silently downloads now (buildItem future-only guard), no feedback that the schedule was ignored.
L58 — chooseFolder passes the macOS-only createDirectory property — dead option on Windows.
L59 — THEME_BACKGROUND (index.ts) duplicates pageBackground (theme.ts) — two hand-synced color constants (a "keep in sync" comment guards them).
L60 — 'external-url' channel name lacks the category: prefix every other IPC channel uses.
L61 — taskbarProgress is the lone ipcMain.on (fire-and-forget) amid all-invoke channels.
L62 — "Best available" synthetic format hardcodes ext:'mp4'/hasAudio:true (probe.ts) — mislabels when the chosen container is mkv/webm.
L63 — audioQuality() unknown label → silent '0' (best) — the audio analog of H5.
L64 — ARIA2C_ARGS connection params hardcoded (-x16 -s16 -k1M), no user control.
L65 — Pause uses taskkill /F like cancel — a forced kill risks an unflushed .part tail vs a graceful stop.
L66 — Sidebar caption flips "yt-dlp frontend" → "v" once the version loads (text shift on boot).
L67 — Onboarding has no Skip and can't be revisited (no "show tips again").
L68 — Background-running notification fires once per process (notifiedBackground never resets) — won't remind on later window closes.
L69 — settings.ts mixes path helpers with persistence (getDefaultMediaDir/ ensureMediaDirs/getDownloadArchivePath alongside the store) — split a paths.ts. Fixed: the three path helpers moved to paths.ts; settings.ts is now just the electron-store persistence layer (its now-unused path/fs imports dropped). download.ts and index.ts import the helpers from ./paths. applyLaunchAtStartup stays in settings.ts — it's OS login-item integration referenced by applySettings, not a path helper.
L70 — crypto.randomUUID fallback is effectively unreachable in Electron/Node 26 (typeof crypto !== 'undefined' is always true) — dead defensive branch (see M7). Fixed with M7: the branch now lives once in newId (kept so the fn is total in any host) and is covered by a test that stubs crypto to exercise it.
L71 — Settings folder inputs are readOnly with only a Browse button — no way to paste a known path.
L72 — History re-download drops the thumbnail (passes only title/channel), so the re-queued row loses its thumbnail until re-probed.
L73 — Two verbs for the same probe action — DownloadBar "Fetch" vs LibraryView "Index".
L74 — Accent swatches are triple-labeled (aria-pressed + aria-label + title).
L75 — Update-token field always visible in the Software-update card, even when no update is pending — buries an advanced/rarely-needed input.
L76 — Duplicate-warning may show a placeholder title — setDup(existing.title) can be the titleFromUrl placeholder before metadata resolves ('YouTube video (id)').
L77 — ffmpeg/ffprobe versions have no re-check affordance (load once; "not found" sticks with no retry) unlike the yt-dlp "Check version" button.
L78 — DownloadsView empty-state copy ("Paste a URL above to get started") doesn't match the actual two-step Fetch→Download affordance.
L79 — SponsorBlock default categories = ['sponsor'] only — enabling SB silently covers just sponsors until the user expands categories (expectation gap).

Round 4 (2026-06-29) — doc/code drift, build artifacts, edge cases:

L80 — ROADMAP wrong file path. ROADMAP.md Phase A says the flags are emitted "in buildArgs (src/main/download.ts)" — buildArgs lives in src/main/buildArgs.ts.
L81 — ROADMAP internal contradiction. Phase A: "--split-chapters still TODO"; Phase L: [x] split-chapters done. Phase A wasn't updated when L landed.
L82 — PINCHFLAT roadmap interface sketches are stale. ROADMAP-PINCHFLAT.md Phase F's Source/MediaItem code blocks omit shipped fields (videoId, itemCount, watched, feedUrl) — design sketches that drifted from shared/ipc.ts.
L83 — Dead build artifacts. electron-builder emits .blockmap differential-update files for each NSIS installer, but the custom updater.ts does a full download and never consumes them.
L84 — dist/ accumulates unboundedly. ~620 MB per build with no cleanup; it currently holds 0.1.0–0.5.0 Setup + portable artifacts (~3 GB). Add a clean step or prune.
L85 — .claude/launch.json is committed and misplaced. A VS Code launch config lives in .claude/ (VS Code reads .vscode/launch.json), so no tool consumes it; it's also tracked (not gitignored).
L86 — History select-all + filter change deletes hidden rows. selected persists across a filter change, so "Delete selected" can remove entries no longer visible (surprising).
L87 — History re-download ignores original options. redownload re-queues url/kind/quality only; the post-processing DownloadOptions used originally are lost (current defaults apply).
L88 — applyEvent('progress') can promote a queued item to downloading outside pump() — a latent concurrency edge if a progress event ever arrives before/without the launch transition.
L89 — Inconsistent release artifacts. Only 0.4.1 carries .sha256 files (hand-made) and the version sequence skips 0.3.x — symptomatic of the manual release process behind H8.

Round 5 (2026-06-29) — code-level micro-inconsistencies & polish:

L90 — Two idioms for "value in const array." settings.ts sanitizeOptions uses ARR.includes(x as never) (L116–120) while setSettings uses (ARR as readonly string[]).includes(x as string) (L275/323). Pick one.
L91 — Unsafe tuple cast / fragile encoding. value.split('|') as [MediaKind, string] (SettingsView.tsx:411) trusts a '|'-joined kind|quality string; a value without '|' yields undefined quality. Use a typed pair, not a string.
L92 — Preload names diverge from main fn names. markSourceItemDownloaded↔setMediaItemDownloaded, syncSources↔syncWatchedSources. Align the names across the boundary.
L93 — SettingsView bypasses the store layer. It calls window.api directly for cookies/ffmpeg/yt-dlp/app-update/backup while using stores for settings/templates/errorlog — mixed data-access in one component.
L94 — summarizeQueue recomputed every render in DownloadsView.tsx (no useMemo) — and again on every store change in App's taskbar effect. Memoize/share.
L95 — "Sign in" hyphenation varies in the Cookies card ("Sign in…", "Site to sign in to", "Sign-in window", "Signing in…").
L96 — Ellipsis-on-dialog-buttons inconsistent. "Export backup…/Import backup…/Sign in…" use … (opens a dialog), but "Browse" / "Check for updates" / "Update now" don't. Adopt the … = opens-a-dialog convention.
L97 — Advanced-field placeholders inconsistent. Adjacent fields use an example (web_safari), a literal (none), and Optional — Gitea access token. Pick one placeholder style.
L98 — "Embed chapters" has no hint while every sibling toggle in DownloadOptionsForm does.
L99 — URL input has an id but no label. input={{ id: 'aerofetch-url' }} with no <label for>/aria-label (placeholder only) — see M28.
L100 — Inconsistent elevation. DownloadBar (shadow4) and CommandPalette (shadow28) float; every other card (Settings, QueueItem, History, Library, Templates) is flat (border-only). Define an elevation scale.
L101 — No z-index scale. CommandPalette and Hint both hardcode zIndex: 1000.
L102 — Two mental models for "format." Settings sets it via one combined Video/Audio dropdown (FORMAT_OPTIONS); the DownloadBar uses a Video/Audio segmented control + a separate quality dropdown.
L103 — Two busy-indicator patterns. Fetch/Index swap the button icon to a Spinner; the Settings check/update buttons keep their icon and render a separate adjacent Spinner.
L104 — History isn't virtualized. It renders all filtered rows, while Downloads and Library use VirtualList.
L105 — MediaKind declared twice. In both ipc.ts and store/downloads.ts; components import it from both. Single source it. Fixed: the store now imports MediaKind from @shared/ipc and re-exports it, so the duplicate local type MediaKind is gone while existing import { MediaKind } from '../store/downloads' sites still resolve.
L106 — Refresh icons used interchangeably. ArrowClockwiseRegular (retry, re-download, check-for-new, update-yt-dlp) vs ArrowSyncRegular (re-index, check-for-updates) for the same "redo/refresh" idea.
L107 — Spinner sizes mixed — "tiny" almost everywhere, "extra-tiny" for the QueueItem queued row.
L108 — Main window sets no explicit title (relies on the document <title>).
L109 — Versions auto-load with no indicator. yt-dlp/ffmpeg versions in About just appear; only the manual "Check" button shows a spinner.
L110 — One muted-text token, many class aliases. colorNeutralForeground3 is re-declared as hint/sub/meta/srcSub/stats/count/emptyHint/previewMeta across components.
L111 — Two helper-text mechanisms — Fluent Field hint vs manual <Caption1 className={hint}>; SettingsView uses both.
L112 — Switch labeling inconsistent. Settings/DownloadOptionsForm show "On"/"Off" text; Library switches use aria-label only (no visible state text).
L113 — Tooltip ≠ aria-label. The Fetch button's Hint says "Fetch formats / playlist" but its aria-label says "Fetch formats or playlist" (DownloadBar).
L114 — Row titles use different components — Text (QueueItem/History/Templates) vs span (Library) vs Caption1 elsewhere.
L115 — Equivalent row actions labeled inconsistently — "Re-index" is icon+text; the comparable "Retry"/"Remove"/"Re-download" are icon-only.
L116 — Empty-state structure varies — Downloads (icon + line), History (colored badge + line + sub-hint), Library (icon + line, no sub-hint).
L117 — Terminal/error-log "empty" aren't centered blocks like the other empty states (inline text instead).
L118 — Cross-component focus via hardcoded id. App focuses the URL field with document.getElementById('aerofetch-url') — brittle coupling into DownloadBar's markup.
L119 — "No items" copy varies — "No … yet" (most) vs "Output will appear here." (Terminal) vs "No errors logged." (Diagnostics).
L120 — Fluent Card vs hand-styled div cards. Only Settings/Onboarding use <Card>; every other card surface is a bespoke styled <div>.
L121 — Raw scrim literal. CommandPalette backdrop is rgba(0,0,0,0.32) (the only raw rgba in the renderer), identical in light/dark — low contrast over a dark UI.
L122 — "Checking…" indicated twice — the Settings update button changes its label to "Checking…" and a separate Spinner renders beside it.
L123 — Caption1 is overloaded for hints, metadata, counts, and timestamps — one size doing four jobs.
L124 — Body1 vs Text role overlap — Body1 appears only in empty states/onboarding/gate; Text carries titles; the split isn't principled.
L125 — Icon sizing has two syntaxes — px strings (fontSize: '20px') on icon containers vs numeric fontSize={28} on inline icons.
L126 — Uneven text truncation — some titles/metas use nowrap+ellipsis, others wrap; no shared truncation utility.
L127 — Notification sets no icon — completion toasts used the default Electron icon though getAppIconPath() existed. Fixed with W13 (cached getAppIconImage() passed as icon at both notification sites).
L128 — Preview seed/mock data ships in production. The PREVIEW runtime check can't be tree-shaken, so each store's seed arrays + fake ticker are bundled into the Electron renderer.
L129 — Hint align is silently ignored for left/right placements yet callers still pass it.
L130 — Error-string style is mixed — internal errors are lowercase/no-period ("timed out", "interrupted"); user-facing ones are capitalized with periods. Fine when interpolated, jarring if shown raw.
L131 — Taskbar error state is ephemeral — it's driven by live error items, so "Clear finished" flips the red taskbar bar back to normal even though failures occurred (out of sync with the persisted error log).
L132 — clearProbe + form-reset logic is duplicated in DownloadBar (onUrlChange, download, addPlaylist).
L133 — Field controls mix aria-label + visible label. Many Field label="X" wrap a Select aria-label="X", so AT announces the name twice (extends M20 across DownloadOptionsForm).
L134 — Inconsistent disabled affordance for busy buttons. Some stay enabled-looking with a spinner icon (Fetch/Index) while others are disabled with adjacent text (Settings) — no single "busy" convention.
L135 — Textarea vs Input for similar fields. Trim uses a Textarea; the visually-similar single-line fields use Input — fine, but the trim/schedule panels and the template form mix both with no shared field style.

Round 6 (2026-06-29) — behavioral/logic edge cases:

L136 — Incognito leaks outside history. Even if the (unreachable, M6) private flag were set, download.ts still writes failures to errorlog.json (title + URL) and shows the title in completion notifications — the "private" promise covers only history.
L137 — Stuck 0% for unknown-size downloads. parseProgress returns progress: 0 when total_bytes/_estimate are absent (livestreams, some sites), so the bar reads 0% the whole time instead of an indeterminate state. Fixed: parseProgress now sets sizeUnknown: !totalBytes on DownloadProgress; the store threads it onto the item and QueueItem renders an indeterminate bar + "Downloading…" (instead of a frozen 0%) when it's set, reusing the existing SR7 indeterminate path.
L138 — Clipboard read on every window focus. useClipboardLink.ts reads the full clipboard on each focus (and once on mount, possibly before clipboardWatch has loaded — FALLBACK is true). Reading all clipboard text whenever focused may surprise privacy-conscious users.
L139 — Auto-update vs concurrent spawn race. runStartupYtdlpAutoUpdate can overwrite yt-dlp.exe on launch while a deep-link/queued download spawns the same binary — a Windows file-in-use/corrupt-spawn window.
L140 — Retry-during-teardown race. retry reuses the same id; if the previous process's close handler hasn't removed it from active yet, startDownload returns "already running" → markError. Fixed in download.ts: cancelDownload/pauseDownload now drop the item from active synchronously (so a retry/resume's same-id spawn is never rejected by the stale entry), and the doomed child's close/error/watchdog release the slot through a new releaseActive(id, rec) that only deletes when that rec still owns the id — so a late teardown can't evict the fresh spawn. The transient cookie jar is now keyed per spawn (-${spawnSeq}) so the old download's cleanup can't unlink the new one's file. (with L148)
L141 — Renderer history grows unbounded in memory. useHistory.add prepends without a cap while main caps history.json at 500; in a long session the in-memory list exceeds the persisted cap (resets on reload). Fixed in store/history.ts: add now .slice(0, MAX_ENTRIES) (500, the same cap as main's history.ts) and de-dupes by url as well as id, so the optimistic in-memory list matches what a reload would show (also aligns with main's M35 url de-dup).
L142 — IPC mutation return values are discarded everywhere. history/templates/sources/settings IPC calls return the authoritative (validated/capped/sanitized) state, but every renderer caller does optimistic-only updates and ignores it — client and persisted state can silently diverge until reload (generalizes M34).
L143 — No in-window "quit anyway." With a download active (or tray mode), closing only hides; quitting requires the tray menu. If the tray ever fails to create, the only exit is Task Manager (mitigated today by the embedded fallback tray icon).
L144 — Duplicate guard checks the queue only, not history. Re-adding a URL downloaded earlier (already cleared from the queue) gives no "already downloaded" hint (roadmap notes this as a possible extension).
L145 — useClipboardLink re-offers a dismissed link after a tab switch. lastSeen is per-hook-instance; switching Downloads↔Library remounts it, so a previously-dismissed clipboard link is offered again.
L146 — parseTrimSections accepts malformed multi-colon times. The \d+(?::\d{1,2})* pattern passes tokens like 1:2:3:4-5:6:7:8, which then reach yt-dlp's --download-sections and fail there rather than being rejected up front.
L147 — macOS branches in a Windows-only app. app.on('activate') and the process.platform !== 'darwin' guard in window-all-closed are dead on Windows — boilerplate that implies multi-platform support the app doesn't ship.
L148 — clearFinished/remove can free a slot before the killed process exits. Removing a just-canceled item lets pump() launch into the "freed" slot while taskkill is still tearing down the prior tree — a brief window over the concurrency cap. Fixed with L140: cancelDownload/pauseDownload release the active slot the instant they issue the kill (rather than on the async close), so main's concurrency accounting matches the renderer immediately — the just-promoted next item is neither falsely rejected by the maxConcurrent guard nor run over the cap while the prior tree dies.

Round 7 (2026-06-29) — copy, a11y patterns & micro-behavior:

L149 — Hint length wildly inconsistent. Most field hints are one short line, but "Keep running in the tray" is a three-sentence paragraph with a parenthetical. Normalize hint length/voice.
L150 — "PO token" capitalization varies — PO Token (ipc.ts/ROADMAP) vs PO token / Proof-of-Origin token (SettingsView). Pick one.
L151 — Mixed range dashes. En-dash in prose ("2–3 is a good balance") vs hyphen in time-range placeholders ("1:30-2:00"). Choose one convention.
L152 — Search-field sizing differs per screen. History minWidth 180 / maxWidth 320, Settings inline width: 100%, DownloadBar flexGrow. No shared search-input width.
L153 — Generic "Dismiss" aria-labels. Three close buttons (DownloadBar suggestion + dup, Library suggestion) all read just "Dismiss" — ambiguous to a screen reader. Name what's dismissed.
L154 — Instructional text in an aria-label. Sidebar theme-cycle button is aria-label="Theme: Dark. Click to change." — "Click to change" is UI instruction, not a name.
L155 — Accent swatches aren't a radiogroup. They're a single-select set rendered as plain buttons with aria-pressed, while the Theme controls (also single-select) use role="radiogroup"/radio. Inconsistent single-select a11y pattern.
L156 — datetime-local schedule has no min. Past times are selectable, then silently download now (extends L57). Add min={now}.
L157 — removeSource doesn't cancel in-flight downloads. Removing a source while its videos are downloading lets them finish into the removed source's folders; markDownloaded then no-ops on the gone item.
L158 — Drag highlight flickers. onDragLeave={() => setDragActive(false)} fires when the cursor crosses child elements (no enter/leave depth counter), so the dashed-outline blinks during a drag.
L159 — Dead fallback branch. copyErrorReport falls back to "No errors logged." but its button is disabled when there are no entries, so the fallback is unreachable.
L160 — One-off inline margins. marginTop literals (Onboarding 2px, QueueItem 4px, SettingsView 8px) instead of style classes (extends L5).
L161 — height: 100% screens inside a padded scroll container. Downloads/Terminal set height: 100% while App's <main> is overflowY: auto + 24/28px padding — a fragile coupling that can double-scroll or misalign the virtualized list's viewport.
L162 — Per-thumbnail store subscription. Every MediaThumb calls useResolvedDark() (two store subscriptions) instead of receiving a resolved theme prop — N subscriptions per list.
L163 — QueueItem makes 9 separate useDownloads selector calls instead of one destructured selection — repeated boilerplate per row.

Round 8 (2026-06-29) — formatting micro-inconsistencies:

L164 — Metadata separator glyph/spacing is inconsistent. Meta lines join with ' • ' (2-space bullet) in QueueItem/History/DownloadBar/DownloadsView, with ' · ' (1-space midd·dot) in LibraryView, and with ' • ' (1-space bullet) in QueueItem's "Paused • 42%". Three styles for one role. Standard: one separator constant (glyph + spacing).
L165 — The two byte/speed formatters round differently. download.ts fmtBytes uses toFixed(v >= 100 ? 0 : 1) ("512 MB") while queueStats formatSpeed uses toFixed(1) ("512.0 MB/s") — visibly different precision for the same magnitudes (compounds the duplicate-formatter issue H2/M9).
L166 — ETA has no hour rollover. fmtEta (download.ts/downloads.ts) and formatEta (queueStats) emit M:SS only, so a 2-hour ETA renders as "120:00", whereas fmtDuration (indexerCore) correctly rolls to H:MM:SS. Unify on the hour-aware format.
L167 — PROGRESS_TEMPLATE is exported but used only inside buildArgs.ts — a superfluous public export (download.ts parses the prog| lines independently). Make it module-private.

Round 9 (2026-06-29) — type-safety & build config:

L168 — noUncheckedIndexedAccess is off. Array/index/tuple access is typed as always-defined, so the exact edge cases already filed compile clean: the split('|') as [MediaKind, string] cast (L91/CL2) and parseProgress's positional destructure of a possibly-short split('|'). Enabling it would surface them at build time.
L169 — noFallthroughCasesInSwitch is off. The large setSettings switch and applyEvent switch aren't fallthrough-guarded; a missing break/return wouldn't be caught.
L170 — No source maps in production. sourceMap: false (toolkit) and no build.sourcemap in electron.vite.config.ts, so field crash stack traces are unmapped — combined with no logging (CC8/M29), diagnosing a user-reported crash is very hard. Consider hidden/external source maps.
L171 — main.tsx mock drift. The preview mock's version strings disagree (getAppVersion→'0.4.0-preview' vs checkForAppUpdate.currentVersion→'0.4.0'), and its setSettings skips the real validation/sanitization — so the browser preview can accept settings the app rejects, masking M34-class issues during design.
L172 — skipLibCheck: true (toolkit) hides type errors in dependency .d.ts files — standard practice, low risk, noted for awareness (a dep type regression won't fail typecheck).

UI consistency

Cross-screen review (Downloads, Library, History, Terminal, Settings, Onboarding, Command palette, Sidebar, cookie sign-in window). Each item: what's inconsistent → Standard: the single rule to adopt. Items prefixed UI; where a dimension was already filed, the existing ID is referenced instead of re-filing. The app uses Fluent tokens well (theme-awareness is mostly solid); the gaps are an undefined spacing/radius/type scale and a drift between Fluent components and hand-rolled ones.

Layout, spacing & width

UI1 — No shared content width. SettingsView is maxWidth: 640px (SettingsView.tsx), but Downloads/Library/History/Terminal are full-width; Onboarding card is 460px, CommandPalette 560px. On a wide window Settings is a narrow column while siblings stretch edge-to-edge. Standard: one reading-width token (e.g. 720px) applied by a shared Screen wrapper, or commit to full-width everywhere.
UI2 — Per-screen vertical rhythm differs. Root section gap is 16 (Settings/Terminal), 20 (Downloads), 18 (Library), 12 (History). Standard: a single section-gap (16px) via a shared screen wrapper.
UI3 — Card padding has no scale. 14 (QueueItem) / 16 (DownloadBar) / 20 (Settings card) / 32 (Onboarding) / 10px 12px (History row) / 12px 14px (Library head) / 8px 10px (template row). Standard: a padding scale (e.g. control 8–10, list-row 12, card 16, hero 24) keyed to surface tier.
UI4 — Asymmetric app content padding. padding: '24px 28px' (App.tsx) — 28px horizontal appears nowhere else. Standard: symmetric or scale-based padding.
UI5 — Action-cluster gaps split 4px vs 8px. Icon-button rows use 4px (QueueItem/History/ TemplateManager) but DownloadBar/Library action rows use 8px. Standard: 4px for icon-button groups, 8px for labelled-control rows. (Good baseline already: every empty-state uses 56px 16px — keep it.)

Corner radius

UI6 — Thumbnail radius varies for the same element. QueueItem Large, History Medium, Library rowThumb Small, DownloadBar previewThumb Medium. Standard: one thumbnail radius (Medium/10px). (Distinct from L9, which is thumbnail pixel dimensions.)
UI7 — Card radius (XLarge vs Large) has no stated rule. Top-level cards use XLarge (16), list rows Large (12), but it's applied by feel. Standard: document surface tiers — page-card XLarge, list-item Large, control Medium — and apply uniformly.
UI8 — Circular shapes mix token and literal. borderRadiusCircular (Library pill/watchBadge) vs literal '50%' (SettingsView swatch, History emptyBadge). Standard: always the token.

Typography

UI9 — Screen titles are inconsistent. Most screens use <Subtitle2> (Downloads "Queue", Library, Terminal, Settings cards); Onboarding uses <Title2>; History has no title at all (just a count). Standard: one page-title style on every screen.
UI10 — Only Library has a screen subtitle/description. Others jump straight to content. Standard: a consistent header block (title + optional one-line description).
UI11 — Semantic type ramp vs ad-hoc px. Sidebar brandName/navItem and Library watchBadge/pill set raw fontSizeBaseXXX; sectionIcon/mark use literal '20px'/'26px'. Standard: Fluent type components/tokens; no literal px font sizes.

Icons

UI12 — No icon-size scale. Inline fontSize of 11/14/16/18/20/22/26/28/40 is scattered across components. Standard: a small set (16 inline / 20 control / 24 section / 40 empty-state).
UI13 — Regular vs Filled weight mixed for one concept. ArrowDownloadRegular (nav, buttons) vs ArrowDownloadFilled (brand mark). Standard: one weight per concept (Filled only for brand/emphasis).

Buttons & controls

UI14 — Two hand-rolled segmented controls. DownloadBar kind toggle (segment, padding 7px 16px) and Sidebar theme toggle (themeSeg, padding 7px 4px) are separate implementations with different padding/markup. Standard: one shared SegmentedControl.
UI15 — Raw <button>s alongside Fluent <Button>. Sidebar navItem/iconBtn/themeSeg, DownloadBar segment/plKindBtn, CommandPalette item, and Library groupHead (a role="button" div) are bespoke. Standard: wrap recurring patterns so hover/focus/disabled are uniform (ties to L5/M15).
UI16 — Button size hierarchy isn't applied uniformly. DownloadBar large; Library "Index" large but its toolbar small; History all small; Settings mostly default. Standard: size-by-role (screen primary = large; secondary = medium; row actions = small).
UI17 — appearance="secondary" used in only two spots (Library "Check for new", Terminal "Stop") while every other non-primary button is subtle. Standard: pick subtle or secondary as the standard non-primary appearance.
UI18 — Two status-chip systems. QueueItem uses Fluent Badge; LibraryView uses custom color pill spans for the same item-status concept (and labels differ — see M8). Standard: one shared status-chip component + label map.
UI19 — Suggestion-banner CSS duplicated. Identical suggestion/suggestionText styles in DownloadBar and LibraryView. Standard: a shared LinkSuggestion component (also kills drift).

Colors & selection

UI20 — "Selected/active" styling is split. Solid brand (colorBrandBackground + on-brand text) for DownloadBar/Sidebar segments, but brand-tint (colorBrandBackground2 + colorBrandForeground2) for Sidebar nav, CommandPalette item, Library pill. Standard: one active treatment per control class.
UI21 — Sidebar active-nav rail is expanded-only. The inset brand box-shadow shows only when expanded; collapsed relies on tint alone. Standard: a consistent active indicator in both states.
UI22 — Brand-icon tiles differ. mark (on-brand on solid brand) vs srcIcon (brandForeground2 on brand-tint) vs sectionIcon (compoundBrand, no tile). Standard: a defined icon-emphasis set.

UI23 — Fragmented overlay/dialog system. Native OS dialogs (pickers, backup save/open, backup warning messageBox), one custom React overlay (CommandPalette), a full-screen view (Onboarding), and an unstyled separate BrowserWindow (cookie sign-in) that shows none of the app's theme/chrome. Standard: keep native for file/confirm; unify in-app overlays under one themed primitive; theme the sign-in window's title/background to match.
UI24 — No context menus anywhere. Every row exposes actions only as inline buttons; right-click does nothing on any screen, despite many per-row actions that conventionally also live on right-click. Standard: add consistent right-click menus mirroring row actions, or note "none by design."
UI25 — No in-app global status surface. Queue progress shows only on the Downloads tab's summary strip; on any other tab there's no in-app sign downloads are running (only the OS taskbar). Standard: a persistent affordance (e.g. a sidebar "Downloads" badge with the active count).

Animations & transitions

UI26 — Lone animation. Only the sidebar width transitions (0.15s ease); tab switches, panel expand/collapse, banners, and Library card expansion are all instant. Standard: one motion policy — either add subtle, consistent transitions (gated on prefers-reduced-motion) or drop the sidebar one.

Hover, focus, disabled, keyboard & accessibility

UI27 — Command palette uses JS hover, not CSS. Items highlight via onMouseEnter setting itemActive (no :hover), unlike every other list, and expose no aria-selected/active-descendant, so the highlight is invisible to screen readers. Standard: CSS :hover + listbox/option semantics.
UI28 — Command palette input has no focus ring. The search <input> sets outline: 'none' with no replacement. Standard: a visible focus ring (Fluent stroke token). (a11y)
UI29 — Fragmented focus treatment. Fluent ring (Fluent controls) vs custom border (Select) vs removed (palette input) vs UA default (Sidebar buttons, segments, and Library cardHead/groupHead which are role="button" tabIndex=0 with no :focus-visible → invisible keyboard focus). Standard: one focus-ring style on all interactive elements, custom and native. (a11y; extends L14)
UI30 — Hand-rolled radiogroups aren't arrow-navigable. DownloadBar kind and Sidebar theme use role="radiogroup"/radio but implement click only — no ←/→ roving focus a radiogroup implies. Standard: roving-tabindex arrow keys, or Fluent's RadioGroup. (a11y)
UI31 — Select can't be disabled. The native-<select> wrapper exposes no disabled prop, so that control can't show a disabled state while Fluent controls can. Standard: add disabled + styling.
UI32 — Native-control dark mode is uneven. The DownloadBar datetime-local sets colorScheme: 'light dark' explicitly; the Select relies on the root colorScheme. Standard: set colorScheme consistently on both.
UI33 — No semantic headings. Titles render as Subtitle2/Title2 (styled spans), so there's no h1–h6 hierarchy for screen-reader heading navigation (landmarks <nav>/<main> exist; headings don't). Standard: render titles as real headings (as="h1"/"h2" or role="heading" aria-level). (a11y)

Top cohesion-breakers (the "not one product" shortlist)

Status chips — Fluent Badge (Downloads) vs custom color pills (Library) for the same concept (UI18, M8).
Segmented controls — two separate hand-rolled versions (UI14).
Buttons — Fluent <Button> vs many bespoke <button>s with divergent hover/focus (UI15, UI29).
Content width — Settings is a 640px column; every other screen is full-width (UI1).
Focus rings — four different focus treatments incl. one removed and several invisible (UI28–UI29).
Screen headers — Subtitle2 / Title2 / none (UI9–UI10).

UX review (first-run perspective)

Walking the app as a new user. Ranked by severity. UX IDs; existing IDs referenced where the root cause is already filed.

High — core-flow friction

UX1 — Per-download options are unreachable; you must change global Settings for one video. The DownloadBar exposes only URL · Video/Audio · quality · Trim · Schedule. There is no per-download post-processing panel, custom-command panel, command preview, or incognito toggle — so DownloadItem.options/extraArgs and the whole Phase A/C per-download-override plumbing are unreachable; every download uses settings.downloadOptions. To grab one video as MP3-with-subs a user must edit global Settings, download, then revert. (Supersedes/expands M5, M6.) Fix: add a collapsible per-download Options panel (reuse DownloadOptionsForm) — the plumbing already exists. Fixed: a collapsible "Advanced" panel in DownloadBar.tsx reuses DownloadOptionsForm for per-download overrides (audio format, container, codec, format-sort, subtitles, SponsorBlock), passed via AddOptions.options → startDownload. The panel also carries the M6 incognito checkbox and sits beside the M5 command preview. Overrides are one-shot: they reset to the global defaults after each download (matching Trim/Schedule).
UX2 — "Fetch" vs "Download" is ambiguous, and Enter does the wrong thing. Two unlabeled icon buttons (magnifier = "Fetch", clipboard = "Paste") sit next to "Download"; a first-timer can't tell that Download works without Fetch. Pressing Enter in the URL field runs a probe, not the download (L27) — violating "type URL + Enter = go". Fix: label the action, make Enter download (or fetch-then-download), and present Fetch as optional ("Preview formats"). Fixed in DownloadBar.tsx: Enter is now "go" — it starts the download (or adds the fetched playlist when the playlist panel is open) instead of probing; probing stays an explicit, optional click. The magnifier button is relabeled from "Check URL" to "Preview available formats (optional)" (both its tooltip and aria-label), and the URL placeholder now reads "Paste a video or playlist URL, then press Enter to download" so it's clear Download works without Fetch. download() already enqueues with the presets when nothing has been probed, so the Enter-downloads path needs no probe. (resolves L27's Enter inconsistency too.)
UX3 — Library "Index" is jargon and a hidden two-stage workflow. Pasting a channel URL in the Downloads bar tries to treat it as one item; whole channels belong in the Library tab, but nothing signposts that. "Index" reads like "Download" but only catalogs — you must then expand, select, and Download. Fix: rename to "Add channel/playlist," and after indexing surface a clear "Download N videos" next step; detect channel URLs in the Downloads bar and suggest the Library. Fixed across three seams. (1) De-jargoned the Library (LibraryView.tsx): the primary button is now "Add" (was "Index"), "Re-index" → "Refresh", and the header description / empty state / placeholder / error copy drop "index" for "add". The post-add next step already exists — indexSource auto-selects the new source so its card expands with a prominent "Download N pending" primary button. (2) Channel detection in the Downloads bar — a new pure looksLikeChannelOrPlaylist (conservative: only clear YouTube channel/dedicated-playlist shapes; a /watch video, even with a list=, is never flagged and keeps working in the bar) drives a dismissible brand-tinted nudge in DownloadBar.tsx: "This looks like a channel or playlist. Add it in the Library…" with an Open in Library action. (3) The handoff goes through a small new store/nav.ts (App's tab state moved into it) that carries a one-shot pendingLibraryUrl; the Library consumes it on mount to pre-fill its add field. Unit-tested (looksLikeChannelOrPlaylist in test/clipboardLink.test.ts) and verified end-to-end in the browser preview (channel URL → nudge → Open in Library → Library tab with the URL pre-filled).
UX4 — Destructive actions have no confirmation and no undo (L13). "Clear history," "Clear log," "Remove source" (deletes an entire indexed channel + items), and "Delete selected" are all one click. A user exploring can wipe data irreversibly. Fix: confirm destructive/bulk deletes (or offer an undo toast).
UX5 — First run can't choose the download folder. Onboarding.tsx only describes Documents\Video/Audio — there's no picker (the ROADMAP claims one). The user must later discover Settings → Downloads. Fix: put the folder picker in onboarding as documented. Fixed: the "Where downloads go" block in Onboarding.tsx now has interactive Video and Audio rows — each shows the current folder (or the Documents\Video / Documents\Audio default) with a Choose… button that opens the OS picker via the settings store's chooseDir (the same proven path DownloadsCard uses, seeded at the current value — W5). Picking a folder persists immediately, so the choice is already saved when the user clicks "Get started"; leaving it untouched keeps the Documents defaults. Verified in the browser preview with onboarding forced on.

Medium — confusion, feedback & organization

UX6 — Silent failures on file actions. openFile/showInFolder in the stores call window.api.openPath(...) and ignore the returned error string; reveal.ts refuses missing/moved files or disallowed types and returns an error nobody surfaces. Clicking "Open file" on a moved download does nothing, with no message. Fix: surface open/reveal errors.
UX7 — Settings is one long unsegmented scroll of ~11 cards with no section nav/anchors; the only finder is the hide-cards search (M14). Order is arbitrary and related items are split. Fix: group into sub-sections (or a left rail) with a stable, logical order.
UX8 — "Default format" vs "Format & post-processing" are two places for one concept. Kind + quality live under Downloads; container/codec/subs/SponsorBlock live in a separate card. Fix: co-locate, or clearly label one "defaults" and the other "advanced post-processing."
UX9 — No global completion feedback off the Downloads tab (UI25). If OS notifications are off/suppressed (focus assist) and you're on another tab, a finished download gives no in-app sign. Fix: a sidebar Downloads badge / lightweight in-app toast.
UX10 — Re-download silently changes quality (H5) — a confusing "I asked for 720p, got Best."
UX11 — Scheduled downloads silently never fire if the app is quit (M4). The hint is easy to miss; the user returns to find nothing happened. Fix: warn at schedule time that it requires the app running (or persist + relaunch).
UX12 — Terminal is a dead-end when custom commands are off (L18). The nav item is always visible; clicking it shows a gate pointing to a setting on another screen. Fix: hide/disable the nav item, or let the gate enable the setting inline.
UX13 — Backup export warns of nothing; it contains secrets (M22). A user "backs up settings" and ships proxy creds / tokens in cleartext. Fix: warn, or mask/omit secrets.
UX14 — Duplicate warning can show a placeholder title (L76): 'Already in your queue: "YouTube video (abc123)"' before metadata resolves looks broken. Fix: fall back to the URL.
UX15 — No bulk actions in the Downloads queue. History has a select-mode + bulk delete; Downloads has only per-row remove + "Clear finished." Inconsistent. Fix: mirror select/bulk, or add "Cancel all."

Low — polish & smaller friction

UX16 — URL field isn't focused on launch. aerofetch-url is only focused via the command palette; opening the app or the Downloads tab requires a click to start typing. Fix: autofocus it.
UX17 — Icon-only Fetch/Paste buttons rely on hover tooltips for meaning (UI a11y; new users on touch/keyboard miss them). Fix: labels or aria-described affordances.
UX18 — The quality control morphs after Fetch (preset list → real formats; label "Quality" → "Quality / format") in place — a surprising transform. Fix: keep a stable control with a clear "formats loaded" state.
UX19 — Window size/position isn't remembered. index.ts opens a fixed 920×700 every launch (no bounds persistence). Fix: persist + restore window bounds.
UX20 — "App is still running" surprise. Closing with a download active hides to tray and notifies once per process (L68); later closes give no hint, so the window "won't close" reads as a bug. Fix: a persistent tray hint / first-close explainer.
UX21 — No keyboard-shortcut discoverability. Ctrl+K (palette), Enter, Ctrl+Enter are undocumented; there's no "?"/shortcuts screen. Fix: a shortcuts hint or help affordance.
UX22 — Onboarding is shallow and one-shot (L67): three tips, no folder choice, not revisitable; the clipboard tip requires a focus event a first-timer won't trigger.
UX23 — Settings folder paths are read-only (L71) — no paste; Browse-dialog only.
UX24 — "Check N watched for new" is disabled with no explanation when no source is watched — a user with indexed (but unwatched) sources sees a dead button. Fix: tooltip / enable with a hint to watch a source.
UX25 — Empty-state copy mismatches the flow (L78): Downloads says "Paste a URL above to get started," but the actual path is Fetch/Download.
UX26 — yt-dlp/ffmpeg version + initial settings load have no skeleton/spinner — brief blank states on boot (plus the documented one-frame theme flash). Fix: lightweight loading states.

Windows platform conventions

Review against Windows 11 / Fluent desktop conventions. W IDs are new; existing IDs are referenced where a dimension is already filed. The app gets the big things right (native dialogs, per-user no-admin install, AppUserModelID, tray, taskbar progress, jump list, nativeTheme dark-mode follow, DPI handled by Chromium). The deviations:

Window behavior & resizing

W1 — No minimum window size. createWindow sets width/height but no minWidth/minHeight (index.ts), so the window can be dragged down to a few pixels and the layout (212px sidebar + content) breaks. Standard: set a sensible min (e.g. 640×480).
W2 — Window placement isn't persisted (extends UX19): size, position, maximized state, and which monitor are all forgotten — it reopens 920×700 on the primary display every launch. Standard: persist & restore window placement per Windows app convention (e.g. electron-window-state).
W3 — Title bar doesn't follow the in-app theme. nativeTheme.themeSource is deliberately never set (index.ts:97), so the OS-drawn caption follows the OS theme. Choosing an explicit in-app dark theme on a light OS leaves a light title bar on a dark app (and vice-versa). Standard: set nativeTheme.themeSource to the resolved mode, or use titleBarOverlay with themed colors.

Dialogs & file pickers

W4 — Text fields have no Cut/Copy/Paste context menu. Electron adds no default editing menu and the app registers no context-menu handler, so right-clicking any input/textarea (URL, search, terminal args, template fields) shows nothing — a basic Windows text-editing affordance is missing. Standard: wire a standard editing context menu (and spellcheck suggestions for textareas).
W5 — File pickers don't open at the current value. chooseFolder sets no defaultPath, so the folder dialog opens at a default location instead of the currently-configured Video/Audio folder. Standard: seed the picker with the current path. (Native dialogs themselves are correct — good.)
W6 — Cookie sign-in is a separate taskbar window. openCookieLoginWindow creates a BrowserWindow with no parent/modal (cookies.ts), so it appears as a second AeroFetch taskbar button rather than a child/modal dialog. Standard: parent: mainWindow (+ modal if appropriate) so it groups under the app.

Keyboard, context menus & focus

W7 — Lists have no keyboard navigation. The queue, history, and library lists can't be arrowed through, Delete doesn't remove the focused/selected item, and there's no Ctrl+A select-all — all standard Windows list behaviors. Standard: roving focus + Delete/Ctrl+A on list surfaces. (a11y; see also UI30)
W8 — No standard accelerators. No Ctrl+, (Settings), F1 (help), or F5 (refresh); Ctrl+K (palette) is the only global shortcut and is undiscoverable (UX21). Standard: add the conventional accelerators + a discoverable shortcut list.
W9 — Focus isn't restored or advanced. Closing the command palette doesn't return focus to the trigger; finishing onboarding and switching tabs don't move focus into the new content. Standard: restore focus on overlay close; move focus to the activated panel. (extends UI28–UI29)
(ref) Context menus absent app-wide — UI24; the text-field case is W4.

System tray, taskbar & icons

W10 — No taskbar attention flash. When a background download completes while the window is minimized/hidden, the app doesn't flashFrame the taskbar button. Standard: flash for attention on background completion (pairs with the existing notification).
W11 — No taskbar overlay badge (deferred in roadmap): a download manager conventionally shows an active-count / error overlay icon via setOverlayIcon. Standard: add it (the progress bar's error mode is not a substitute).
W12 — Fallback tray icon is single-resolution. The embedded fallback is a 32×32 PNG, so on 150%/200% DPI the tray glyph is blurry when the real multi-size .ico is absent. Standard: a multi-size fallback (or rely only on the .ico).
W13 — Notifications set no icon. new Notification({title, body}) omitted icon; on the portable build (no installed AUMID shortcut) Windows toasts showed a generic icon. Fixed: both notification sites (download.ts completion/failure toast + index.ts background-running toast) now pass icon: getAppIconImage() — a new cached NativeImage helper in binaries.ts that loads the app .ico once and falls back to an empty image (OS default) if it's missing. (refines L127)
W14 — App/notification icon is a placeholder (M3-orig) — Fixed: redesigned icon.svg into a proper mark (teal brand square with a top-lit gradient + soft sheen and a bold rounded download glyph over a landing shelf), legible down to 16px; regenerated the multi-size build/icon.ico (256/128/64/48/32/16) via ImageMagick. The notification-icon wiring (passing the asset to new Notification) is also done — see W13/L127.

High DPI, multiple monitors, touch

W15 — Software rendering is global. Hardware acceleration is disabled for a documented GPU workaround; on high-DPI/large windows this trades GPU compositing for CPU, which can be sluggish. Standard: re-enable HW accel where the target GPU allows (the memo already flags revisiting this).
W16 — Touch targets too small / hover-only labels. Icon-only row actions are ~32px, 4px apart, 4 per row (below the ~40px touch guideline), and their only labels are hover tooltips (Hint) that never appear on touch. Standard: ≥40px touch targets and non-hover labels. (extends UX17)

Dark mode & accessibility (Windows-specific)

W17 — No aria-live for status changes. Narrator doesn't announce download progress, completion, or errors — there are no live regions. Standard: polite live regions for queue/status updates.
W18 — Custom colors unverified under High Contrast. The status pills, segmented controls, accent swatches, and thumbnail tints use explicit background colors that Windows forced-colors mode may not adapt (nothing sets forced-color-adjust). Standard: test under each Contrast theme; let system colors win.
(ref) No semantic headings / radiogroup arrow-nav / focus rings — UI33, UI30, UI28–29 (all bear on Narrator + keyboard users).

Settings & standard conventions (mostly OK)

W19 — Window/taskbar don't reflect state. No window title at all (L108), so the taskbar button never shows "3 downloading" or similar. Standard: reflect activity in the title/tooltip.
(OK) Per-user no-admin install, NSIS uninstaller, aerofetch:// registration, AppUserModelID, tray tooltip + left-click restore + right-click menu, taskbar progress, and jump list all follow Windows conventions. (Non-goal) unsigned binary → SmartScreen prompt — accepted; no certificate will be purchased (the build stays signing-ready via env vars if that ever changes — see SIGNING.md).

Code consistency & conventions

A cross-cutting consistency pass over the dimensions requested. Many specifics are already filed; this section consolidates them by theme and — the point of the exercise — recommends one standard each. CC IDs are the consolidated items; existing IDs are referenced, not re-filed. The codebase is actually stylistically consistent (no-semicolon, single-quote, 2-space) and has a genuinely good pure/impure split — but that style is unenforced and several "do the same thing two ways" seams have crept in.

CC1 — Naming conventions. Boolean settings have no convention: useAria2c (verb-prefix), autoUpdateYtdlp (auto-prefix), customCommandEnabled (suffix), downloadArchive/restrictFilenames (bare). Keys say videoDir/audioDir while the UI says "folder." Preload names diverge from main (L92); MediaKind is declared twice (L105). Standard: booleans as is/has/should/<verb> consistently; one term ("folder") across keys + UI; align preload↔main names; single-source shared types in @shared.
CC2 — Coding style is consistent but unenforced. No ESLint/Prettier config, script, or dep (L44), so the (good) house style drifts only by discipline; ?? vs || is occasionally misused for null checks. Standard: add Prettier + typescript-eslint with lint/format scripts in CI; codify the existing style.
CC3 — Different patterns for the same problem. JSON persistence (M1), status chips (UI18), segmented controls (UI14), buttons (UI15), overlays/dialogs (UI23), three yt-dlp probe spawners (probeMedia/probeMeta/probeFlat), and duplicated stdout line-buffering in download.ts and terminal.ts. Standard: one helper per concern (a jsonStore, a StatusChip, a SegmentedControl, one spawn-and-stream helper).
CC4 — Duplicate utilities. Formatting (M9), youtubeId (H2), newId (M7), JSON I/O (M1), MediaKind (L105) — plus execFile is hand-wrapped in a new Promise in five places (probe/ytdlp/ffmpeg/download.probeMeta/indexer.probeFlat) instead of one promisifyd helper, and the stdout newline-split loop is copied in two. Standard: src/main/lib/ + src/renderer/src/lib/ with one each of: format, youtube, jsonStore, ytdlpExec (promisified spawn + line stream).
CC5 — Async patterns are mixed. Three I/O idioms: callback-wrapped new Promise (execFile ×5), async/await+fetch (updater check, sync), and event-emitter-wrapped Promise (net.request in updater). Renderer mixes .then().catch() (stores) with async/await+try/catch (components). Standard: async/await everywhere; a shared execFileAsync; wrap event-emitter APIs once in a helper.
CC6 — Five failure-signaling conventions. { ok, error } result objects (download/updater/ ytdlp/backup/IPC), throw (assertHttpUrl), null (indexerCore), [] (history/sources read errors), and a bare error string (reveal.safeOpenPath). cleanError is applied to some spawn stderr but not ytdlp/ffmpeg. Standard: a Result<T> ({ ok, value?/error? }) across every service/IPC boundary; throw only inside pure helpers, caught at the boundary; always run yt-dlp stderr through cleanError.
CC7 — Dependency-injection styles. Pure modules take deps as params (good — binDir, now); the impure shell uses module singletons (getSettings(), getYtdlpPath(), lazy getStore()); progress is callback-injected; the WebContents sender is a param in some handlers and a closure in others. Standard: keep pure-core param injection; in the shell, pass wc/onProgress consistently as the leading argument and keep singleton access for config/binaries.
CC8 — No logging strategy. Effectively no diagnostics — a single stray console.error in preload, and ~29 swallowed catches (M29); errorlog.ts is domain data, not logging. Standard: one small leveled logger (e.g. electron-log) written to userData, called at every catch; keep errorlog.ts for user-facing download failures only.
CC9 — Four validation styles. Type-guard predicates (isValid* in validation.ts), coerce-with-fallback (sanitizeOptions, templates.sanitize), an imperative per-key switch (setSettings, M24), and throw (assertHttpUrl). Standard: one schema layer (e.g. zod) that both validates and coerces; setSettings runs values through the same schema instead of a bespoke switch.
CC10 — Mixed serialization/persistence. electron-store (settings) and hand-rolled pretty-JSON files (history/errorlog/templates/sources/media-items, M1) for the same job, plus yt-dlp-mandated formats (Netscape cookies, plaintext archive) and base64 enc:v1: secrets. Standard: one jsonStore<T>() abstraction for the app's own records; pick either electron-store or the JSON stores for everything, not both; leave the yt-dlp-format files alone.
CC11 — Configuration is scattered. electron-store + localStorage (sidebar, M19) + env vars (PORTABLE_EXECUTABLE_DIR, CSC_LINK, AEROFETCH_REAL_DOWNLOAD) + hardcoded module consts (update host/owner/repo, timeouts, caps, 09:00, ARIA2C_ARGS, L10). Standard: a config.ts for build/host constants; fold localStorage UI prefs into the settings store so there's one persisted-prefs source.
CC12 — Project organization. Renderer components/ mixes screens (views) with reusable widgets; helpers (theme/thumb/useClipboardLink) sit at src root; the pure queueStats lives in store/; main mixes pure (buildArgs/validation/indexerCore/ytdlpPolicy) and impure modules in one flat dir. Standard: renderer views/ + components/ + lib/; main core/ (pure) + services; move queueStats to lib.
CC13 — View/state boundary (the project's "MVVM"). It's React+Zustand, but the container/ presentational split is inconsistent: orchestration lives in stores for downloads/sources yet inside the component for DownloadBar, and SettingsView calls window.api directly (L93, UX1). Standard: stores/ hooks are the view-models (own orchestration + all IPC); components stay presentational; no window.api in components.
CC14 — State ownership is unprincipled. State lives in Zustand stores, component useState, localStorage, the main electron-store (mirrored into a renderer store), and module-level vars (idCounter, notifiedBackground, active). Persisted state is optimistic-only and never reconciled (M34/L142); two stores form a cycle (C2). Standard: main owns persisted state; renderer stores mirror it and apply the authoritative value the IPC call returns; UI-only state in stores; break store cycles via a coordinator.

Recommended single style (apply project-wide)

Errors: one Result<T> = { ok: true; value } | { ok: false; error } across every service/IPC boundary; throw only in pure helpers; one logger (leveled, file-backed) invoked at every catch.
Async: async/await only; one execFileAsync + one spawn/stream helper; wrap event-emitter APIs once.
Validation: one schema lib (zod) that validates and coerces; reuse it in setSettings, backup import, and JSON-store reads.
Persistence/serialization: one jsonStore<T>() (or electron-store) for app records — not both; one config module for host/build constants; one persisted-prefs store (no localStorage).
Shared code: lib/ for pure utils (format, youtube, ids, jsonStore); @shared is the only home for cross-process types (no re-declared MediaKind).
UI: design tokens (spacing/radius/type/icon scales) + shared primitives (Screen, StatusChip, SegmentedControl, LinkSuggestion, button/focus); stores are view-models, components presentational.
Naming: booleans is/has/should/<verb>; "folder" not "dir"; preload methods match main names; verbNoun for store actions, onX for component handlers.
Tooling: Prettier + typescript-eslint with lint/format/CI gates so all of the above stays enforced rather than aspirational.

Code cleanliness

A dead-code / clutter review. First, the good news — the codebase is genuinely clean on most axes: no TODO/FIXME/HACK/XXX in source (only in roadmap docs), no commented-out code, no debugger/debug logging (the lone @ts-ignore ×2 in preload is the legitimate browser-fallback window assignment), every source file is imported, and the dead IPC surface is exactly the two already filed. Several listed categories are N/A to this stack and worth recording so they're not re-asked:

Unused XAML / WPF — N/A (Electron + React/HTML, no XAML).
Unused strings / localization — N/A (no i18n/string-resource files; strings are hard-coded, i18n deferred), so nothing to be "unused."
Unused images / icons — none: the only assets are build/icon.{ico,svg} (used) and the inline base64 fallback tray PNG (used); thumbnails are remote. (Clutter, not shipped: dist/ ~3 GB of old installers — L84; .frames/ 19 gitignored captures.)
Unused files / resources — none in src or resources/bin (yt-dlp/ffmpeg/ffprobe all used; aria2c optional).

Dead / unreachable code (the real list):

Safe to remove now — getDefaultFolder (M2): channel + preload method + main handler + mock, zero callers. Pure deletion, no behavior change.
Decide "wire or remove" — command preview (M5): channel + preload previewCommand + main previewCommand() + formatCommandLine/quoteForDisplay (buildArgs, unit-tested) + CommandPreviewResult + mock. Either surface it (UX1's per-download panel) or delete the whole chain (and its tests).
Decide "wire or remove" — incognito/private (M6): DownloadItem.incognito + AddOptions.incognito
- buildItem handling + two history-skip checks + the QueueItem "Private" badge. No UI sets it. Add a toggle or strip the plumbing.
Decide "wire or remove" — per-download options/extraArgs (UX1): DownloadItem.options/extraArgs, StartDownloadOptions.options/extraArgs, AddOptions.options/extraArgs are plumbed end-to-end but never set by any UI. Largest block of built-but-unreachable code — wire the panel or remove the fields.
Comment, not code — MAX_ENQUEUE_BATCH (M33): referenced by ipc.ts:629 + the roadmap but never implemented; fix the comment (nothing to delete).

New cleanliness findings:

CL1 — Magic-string protocol markers duplicated across the emit/parse boundary. 'prog|' and 'path|' are hard-coded in buildArgs.ts (PROGRESS_TEMPLATE / --print after_move:path|…) and again in download.ts (line.startsWith('prog|') / 'path|'). Change one and the other breaks silently. Fix: export shared marker constants from one module.
CL2 — Long positional parameter list. buildArgs(opts, outputTemplate, o, binDir, access, extraArgs) takes six positional args (and o vs opts is easy to swap). Fix: pass a single options object. Fixed: buildArgs(input: BuildArgsInput) now takes one named object (opts/outputTemplate/ options/binDir/access/extraArgs?) destructured at the top, so callers can't transpose the two path-like strings or opts/options. download.ts's buildCommand and both test harnesses updated.
CL3 — Large method: startDownload (~130 lines) bundles spawn + dual metadata path + four inline child event handlers. Fix: extract the stdout-parse + close/error wiring (pairs with CC3's spawn-stream helper). Fixed: the stdout/stderr parse, the close/error handlers, and the B1 idle watchdog moved into a wireChildProcess({ wc, opts, rec, cleanup, getTitle }) helper in download.ts. startDownload is now a linear pre-flight (binary checks → URL normalise → concurrency guard → cookies → spawn → metadata probe → wire). getTitle is a getter because the parallel metadata probe may fill the resolved title in after wiring is set up. Behaviour unchanged.
CL4 — Deep nesting: updater.downloadAppUpdate — Promise → net.request → response → data with nested conditionals/teardown is the hardest-to-follow block. Fix: extract a streamToFile helper.
CL5 — Superfluous exports. PROGRESS_TEMPLATE (L167) and getManagedBinDir are exported but used only within their own module. Fix: make them module-private.
CL6 — Redundant wrappers (minor): MediaThumb's kind === 'audio' ? 'audio' : 'video' (L15), clearDir = update({[t]:''}), and the store openFile/showInFolder thin wrappers around window.api. Harmless; collapse opportunistically.

Magic numbers / strings (consolidated, see L10): timeouts 15_000/30_000/60_000/180_000, maxBuffers 4/64/128/256×1024×1024, caps 500/200/100/20000/80, VIRTUALIZE_AT 100, installer handoff 1500, tickers 650/15_000, stderr tail 4000; magic strings 'enc:v1:', 'persist:aerofetch-login', 'AeroFetchDailySync', '--sync', 'prog|'/'path|' (CL1). Fix: a constants.ts (CC11) — names over literals.

What can safely be removed (recommendation)

Now (zero risk): the getDefaultFolder slice (M2); un-export PROGRESS_TEMPLATE + getManagedBinDir (CL5).
Now (housekeeping): prune dist/ to the current release (L84); the macOS-only branches if Windows-only is committed (L147).
Decision required (don't silently delete — these are documented features): command preview (M5), incognito (M6), and per-download options/extraArgs (UX1) — each is "wire it or remove it." Given UX1 rates the per-download panel as high value, wiring is likely better than deleting.
Not removable (intentional): preview seed/mock data + PREVIEW branches (C1/L128) — they power the browser-preview dev workflow; consolidate (C1) rather than delete.

Simplification opportunities

Reusable abstractions that shrink the code and read better — no premature optimization, just de-duplication. Organized by the requested categories; each lists the repetition (with refs), the abstraction, and a rough LOC delta (net, after the helper's own cost). Estimates are deliberately conservative.

#	Category	Repetition (refs)	Reusable abstraction	~Net LOC
SIMP1	Repeated file handling	JSON read/save+cap+try/catch in history/errorlog/templates; sources already has it (M1, CC10)	`createJsonStore<T>(file, isValid, cap)`	−40
SIMP2	Repeated networking	`execFile`-in-`Promise` ×5 (probe/ytdlp×2/ffmpeg/probeMeta/indexer) (CC4/CC5)	`execFileAsync` + `spawnYtdlpJson()`	−40
SIMP3	Repeated parsing	byte/speed/eta/duration formatters ×4 (M9, L165, L166)	`lib/format.ts` (hour-aware, one precision rule)	−40
SIMP4	Repeated parsing	YouTube id/URL parsing ×4 (H2)	`lib/youtube.ts`	−30
SIMP5	Repeated logic	stdout line-buffering ×2 + `taskkill` tree-kill ×2 (download.ts/terminal.ts) (CC3, new)	`lineStream(stream, onLine)` + shared `killTree(pid)`	−25
SIMP6	Repeated commands	7 identical preload `on` subscribe/unsubscribe wrappers (new*)	`subscribe(channel, cb)` helper in preload	−20
SIMP7	Repeated event handlers	`Set<string>` add/remove/toggle/toggle-all in DownloadBar/Library/History (new)	`useSelection()` hook	−30
SIMP8	Repeated view models	async-action `setBusy/try/catch/finally + result + error` ×~7 in SettingsView (new)	`useAsyncAction()` hook	−50
SIMP9	Repeated UI (cards)	hand-styled `<div>` card surfaces ×6 (UI7/UI20/L120)	`<Surface tier>` (or use Fluent `Card`)	−30
SIMP10	Repeated UI (settings)	`sectionHeader` + `Card` ×11 and Switch+`Field`+"On/Off" ×~12 in SettingsView	`<SettingsCard icon title>` + `<ToggleField>`	−90
SIMP11	Repeated UI (row actions)	`Hint`+`Button` icon-action ×~16 (QueueItem/History/Templates)	`<IconAction label icon onClick>`	−55
SIMP12	Repeated UI (empty states)	centered icon+text `empty` block ×3 (L116)	`<EmptyState icon title hint?>`	−25
SIMP13	Repeated dialogs/banners	suggestion banner ×2 (UI19); status chips Badge-vs-pill (UI18, M8)	`<LinkSuggestion>` + `<StatusChip>`	−40
SIMP14	Repeated UI (controls)	two hand-rolled segmented controls (UI14)	`<SegmentedControl>`	−30
SIMP15	Repeated validation	type-guards + `sanitizeOptions` + `setSettings` switch (CC9, M24)	one schema (zod) validate+coerce	−60
SIMP16	Repeated networking	`net.request` + redirect-revalidate + timeout ×2 in updater (`fetchTrustedText`/`downloadAppUpdate`) (new)	`trustedRequest(url, {sink})`	−30
SIMP17	Repeated logic (misc)	`newId` ×3 (M7), `PREVIEW` ×8 (C1), `(ARR as readonly string[]).includes` ×N (L90)	`lib`: `newId`, `isPreview`, `isMember`	−15
SIMP18	Repeated converters	`MediaKind` ×2 (L105), kind\|quality string encode/decode (CL2/L91)	single-source type + typed pair	−10

Highest-value (do these first)

SettingsView decomposition (SIMP10 + SIMP8 + SIMP11). A <SettingsCard> + <ToggleField> + useAsyncAction + <IconAction> would take the 1104-line file to roughly ~600, and the per-card split (H1) falls out for free. Biggest single readability win.
createJsonStore (SIMP1) collapses three near-identical persistence modules to thin configs and removes the M1/CC10 "two ways to persist" seam.
lib/format.ts + lib/youtube.ts (SIMP3/SIMP4) remove the most-copied pure utilities and fix the formatter divergences (L165/L166) at the same time.
execFileAsync/spawnYtdlpJson (SIMP2/SIMP5) unify five spawn sites + the duplicated kill/line-buffer.

Estimate

Gross duplicated lines removable ≈ 650–750; the new helpers/primitives add back ≈ 150–200, for a net reduction of ~550–800 lines (~5–7% of the ~12.5K total). Concentration: SettingsView ~−450 (1104 → ~600), the JSON stores ~−40, main spawn/format/util helpers ~−120, shared UI primitives ~−150. The real payoff is readability and killing the "two-ways-to-do-X" seams (M1/M8/M9/UI14/UI18/CC*), not the line count. Caveat: stop short of over-abstracting — a createMirroredStore factory or a generic form engine would cost more clarity than it saves; keep abstractions at the "one obvious helper" level.

Bug hunt (execution-path review)

Tracing real code paths for latent bugs by category. New bugs get B IDs; the genuine bugs found in earlier passes are listed so this is complete; and the categories that came back clean are recorded (bug-hunting that finds nothing is a result too).

New bugs

B1 — No stall/idle timeout on downloads (resource leak + stuck slot). spawn(ytdlp, …, { windowsHide: true }) (download.ts:306) sets no timeout, and buildArgs emits no --socket-timeout. A hung connection means yt-dlp never exits → the active map entry and the renderer's downloading item persist forever, permanently consuming a concurrency slot with no recovery or feedback. (The app-updater download does have DOWNLOAD_IDLE_TIMEOUT_MS; downloads don't.) Fix: pass --socket-timeout and/or an app-side idle watchdog that kills + errors a stalled child.
B2 — Source indexing can't be cancelled. indexSource walks a channel's playlists with sequential probes (each up to the 180 s probeFlat timeout); the UI shows "indexing…" with the Index button disabled and no cancel. A large channel locks the add-source flow for minutes with no abort. Fix: thread an AbortSignal/cancel token and a Cancel button.
B3 — extractSha256 ignores the filename (wrong-hash risk). It returns the first 64-hex token in the file (updater.ts); a combined multi-file checksum uploaded as <asset>.sha256 would verify the installer against the wrong line's hash. Safe only by the one-hash- per-asset convention. Fix: match the hash on the asset's filename line.
B4 — probeMeta assumes one line per --print field. It does stdout.split('\n') → [title, uploader, duration] (download.ts); a title containing a newline shifts channel and duration by a line. Fix: use a single --print with an unlikely delimiter, or -J.
B5 — Missing status guard on the meta event. Between cancel() and the child's close, active.has(id) is briefly true, so probeMeta can send a meta event for a just-canceled item; applyEvent's meta case (unlike progress/done/error) has no canceled guard, so it updates a canceled item's title. Harmless today, but the asymmetry is a latent bug. Fix: guard meta like the others.
B6 — App-update download has no cancel. Once downloadAppUpdate starts there's no user abort — only completion or the idle timeout stops it; the progress UI offers no Cancel. Fix: expose cancel (abort the request).
B7 — Cookie-login promise can never resolve if the window is destroyed without close. openCookieLoginWindow resolves only via the close→exportAndResolve path; a destroy() (or a closed without close) would leave pendingResolvers pending forever. Not triggered by current code, but a latent never-resolve. Fix: also resolve/reject on closed.

Real bugs already filed (confirmed in this pass)

M32 playlist/channel batches download in reverse order · M35 History re-download duplicates rows · M34 optimistic settings never reconcile (UI shows unsaved values) · L88 a progress event can flip a queued item to downloading outside pump() · L139 startup yt-dlp auto-update vs a concurrent download spawning the same exe (Windows file-in-use) · L140 retry-during-teardown hits the "already running" guard · L148 clearFinished can free a slot before the killed tree exits (brief over-cap) · L157 markDownloaded no-ops after removeSource (orphan downloads).

Came back clean (no bug found)

IPC-after-destroy: every wc.send/e.sender.send/mainWindow.* is guarded by isDestroyed().
Threading / UI threading / synchronization: single JS thread in main and renderer; React state updates are always on-thread; the active map + module vars are main-thread-only — no data races.
Infinite loops: the stdout line-buffer advances each iteration; parseExtraArgs/parseRssVideoIds regexes can't zero-width-match; no self-recursive pump.
Stream disposal (updater): downloadAppUpdate has a single finish() that aborts the request, destroys the file stream, and unlinks the partial — correct on every failure path.
Event-listener cleanup: component useEffect subscriptions return their unsubscribe; module-level subscriptions are app-lifetime by design.
Off-by-one / boundary: parseProgress guards parts.length < 6; playlist/collection indexing is 1-based throughout; MAX_ENTRIES slices are correct; fmtBytes clamps the unit index.

Resilience & failure-mode review

A fresh lens: what happens when the environment fails (disk full, permission denied, corrupt file, killed mid-write, huge inputs) rather than when the logic is wrong. These are robustness findings, not cosmetics. R IDs.

R1 — JSON stores are not written atomically (corruption on crash/power-loss). The hand-rolled stores (history/errorlog/templates/sources/media-items) persist via writeFileSync(file, JSON.stringify…) — not write-temp-then-rename. A crash/power-cut mid-write truncates the file; the next read hits a parse error and returns []. electron-store (settings) is atomic, so durability is inconsistent across the app. Fix: an atomic write (temp + rename, or write-file-atomic) in the shared jsonStore (SIMP1).
R2 — A corrupt/invalid store silently loses all data. readJsonArray/listHistory etc. catch a parse error and return [] with no warning, backup, or recovery — one bad byte wipes the user's history/ sources/templates from their perspective. Fix: on parse failure, back up the bad file (.corrupt) and surface a notice.
R3 — O(n) full-file rewrite per download completion (≈O(n²) per channel), synchronously on the main thread. setMediaItemDownloaded (sources.ts:126) reads + parses the entire media-items.json (up to MAX_ITEMS = 20,000) and rewrites the whole file on every completion, and addHistory rewrites all of history.json likewise. Downloading a 1,000-video channel ⇒ ~1,000 full read-parse-write cycles of a multi-MB file, blocking the IPC/event loop each time. Fix: in-memory cache + debounced/batched atomic writes (or the deferred better-sqlite3).
R4 — Canceled downloads orphan .part files. cancelDownload tree-kills yt-dlp but never deletes the partial; canceled items vanish from the UI while .part/fragment files accumulate in the output folder. (App crash mid-download likewise — the queue isn't persisted to resume, M4.) Fix: clean up the partial on cancel, or surface/offer-resume for orphans.
R5 — Settings write failure is unhandled. setSettings calls store.set(...) with no try/catch; on disk-full/read-only electron-store throws → the IPC rejects → the renderer's setSettings().catch(() => {}) swallows it while the optimistic UI keeps the change (the disk-full form of M34). Fix: catch and report.
R6 — Silent data loss on any store write failure. A completed download that can't be recorded (disk full) shows "Completed" in-session but is gone on restart, with no error (the write catch is empty, M29). Fix: detect write failure and warn. Fixed (log half) in jsonStore.ts: writeJsonAtomic now returns whether the write landed and logs the failure (with the path) instead of an empty catch, and removes the leftover .tmp; createJsonStore's flush only clears the dirty flag on success, so a failed write stays pending and is retried on the next write() or the quit-time flushAllStores() rather than dropped. Unit-tested in test/jsonStore.test.ts. Scope note: like M29 this delivers the "no longer silent" half (logged + retried); the user-facing toast needs the leveled file logger / toast sink deferred to CC8.
R7 — safeStorage unavailable ⇒ secrets silently stored as plaintext. encryptSecret falls back to plaintext when DPAPI/safeStorage isn't available, with no indication — compounds H7 (cookies) and the backup-cleartext issue (M22). Fix: warn (or refuse to store) when encryption is unavailable. Fixed in settings.ts: encryptSecret now console.warns before returning a non-empty secret as plaintext, so the cleartext fallback is no longer silent. Chose warn-not-refuse to preserve the pre-encryption behaviour (storing still works); DPAPI is effectively always present on Windows, so this should never fire in practice. (refusing/at-rest enforcement remains an option if ever wanted.)
R8 — Pretty-printed JSON for large stores. JSON.stringify(value, null, 2) inflates size/write time for the potentially-20k-item media store (ties R3). Fix: compact JSON for the large stores.
R9 — Clock-skew sensitivity. shouldAutoCheckYtdlp and the scheduled-download promoter compare Date.now(); a backward system-clock correction can skip or double-fire a check/schedule. Minor; note for awareness.

Ship-readiness (perceived quality)

Obsessive "does it feel finished" pass. The biggest untapped vein is defaults (first-run impressions), plus a few stuck-status / progress glitches. SR IDs; already-filed perceived-quality items are listed at the end so the picture is complete. Verified-clean first: card/label/button text is consistently sentence case, and a careful read found no spelling typos — the polish gaps are defaults, jargon, and a couple of stuck states, not sloppy text.

Poor / risky defaults (first-run impressions)

SR1 — Theme defaults to 'light', not 'system'. A dark-mode Windows user gets a bright white app on first launch despite the app fully supporting "follow system." Single most-noticeable first-run miss. Fix: default theme: 'system'.
SR2 — ytdlpChannel defaults to 'nightly'. The app ships auto-pulling yt-dlp's daily, less-tested build (auto-update also on by default); one nightly regression breaks downloads for everyone. Defensible for chasing YouTube changes, but a risky default for a commercial release. Fix: consider stable as the shipped default.
SR3 — autoDownloadNew defaults to true. The moment a user marks a channel "watched," new uploads auto-download with no per-event consent — can quietly fill a disk. Fix: default off (let watching be "notify," downloading be opt-in).
SR4 — clipboardWatch defaults to true. The app reads the clipboard on every window focus from first launch (R7/L138). A privacy-conscious default would be off or first-run-prompted. Fix: default off, or ask on first run.
SR5 — Audio defaults to MP3 (lossy). defaultAudioQuality: 'Best (MP3)' + audioFormat: 'mp3' give a lossy re-encode by default; m4a/opus are higher quality at the same size. Minor (MP3 = max compatibility), but "Best" implying MP3 is a quality mismatch (M18).

Stuck states & progress glitches

SR6 — "Resolving…" can stick forever. A queued item's channel shows the 'Resolving…' placeholder until a meta event arrives; if metadata never resolves (error before meta, or no channel in the probe), the row reads "Resolving… • 1080p • Video" permanently — looks hung. Fix: clear the placeholder on error / when meta fails.
SR7 — Progress bar visibly resets mid-download. A video+audio merge downloads as two streams, so the bar fills 0→100%, then resets to 0→100% again before muxing — looks like a glitch/restart to the user. Fix: weight the two phases (e.g. 0–50% / 50–100%) or show a "merging…" state.
SR8 — Window title never reflects state (L108/W19): always the static "AeroFetch," so the taskbar can't show "3 downloading." A finished-feeling app updates its title/tooltip with activity.

Wording / jargon polish

SR9 — Dev jargon in user-facing option hints (extends M37): "mux them into the video," "Tiebreaker, not a hard filter," "Endcards / credits" ("End cards"), "Proof-of-Origin token," "--extractor-args." Reads like engineer notes. Fix: plain-language hints.
SR10 — Inconsistent product self-description / casing surfaced to users: "yt-dlp frontend" caption flips to "v0.5.0" on load (L66); "Sign in" vs "Sign-in" (L95); "PO token" vs "PO Token" (L150).

Also reduces perceived quality (already filed — listed for completeness)

Onboarding has no folder picker / feels thin (UX5/UX22); no boot loading state + one-frame theme flash (UX26); refresh-icon mismatch ArrowClockwise vs ArrowSync (L106) and Regular/Filled brand icon (UI13); only the sidebar animates, everything else snaps (UI26); separator glyph/spacing inconsistency •/· (L164); the command palette is undiscoverable (UX21). (The unsigned-build SmartScreen prompt is accepted as a non-goal — no certificate.)

Ship-blockers (highest perceived-quality impact): SR1 (light-on-dark first launch), SR7 (progress visibly restarting), SR6 ("Resolving…" stuck), and W14 (placeholder icon) — all now resolved. The unsigned-build SmartScreen prompt is accepted as a non-goal (no certificate). Together these were most of the "this feels finished" gap.

Performance (no premature optimization — real hot paths only)

A fresh lens: redundant work on hot paths and scaling cliffs, not micro-tuning. PERF IDs. Verified acceptable first: memoized QueueItems don't re-render when their item is unchanged (the applyEvent map preserves references for untouched items); the queue + large library lists are virtualized; electron-store is constructed lazily. The issues:

PERF1 — getSettings() is heavy and on every hot path. It runs per download spawn (twice — in buildCommand and the maxConcurrent check), per completion (notify), and on the system-theme bridge; each call re-reads the whole store and, for users who've configured a proxy/PO-token/update-token, runs up to 3 safeStorage.decryptString (DPAPI) calls. Fix: cache the decrypted settings, invalidate on write.
PERF2 — templates.json is read+parsed on every download. resolveExtraArgs evaluates templates: listTemplates() eagerly as an argument (download.ts:182) before selectExtraArgs checks customCommandEnabled, so the file is read even when custom commands are off. Fix: pass a lazy getter, or short-circuit on the gate first.
PERF3 — pump() is O(n) per queue event. It filter+reverse+slices the entire items array on every add/done/error/cancel/progress-driven change; with M33's unbounded channel enqueue (thousands of items) every event becomes O(n), and several events fire per second during active downloads. Fix: track running/queued counts + a pointer instead of rescanning.
PERF4 — summarizeQueue runs twice per progress tick. Once in App's store subscription (which also pushes a taskbar IPC every tick, L25) and once in DownloadsView's render (no useMemo, L94) — each O(items), every ~second per active download. Fix: compute once, memoize, throttle the taskbar push.
PERF5 — VirtualList gets new function identities each render. estimateSize/getKey/ renderItem are passed as inline arrows, so the virtualizer can't rely on stable references (risking re-measures/cache churn). Fix: useCallback/hoist them.
PERF6 — Per-thumbnail store subscriptions. Each MediaThumb calls useResolvedDark() (two store subscriptions) (L162); a long list creates N×2 subscriptions. Fix: resolve once, pass as a prop.
PERF7 — (ref R3) O(n²) media-items rewrites dominate the main-process cost when downloading a channel; closed by the cached/atomic jsonStore (SIMP1) — the single highest-value perf fix.
PERF8 — No code-splitting. All views (incl. the rarely-used Terminal/Settings) load up front in one renderer bundle alongside Fluent UI + React; software rendering (W15) compounds first-paint cost. Minor for a desktop app, but lazy-loading heavy views would trim startup. Fix: React.lazy the heavy tabs.

Priority: PERF7/R3 (scaling cliff) and PERF1/PERF2 (per-download redundant I/O + crypto) are the only ones with real user-visible impact; the rest are good hygiene. None warrant work before the correctness bugs (B1, M32, M35) — listed for completeness, not urgency.

Completed

Security & correctness audit (2026-06-23):

S1 — Backup import: confirm before enabling imported custom-command templates.
S2 — Cookie login window: restrict popups to http(s)/about: schemes.
S3 — Enforce maxConcurrent in main (startDownload), not just the renderer.
S4 — Path-traversal sanitization for filenameTemplate + outputDir.
S5 — Per-row validation on persisted JSON reads.
C1 (orig) — Bundle the missing ffprobe.exe; assert ffmpeg+ffprobe presence up front.
P1 — Stop getSettings() writing to disk on every read.
P2 — Forward the renderer's pre-probed metadata to main; skip the redundant probe.
P3 — Document "lower maxConcurrent mid-flight doesn't pause overflow".
M1 (orig) — Extract duplicated cleanError to log.ts.
M2 (orig) — Document parseExtraArgs quoting limitations.
M3 (orig) — App icon placeholder (designed asset still wanted pre-v1.0).

Deferred

Designed app icon before v1.0 (placeholder shipped).
Migrate JSON stores to better-sqlite3 if a user indexes many large channels.
Metadata editing (--parse-metadata/--replace-in-metadata) — held pending a live recipe.
PO-token WebView auto-minting — only the --extractor-args plumbing shipped.
Taskbar overlay badge (needs a drawn NativeImage).
i18n — deliberately deferred (note: UI strings are hard-coded throughout).
Code signing — non-goal: no certificate will be purchased, so builds ship unsigned and the SmartScreen prompt is accepted. The build remains signing-ready via CSC_LINK/CSC_KEY_PASSWORD env vars if this ever changes — see SIGNING.md.
Live smoke-test of OS-level wiring (tray/jump list/scheduled sync/aerofetch://).

136 KiB Raw Blame History Unescape Escape