Files
SubMiner/docs/architecture/layering.md
T
sudacode 2a0e931325 refactor(main): drop pass-through main-deps builders (#306)
* refactor(main): drop mining/anki main-deps builders

* refactor(anilist): drop main-deps builders

* refactor(jellyfin): drop main-deps builders

* refactor(overlay): drop overlay and shortcut main-deps builders

* refactor(main): drop ipc, tray, and osd main-deps builders

* refactor(startup): drop startup main-deps builders

* test(scripts): ignore stray local requests in AUR download test

Also apply prettier to launcher/mpv.test.ts so format:check:src passes.

* fix(shortcuts): forward overlay numeric selection hooks through the composer

composeShortcutRuntimes only passed the digit callbacks, so the visible-overlay
selection added in #78 never ran from the multi-copy/mine-sentence shortcuts.

* fix(stats): skip mpv auto-connect when stats starts the immersion tracker

The immersion-startup main-deps builder never forwarded shouldAutoConnectMpv,
so background stats and stats CLI startup always connected to mpv. Drop the
builder and pass the deps straight to the handler.

* build(deps): bump follow-redirects override to 1.16.2

Resolves GHSA-mrwp-f3q8-3g9p (high), which fails the quality-gate
bun audit --audit-level high step.

* test(subtitles): cover the null-tokenization settle path in prefetch test

The mock ignored the value the test resolved, so the null case never ran.

* test(e2e): surface mpv crashes and install current mpv on macOS CI

The harness IPC client never handled socket close, so a crashed mpv left
commands pending until the 120s test timeout with an empty mpv.log. Reject
pending commands on close, write mpv's own log via --log-file, and refresh
Homebrew on macOS CI so the installed mpv build no longer depends on the
runner image.

* test(e2e): render mpv through cocoa-cb OpenGL on macOS

mpv 0.41.0_12 with libplacebo 7.387.0 segfaults in gpu-next's MoltenVK path
on GitHub's paravirtual macOS GPU on the first frame, so the E2E session
never started.

* test(e2e): name mpv-stdio.log in the mpv close diagnostic
2026-10-31 00:50:33 -07:00

1.5 KiB

Layering Rules

Status: active
Last verified: 2026-05-23
Owner: Kyle Yasuda
Read when: deciding whether a dependency direction is acceptable

Preferred Dependency Flow

  1. src/main.ts
  2. src/main/ composition and runtime adapters
  3. src/core/services/ focused services
  4. src/core/utils/ and other pure helpers

Renderer, launcher, plugin, and stats each keep their own local layering and should not become a grab bag for unrelated cross-runtime behavior.

Rules

  • Keep src/main.ts thin; wire, do not implement.
  • Pass deps straight to a handler factory (createXHandler({...})). Do not add *-main-deps.ts builders that only re-wrap deps; existing ones are being removed.
  • Prefer injecting dependencies from src/main/ instead of reaching outward from core services.
  • Keep side effects explicit and close to composition boundaries.
  • Put reusable business logic in focused services, not in top-level lifecycle files.
  • Keep renderer concerns in src/renderer/; avoid leaking DOM behavior into main-process code.
  • Treat launcher/*.ts and the runtime bootstrap generators as source of truth for launcher behavior. scripts/build-launcher.ts creates dist/launcher; never hand-edit those artifacts.

Smells

  • main.ts grows because logic was not extracted
  • service reaches directly into unrelated runtime state
  • renderer code depends on main-process internals
  • docs-site page becomes the only place internal architecture is explained