# Instant providers

Instant providers turn the current query into temporary, actionable rows. They
run alongside fuzzy menu search; they do not replace or mutate the underlying
Omarchy menu model.

## Contract

`InstantProviders.requestsForQuery(query)` returns zero or more declarative
requests. A request contains a provider ID, the original query, display detail,
provider-specific metadata, and a command represented as an argument array.
Commands must never be assembled into a shell string.

When a process finishes, `InstantProviders.resultRow(...)` validates and cleans
its output and returns either a complete display-model row or `null`. Instant
rows must include `kind: "instant"` and a `copyText` value. The existing UI can
then render, select, and activate the result without provider-specific layout
code.

## Lifecycle

1. A query change increments a revision and clears previous instant results.
2. Recognized requests wait for a 90 ms debounce.
3. Work executes asynchronously through `Quickshell.Io.Process`.
4. A newer query stops the current process; revision checks discard any late
   output.
5. Valid results are prepended to the ordinary fuzzy matches.
6. Enter copies the selected result with `wl-copy` and closes the launcher.

The queue is intentionally generic even though version 0.5 ships with one
provider. Future providers can reuse the same cancellation and display path.

## Calculator provider

The calculator uses `qalc` in terse, colorless mode. Conservative intent
detection recognizes clear arithmetic, percentages, and `to`/`in`
conversions. A leading `=` explicitly opts any query into calculation.

Currency conversion is the only request with preparation work. The launcher
attempts `qalc -e` once per shell session and caps that refresh at four seconds.
The refresh runs in parallel while the visible calculation immediately uses
`qalc`'s cached exchange rates, so network availability never gates a result.

## Adding a provider

- Keep intent detection conservative so ordinary launcher searches are not
  hijacked.
- Return argument arrays and never invoke a shell for user-authored input.
- Put output parsing and row construction in `InstantProviders.js` so it stays
  unit-testable outside QML.
- Use a distinct provider ID and stable `itemId`.
- Add provider-specific activation only when the generic `copyText` behavior is
  insufficient.
- Add intent, request-safety, parsing, and result-row tests before deployment.

An AI provider should build on this contract but remain explicitly invoked
(for example with `?`) and should add timeout, privacy, and error-state rules
before any network request is introduced.