Module lua_api 

Lua scripting API (v1, via mlua).

Exposes on_select, on_enter_dir, and register_action hooks to Lua scripts. Hooks are registered during plugin load; Trail fires them at appropriate runtime moments via the fire_* methods.

Hook Contract

Each loaded plugin is a Lua chunk executed once at load time. The chunk calls trail.on_select(fn), trail.on_enter_dir(fn), or trail.register_action(name, fn) to register callbacks. Trail fires those callbacks by calling fire_on_select, fire_on_enter_dir, or fire_action.

Hook errors are logged at debug level and never propagate — a misbehaving plugin must not crash the application.

Lifetime notes

mlua::Function carries a 'lua lifetime bound to the Lua instance. We store callbacks using mlua::RegistryKey instead, which is 'static and keeps the value alive as long as the Lua state exists.

Structs

PluginEngine

The v1 plugin engine: an embedded Lua interpreter with Trail’s hook API.

Enums

PluginError

Errors that can arise when loading or running Lua plugins.