Fix C1/C2 + reliability cluster (L140/L141/L148, R6/R7)

Critical: - C1: single source of truth for IPC mock + Settings defaults. DEFAULT_SETTINGS in @shared/ipc; main DEFAULTS, renderer FALLBACK, and preview MOCK_SETTINGS all derive from it. Whole browser mock collapsed into one typed mockApi.ts; main.tsx shrinks to window.api = mockApi. PREVIEW check single-sourced in isPreview.ts. - C2: break the downloads<->sources circular import via a typed event bus (store/coordinator.ts). App eagerly imports sources for side-effects so startup load + scheduled --sync + downloadCompleted subscription still run. Reliability: - L140/L148: cancel/pause release the active slot synchronously; identity-guarded releaseActive; per-spawn cookie jar so a same-id retry/resume is never rejected by a stale entry nor run over the concurrency cap. - L141: renderer history capped at 500 + url de-dup to match main. - R6: writeJsonAtomic reports/logs write failures and keeps data dirty for retry instead of an empty catch. - R7: encryptSecret warns before the plaintext fallback. typecheck + 243 tests + eslint green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-30 20:25:49 -04:00
parent 6c19899f75
commit 7e3e5af52d
20 changed files with 596 additions and 413 deletions
@@ -12,6 +12,12 @@ import { LiveRegion } from './components/LiveRegion'
 import { getTheme, pageBackground } from './theme'
 import { useSettings } from './store/settings'
 import { useDownloads } from './store/downloads'
+// Eagerly load the sources store for its startup side-effects (load persisted
+// sources + the watched-source / scheduled `--sync` kickoff) and its cross-store
+// subscription (coordinator's downloadCompleted → markDownloaded). Before C2 this
+// was guaranteed by downloads.ts importing it; now that the cycle is broken, App
+// owns the eager load so it survives the views becoming lazy-loaded (PERF8).
+import './store/sources'
 import { summarizeQueue } from './store/queueStats'
 import { useResolvedDark } from './store/systemTheme'
 import { logError } from './reportError'
@@ -28,6 +28,7 @@ import {
  DismissRegular
 } from '@fluentui/react-icons'
 import type { MediaItem, Source, MediaKind } from '@shared/ipc'
+import { isPreview as PREVIEW } from '../isPreview'
 import { useSources } from '../store/sources'
 import { useSettings } from '../store/settings'
 import { useClipboardLink, looksLikeSingleVideo } from '../useClipboardLink'
@@ -43,9 +44,6 @@ import { SegmentedControl } from './ui/SegmentedControl'
 import { useFocusStyles } from './ui/focusRing'
 import { THUMB_XS } from '../thumbSizes'

-// True in the standalone browser preview (no Electron preload).
-const PREVIEW = typeof window === 'undefined' || !window.electron
-
 /** Per-item status shown in the library: a live queue status, or pending/downloaded. */
 type ItemStatus = DownloadStatus | 'pending'

@@ -0,0 +1,8 @@
+/**
+ * True in the standalone browser UI preview, where Electron's preload never ran
+ * so `window.electron` (and the real `window.api` IPC bridge) is absent. The
+ * stores and a few views branch on this to drive seed data / fake tickers instead
+ * of calling IPC. Single-sourced here (C1) so the check isn't re-declared in ~8
+ * files — import it as `PREVIEW` where that reads better locally.
+ */
+export const isPreview = typeof window === 'undefined' || !window.electron
@@ -1,279 +1,16 @@
 import './assets/base.css'
 import React from 'react'
 import ReactDOM from 'react-dom/client'
-import { DEFAULT_DOWNLOAD_OPTIONS, type Settings, type CommandTemplate } from '@shared/ipc'
 import App from './App'
 import { ErrorBoundary } from './components/ErrorBoundary'
+import { mockApi } from './mockApi'

 // In the standalone UI preview (browser, no Electron preload) window.api isn't
