viexp/docs/decisions/ADR-003-file-type-modules.md

type, adr, status, date, supersedes, tags

type	adr	status	date	supersedes	tags
decision	003	accepted	2026-10-17		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.