smelt.lifecycle¶
Tier: Host - Available in every runtime, including headless mode.
Classification: Supported - Primary alpha facade for user config and plugins.
Host-phase hooks keyed by event name. on(event, fn) is the general form; on_ready / on_shutdown are shorthands. on_ready fires after each generation is committed (cold start and /reload) with ctx = { kind = "launch" | "reload" }; use it for work that requires committed runtime state or current layout. Normal configuration and plugin bodies already have UiHost access. on_shutdown fires once on graceful process exit. The registry is wiped between generations - re-register the hook in module body if you want it to fire every time. Each on* returns a Reg whose :remove() unregisters the hook before it fires.
smelt.lifecycle.guard¶
Types: smelt.lifecycle.Guard
Create a guard whose :alive() flips false when any scoped epoch changes.
Scopes are "session", "history", "input", or a concrete signal name.
Use :latest(key) when only the newest request in a family may complete.
smelt.lifecycle.on¶
Types: smelt.Reg
Queue fn(ctx) for the lifecycle event named event. Multiple hooks per event fire in registration order. Emitted events: "ready" (after launch and after each /reload; ctx = { kind = "launch" | "reload" }) and "shutdown" (after the TUI tears down, before process exit; ctx = { session_id, has_messages, ephemeral }). Returns a Reg whose :remove() unregisters the hook before it fires; calling :remove() after the hook has already fired is a no-op returning false.
smelt.lifecycle.on_ready¶
Types: smelt.Reg
Shorthand for lifecycle.on("ready", fn). The host calls fn(ctx) after generation zero commits (ctx.kind = "launch") and after every successful /reload (ctx.kind = "reload"). The full UiHost-tier surface is also available while normal configuration and plugin bodies load; use this hook specifically for work that requires committed runtime state or current layout. The registry is wiped between generations, so re-registering this hook at module top is the correct way to make it fire every cycle. Prefer plain module body for declarations and callback registration. Returns a Reg whose :remove() unregisters the hook before it fires.
smelt.lifecycle.on_shutdown¶
Types: smelt.Reg
Shorthand for lifecycle.on("shutdown", fn). The host calls fn(ctx) once after the TUI tears down, before the process exits. Stdout is cooked at that point so print writes land in the user's terminal scrollback. ctx = { session_id: string, has_messages: boolean, ephemeral: boolean }. Hooks fire on graceful exit paths, including handled interrupt and termination signals. Returns a Reg whose :remove() unregisters the hook before shutdown fires.