-// injected. Stub the full surface so the UI renders and stays interactive during
-// design work. The store detects preview mode (no window.electron) and drives a
-// fake progress ticker instead of calling these, so most are inert no-ops.
-// In the real Electron app this branch is skipped — preload provides window.api.
+// injected. Install the mock surface (mockApi.ts) so the UI renders and stays
+// interactive during design work. In the real Electron app this branch is
+// skipped — preload provides the real window.api.
 if (import.meta.env.DEV && !window.api) {
-  const MOCK_SETTINGS: Settings = {
-    videoDir: 'C:\\Users\\you\\Documents\\Video',
-    audioDir: 'C:\\Users\\you\\Documents\\Audio',
-    defaultKind: 'video',
-    defaultVideoQuality: 'Best available',
-    defaultAudioQuality: 'Best',
-    maxConcurrent: 2,
-    filenameTemplate: '%(title)s.%(ext)s',
-    theme: 'system',
-    accentColor: 'teal',
-    clipboardWatch: true,
-    downloadOptions: DEFAULT_DOWNLOAD_OPTIONS,
-    proxy: '',
-    rateLimit: '',
-    useAria2c: false,
-    cookieSource: 'none',
-    cookiesBrowser: 'chrome',
-    youtubePlayerClient: '',
-    youtubePoToken: '',
-    restrictFilenames: false,
-    downloadArchive: false,
-    autoUpdateYtdlp: true,
-    ytdlpChannel: 'nightly',
-    ytdlpLastUpdateCheck: Date.now() - 3_600_000,
-    customCommandEnabled: false,
-    defaultTemplateId: null,
-    notifyOnComplete: true,
-    autoDownloadNew: true,
-    hasCompletedOnboarding: true,
-    minimizeToTray: false,
-    launchAtStartup: false,
-    sidebarCollapsed: false,
-    updateToken: ''
-  }
-  // Stands in for the cookies.txt file's mtime — lets the Cookies card's
-  // sign-in/clear flow be exercised in this browser-only preview.
-  let mockCookiesSavedAt: number | null = null
-  // Stands in for templates.json — lets the Custom commands card's CRUD and
-  // the download bar's template picker be exercised in this browser-only preview.
-  let mockTemplates: CommandTemplate[] = [
-    { id: 'tpl1', name: 'Write thumbnail, no mtime', args: '--write-thumbnail --no-mtime' }
-  ]
-
-  window.api = {
-    getAppVersion: async () => '0.4.0-preview',
-    checkForAppUpdate: async () => {
-      await new Promise((r) => setTimeout(r, 400))
-      return {
-        ok: true,
-        available: true,
-        currentVersion: '0.4.0',
-        latestVersion: '0.5.0',
-        notes:
-          '### What’s new in v0.5.0\n- In-app updater (this screen!)\n- Faster downloads\n- Bug fixes',
-        htmlUrl: 'https://gitea.netbird.zimspace.uk:5938/debont80/AeroFetch/releases',
-        downloadUrl: 'https://gitea.netbird.zimspace.uk:5938/example/AeroFetch-Setup-0.5.0.exe',
-        assetName: 'AeroFetch-Setup-0.5.0.exe'
-      }
-    },
-    downloadAppUpdate: async () => ({
-      ok: false,
-      error: 'Downloading updates is disabled in the browser preview.'
-    }),
-    runAppUpdate: async () => ({ ok: true }),
-    onAppUpdateProgress: () => () => {},
-    getYtdlpVersion: async () => ({ ok: true, version: '2025.06.01 (UI preview mock)' }),
-    getFfmpegVersions: async () => ({
-      ffmpeg: '7.1-full_build (UI preview mock)',
-      ffprobe: '7.1-full_build (UI preview mock)'
-    }),
-    probe: async (url: string) => {
-      await new Promise((r) => setTimeout(r, 700)) // simulate network latency
-      // A 'list'/'playlist' URL exercises the playlist selection UI in preview.
-      if (/list=|playlist/i.test(url)) {
-        return {
-          ok: true,
-          kind: 'playlist',
-          playlist: {
-            title: 'Full Electron Course — All Episodes',
-            uploader: 'DevChannel',
-            count: 5,
-            entries: Array.from({ length: 5 }, (_, i) => ({
-              index: i + 1,
-              id: `vid${i + 1}`,
-              title: `Episode ${i + 1} — ${['Setup', 'Main Process', 'IPC', 'Packaging', 'Release'][i]}`,
-              url: `https://youtube.com/watch?v=vid${i + 1}`,
-              durationLabel: `${10 + i}:0${i}`,
-              uploader: 'DevChannel'
-            }))
-          }
-        }
-      }
-      return {
-        ok: true,
-        kind: 'video',
-        info: {
-          title: 'Building a Desktop App with Electron — Full Course',
-          channel: 'DevChannel',
-          durationLabel: '1:42:08',
-          thumbnail: undefined,
-          formats: [
-            { id: '__best__', label: 'Best available', ext: 'mp4', hasAudio: true },
-            {
-              id: '299',
-              label: '1080p60 · mp4 · 248 MB',
-              height: 1080,
-              ext: 'mp4',
-              filesizeLabel: '248 MB',
-              hasAudio: false
-            },
-            {
-              id: '136',
-              label: '720p · mp4 · 124 MB',
-              height: 720,
-              ext: 'mp4',
-              filesizeLabel: '124 MB',
-              hasAudio: false
-            },
-            {
-              id: '135',
-              label: '480p · mp4 · 72 MB',
-              height: 480,
-              ext: 'mp4',
-              filesizeLabel: '72 MB',
-              hasAudio: false
-            },
-            {
-              id: '134',
-              label: '360p · mp4 · 38 MB',
-              height: 360,
-              ext: 'mp4',
-              filesizeLabel: '38 MB',
-              hasAudio: false
-            }
-          ]
-        }
-      }
-    },
-    startDownload: async () => ({ ok: true }),
-    cancelDownload: async () => {},
-    pauseDownload: async () => {},
-    chooseFolder: async () => null,
-    openPath: async () => '',
-    openUrl: async () => {},
-    showInFolder: async () => {},
-    readClipboard: async () => '',
-    getSettings: async () => MOCK_SETTINGS,
-    setSettings: async (partial) => Object.assign(MOCK_SETTINGS, partial),
-    listHistory: async () => [],
-    addHistory: async () => [],
-    removeHistory: async () => [],
-    removeManyHistory: async () => [],
-    clearHistory: async () => [],
-    cookiesLogin: async () => {
-      await new Promise((r) => setTimeout(r, 600)) // simulate the sign-in window
-      mockCookiesSavedAt = Date.now()
-      return { ok: true, cookieCount: 14 }
-    },
-    cookiesStatus: async () =>
-      mockCookiesSavedAt ? { exists: true, savedAt: mockCookiesSavedAt } : { exists: false },
-    cookiesClear: async () => {
-      mockCookiesSavedAt = null
-    },
-    listTemplates: async () => mockTemplates,
-    saveTemplate: async (template) => {
-      mockTemplates = [template, ...mockTemplates.filter((t) => t.id !== template.id)]
-      return mockTemplates
-    },
-    removeTemplate: async (id) => {
-      mockTemplates = mockTemplates.filter((t) => t.id !== id)
-      return mockTemplates
-    },
-    previewCommand: async (opts) => {
-      await new Promise((r) => setTimeout(r, 300)) // simulate the main-process round-trip
-      const extra = opts.extraArgs ? ` ${opts.extraArgs}` : ''
-      const dir = opts.kind === 'audio' ? MOCK_SETTINGS.audioDir : MOCK_SETTINGS.videoDir
-      return {
-        ok: true,
-        command:
-          `yt-dlp.exe -f "bv*+ba/b" -o "${dir}\\%(title)s.%(ext)s"` + `${extra} -- ${opts.url}`
-      }
-    },
-    updateYtdlp: async (channel) => {
-      await new Promise((r) => setTimeout(r, 600)) // simulate the self-update run
-      return {
-        ok: true,
-        output: `yt-dlp is already up to date (channel: ${channel}, UI preview mock)`
-      }
-    },
-    // No background updater in the browser preview — hand back an inert unsubscribe.
-    onYtdlpAutoUpdateStatus: () => () => {},
-    listErrorLog: async () => [],
-    clearErrorLog: async () => [],
-    exportBackup: async () => ({
-      ok: true,
-      path: 'C:\\Users\\you\\Downloads\\aerofetch-backup.json'
-    }),
-    importBackup: async () => ({ ok: true }),
-    onDownloadEvent: () => () => {},
-    getSystemTheme: async () => ({
-      shouldUseDarkColors: false,
-      shouldUseHighContrastColors: false
-    }),
-    onSystemThemeUpdate: () => () => {},
-    openHighContrastSettings: async () => {},
-    onExternalUrl: () => () => {},
-    // Media-manager sources — a seeded channel so the (Phase H) Library view has
-    // demo data in this browser-only preview.
-    listSources: async () => [
-      {
-        id: 'src-demo',
-        url: 'https://www.youtube.com/@DevChannel',
-        kind: 'channel',
-        title: 'DevChannel',
-        channel: 'DevChannel',
-        addedAt: Date.now() - 86_400_000,
-        lastIndexedAt: Date.now() - 3_600_000,
-        itemCount: 7
-      }
-    ],
-    indexSource: async (url) => {
-      await new Promise((r) => setTimeout(r, 800)) // simulate the index walk
-      return {
-        ok: true,
-        source: {
-          id: 'src-demo',
-          url,
-          kind: 'channel',
-          title: 'DevChannel',
-          channel: 'DevChannel',
-          addedAt: Date.now(),
-          lastIndexedAt: Date.now(),
-          itemCount: 7
-        },
-        itemCount: 7
-      }
-    },
-    reindexSource: async () => ({ ok: true, itemCount: 7, newCount: 0 }),
-    removeSource: async () => [],
-    markSourceItemDownloaded: async () => [],
-    setSourceWatched: async () => [],
-    syncSources: async () => ({ ok: true, newItems: [] }),
-    getScheduledSync: async () => ({ enabled: false }),
-    setScheduledSync: async (enabled: boolean) => ({ enabled }),
-    listSourceItems: async (sourceId) =>
-      Array.from({ length: 7 }, (_, i) => ({
-        id: `${sourceId}:vid${i + 1}`,
-        sourceId,
-        videoId: `vid${i + 1}`,
-        title: `Episode ${i + 1}`,
-        url: `https://youtube.com/watch?v=vid${i + 1}`,
-        playlistTitle: i < 5 ? 'Full Electron Course' : 'Uploads',
-        playlistIndex: i < 5 ? i + 1 : i - 4,
-        durationLabel: `${10 + i}:0${i}`,
-        downloaded: i < 2
-      })),
-    onIndexProgress: () => () => {},
-    runTerminal: async () => ({ ok: true }),
-    cancelTerminal: async () => {},
-    onTerminalOutput: () => () => {},
-    setTaskbarProgress: async () => {},
-    mintPoToken: async () => null
-  }
+  window.api = mockApi
 }

 ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
