---
type: decision
adr: 002
status: accepted
date: 2026-10-17
supersedes: 
tags: [adr, plugins, architecture]
---

# ADR-002: three-phase extension architecture (TOML → scripts → Lua)

## Context
viexp must let Linux users disable, replace and add file-type behaviors easily. Research
([[research/plugin-architecture]]) shows: declarative rules carry configuration, external
process contracts carry ~90% of real-world extension, and embedded interpreters are the most
expensive layer to stabilize (yazi is still "beta" partly because of it). WASM (zellij) costs
host complexity that a single-maintainer learning project cannot afford.

## Options considered
| Option | Pros | Cons |
|--------|------|------|
| Phased: TOML rules → script contract → Lua (mlua) | each phase shippable; users' language of choice; no unsafe early | three layers to document eventually |
| Lua from day 1 | yazi-grade power early | API design + FFI before first working product; high frustration risk |
| WASM components (wasmtime/extism) | best sandboxing | WIT churn, users must compile components; zellij-scale effort |
| External-only | simplest | no stateful in-process previews/fetchers ever |

## Decision (confirmed with the project owner, 2026-10-17)
1. **v0.1 — declarative registry**: `modules.toml` maps mime/glob → previewer/opener; per-module
   `enabled` switch; user rules merge via `prepend_*`/`append_*` (yazi semantics). All built-in
   modules dispatch through the same tables.
2. **v0.2 — external process contract (frozen, documented)**: previewer argv = `(path, width,
   height, x, y)`; env context (mime, selection file, session dir); write-back via FIFO/socket
   (nnn-style opcodes); `cleaner` hook; documented exit codes + SIGPIPE semantics.
   Reference plugins in bash and Python ship in-repo.
3. **v1.0+ — embedded Lua** via **mlua with vendored Lua**, registered through the same tables;
   only for what scripts cannot do (stateful/in-process previews). Re-evaluate Luau if sandbox
   isolation becomes a requirement. **WASM is explicitly rejected for v1.x.**

## Consequences
- Positive: shippable increments; extension by Linux-familiar means; Lua postponed until the
  host API is stable enough to expose.
- Negative: three layers of documentation eventually; write-back protocol must be designed
  carefully once and frozen.
- Mitigations: one dispatch model for all layers (yazi lesson); contract docs written as part
  of the v0.2 sprint DoD, not after.