---
type: decision
adr: 003
status: accepted
date: 2026-10-17
supersedes: 
tags: [adr, modules, config]
---

# ADR-003: file-type modules are registry entries, disableable at runtime

## Context
Requirement: images, video, audio, PDF, DJVU, EPUB and Markdown previews work out of the box,
but a user can disable or replace any of them without recompiling. Cargo features alone fail
this: feature unification breaks packagers, and removing a default feature is a breaking
change ([[research/plugin-architecture]]).

## Options considered
| Option | Pros | Cons |
|--------|------|------|
| Runtime registry + per-module `enabled` flag (+ optional cargo features for binary size) | one-line disable; replaceable by script rule; packager-safe | slightly larger default binary |
| Cargo features only | smallest binaries | recompile to disable; unification traps; breaking-change semantics |
| Everything external scripts (ranger scope.sh model) | max flexibility | out-of-box experience degrades; 700-line bash nobody dares edit |

## Decision
Every file-type capability is a **module** registered in a TOML registry:
`name`, `match` (mime/glob), `previewer` (built-in id or external command), `opener`,
`enabled` (default true). Precedence: user rules → built-in rules, with `prepend_/append_`
merge. Built-in implementations live behind additive cargo features (default-on: `image`,
`pdf`, `media`, …) purely to trim binaries; a feature-disabled module degrades to a TOML rule
pointing at an external tool (e.g. `pdftotext`) instead of disappearing.

## Consequences
- Positive: `enabled = false` in one line; third-party replacement without recompile; matches
  ADR-002 phase 1 exactly.
- Negative: two config concepts (registry + features) need clear documentation.
- Mitigations: features documented as "binary size only, not functionality"; docs page
  "Disabling and replacing modules" is part of the v0.1 docs DoD.