@@ -0,0 +1,255 @@
+import { DEFAULT_SETTINGS, type Settings, type CommandTemplate } from '@shared/ipc'
+
+/**
+ * The browser-preview stand-in for the real `window.api` IPC bridge (C1). In the
+ * standalone UI preview (browser, no Electron preload) `window.api` isn't
+ * injected, so main.tsx assigns this mock to keep the UI interactive during
+ * design work. Typed as the real `Api` surface (`Window['api']`) so it can't
+ * silently drift from the preload contract — a missing or mistyped method is a
+ * compile error. Most methods are inert no-ops because the stores detect preview
+ * mode (no window.electron) and drive a fake progress ticker instead.
+ */
+type Api = Window['api']
+
+// The preview settings: the canonical defaults, plus preview-only tweaks —
+// placeholder folders, a nightly channel + a recent check to exercise the
+// updater card, auto-download on, and onboarding already dismissed so design
+// work isn't blocked behind the welcome screen.
+const MOCK_SETTINGS: Settings = {
+  ...DEFAULT_SETTINGS,
+  videoDir: 'C:\\Users\\you\\Documents\\Video',
+  audioDir: 'C:\\Users\\you\\Documents\\Audio',
+  ytdlpChannel: 'nightly',
+  ytdlpLastUpdateCheck: Date.now() - 3_600_000,
+  autoDownloadNew: true,
+  hasCompletedOnboarding: true
+}
+
+// Stands in for the cookies.txt file's mtime — lets the Cookies card's
+// sign-in/clear flow be exercised in this browser-only preview.
+let mockCookiesSavedAt: number | null = null
+// Stands in for templates.json — lets the Custom commands card's CRUD and
+// the download bar's template picker be exercised in this browser-only preview.
+let mockTemplates: CommandTemplate[] = [
+  { id: 'tpl1', name: 'Write thumbnail, no mtime', args: '--write-thumbnail --no-mtime' }
+]
+
+export const mockApi: Api = {
+  getAppVersion: async () => '0.4.0-preview',
+  checkForAppUpdate: async () => {
+    await new Promise((r) => setTimeout(r, 400))
+    return {
+      ok: true,
+      available: true,
+      currentVersion: '0.4.0',
+      latestVersion: '0.5.0',
+      notes:
+        '### What’s new in v0.5.0\n- In-app updater (this screen!)\n- Faster downloads\n- Bug fixes',
+      htmlUrl: 'https://gitea.netbird.zimspace.uk:5938/debont80/AeroFetch/releases',
+      downloadUrl: 'https://gitea.netbird.zimspace.uk:5938/example/AeroFetch-Setup-0.5.0.exe',
+      assetName: 'AeroFetch-Setup-0.5.0.exe'
+    }
+  },
+  downloadAppUpdate: async () => ({
+    ok: false,
+    error: 'Downloading updates is disabled in the browser preview.'
+  }),
+  runAppUpdate: async () => ({ ok: true }),
+  onAppUpdateProgress: () => () => {},
+  getYtdlpVersion: async () => ({ ok: true, version: '2025.06.01 (UI preview mock)' }),
+  getFfmpegVersions: async () => ({
+    ffmpeg: '7.1-full_build (UI preview mock)',
+    ffprobe: '7.1-full_build (UI preview mock)'
+  }),
+  probe: async (url: string) => {
+    await new Promise((r) => setTimeout(r, 700)) // simulate network latency
+    // A 'list'/'playlist' URL exercises the playlist selection UI in preview.
+    if (/list=|playlist/i.test(url)) {
+      return {
+        ok: true,
+        kind: 'playlist',
+        playlist: {
+          title: 'Full Electron Course — All Episodes',
+          uploader: 'DevChannel',
+          count: 5,
+          entries: Array.from({ length: 5 }, (_, i) => ({
+            index: i + 1,
+            id: `vid${i + 1}`,
+            title: `Episode ${i + 1} — ${['Setup', 'Main Process', 'IPC', 'Packaging', 'Release'][i]}`,
+            url: `https://youtube.com/watch?v=vid${i + 1}`,
+            durationLabel: `${10 + i}:0${i}`,
+            uploader: 'DevChannel'
+          }))
+        }
+      }
+    }
+    return {
+      ok: true,
+      kind: 'video',
+      info: {
+        title: 'Building a Desktop App with Electron — Full Course',
+        channel: 'DevChannel',
+        durationLabel: '1:42:08',
+        thumbnail: undefined,
+        formats: [
+          { id: '__best__', label: 'Best available', ext: 'mp4', hasAudio: true },
+          {
+            id: '299',
+            label: '1080p60 · mp4 · 248 MB',
+            height: 1080,
+            ext: 'mp4',
+            filesizeLabel: '248 MB',
+            hasAudio: false
+          },
+          {
+            id: '136',
+            label: '720p · mp4 · 124 MB',
+            height: 720,
+            ext: 'mp4',
+            filesizeLabel: '124 MB',
+            hasAudio: false
+          },
+          {
+            id: '135',
+            label: '480p · mp4 · 72 MB',
+            height: 480,
+            ext: 'mp4',
+            filesizeLabel: '72 MB',
+            hasAudio: false
+          },
+          {
+            id: '134',
+            label: '360p · mp4 · 38 MB',
+            height: 360,
+            ext: 'mp4',
+            filesizeLabel: '38 MB',
+            hasAudio: false
+          }
+        ]
+      }
+    }
+  },
+  startDownload: async () => ({ ok: true }),
+  cancelDownload: async () => {},
+  pauseDownload: async () => {},
+  chooseFolder: async () => null,
+  openPath: async () => '',
+  openUrl: async () => {},
+  showInFolder: async () => {},
+  readClipboard: async () => '',
+  getSettings: async () => MOCK_SETTINGS,
+  setSettings: async (partial) => Object.assign(MOCK_SETTINGS, partial),
+  listHistory: async () => [],
+  addHistory: async () => [],
+  removeHistory: async () => [],
+  removeManyHistory: async () => [],
+  clearHistory: async () => [],
+  cookiesLogin: async () => {
+    await new Promise((r) => setTimeout(r, 600)) // simulate the sign-in window
+    mockCookiesSavedAt = Date.now()
+    return { ok: true, cookieCount: 14 }
+  },
+  cookiesStatus: async () =>
+    mockCookiesSavedAt ? { exists: true, savedAt: mockCookiesSavedAt } : { exists: false },
+  cookiesClear: async () => {
+    mockCookiesSavedAt = null
+  },
+  listTemplates: async () => mockTemplates,
+  saveTemplate: async (template) => {
+    mockTemplates = [template, ...mockTemplates.filter((t) => t.id !== template.id)]
+    return mockTemplates
+  },
+  removeTemplate: async (id) => {
+    mockTemplates = mockTemplates.filter((t) => t.id !== id)
+    return mockTemplates
+  },
+  previewCommand: async (opts) => {
+    await new Promise((r) => setTimeout(r, 300)) // simulate the main-process round-trip
+    const extra = opts.extraArgs ? ` ${opts.extraArgs}` : ''
+    const dir = opts.kind === 'audio' ? MOCK_SETTINGS.audioDir : MOCK_SETTINGS.videoDir
+    return {
+      ok: true,
+      command: `yt-dlp.exe -f "bv*+ba/b" -o "${dir}\\%(title)s.%(ext)s"` + `${extra} -- ${opts.url}`
+    }
+  },
+  updateYtdlp: async (channel) => {
+    await new Promise((r) => setTimeout(r, 600)) // simulate the self-update run
+    return {
+      ok: true,
+      output: `yt-dlp is already up to date (channel: ${channel}, UI preview mock)`
+    }
+  },
+  // No background updater in the browser preview — hand back an inert unsubscribe.
+  onYtdlpAutoUpdateStatus: () => () => {},
+  listErrorLog: async () => [],
+  clearErrorLog: async () => [],
+  exportBackup: async () => ({
+    ok: true,
+    path: 'C:\\Users\\you\\Downloads\\aerofetch-backup.json'
+  }),
+  importBackup: async () => ({ ok: true }),
+  onDownloadEvent: () => () => {},
+  getSystemTheme: async () => ({
+    shouldUseDarkColors: false,
+    shouldUseHighContrastColors: false
+  }),
+  onSystemThemeUpdate: () => () => {},
+  openHighContrastSettings: async () => {},
+  onExternalUrl: () => () => {},
+  // Media-manager sources — a seeded channel so the (Phase H) Library view has
+  // demo data in this browser-only preview.
+  listSources: async () => [
+    {
+      id: 'src-demo',
+      url: 'https://www.youtube.com/@DevChannel',
+      kind: 'channel',
+      title: 'DevChannel',
+      channel: 'DevChannel',
+      addedAt: Date.now() - 86_400_000,
+      lastIndexedAt: Date.now() - 3_600_000,
+      itemCount: 7
+    }
+  ],
+  indexSource: async (url) => {
+    await new Promise((r) => setTimeout(r, 800)) // simulate the index walk
+    return {
+      ok: true,
+      source: {
+        id: 'src-demo',
+        url,
+        kind: 'channel',
+        title: 'DevChannel',
+        channel: 'DevChannel',
+        addedAt: Date.now(),
+        lastIndexedAt: Date.now(),
+        itemCount: 7
+      },
+      itemCount: 7
+    }
+  },
+  reindexSource: async () => ({ ok: true, itemCount: 7, newCount: 0 }),
+  removeSource: async () => [],
+  markSourceItemDownloaded: async () => [],
+  setSourceWatched: async () => [],
+  syncSources: async () => ({ ok: true, newItems: [] }),
+  getScheduledSync: async () => ({ enabled: false }),
+  setScheduledSync: async (enabled: boolean) => ({ enabled }),
+  listSourceItems: async (sourceId) =>
+    Array.from({ length: 7 }, (_, i) => ({
+      id: `${sourceId}:vid${i + 1}`,
+      sourceId,
+      videoId: `vid${i + 1}`,
+      title: `Episode ${i + 1}`,
+      url: `https://youtube.com/watch?v=vid${i + 1}`,
+      playlistTitle: i < 5 ? 'Full Electron Course' : 'Uploads',
+      playlistIndex: i < 5 ? i + 1 : i - 4,
+      durationLabel: `${10 + i}:0${i}`,
+      downloaded: i < 2
+    })),
+  onIndexProgress: () => () => {},
+  runTerminal: async () => ({ ok: true }),
+  cancelTerminal: async () => {},
+  onTerminalOutput: () => () => {},
+  setTaskbarProgress: async () => {},
+  mintPoToken: async () => null
+}
@@ -0,0 +1,48 @@
+import type { AddEntry } from './downloads'
+
+/**
+ * A tiny typed event bus that owns the cross-store reactions between the
+ * downloads and sources stores (C2). Previously `downloads.ts` imported
+ * `useSources` and `sources.ts` imported `useDownloads`, a circular dependency
+ * that only worked because both sides reached across lazily via `.getState()`.
+ *
+ * Now each store depends on this bus instead of on the other: a store *emits* the
+ * events it produces and *subscribes* to the ones it consumes. The bus itself has
+ * no runtime dependency on either store (the `AddEntry` import is type-only and is
+ * erased at build time), so there is no import cycle.
+ *
+ *   sources  --enqueueDownloads-->  downloads   (queue a channel's media items)
+ *   downloads --downloadCompleted--> sources    (mark the source item downloaded)
+ */
+export interface StoreEvents {
+  /** sources → downloads: enqueue a batch of media items as downloads */
+  enqueueDownloads: AddEntry[]
+  /** downloads → sources: a download tied to a source MediaItem finished */
+  downloadCompleted: { mediaItemId: string; filePath?: string }
+}
+
+type Handler<K extends keyof StoreEvents> = (payload: StoreEvents[K]) => void
+
+// Heterogeneous handler sets keyed by event name. The `never` payload is the
+// standard trick for a per-key event map; the public on/emit signatures keep the
+// payload types sound at every call site.
+const handlers = new Map<keyof StoreEvents, Set<(payload: never) => void>>()
+
+/** Subscribe to a store event. Returns an unsubscribe function. */
+export function on<K extends keyof StoreEvents>(event: K, handler: Handler<K>): () => void {
+  let set = handlers.get(event)
+  if (!set) {
+    set = new Set()
+    handlers.set(event, set)
+  }
+  const erased = handler as (payload: never) => void
+  set.add(erased)
+  return () => set.delete(erased)
+}
+
+/** Dispatch a store event to all current subscribers. */
+export function emit<K extends keyof StoreEvents>(event: K, payload: StoreEvents[K]): void {
+  const set = handlers.get(event)
+  if (!set) return
+  for (const handler of set) (handler as Handler<K>)(payload)
+}
@@ -6,9 +6,10 @@ import {
  type CollectionContext,
  type MediaKind
 } from '@shared/ipc'
