Rewritten 2026-11-14 to the shipped launcher (owner decision, Zen of Nugu); calculator, clipboard, and window providers are out of scope until a follow-up spec adds them.
Ranking revised 2026-11-14 (owner decision): match tiers replace loose subsequence matching, and frecency replaces usage-blind ranking.
Query lifetime revised 2026-11-14 (owner decision): a launch clears the query; dismissal keeps it, selected.
Behavior
The launcher searches installed applications from their desktop entries.
The search field takes focus on open.
Closing without a launch (Escape, outside click, the chip, switching popups) keeps the query and selection; the next open restores the query fully selected, so typing replaces it and Enter launches the selected match.
A successful launch, app or desktop action, clears the query and selection; the next open starts empty and lists frecent apps first.
Query and app text are matched case- and accent-folded; every query word must match, and an app's tier is its weakest word's tier.
Name tiers rank exact, prefix, word start, substring, initials, then a tight fuzzy match with a gap cut-off; generic name, keywords, categories, comment, and desktop id match only at word starts and rank below every name match.
Within a tier, frecency ranks first, then match quality, then title; frecency never lifts an app across tiers.
Frecency adds 1 per launch, desktop actions included, to a score that halves every 7 days, stored under the Quickshell state path.
Empty queries list frecent applications by frecency, then the rest in title order.
The result list shows each application's themed icon, with a glyph fallback, its name, and a concise lowercase subtitle.
A side pane shows the selected application's icon and actions: open and its desktop actions; desktop-entry facts sit behind a details disclosure that keeps its state.
Up and down change selection; Enter opens the selected application; Ctrl plus a number runs that desktop action; launching closes the popup.
No match shows no apps match "<query>" with clear search; no installed applications shows no apps found.
Constraints
Launch records remain telemetry; only frecency affects ranking.
Matching data is precomputed once per app-list change, never per keystroke.
Public IPC follows NL-SPEC-86A037A0; launcher panel intents pass row objects directly to the typed service.
Search responses expose functional state without view narration.
Acceptance
Pure checks prove tiers, multi-word and accent matches, misses, frecency decay, order, and persistence, with top results pinned on an installed-apps snapshot.
Pure launcher tests, isolated production-service checks, and the launcher interaction suite pass.
The launcher suite proves keyboard and pointer launch, desktop actions, both empty states, the details disclosure, frecency order on reopen, a kept query that typing replaces after dismissal, and an empty field after every kind of launch.
The launcher has no decorative bottom stripe.
---
id: NL-SPEC-F3E26F58
type: spec
title: Launcher popup
---
# Launcher popup
Rewritten 2026-11-14 to the shipped launcher (owner decision, Zen of Nugu); calculator, clipboard, and window providers are out of scope until a follow-up spec adds them.
Ranking revised 2026-11-14 (owner decision): match tiers replace loose subsequence matching, and frecency replaces usage-blind ranking.
Query lifetime revised 2026-11-14 (owner decision): a launch clears the query; dismissal keeps it, selected.
## Behavior
- The launcher searches installed applications from their desktop entries.
- The search field takes focus on open.
- Closing without a launch (Escape, outside click, the chip, switching popups) keeps the query and selection; the next open restores the query fully selected, so typing replaces it and Enter launches the selected match.
- A successful launch, app or desktop action, clears the query and selection; the next open starts empty and lists frecent apps first.
- Query and app text are matched case- and accent-folded; every query word must match, and an app's tier is its weakest word's tier.
- Name tiers rank exact, prefix, word start, substring, initials, then a tight fuzzy match with a gap cut-off; generic name, keywords, categories, comment, and desktop id match only at word starts and rank below every name match.
- Within a tier, frecency ranks first, then match quality, then title; frecency never lifts an app across tiers.
- Frecency adds 1 per launch, desktop actions included, to a score that halves every 7 days, stored under the Quickshell state path.
- Empty queries list frecent applications by frecency, then the rest in title order.
- The result list shows each application's themed icon, with a glyph fallback, its name, and a concise lowercase subtitle.
- A side pane shows the selected application's icon and actions: `open` and its desktop actions; desktop-entry facts sit behind a `details` disclosure that keeps its state.
- Up and down change selection; Enter opens the selected application; Ctrl plus a number runs that desktop action; launching closes the popup.
- No match shows `no apps match "<query>"` with `clear search`; no installed applications shows `no apps found`.
## Constraints
- Launch records remain telemetry; only frecency affects ranking.
- Matching data is precomputed once per app-list change, never per keystroke.
- Public IPC follows `NL-SPEC-86A037A0`; launcher panel intents pass row objects directly to the typed service.
- Search responses expose functional state without view narration.
## Acceptance
- Pure checks prove tiers, multi-word and accent matches, misses, frecency decay, order, and persistence, with top results pinned on an installed-apps snapshot.
- Pure launcher tests, isolated production-service checks, and the launcher interaction suite pass.
- The launcher suite proves keyboard and pointer launch, desktop actions, both empty states, the details disclosure, frecency order on reopen, a kept query that typing replaces after dismissal, and an empty field after every kind of launch.
- The launcher has no decorative bottom stripe.