@leavepulse/ui 0.46.0 → 0.47.0

package/src/components/LpCommandPalette.vue

@@ -37,6 +37,7 @@ import {
   DialogTitle,
 } from "reka-ui"
 import { computed, nextTick, onBeforeUnmount, ref, shallowRef, useId, watch } from "vue"
+import LpAvatar from "./LpAvatar.vue"
 import LpIcon from "./LpIcon.vue"
 import LpScrollArea from "./LpScrollArea.vue"
 import { useAsyncTask } from "../composables/useAsyncTask"
@@ -45,7 +46,44 @@ import { useClipboard } from "../composables/useClipboard"
 import { useHotkeys } from "../composables/useHotkeys"
 import { useModalLayer } from "./modalDepth"
 import { useLabels } from "../composables/useLpConfig"
-import { parseCommandQuery, rankCommandItems } from "./commandSearch"
+import {
+  applyQueryFilters,
+  highlightParts,
+  parseCommandQuery,
+  parsePaletteQuery,
+  rankCommandItems,
+  type HighlightPart,
+  type PaletteQuery,
+} from "./commandSearch"
+import {
+  commandHasPreview,
+  fallbackRows,
+  matchModePrefix,
+  modeChipLabel,
+  pushRecent,
+  readRecent,
+  recentVisible,
+  resolveRecentItems,
+  toRecentItem,
+  type RecentEntry,
+  type RecentItem,
+} from "./commandPalette"
+
+/**
+ * A picture in a row's icon slot: an avatar, a project logo, a world's
+ * thumbnail. While it loads, and for good if it fails, the row shows
+ * `fallback` (initials) or else `icon`, so a dead link never leaves a hole.
+ */
+export interface CommandImage {
+  src?: string | null
+  alt?: string
+  /** Text shown while there is no picture, usually initials. */
+  fallback?: string
+  /** Icon shown while there is no picture; the command's `icon` when unset. */
+  icon?: string
+  /** circle for people, soft or square for things. Defaults to soft. */
+  shape?: "circle" | "soft" | "square"
+}
 
 export interface Command {
   id: string
@@ -66,6 +104,12 @@ export interface Command {
    */
   highlight?: string[]
   icon?: string
+  /**
+   * A picture in place of the icon: a URL, or a `CommandImage` with a
+   * fallback. Sized like the icon and faded in once loaded; until then, and
+   * when it fails, the fallback (or `icon`) holds the slot.
+   */
+  image?: string | CommandImage
   /** Right-aligned hint, e.g. "⌘P". */
   shortcut?: string
   /** Extra search terms not shown but matched against the query. */
@@ -86,11 +130,60 @@ export interface Command {
    * and what lets the second step search a list too big to enumerate.
    *
    * `onSelect` still runs when the mode opens, so a command can both act and
-   * drill in.
+   * drill in. A fetcher is called like `search` (see CommandFetcher): its
+   * abort signal may never reach the transport, and an answer that lands
+   * after the query moved on or the mode was left is discarded.
    */
-  children?: Command[] | ((query: string, signal: AbortSignal) => Command[] | Promise<Command[]>)
+  children?: Command[] | CommandFetcher
   /** Placeholder while inside this command's mode. */
   childPlaceholder?: string
+  /**
+   * The mode's name in the chip beside the box, when the row's label is a
+   * sentence: "Mods" for a row reading `Search mods for "{query}"`. Without
+   * it a `{query}` placeholder and its quotes are dropped from the label.
+   */
+  modeLabel?: string
+  /**
+   * Typed at the start of the box, enters this command's mode directly, and
+   * whatever follows the prefix becomes the query inside it: ">" for
+   * commands, "mr " for a mod search. Only for a command with `children`,
+   * matched against the list on screen (the root, or the open mode's own
+   * static children), longest prefix first, letters in any case. Entering
+   * this way does not run `onSelect`. The row shows the prefix as its hint
+   * when it has no `shortcut`.
+   */
+  prefix?: string
+  /**
+   * Opening this mode takes the query typed so far along, operators and
+   * all, so typing "sodium", arrowing to "Search mods" and pressing Enter
+   * opens the mod search already searching for sodium instead of starting
+   * it empty. Backspace out of the mode restores the query as it was.
+   */
+  carryQuery?: boolean
+  /**
+   * A "search somewhere else" row: listed only while words are typed, for
+   * any words (it is not matched against them), after local and fetched
+   * results: at the end of the list, or of its group when that group is
+   * already listed. `{query}` in the label becomes the
+   * typed words without the operators, `Search Modrinth for "{query}"`;
+   * `-word` and `in:group` still apply to the row's own label, keywords and
+   * group. Usually a mode with `carryQuery`, so picking it runs the search.
+   */
+  fallback?: boolean
+  /**
+   * Keep this out of the recent history. Picks are remembered wherever they
+   * are made, inside modes and among fetched results too; a pick that is a
+   * setting rather than a destination (a language, a zoom step) can opt out.
+   * Rows offered by Tab (`actions`) are never remembered.
+   */
+  remember?: boolean
+  /**
+   * A JSON-safe value stored with this command in the recent history and
+   * handed back to `resolveRecent`: what an app needs to rebuild a result
+   * that a search fetched (a project id, a hit), since the command's
+   * functions cannot be stored.
+   */
+  recentData?: unknown
   /**
    * Keep the palette open after this runs. For a command that toggles
    * something the user may want to toggle again (a theme, a filter) without
@@ -118,9 +211,41 @@ export interface Command {
    * breaks are kept. Without it the pane shows the `excerpt`.
    */
   preview?: string
+  /**
+   * This row has nothing for the pane, even with a `#preview` slot: the pane
+   * folds away while it is highlighted instead of the slot having to draw a
+   * placeholder. For a whole class of rows, `hasPreview` says it once.
+   */
+  noPreview?: boolean
   onSelect?: () => void
 }
 
+/**
+ * Commands fetched for a query: `search` at the root, a function `children`
+ * inside a mode.
+ *
+ * `query` is the box's positive words only, in the case they were typed:
+ * `sodium -forge in:mods` arrives as "sodium", because a server would treat
+ * the operators as words to find. They come in `parsed` instead (a
+ * PaletteQuery: `raw`, `text`, lowercased `include`, `exclude` and `groups`)
+ * for a provider that can scope or exclude on its side; either way the
+ * palette drops returned rows that match an exclusion or miss an `in:` scope.
+ *
+ * `signal` aborts when the query moves on, the mode is left or the palette
+ * closes. It is a courtesy, not a guarantee: hand it to `fetch` and the
+ * request is cancelled, but a transport that cannot be cancelled (a Tauri
+ * `invoke`, a worker message, most SDKs) never sees it and runs to the end.
+ * That is safe: an answer that lands after a newer request was made, or
+ * after the palette closed, is discarded and never reaches the list, so a
+ * fetcher does not need to check the signal itself. Checking it before an
+ * expensive step is only a saving.
+ */
+export type CommandFetcher = (
+  query: string,
+  signal: AbortSignal,
+  parsed: PaletteQuery,
+) => Command[] | Promise<Command[]>
+
 /** Footer hints and the mode chip, spelled out so an app can translate them. */
 export type PaletteLabels = {
   navigate: string
@@ -165,28 +290,46 @@ const props = withDefaults(
      * (or too remote) to hand over as a list: people, files, tickets. Called
      * debounced, never for a query shorter than `minChars`, and only its
      * newest call counts: an earlier one that lands late is dropped, so a slow
-     * response can't overwrite a fresher list.
+     * response can't overwrite a fresher list. The abort signal may never
+     * reach the transport (a Tauri invoke cannot be cancelled); the late
+     * answer is discarded all the same. See CommandFetcher for what
+     * `query` and `parsed` hold: the operators are stripped from the first,
+     * and the palette applies them to the results itself.
      *
      * Results join the static commands, so a palette can do both.
      */
-    search?: (query: string, signal: AbortSignal) => Command[] | Promise<Command[]>
+    search?: CommandFetcher
     /** Wait after the last keystroke before `search` runs. */
     debounce?: number
-    /** Shortest query `search` runs for. */
+    /** Shortest query `search` runs for, counted on its positive words. */
     minChars?: number
     /**
-     * Ids of recently picked commands, newest first — bind it to storage and
-     * the palette opens on what this person actually uses. It only reorders
-     * commands already in the list; an id that no longer resolves is skipped,
-     * so a stored history never resurrects a command that has gone away.
+     * Recently picked commands, newest first — bind it to storage and the
+     * palette opens on what this person actually uses. An item is a root
+     * command's id, or a RecentEntry for a pick made inside a mode or among
+     * fetched results (the `remember` event hands over exactly what to
+     * store; `pushRecent` adds it to a list). A root id only reorders
+     * commands already in the list. An entry is found again down its path
+     * of static children, then through `resolveRecent`, then from its own
+     * `href`; what none of them finds is skipped, so a stored history never
+     * resurrects a command that has gone away.
      */
-    recent?: string[]
+    recent?: RecentItem[]
     /**
      * Let the palette keep the history itself, in localStorage under this key:
-     * every top-level command run is remembered, newest first. Ignored while
-     * `recent` is bound, which stays the way to store it somewhere else.
+     * every pick is remembered, newest first, root ones as bare ids as before
+     * and deeper ones as entries. Ignored while `recent` is bound, which
+     * stays the way to store it somewhere else.
      */
     recentKey?: string
+    /**
+     * Finds the live command for a remembered pick the palette cannot find
+     * itself: a result a fetcher returned, or one inside a mode whose
+     * children are fetched. Gets the stored entry, with the command's
+     * `recentData` as `data`; returns the command to show and run, or
+     * nothing to drop it.
+     */
+    resolveRecent?: (entry: RecentEntry) => Command | null | undefined
     /** How many recent commands to surface. */
     recentLimit?: number
     /** Headings the palette adds itself. */
@@ -207,8 +350,10 @@ const props = withDefaults(
      * `preview` text, or the `preview` slot. For palettes that search
      * content rather than commands: the excerpt says why a row matched, the
      * pane lets it be read without leaving the page. It opens only for a row
-     * with `preview` or `excerpt` (any row, with the slot): the dialog eases
-     * wider, the pane slides in, and the text arrives paragraph by paragraph.
+     * with `preview` or `excerpt` (any row, with the slot, unless `hasPreview`
+     * or the row's `noPreview` says otherwise): the dialog eases wider, the
+     * pane slides in, and the text arrives paragraph by paragraph. A slot
+     * that renders nothing for a row falls back to that built-in text.
      * Hidden below the md breakpoint, where there is no room beside the list.
      *
      * The width is an inline style rather than a pair of classes: a base
@@ -216,6 +361,14 @@ const props = withDefaults(
      * build in an order where the base won, and the pane opened squeezed.
      */
     previewPane?: boolean
+    /**
+     * Which rows the pane opens for. With a `#preview` slot every row would
+     * otherwise qualify, and an app whose previews cover only some kinds of
+     * row had to draw a placeholder for the rest. Return false and the pane
+     * folds away for that row, as it does for a row without text. A row's
+     * own `noPreview` wins over this.
+     */
+    hasPreview?: (command: Command) => boolean
     /**
      * Frosted glass instead of a solid panel: the page shows through,
      * blurred, under a lighter scrim (.lp-glass-overlay, .lp-scrim--light).
@@ -274,6 +427,13 @@ const emit = defineEmits<{
    * navigation, not a pick.
    */
   (e: "run", id: string, command: Command): void
+  /**
+   * A pick the recent history keeps, as the item to store: a bare id for a
+   * root command, a RecentEntry for anything deeper. For apps that bind
+   * `recent` and keep the history themselves: `recent = pushRecent(recent,
+   * item, 20)`.
+   */
+  (e: "remember", item: RecentItem, command: Command): void
 }>()
 
 const query = ref("")
@@ -354,7 +514,9 @@ function onTab(event: KeyboardEvent) {
   if (!c || !actions.length) return
   event.preventDefault()
   event.stopPropagation()
-  enter({ id: `${c.id}:actions`, label: c.label, icon: c.icon, children: actions })
+  const actionsMode: Command = { id: `${c.id}:actions`, label: c.label, icon: c.icon, children: actions }
+  syntheticModes.add(actionsMode)
+  enter(actionsMode)
 }
 
 /*
@@ -382,8 +544,8 @@ watch(
   },
 )
 
-function enter(c: Command) {
-  trailState.value = [...trailState.value, { query: query.value, selectedId: selectedId.value }]
+function enter(c: Command, parentQuery = query.value) {
+  trailState.value = [...trailState.value, { query: parentQuery, selectedId: selectedId.value }]
   trail.value = [...trail.value, c]
   query.value = ""
   select(0)
@@ -431,7 +593,7 @@ const found = shallowRef<Command[]>([])
 const task = useAsyncTask<Command[]>()
 const searching = task.pending
 
-function fetcher(): ((q: string, signal: AbortSignal) => Command[] | Promise<Command[]>) | null {
+function fetcher(): CommandFetcher | null {
   const current = mode.value
   if (current) {
     return typeof current.children === "function"
@@ -459,7 +621,8 @@ function refresh() {
   failed.value = false
   const run = fetcher()
   if (!run) return
-  const q = query.value.trim()
+  const parsed = parsePaletteQuery(query.value.trim())
+  const q = parsed.text
   // A fetching mode runs on an empty query too: opening it should show the
   // first page, not an empty screen waiting for a keystroke. Root search does
   // not — ⌘K would fire a request at every open.
@@ -467,7 +630,7 @@ function refresh() {
   if (!inMode && q.length < Math.max(1, props.minChars)) return
   // A failing provider: the static commands still stand, with a line saying
   // that the rest could not be fetched.
-  task.run((signal) => run(q, signal), {
+  task.run((signal) => run(q, signal, parsed), {
     delay: props.debounce,
     apply: (hits) => (found.value = hits),
     fail: () => {
@@ -498,9 +661,10 @@ const source = computed<Command[]>(() => (mode.value ? modeItems.value : props.c
  */
 const local = computed<{ items: Command[]; terms: string[] }>(() => {
   const terms = parseCommandQuery(query.value)
+  // Fallback rows are not matched against the query; they get their own pass.
   const filtered = query.value.trim()
-    ? source.value
-    : source.value.filter((c) => !c.hidden)
+    ? source.value.filter((c) => !c.fallback)
+    : source.value.filter((c) => !c.hidden && !c.fallback)
   // Empty query: show everything EXCEPT hidden commands (they only surface once
   // typed). With a query, hidden commands rank like any other.
   if (!terms.include.length && !terms.exclude.length && !terms.groups.length) return { items: filtered, terms: [] }
@@ -519,48 +683,91 @@ const ranked = computed<Command[]>(() => local.value.items)
 const fetched = computed<Command[]>(() => {
   if (!found.value.length) return []
   const seen = new Set(ranked.value.map((c) => c.id))
-  return found.value
+  const rows = found.value
     .filter((c) => !seen.has(c.id))
     .map((c) => (c.group ? c : { ...c, group: props.resultsLabel }))
+  return applyQueryFilters(rows, parseCommandQuery(query.value))
 })
 
+/*
+ * "Search elsewhere" rows for the typed words, labelled with them. The row
+ * on screen is a copy with the label filled in; the command it stands for
+ * is what runs and what a mode chip names.
+ */
+const fallbackOf = new WeakMap<Command, Command>()
+const fallbacks = computed<Command[]>(() =>
+  fallbackRows(source.value, query.value).map(({ command, label }) => {
+    const row = { ...command, label }
+    fallbackOf.set(row, command)
+    return row
+  }),
+)
+
 /*
  * Recent picks, newest first, lifted out of the list they already belong to.
  * Only on the root's empty query: once someone types, or drills into a mode,
  * relevance is the better order and a duplicated row is just noise.
  */
 const RECENT_KEEP = 20
-const ownRecent = ref<string[]>([])
+const ownRecent = ref<RecentItem[]>([])
 watch(
   () => props.recentKey,
   (key) => {
     if (!key || typeof localStorage === "undefined") return
     try {
-      const stored: unknown = JSON.parse(localStorage.getItem(key) ?? "[]")
-      ownRecent.value = Array.isArray(stored) ? stored.filter((v): v is string => typeof v === "string") : []
+      ownRecent.value = readRecent(JSON.parse(localStorage.getItem(key) ?? "[]"))
     } catch {
       ownRecent.value = []
     }
   },
   { immediate: true },
 )
-function remember(id: string) {
+
+/*
+ * Where each recent row was found, so running it again remembers it under
+ * the same path rather than as a root pick. Modes the palette makes up
+ * itself (Tab's actions) are not destinations, and nothing picked in them
+ * is remembered.
+ */
+const recentPath = new WeakMap<Command, string[]>()
+const syntheticModes = new WeakSet<Command>()
+
+function remember(c: Command) {
+  if (c.remember === false || trail.value.some((step) => syntheticModes.has(step))) return
+  const path = recentPath.get(c) ?? trail.value.map((step) => step.id)
+  const item = toRecentItem(c, path)
+  emit("remember", item, c)
   const key = props.recentKey
   if (!key || props.recent) return
-  ownRecent.value = [id, ...ownRecent.value.filter((v) => v !== id)].slice(0, RECENT_KEEP)
+  ownRecent.value = pushRecent(ownRecent.value, item, RECENT_KEEP)
   try {
     localStorage.setItem(key, JSON.stringify(ownRecent.value))
   } catch {}
 }
-const recentIds = computed(() => props.recent ?? (props.recentKey ? ownRecent.value : []))
+const recentList = computed(() => props.recent ?? (props.recentKey ? ownRecent.value : []))
+
+function fromEntry(entry: RecentEntry): Command {
+  return { id: entry.id, label: entry.label, description: entry.description, icon: entry.icon, image: entry.image, href: entry.href }
+}
 
+/*
+ * Shown while no words are typed: at an empty box, and under operators
+ * alone, which filter them like any row ("-theme", "in:recent").
+ */
 const recentItems = computed<Command[]>(() => {
-  if (mode.value || query.value.trim() || !recentIds.value.length) return []
-  const byId = new Map(props.commands.map((c) => [c.id, c]))
+  if (mode.value || !recentList.value.length) return []
+  const terms = parseCommandQuery(query.value)
+  if (terms.include.length) return []
+  const found = resolveRecentItems(recentList.value, props.commands, {
+    limit: Number.POSITIVE_INFINITY,
+    resolve: props.resolveRecent,
+    fromEntry,
+  })
   const out: Command[] = []
-  for (const id of recentIds.value) {
-    const c = byId.get(id)
-    if (c && !c.disabled && !out.includes(c)) out.push(c)
+  for (const { command, path } of found) {
+    if (out.includes(command) || !recentVisible(command, terms, props.recentLabel)) continue
+    recentPath.set(command, path)
+    out.push(command)
     if (out.length >= props.recentLimit) break
   }
   return out
@@ -585,6 +792,17 @@ const grouped = computed<{ name: string; items: Command[] }[]>(() => {
   // the same row on screen twice with nothing to tell them apart.
   for (const c of ranked.value) if (!recent.includes(c)) push(c, c.group ?? "")
   for (const c of fetched.value) push(c, c.group ?? "")
+  // Last, whatever their group: they are the way out when nothing above is it.
+  const tail = new Map<string, Command[]>()
+  for (const c of fallbacks.value) {
+    const group = c.group ?? ""
+    if (map.has(group)) map.get(group)!.push(c)
+    else tail.set(group, [...(tail.get(group) ?? []), c])
+  }
+  for (const [group, items] of tail) {
+    map.set(group, items)
+    order.push(group)
+  }
   return order.map((name) => ({ name, items: folded(name, map.get(name)!) }))
 })
 
@@ -621,8 +839,14 @@ function folded(name: string, items: Command[]): Command[] {
 const flat = computed(() => grouped.value.flatMap((g) => g.items))
 
 const slots = defineSlots<{
-  /** Body of the preview pane for the highlighted command. */
-  preview?: (props: { command: Command }) => unknown
+  /**
+   * Body of the preview pane for the highlighted command. `highlight(text)`
+   * splits any text around the words typed (positive terms only, plus the
+   * command's own `highlight` words), the same matching the rows use; the
+   * LpPalette* blocks take its result wherever they take text, and
+   * `query` is the parsed box for anything else.
+   */
+  preview?: (props: { command: Command; highlight: (text: string) => HighlightPart[]; query: PaletteQuery }) => unknown
 }>()
 
 const active = computed<Command | undefined>(() => {
@@ -636,16 +860,55 @@ const previewRef = ref<{ viewportEl: HTMLElement | null } | null>(null)
  * beside a list of commands is a column of dead space. With the slot the app
  * decides what to show, so any highlighted row opens it.
  */
-const paneOpen = computed(
-  () => props.previewPane && !!active.value && (!!slots.preview || !!(active.value.preview || active.value.excerpt)),
+const previewable = computed(() =>
+  props.previewPane && commandHasPreview(active.value, { slot: !!slots.preview, hasPreview: props.hasPreview }),
+)
+
+/*
+ * The row the pane shows. It follows the highlight while the highlight has a
+ * preview, and lingers for a moment when it lands on a row without one:
+ * arrowing through a list where every other row has a preview would
+ * otherwise widen and narrow the dialog on every keystroke. Only when the
+ * highlight stays on such rows does the pane fold.
+ */
+const PANE_LINGER_MS = 160
+const paneCommand = shallowRef<Command | undefined>()
+let lingerTimer: ReturnType<typeof setTimeout> | undefined
+watch(
+  [active, previewable],
+  ([command, show]) => {
+    clearTimeout(lingerTimer)
+    if (show) {
+      paneCommand.value = command
+      return
+    }
+    if (!paneCommand.value) return
+    lingerTimer = setTimeout(() => (paneCommand.value = undefined), PANE_LINGER_MS)
+  },
+  { immediate: true },
 )
+onBeforeUnmount(() => clearTimeout(lingerTimer))
+
+const paneOpen = computed(() => props.previewPane && !!paneCommand.value)
+
+function paneHighlight(text: string): HighlightPart[] {
+  return highlight(text, paneBody.value?.highlight)
+}
+const paneQuery = computed(() => parsePaletteQuery(query.value.trim()))
+
+// What the pane draws: the last row it showed, kept while the pane slides out
+// so it leaves with its content instead of emptying first.
+const paneBody = shallowRef<Command | undefined>()
+watch(paneCommand, (command) => {
+  if (command) paneBody.value = command
+})
 
 /*
  * The text in paragraphs, so they can arrive one after another. A blank line
  * separates them, as in the `preview` the consumer wrote.
  */
 const paragraphs = computed(() =>
-  (active.value?.preview ?? active.value?.excerpt ?? "")
+  (paneBody.value?.preview ?? paneBody.value?.excerpt ?? "")
     .split(/\n{2,}/)
     .map((part) => part.trim())
     .filter(Boolean),
@@ -657,7 +920,7 @@ const paragraphs = computed(() =>
  * would otherwise print the same sentences twice, once small and once large.
  */
 const paneDescription = computed(() => {
-  const description = active.value?.description?.trim()
+  const description = paneBody.value?.description?.trim()
   if (!description) return undefined
   const body = paragraphs.value.join(" ")
   return body.startsWith(description) ? undefined : description
@@ -673,7 +936,7 @@ const STAGGER_MAX = 10
  * from the top rather than wherever the previous result was scrolled to.
  */
 watch(
-  () => active.value?.id,
+  () => paneCommand.value?.id,
   async () => {
     if (!paneOpen.value) return
     await nextTick()
@@ -692,46 +955,48 @@ function flatIndexOf(c: Command): number {
 }
 
 // ── highlight ────────────────────────────────────────────────
-// Split text around query terms (≥2 chars, longest-first) for <mark> wrapping,
-// without v-html. Multi-word queries highlight each term.
-interface Part {
-  text: string
-  hit: boolean
+// Split text around the positive query terms (and a row's own `highlight`
+// words) for <mark> wrapping, without v-html. Exclusions are never marked.
+function highlight(value: string, extra: string[] = []): HighlightPart[] {
+  return highlightParts(value, [...local.value.terms, ...extra])
 }
-function highlight(value: string, extra: string[] = []): Part[] {
-  const terms = [...new Set([...local.value.terms, ...extra.map((t) => t.toLowerCase())].filter((t) => t.length >= 2))].sort(
-    (a, b) => b.length - a.length,
-  )
-  if (!value || terms.length === 0) return value ? [{ text: value, hit: false }] : []
-  const lower = value.toLowerCase()
-  const parts: Part[] = []
-  let i = 0
-  while (i < value.length) {
-    let at = -1
-    let term = ""
-    for (const t of terms) {
-      const found = lower.indexOf(t, i)
-      if (found !== -1 && (at === -1 || found < at || (found === at && t.length > term.length))) {
-        at = found
-        term = t
-      }
-    }
-    if (at === -1) {
-      parts.push({ text: value.slice(i), hit: false })
-      break
-    }
-    if (at > i) parts.push({ text: value.slice(i, at), hit: false })
-    parts.push({ text: value.slice(at, at + term.length), hit: true })
-    i = at + term.length
-  }
-  return parts
+
+// ── row picture ──────────────────────────────────────────────
+/*
+ * A string is shorthand for the src. A picture with nothing to fall back on
+ * borrows the command's icon, so a row that had an icon keeps one while the
+ * picture loads or after it fails.
+ */
+// The avatar's own radii are drawn for 36px and up; at the icon's size a card
+// radius rounds a square into a blob. Whole literals so Tailwind sees them.
+const IMAGE_RADIUS = { circle: "rounded-pill", soft: "rounded-[6px]", square: "rounded-[3px]" } as const
+
+function imageOf(c: Command): CommandImage | null {
+  if (!c.image) return null
+  const image = typeof c.image === "string" ? { src: c.image } : c.image
+  return { ...image, icon: image.icon ?? c.icon }
 }
 
 // ── selection + keyboard ─────────────────────────────────────
-watch(query, () => {
+watch(query, (value) => {
+  if (enterByPrefix(value)) return
   select(0)
   refresh()
 })
+
+/*
+ * A prefix typed (or pasted) at the start of the box opens its mode with the
+ * rest of the text as the query there. The list it leaves is remembered with
+ * an empty query: Backspace out of the mode should land on the plain list,
+ * not on the prefix, which would open the mode again on the spot.
+ */
+function enterByPrefix(value: string): boolean {
+  const hit = matchModePrefix(value, source.value)
+  if (!hit) return false
+  enter(hit.command, "")
+  query.value = hit.rest
+  return true
+}
 watch([query, trail, () => props.open], () => {
   expanded.value = new Set()
 })
@@ -807,6 +1072,7 @@ function openInNewTab(c: Command) {
   if (!c.href) return
   window.open(c.href, "_blank", "noopener")
   emit("run", c.id, c)
+  remember(c)
   emit("update:open", false)
 }
 
@@ -821,13 +1087,14 @@ function onRowClick(event: MouseEvent, c: Command) {
   run(c)
 }
 
-function run(c: Command | undefined) {
-  if (!c || c.disabled) return
+function run(row: Command | undefined) {
+  if (!row || row.disabled) return
+  const c = fallbackOf.get(row) ?? row
   // The highlight stays on the same index, which is now the first row that
   // was hidden: the arrows carry on from where the fold was.
-  const group = moreOf.get(c)
+  const group = moreOf.get(row)
   if (group !== undefined) {
-    selectedId.value = firstHidden.get(c) ?? null
+    selectedId.value = firstHidden.get(row) ?? null
     expanded.value = new Set([...expanded.value, group])
     inputRef.value?.focus()
     return
@@ -838,11 +1105,13 @@ function run(c: Command | undefined) {
   // A command with children drills in instead of closing, and is navigation
   // rather than a pick — so it stays out of the recency history.
   if (c.children) {
+    const carried = query.value
     enter(c)
+    if (c.carryQuery) query.value = carried
     return
   }
   emit("run", c.id, c)
-  if (!mode.value) remember(c.id)
+  remember(c)
   if (c.keepOpen) {
     // Back to the top of a fresh list: the query that found this command is
     // spent, and leaving it would hide whatever the action just changed.
@@ -975,7 +1244,7 @@ useHotkeys(() =>
             @click="popTo(i)"
           >
             <LpIcon v-if="step.icon" :name="step.icon" :size="13" />
-            {{ step.label }}
+            {{ modeChipLabel(step) }}
             <LpIcon name="lucide:x" :size="12" class="opacity-60" />
           </button>
 
@@ -1048,7 +1317,21 @@ useHotkeys(() =>
                   @click="onRowClick($event, c)"
                   @pointerenter="onPointerEnter(c)"
                 >
-                  <LpIcon v-if="c.icon" :name="c.icon" :size="16" class="shrink-0" :class="{ 'mt-0.5': c.excerpt }" />
+                  <!-- A picture takes the icon's slot at the icon's footprint, with
+                       a negative margin so a 20px avatar does not make its row
+                       taller than its neighbours. -->
+                  <LpAvatar
+                    v-if="imageOf(c)"
+                    :src="imageOf(c)!.src ?? undefined"
+                    :alt="imageOf(c)!.alt ?? ''"
+                    :fallback="imageOf(c)!.fallback"
+                    :icon="imageOf(c)!.icon"
+                    :shape="imageOf(c)!.shape ?? 'soft'"
+                    :pixel-size="20"
+                    class="-my-0.5 -ml-0.5 shrink-0 text-[9px]"
+                    :class="IMAGE_RADIUS[imageOf(c)!.shape ?? 'soft']"
+                  />
+                  <LpIcon v-else-if="c.icon" :name="c.icon" :size="16" class="shrink-0" :class="{ 'mt-0.5': c.excerpt }" />
                   <span class="min-w-0 flex-1">
                     <span class="block truncate font-medium">
                       <template v-for="(p, pi) in highlight(c.label, c.highlight)" :key="`l${pi}`">
@@ -1078,6 +1361,12 @@ useHotkeys(() =>
                     </span>
                   </span>
                   <kbd v-if="c.shortcut" class="shrink-0 text-xs text-muted">{{ c.shortcut }}</kbd>
+                  <!-- The prefix that opens this mode from the box, so the
+                       shortcut is learned by seeing it rather than reading docs. -->
+                  <kbd
+                    v-else-if="c.prefix && c.children"
+                    class="shrink-0 rounded border border-line px-1.5 font-mono text-[11px] whitespace-pre text-muted"
+                  >{{ c.prefix }}</kbd>
                   <!-- Drills in rather than runs: worth saying before the click,
                        since the two look identical otherwise. -->
                   <LpIcon
@@ -1118,11 +1407,22 @@ useHotkeys(() =>
               <LpScrollArea ref="previewRef" class="min-h-0 flex-1" content-class="px-5 py-4">
                 <!-- Keyed by the row, so moving the highlight replays the
                      entrance rather than swapping text in place. -->
-                <div v-if="active" :key="active.id">
-                  <slot name="preview" :command="active">
+                <div v-if="paneBody" :key="paneBody.id">
+                  <slot name="preview" :command="paneBody" :highlight="paneHighlight" :query="paneQuery">
                     <div class="lp-cmd-para flex items-center gap-2 text-ink">
-                      <LpIcon v-if="active.icon" :name="active.icon" :size="16" class="shrink-0 text-muted" />
-                      <h3 class="min-w-0 text-base font-semibold">{{ active.label }}</h3>
+                      <LpAvatar
+                        v-if="imageOf(paneBody)"
+                        :src="imageOf(paneBody)!.src ?? undefined"
+                        :alt="imageOf(paneBody)!.alt ?? ''"
+                        :fallback="imageOf(paneBody)!.fallback"
+                        :icon="imageOf(paneBody)!.icon"
+                        :shape="imageOf(paneBody)!.shape ?? 'soft'"
+                        :pixel-size="28"
+                        class="shrink-0"
+                        :class="IMAGE_RADIUS[imageOf(paneBody)!.shape ?? 'soft']"
+                      />
+                      <LpIcon v-else-if="paneBody.icon" :name="paneBody.icon" :size="16" class="shrink-0 text-muted" />
+                      <h3 class="min-w-0 text-base font-semibold">{{ paneBody.label }}</h3>
                     </div>
                     <p v-if="paneDescription" class="lp-cmd-para mt-0.5 text-xs text-muted">
                       {{ paneDescription }}
@@ -1133,7 +1433,7 @@ useHotkeys(() =>
                       class="lp-cmd-para mt-3 whitespace-pre-line text-sm leading-relaxed text-ink/90"
                       :style="{ animationDelay: `${Math.min(i + 1, STAGGER_MAX) * STAGGER_MS}ms` }"
                     >
-                      <template v-for="(p, pi) in highlight(para, active.highlight)" :key="`p${pi}`">
+                      <template v-for="(p, pi) in highlight(para, paneBody.highlight)" :key="`p${pi}`">
                         <mark v-if="p.hit" class="rounded-xs bg-brand/25 text-ink">{{ p.text }}</mark>
                         <template v-else>{{ p.text }}</template>
                       </template>