+import { isPreview as PREVIEW } from '../isPreview'
 import { useSettings } from './settings'
 import { useHistory } from './history'
-import { useSources } from './sources'
+import { emit, on } from './coordinator'
 import { newId } from '../id'

 // Single-sourced from the IPC contract (L105) and re-exported so existing
@@ -99,10 +100,6 @@ export interface AddEntry {
  opts?: AddOptions
 }

-// True when running in the standalone browser preview (no Electron preload).
-// The real preload injects window.electron; the browser stub does not.
-const PREVIEW = typeof window === 'undefined' || !window.electron
-
 interface DownloadState {
  items: DownloadItem[]
  addFromUrl: (url: string, kind: MediaKind, quality: string, opts?: AddOptions) => void
@@ -274,7 +271,9 @@ function recordCompletion(item: DownloadItem): void {
    })
  }
  if (item.mediaItemId) {
-    useSources.getState().markDownloaded(item.mediaItemId, item.filePath)
+    // Tell the sources store to mark its MediaItem downloaded — via the event bus
+    // rather than a direct import, so downloads and sources don't form a cycle (C2).
+    emit('downloadCompleted', { mediaItemId: item.mediaItemId, filePath: item.filePath })
  }
 }

@@ -628,6 +627,11 @@ export const useDownloads = create<DownloadState>((set, get) => {
  }
 })

+// Consume the sources store's enqueue requests (C2): when the user downloads a
+// channel's media items, sources emits the batch on the bus and we add it here —
+// no direct import from sources, so the two stores stay acyclic.
+on('enqueueDownloads', (entries) => useDownloads.getState().addMany(entries))
+
 // Promote scheduled ('saved' + a due scheduledFor) items when their time arrives.
 // Session-only: the queue isn't persisted, so a schedule only fires while the app
 // runs (noted in ROADMAP.md). A 15s tick is plenty for minute-granularity times.
@@ -1,10 +1,8 @@
 import { create } from 'zustand'
 import type { ErrorLogEntry } from '@shared/ipc'
+import { isPreview as PREVIEW } from '../isPreview'
 import { logError } from '../reportError'

-// True in the standalone browser preview (no Electron preload).
-const PREVIEW = typeof window === 'undefined' || !window.electron
-
 // Sample entries so the Diagnostics card has content during UI design.
 const seed: ErrorLogEntry[] = PREVIEW
  ? [
@@ -1,10 +1,8 @@
 import { create } from 'zustand'
-import type { HistoryEntry } from '@shared/ipc'
+import { HISTORY_MAX_ENTRIES, type HistoryEntry } from '@shared/ipc'
+import { isPreview as PREVIEW } from '../isPreview'
 import { logError } from '../reportError'

-// True in the standalone browser preview (no Electron preload).
-const PREVIEW = typeof window === 'undefined' || !window.electron
-
 // Mock history so the History tab has content during UI design.
 const seed: HistoryEntry[] = PREVIEW
  ? [
@@ -44,6 +42,10 @@ const seed: HistoryEntry[] = PREVIEW
    ]
  : []

+// Cap the optimistic in-memory list at the same shared limit main persists to
+// (HISTORY_MAX_ENTRIES) so a long session can't grow it past what a reload would
+// show (L141). De-duping by url as well as id keeps it consistent with main's add
+// (M35), so the optimistic list matches the reload.
 interface HistoryState {
  entries: HistoryEntry[]
  add: (entry: HistoryEntry) => void
@@ -58,7 +60,12 @@ export const useHistory = create<HistoryState>((set, get) => ({
  entries: seed,

  add: (entry) => {
-    set((s) => ({ entries: [entry, ...s.entries.filter((e) => e.id !== entry.id)] }))
+    set((s) => ({
+      entries: [entry, ...s.entries.filter((e) => e.id !== entry.id && e.url !== entry.url)].slice(
+        0,
+        HISTORY_MAX_ENTRIES
+      )
+    }))
    if (!PREVIEW) window.api.addHistory(entry).catch(logError('addHistory'))
  },

@@ -1,48 +1,22 @@
 import { create } from 'zustand'
-import { DEFAULT_DOWNLOAD_OPTIONS, type Settings } from '@shared/ipc'
+import { DEFAULT_SETTINGS, type Settings } from '@shared/ipc'
+import { isPreview as PREVIEW } from '../isPreview'
 import { logError } from '../reportError'

-// True in the standalone browser preview (no Electron preload).
-const PREVIEW = typeof window === 'undefined' || !window.electron
-
-const FALLBACK: Settings = {
-  videoDir: PREVIEW ? 'C:\\Users\\you\\Documents\\Video' : '',
-  audioDir: PREVIEW ? 'C:\\Users\\you\\Documents\\Audio' : '',
-  defaultKind: 'video',
-  defaultVideoQuality: 'Best available',
-  defaultAudioQuality: 'Best',
-  maxConcurrent: 2,
-  filenameTemplate: '%(title)s.%(ext)s',
-  // Mirror main's DEFAULTS (SR1): follow the OS theme until real settings load,
-  // so there's no white-on-first-paint flash for a dark-mode user.
-  theme: 'system',
-  accentColor: 'teal',
-  clipboardWatch: true,
-  downloadOptions: DEFAULT_DOWNLOAD_OPTIONS,
-  proxy: '',
-  rateLimit: '',
-  useAria2c: false,
-  cookieSource: 'none',
-  cookiesBrowser: 'chrome',
-  youtubePlayerClient: '',
-  youtubePoToken: '',
-  restrictFilenames: false,
-  downloadArchive: false,
-  autoUpdateYtdlp: true,
-  ytdlpChannel: 'stable',
-  ytdlpLastUpdateCheck: 0,
-  customCommandEnabled: false,
-  defaultTemplateId: null,
-  notifyOnComplete: true,
-  autoDownloadNew: false,
-  // True in preview so design work isn't blocked behind the welcome screen;
-  // a real first launch gets `false` from main/settings.ts's DEFAULTS instead.
-  hasCompletedOnboarding: PREVIEW,
-  minimizeToTray: false,
-  launchAtStartup: false,
-  sidebarCollapsed: false,
-  updateToken: ''
-}
+// The pre-load fallback is the canonical DEFAULT_SETTINGS (single-sourced from the
+// shared contract, C1) — including theme:'system' (SR1) so there's no white-on-
+// first-paint flash for a dark-mode user before the real settings arrive. In the
+// browser preview a couple of fields differ: placeholder folder paths, and
+// onboarding pre-dismissed so design work isn't blocked behind the welcome screen
+// (a real first launch keeps DEFAULT_SETTINGS' false from main).
+const FALLBACK: Settings = PREVIEW
+  ? {
+      ...DEFAULT_SETTINGS,
+      videoDir: 'C:\\Users\\you\\Documents\\Video',
+      audioDir: 'C:\\Users\\you\\Documents\\Audio',
+      hasCompletedOnboarding: true
+    }
+  : DEFAULT_SETTINGS

 interface SettingsState extends Settings {
  /** true once persisted settings have loaded (always true in preview) */
@@ -1,12 +1,10 @@
 import { create } from 'zustand'
 import type { Source, MediaItem, IndexProgress, MediaKind } from '@shared/ipc'
-import { useDownloads } from './downloads'
+import { isPreview as PREVIEW } from '../isPreview'
 import { useSettings } from './settings'
+import { emit, on } from './coordinator'
 import { logError } from '../reportError'

-// True in the standalone browser preview (no Electron preload).
-const PREVIEW = typeof window === 'undefined' || !window.electron
-
 // --- Preview seed data ------------------------------------------------------

 function seedItems(sourceId: string, playlist: string, n: number, downloadedUpTo = 0): MediaItem[] {
@@ -185,8 +183,11 @@ export const useSources = create<SourcesState>((set, get) => ({
    // Per-batch override (Library video/audio toggle) falls back to the global default (M27).
    const kind = kindOverride ?? settings.defaultKind
    const quality = kind === 'video' ? settings.defaultVideoQuality : settings.defaultAudioQuality
-    // One batched state update + pump, so queuing a whole channel stays O(n).
-    useDownloads.getState().addMany(
+    // Hand the batch to the downloads store via the event bus (C2) rather than a
+    // direct import. addMany applies it as one batched state update + pump, so
+    // queuing a whole channel stays O(n).
+    emit(
+      'enqueueDownloads',
      items.map((it) => ({
        url: it.url,
        kind,
@@ -268,6 +269,12 @@ export const useSources = create<SourcesState>((set, get) => ({
  }
 }))

+// When a download tied to one of our MediaItems finishes, the downloads store
+// emits this on the bus (C2) — mark the item downloaded so the library reflects it.
+on('downloadCompleted', ({ mediaItemId, filePath }) =>
+  useSources.getState().markDownloaded(mediaItemId, filePath)
+)
+
 // Load persisted sources on startup, and subscribe to live indexing progress.
 if (!PREVIEW) {
  window.api
@@ -1,10 +1,8 @@
 import { create } from 'zustand'
 import type { SystemThemeInfo } from '@shared/ipc'
+import { isPreview as PREVIEW } from '../isPreview'
 import { useSettings } from './settings'

-// True in the standalone browser preview (no Electron preload).
-const PREVIEW = typeof window === 'undefined' || !window.electron
-
 const prefersDark =
  typeof window !== 'undefined' && window.matchMedia
    ? window.matchMedia('(prefers-color-scheme: dark)')
@@ -1,10 +1,8 @@
 import { create } from 'zustand'
 import type { CommandTemplate } from '@shared/ipc'
+import { isPreview as PREVIEW } from '../isPreview'
 import { logError } from '../reportError'

-// True in the standalone browser preview (no Electron preload).
-const PREVIEW = typeof window === 'undefined' || !window.electron
-
 // Sample templates so the Settings tab has content during UI design.
 const seed: CommandTemplate[] = PREVIEW
  ? [