VOMPECCC from Scratch: Picking Produce with ICR in Emacs

This is the fourth post in a series on Emacs completion. The first argued that Incremental Completing Read (ICR) is a structural property of an interface rather than a convenience feature. The second broke the Emacs substrate into eight packages (collectively VOMPECCC) each solving one of the six orthogonal concerns of a complete completion system. The third walked through spot, a ~1,100-line Spotify client built as a little shim on top of those packages.

This post is the hands-on complement to the spot post. Where the spot case study reviewed a finished codebase from the outside, this one builds a tiny produce picker tool from scratch, one VOMPECCC package at a time. The use case is deliberately trivial: we have a list of produce items (twenty fruits and ten vegetables) with some metadata, and we want to pick one and do something with it.

Every piece of interesting behavior; the display control, multi-component matching, metadata columns, narrowing keys, contextual actions, transformer-driven type refinement, frecency-based sorting; will be layered on by adding one VOMPECCC package at a time, in order to make it clear exactly what each package provides. By the end, we will have a ~90-line produce picker whose entire UI was composed from six packages that don't know about each other.

We will build a ~90-line produce picker whose entire UI was composed from six packages that don't know about each other.

A caveat: two of the eight VOMPECCC packages are out of scope here. Corfu and Cape target in-buffer completion, and the produce picker in this post is focused on minibuffer interaction. So this post focuses on the six packages that do show up visibly in a live walkthrough: Vertico, Orderless, Marginalia, Prescient, Embark, and Consult.

A note on format. You can open this webpage in EWW and execute the code from within there (you can see my video for an example of how to do this).

This video demo walks through the code in this post live. I have also included prose in each section explaining what each piece of code does. The article is long, so the video will likely be a quicker digestion of this post's message.

Note: wherever you see video demos, you will see, in the upper right hand side (in the tab-bar), the keybindings and associated commands that I am invoking to execute each command. This is relevant because you may have things configured differently on your side. By providing both the kbd and command name, my invocation of behaviors you see in the video should unambiguous.

The data is a list of candidates, which in this implementation are propertized strings, one per produce item. Each candidate is the produce item's name, with five text properties riding along: category, type, color, season, and price. Two of those properties are load-bearing for later phases. category is the completion category, the symbol Marginalia and Embark dispatch on.

A word on the name category, because it is doing more work than it looks like. Of the five property names above, four are arbitrary: type, color, season, price are labels we chose, nothing in Emacs reserves them, and you could rename them all and only have to update our own code. category is the exception because it is a reserved text-property name in Emacs. The Elisp manual specifies that when a character has a category text property whose value is a symbol, that symbol's property list serves as defaults for the character's other text properties. In other words, category is Emacs's standard hook for stamping a typed symbol onto a piece of text. Emacs's completion ecosystem overloads the same name with a second, related meaning, which is that every prompt has a completion category (a symbol like file, buffer, or in our case fruit or vegetable), which Marginalia, Embark, etc… consult through the completion metadata to decide which annotator, keymap, or exporter to dispatch.

There is one important subtlety worth surfacing now, since it explains a lot of what happens later. The framework never reads our category text property directly. Marginalia and Embark dispatch off the prompt-level completion metadata (a separate channel from text properties), and Consult, when we add it in Phase 5, communicates per-candidate categories through a different text property called multi-category rather than ours. So our category property is read only by our own code: a corpus-filtering helper in Phase 4, an Embark exporter in Phase 6, etc…. The framework dispatches because we set the Consult source's :category key to match the data's category property by hand. The two stay in sync because we keep them in sync, not because anyone cross-checks. This is the candidate-as-currency convention being load-bearing for us, with the framework reading a parallel, framework-owned slot for its own dispatch.

type is the finer classification (botanical: pome, berry, citrus, stone, tropical, melon; vegetable: root, leafy, cruciferous, nightshade) used in Phase 6 to drive an Embark transformer that gives citrus its own action set. Both classifications live on the candidate itself. No framework code in any phase below ever invents a category or hardcodes a type, and the routing keys are pulled directly off the candidates.

(defvar my-produce
  (list
   ;; Fruits
   (propertize "apple"      'category 'fruit     'type 'pome        'color "red"    'season "fall"       'price 1.29)
   (propertize "pear"       'category 'fruit     'type 'pome        'color "green"  'season "fall"       'price 1.79)
   (propertize "strawberry" 'category 'fruit     'type 'berry       'color "red"    'season "spring"     'price 3.99)
   (propertize "blueberry"  'category 'fruit     'type 'berry       'color "blue"   'season "summer"     'price 4.99)
   (propertize "raspberry"  'category 'fruit     'type 'berry       'color "red"    'season "summer"     'price 5.99)
   (propertize "blackberry" 'category 'fruit     'type 'berry       'color "black"  'season "summer"     'price 5.49)
   (propertize "lemon"      'category 'fruit     'type 'citrus      'color "yellow" 'season "year-round" 'price 0.79)
   (propertize "lime"       'category 'fruit     'type 'citrus      'color "green"  'season "year-round" 'price 0.39)
   (propertize "orange"     'category 'fruit     'type 'citrus      'color "orange" 'season "winter"     'price 0.99)
   (propertize "grapefruit" 'category 'fruit     'type 'citrus      'color "pink"   'season "winter"     'price 1.49)
   (propertize "peach"      'category 'fruit     'type 'stone       'color "orange" 'season "summer"     'price 2.49)
   (propertize "plum"       'category 'fruit     'type 'stone       'color "purple" 'season "summer"     'price 2.99)
   (propertize "cherry"     'category 'fruit     'type 'stone       'color "red"    'season "summer"     'price 6.99)
   (propertize "apricot"    'category 'fruit     'type 'stone       'color "orange" 'season "summer"     'price 3.99)
   (propertize "mango"      'category 'fruit     'type 'tropical    'color "orange" 'season "summer"     'price 1.99)
   (propertize "pineapple"  'category 'fruit     'type 'tropical    'color "yellow" 'season "year-round" 'price 3.99)
   (propertize "banana"     'category 'fruit     'type 'tropical    'color "yellow" 'season "year-round" 'price 0.59)
   (propertize "papaya"     'category 'fruit     'type 'tropical    'color "orange" 'season "year-round" 'price 2.49)
   (propertize "watermelon" 'category 'fruit     'type 'melon       'color "green"  'season "summer"     'price 0.59)
   (propertize "cantaloupe" 'category 'fruit     'type 'melon       'color "orange" 'season "summer"     'price 2.99)
   ;; Vegetables
   (propertize "carrot"     'category 'vegetable 'type 'root        'color "orange" 'season "year-round" 'price 0.99)
   (propertize "beet"       'category 'vegetable 'type 'root        'color "purple" 'season "fall"       'price 1.49)
   (propertize "radish"     'category 'vegetable 'type 'root        'color "red"    'season "spring"     'price 0.79)
   (propertize "spinach"    'category 'vegetable 'type 'leafy       'color "green"  'season "spring"     'price 2.99)
   (propertize "kale"       'category 'vegetable 'type 'leafy       'color "green"  'season "winter"     'price 2.49)
   (propertize "lettuce"    'category 'vegetable 'type 'leafy       'color "green"  'season "summer"     'price 1.99)
   (propertize "broccoli"   'category 'vegetable 'type 'cruciferous 'color "green"  'season "year-round" 'price 2.99)
   (propertize "cauliflower" 'category 'vegetable 'type 'cruciferous 'color "white" 'season "fall"       'price 3.99)
   (propertize "tomato"     'category 'vegetable 'type 'nightshade  'color "red"    'season "summer"     'price 2.49)
   (propertize "eggplant"   'category 'vegetable 'type 'nightshade  'color "purple" 'season "summer"     'price 3.49))
  "Produce candidates (fruits + vegetables) for the VOMPECCC walkthrough.")

Thirty propertized strings, two completion categories (fruit, vegetable), ten types (six botanical + four vegetable), and four additional properties. For the rest of this post, produce candidate means one of these propertized strings: a plain Emacs string at the surface (the produce name, if you will) with its remaining fields as text properties.

If you are reading this post in your own Emacs, your config may already have VOMPECCC packages enabled, which would muddy this demo of built-in completion. Run this block first to peel them off so the baseline really is the baseline.

;; Reset completion-styles and category configuration to Emacs defaults.
(setq completion-styles '(basic partial-completion emacs22))
(setq completion-category-defaults nil)
(setq completion-category-overrides nil)

;; Drop any custom Orderless wiring so dispatchers and matching styles don't leak in.
(when (boundp 'orderless-style-dispatchers)
  (setq orderless-style-dispatchers nil))
(when (boundp 'orderless-component-separator)
  (setq orderless-component-separator " "))
(when (boundp 'orderless-matching-styles)
  (setq orderless-matching-styles '(orderless-literal orderless-regexp)))

;; Disable every VOMPECCC mode the post will switch back on layer by layer.
(when (bound-and-true-p vertico-prescient-mode) (vertico-prescient-mode -1))
(when (bound-and-true-p prescient-persist-mode) (prescient-persist-mode -1))
(when (bound-and-true-p vertico-mode) (vertico-mode -1))
(when (bound-and-true-p marginalia-mode) (marginalia-mode -1))

After this block, completing-read should behave the way Emacs ships out of the box: a *Completions* buffer instead of a vertical list, prefix-only and partial-completion matching, no annotations, no contextual actions, and no 'frecency'. Phase 1 below demonstrates exactly that, and every subsequent phase adds one layer back.

Before we pull in a single VOMPECCC package, it is worth seeing what the built-in Emacs completion already gives us. completing-read is a function in the Emacs standard library: it prompts the user for an input string, filters candidates based on that string, and then returns the chosen string. That is the entire contract.

(completing-read "Pick something: " my-produce)

When this block runs, the minibuffer opens with the prompt Pick something: = and a blinking cursor. Nothing else is visible at first. Press =TAB and a *Completions* buffer pops open above the minibuffer, laying all thirty produce names across columns. Type a prefix like pe and press TAB again; the *Completions* buffer shrinks to the two produce items whose names start with those letters (peach and pear). Once you pick an item (either by arrowing to it in *Completions* or typing its full name), you accept it with RET and the chosen string echoes into the message area.

This works, but it is visually and ergonomically primitive. Right now we are lacking display control for our candidate list, fuzzy matching, metadata display and filtering, preview, and any way of doing anything with the chosen item except receive its name.

Every phase that follows places layers of the VOMPECCC stack around this function without changing the function itself.

Every phase that follows places layers of the VOMPECCC stack around this function without changing the function itself.

Vertico only does one thing; it just gives us control over how candidates are displayed in the minibuffer. It does not filter, sort, annotate, or act on anything. Any code that calls completing-read; whether it's yours, Emacs's, a third-party package's; is rendered according Vertico's display settings if it is enabled.

(vertico-mode 1)

That is the entire integration! Re-evaluate the Phase 1 block:

(completing-read "Pick something: " my-produce)

This time the *Completions* buffer never appears. Instead, the minibuffer lays out candidates horizontally (my default display style for Vertico). The prompt still sits at the bottom, but to it's right is a flat array of all thirty produce items, one per line, with the first one (apple) highlighted as the current selection. C-n (or C-j in my config) walks the highlight to the right through pear, strawberry, blueberry, and so on through the list; C-p (or C-k in my config) walks it left. RET accepts whichever candidate is currently highlighted. The candidate list filters incrementally whenever we type a letter: typing a single p on the empty prompt collapses it to the 12 items whose names contains p, and each additional character narrows further in real time, with the selection snapping to the first surviving candidate.

Notice our completing-read function call did not change, and, critically, we did not pass Vertico the candidates. Vertico hooked into the minibuffer-setup pipeline at a lower level, and Emacs routes candidates to it. This is critical because this means Vertico now gives us candidate display control everywhere completing-read is used, without us havign to anything except enable vertico mode!

Vertico gave us a better view, but the matching is still the default combination of basic, partial-completion, and emacs22. These styles handle prefix and hyphen-segmented matches, but we lack a way to type more than one independent fragment, do any flex matching, negation, or any way to filter against candidate metadata.

Orderless is a completion style: it plugs into the completion-styles variable and changes how the input string is matched against candidates during completing-read. Orderless in practice reveals its namesake: it lets us split the input on a separator character, and return candidates that contain every component, in any order.

(setq orderless-component-separator ",")

(setq orderless-matching-styles '(orderless-regexp)
      completion-styles '(orderless basic)
      completion-category-defaults nil
      completion-category-overrides '((file (styles basic partial-completion))))

;; A small `tab' shim style: TAB completion only, no fall-through.
;; In-buffer completion (Corfu, the in-buffer counterpart from Post 2)
;; uses it; minibuffer prompts ignore it and pass straight through to Orderless.
(add-to-list 'completion-styles-alist
             '(tab completion-basic-try-completion ignore
                   "Completion style which provides TAB completion only."))

(setq completion-styles '(tab orderless basic))

Note: The basic fallback matters because a handful of Emacs features (TRAMP host completion, for example) require prefix-style matching that Orderless does not handle; basic catches those.

A few notes on the configuration we set up:

• orderless-matching-styles is the chain Orderless uses against any input component that no dispatcher has claimed, and setting it to orderless-regexp is my personal recommendation.
• The file-category override (defined in completion-category-overrides) is an idiomatic exception so that ~/d/s expands to ~/Documents/source/.
• The separator is set to a comma because Orderless's default is a space, and spaces are valuable inside candidate strings because search candidates (and their annotations) often contain whitespace. Reassigning the separator to a rarely-occurring character (,) keeps spaces available as part of any component you might want to match.
• The tab style at the head of completion-styles is a one-line concession to in-buffer completion, because Corfu uses it for plain TAB completion in code buffers, but know that the minibuffer prompts ignore it and fall through to Orderless.

Re-run the produce prompt:

(completing-read "Pick something: " my-produce)

You see Orderless in action when you type more than one component separated by commas. Typing a,e narrows the list to every item containing both an a and an e somewhere, in either order (Order-less, remember? 😜). Each comma-separated component is an independent filter, and the intersection (in the set algebra sense) of their matches is what survives in the candidate list display.

Individual components can override the default matching style through Orderless's style dispatchers, which are single-character affixes that tell Orderless to treat that component in a special way. Out of the box, Orderless ships orderless-affix-dispatch as the default dispatcher, mapping ~ to flex, ! to negation, & to annotation matching, , to initialism, and a few others. Two of those defaults are awkward in our setup: , is already serving as our component separator, so it can't double as a dispatcher prefix; and we want the annotation prefix to support a flex variant, which the affix-alist can't express because each entry maps a single character to a single style. Both reasons motivate replacing the defaults with hand-rolled versions tuned to our preferred prefix vocabulary.

We'll use a customized dispatcher set for the rest of this post.

Each dispatcher is a function of three arguments (pattern, index, total) that inspects a component and, if its dispatcher character appears at either end, returns (STYLE . PATTERN-WITHOUT-AFFIX) as so Orderless knows which matching style to apply. Returning nil passes the component to the next dispatcher in the chain, or to the default style if none match. Accepting the character as either prefix or suffix mirrors the built-in orderless-affix-dispatch and means you don't have to remember which end the trigger goes on, or preempt the matching style before you type out a component. ~bna and bna~ both flex-match.

;; Each dispatcher accepts the dispatcher character as either a
;; PREFIX or a SUFFIX of the component, mirroring the built-in
;; `orderless-affix-dispatch'.

(defun my/orderless-dispatcher-initialism (pattern _index _total)
  "Initialism-match a component starting OR ending with a backtick."
  (cond
   ((string-prefix-p "`" pattern)
    `(orderless-initialism . ,(substring pattern 1)))
   ((string-suffix-p "`" pattern)
    `(orderless-initialism . ,(substring pattern 0 -1)))))

(defun flex-if-twiddle (pattern _index _total)
  "Flex-match a component starting OR ending with `~'."
  (cond
   ((string-prefix-p "~" pattern)
    `(orderless-flex . ,(substring pattern 1)))
   ((string-suffix-p "~" pattern)
    `(orderless-flex . ,(substring pattern 0 -1)))))

(defun annotation-if-at (pattern _index _total)
  "Annotation-match `@P' or `P@'.
Flex-annotation-match `@~P', `~P@', `@P~', or `P~@' --- the inner
`~' may sit at either end of the inner pattern."
  (let ((rest
         (cond
          ((string-prefix-p "@" pattern) (substring pattern 1))
          ((string-suffix-p "@" pattern) (substring pattern 0 -1)))))
    (when rest
      (cond
       ((string-prefix-p "~" rest)
        (let ((re (mapconcat (lambda (c) (regexp-quote (char-to-string c)))
                             (string-to-list (substring rest 1)) ".*")))
          `(orderless-annotation . ,re)))
       ((string-suffix-p "~" rest)
        (let ((re (mapconcat (lambda (c) (regexp-quote (char-to-string c)))
                             (string-to-list (substring rest 0 -1)) ".*")))
          `(orderless-annotation . ,re)))
       (t `(orderless-annotation . ,rest))))))

(defun without-if-bang (pattern _index _total)
  "Exclude a literal match for a component starting OR ending with `!'.
A bare `!' is a no-op (matches every candidate)."
  (cond
   ((equal "!" pattern) '(orderless-literal . ""))
   ((string-prefix-p "!" pattern)
    `(orderless-without-literal . ,(substring pattern 1)))
   ((string-suffix-p "!" pattern)
    `(orderless-without-literal . ,(substring pattern 0 -1)))))

;; `annotation-if-at' precedes `flex-if-twiddle' on purpose:
;; with suffix support, a compound like `@PATTERN~' would otherwise
;; fire flex on the trailing `~' before annotation could claim the
;; leading `@'.  Annotation must get first crack.
(setq orderless-style-dispatchers
      '(my/orderless-dispatcher-initialism
        annotation-if-at
        flex-if-twiddle
        without-if-bang))

Four dispatchers, each demonstrated against the candidate list:

Try the prompt again with these style dispatchers in place.

(completing-read "Pick something: " my-produce)

The annotation dispatcher is the most interesting of the four because it shows that some dispatchers compose. The leading @ picks a slot (annotation rather than name); the inner ~ switches the match style on whatever it's already pointing at. Nothing in Orderless's library knows about @~ as a compound prefix. We wrote that composition ourselves, in a few lines (annotation-if-at).

Note we won't be able to see the annotation dispatcher in action until we add annotations in the Marginalia section, so bear with me!

Orderless stays out of the way. The only thing that changed about our completion setup by introducing Orderless is how Emacs matches your input against the candidate list changed, because we effectively swapped in a different completion style through completion-styles.

Vertico didn't need to know about Orderless. Orderless didn't need to know about Vertico. They compose because Emacs routes their concerns through separate hooks.

To drive the point home, what we did not do matters architecturally: Vertico and Orderless are agnostic to one another. They leverage independent Emacs built-ins (completing-read rendering and completion-styles respectively), and they compose because Emacs natively routes their concerns through these separate channels. You can swap in any other minibuffer candidate display UI (Icomplete-vertical, Mct, fido-vertical-mode), or drop it entirely, and Orderless will still work. You can swap in any other completion style and Vertico will still work.

We can filter tightly now, but in spite of the rich metadata attached to each produce candidate, we can't see anything about a candidate except its name. If you're deciding between peach and apricot, relevant information like price, color, season, etc… is already on the candidate's text properties, but Vertico is only showing us the string itself. Marginalia is the package that promotes candidates into informed choices by displaying their metadata as right-aligned columns next to each candidate name.

The trick that makes Marginalia (and every subsequent VOMPECCC package) possible is the convention already established by the list of produce items: the candidate is its name as a string, with its full record's fields stamped on as text properties. completing-read is satisfied because the candidate is a plain string; the rest of the substrate is satisfied because the properties are right there.

A note on scope before we start: plain completing-read can only carry one completion category at a time, and Marginalia dispatches its annotator off that prompt-level category. The corpus has two categories (fruit and vegetable); to keep this phase honest, we narrow the picker to just fruits for now. Phase 5 will lift this restriction with Consult's multi-source mechanism.

That narrowing is one line of Lisp, but worth pausing on. Every later phase (the Consult sources in Phase 5, the async variant in Phase 8) will partition the corpus by category in the same way, so we factor it out once and read the routing key off the candidate itself rather than off of some separate lookup table. This is the candidate-as-currency convention in miniature: a routing question is answered by reading a text property:

(defun my-produce-of-category (cat)
  "Return candidates from `my-produce' whose `category' is CAT."
  (cl-remove-if-not
   (lambda (cand) (eq (get-text-property 0 'category cand) cat))
   my-produce))

We still need to tell the prompt itself what completion category this is, because Marginalia dispatches its annotator off the prompt's metadata, not off per-candidate text properties. The candidate stamping we did in the corpus is for our own code (the actions, the transformer, the exporter) to read; the framework looks at prompt metadata. The lightest way to set the metadata is completion-extra-properties, a property list that overrides the completion metadata for the duration of one completing-read call:

(defun my-pick-fruit ()
  "Pick a fruit by name."
  (interactive)
  (let ((completion-extra-properties '(:category fruit)))
    (message "You picked: %s"
             (completing-read "Fruit: " (my-produce-of-category 'fruit)))))

The foundational pattern — a completion function that responds to (action 'metadata) with (metadata (category . fruit)) — is still available and is what libraries like Consult build on. However, for a one-off picker without Consult, completion-extra-properties is equivalent and cleaner. Why is this even needed? Because plain completing-read over a list of strings has no way to communicate a category to Marginalia: the framework reads the prompt's completion metadata, and our list of strings doesn't ship any. As soon as we move to Consult in Phase 5, the source-level :category key takes over and the extra-properties step disappears entirely, which is exactly why packages like spot never need this dance. Every spot prompt is a Consult prompt. Our Phase 4 picker is the awkward case precisely because it is deliberately the barest possible call, and a demonstration of a Consult-less completion setup for our produce picker.

The annotator itself is the heart of this phase. It takes a candidate string, reads its text properties directly, and hands a list of columns to marginalia--fields, which does the alignment, per-field truncation, and face application:

(defun my-annotate-produce (cand)
  "Annotate a produce candidate CAND with type, color, season, and price."
  (marginalia--fields
   ((symbol-name (get-text-property 0 'type cand))
    :truncate 13 :face 'marginalia-type)
   ((get-text-property 0 'color cand)  :truncate 10 :face 'marginalia-string)
   ((get-text-property 0 'season cand) :truncate 12 :face 'marginalia-date)
   ((format "$%.2f" (get-text-property 0 'price cand))
    :truncate 8  :face 'marginalia-number)))

Note that I am not writing any layout code at all. marginalia--fields handles padding, alignment, and face application; my job is only to declare which fields go in which columns. Annotating the candidates in this way enables Orderless's @ dispatcher to filter by our produce's metadata, so @berry, @citrus, @root become legitimate filter prefixes.

Registration for the fruit category is one add-to-list against Marginalia's annotator registry, plus enabling the marginalia-mode:

(add-to-list 'marginalia-annotators
             '(fruit my-annotate-produce none))
(marginalia-mode 1)

The registry entry is (CATEGORY ANNOTATOR1 ANNOTATOR2 ... none), where each tail symbol is an annotator marginalia-cycle (M-A) can rotate to in-session. We list two states for our category: our custom annotator, then none (annotations off). This matches spot's convention and gives a clean toggle on M-A. Marginalia's own built-in entries also include a builtin symbol in the chain (which is a fallback that defers to whatever annotation-function the prompt's metadata declares natively) but for a category nobody else knows about (like fruit), there is no built-in to defer to, so leaving it out keeps the cycle to two visibly-different states instead of three.

Run the picker:

(my-pick-fruit)

When (my-pick-fruit) runs, the prompt opens as it did before, but every one of the fruit candidates is now followed by a horizontally aligned set of columns: a type word (pome, berry, citrus, …), a color word (red, yellow, blue, green, …), a season (spring, summer, winter, year-round), and a dollar-formatted price ($0.59, $3.99, $6.99).

Stylistically, each column is padded to a fixed width and rendered in its own face, so the four fields read as distinct groups rather than running together with a delimiter. Where Phase 3 showed strawberry, this phase shows:

strawberry berry red spring $3.99

The list is legible at a glance, and what's more, you can usefully compare peach against apricot on price and season without typing anything. Scanning for cheap in-season fruit, for example, is made easy in this way.

Typing against annotation text is where Marginalia crosses from cosmetic to compositional. Typing yellow at the prompt matches nothing, because yellow is in the annotation column, not the candidate name, and Orderless is still matching against names only. But prefix that same component with @, as in @yellow, and the annotation dispatcher we wired up in Phase 3 tells Orderless to match this particular component against the annotation text instead of the candidate string. The list snaps to exactly the three yellow-colored fruits in the corpus.

To drive home the point that the VOMPECCC packages work independently of one another, Orderless knew nothing about Marginalia, and vice-versa. The @ dispatcher simply matches against whatever is in the "annotation slot" of the current candidate, and that slot happens to contain the words Marginalia stamped there.

The compound variant from Phase 3 cashes in here too: @~sm triggers the flex branch of annotation-if-at, flex-matching the characters s and m against annotation text. Only summer contains them in order, so the list collapses to the summer fruits.

Annotation components compose the same way regular components do. Typing @summer,@red on the empty prompt narrows first to summer fruits, then to the subset of those that are also red. The list collapses to raspberry and cherry, the two red summer fruits in the corpus. You can reach for a fruit by its properties without ever remembering its name. Post 2 called this "an unusually large leverage gain for what feels like a cosmetic layer".

The architectural observation here is that the @ dispatcher is not a Marginalia feature. It is an Orderless feature (a dispatcher we wrote) that happens to work because Marginalia exposes annotations through the same completion-metadata slot Orderless reads from. Swap Marginalia for any other annotator (say, a leaner one you write yourself that only shows price) and the @ filter still works. With an alternative annotation provider, Orderless would just filter against whatever that other annotator produces.

Phase 4 was a single prompt over a fruit-only subset, which was enough to demo Marginalia, but it left the corpus's vegetables out and gave us no way to scope the prompt without typing. What if we want one prompt that holds everything (all categories) in my-produce and lets us flip between fruits and vegetables (and back to all of it) with a single keystroke.

Consult fixes this through its multi-source mechanism: consult--multi takes a list of sources, unifies their candidates into a single prompt, and sets up per-source narrowing keys. Each source declares its own name, its own narrow key, its own completion category, and its own items.

The dispatch story in Phase 5 is the same as in Phase 4: the candidate's completion category is whatever the candidate carries. In Phase 4 we read category off the only candidate type the picker held (a fruit). In Phase 5 each source produces candidates of one category (fruit for the fruit source, vegetable for the vegetable source) and the source-level :category matches the value the data already declared on every candidate. The framework reads the value out of the candidate. The spot post uses the same double-stamping pattern, and the per-candidate text property is the authoritative truth, and the source-level :category keeps Consult's metadata in sync.

Each candidate carries five text properties: category (fruit or vegetable), type, color, season, and price, and is read directly off the candidate by Marginalia, Embark, the annotator, and every action we're about to write.

Here we define two Consult sources (1 per category) each with its own scoped :history variable so previously-selected fruits and previously-selected vegetables don't get mixed together in any one history list:

(defvar my-consult-history-fruit nil
  "History scoped to the fruit Consult source.")

(defvar my-consult-history-vegetable nil
  "History scoped to the vegetable Consult source.")

(defvar my-consult-source-fruit
  `(:name     "Fruits"
    :narrow   ?f
    :category fruit
    :history  my-consult-history-fruit
    :items    ,(lambda () (my-produce-of-category 'fruit)))
  "Consult source for fruits.")

(defvar my-consult-source-vegetable
  `(:name     "Vegetables"
    :narrow   ?v
    :category vegetable
    :history  my-consult-history-vegetable
    :items    ,(lambda () (my-produce-of-category 'vegetable)))
  "Consult source for vegetables.")

A Consult source plist's most important keys:

• :items is the candidate stream. A function that returns a list of candidates, called lazily when the prompt opens. Ours is synchronous because the produce list is local, but for a remote API you would swap :items for :async and consult--dynamic-collection instead. Phase 8 walks through that variant against a faithfully-mocked produce API, and the spot post discusses the consumer-side cost when multiple sources share one endpoint.
• :narrow ?f binds the character that scopes the prompt to just this source. Pressing f SPC at the prompt hides every non-fruit candidate.
• :category fruit is the completion category that propagates onto every candidate from this source, not via our category text property but via Consult's own multi-category text property, which Consult writes from this very key. Marginalia and Embark consult that multi-category channel to pick the right annotator and the right keymap per candidate. We set this key to match the data's category property by hand, so the two declarations stay aligned.
• :history my-consult-history-fruit is a per-source history list. Selecting a candidate from this source appends it to this variable (and only this variable), which means the fruit picker can keep its own history and Vertico's M-p / M-n cycle through a list that is meaningfully scoped instead of polluted with every minibuffer interaction in the session. This per-source scoping is also what makes a per-prompt history-recall command (something like consult-history) useful, which we discuss right after.
• :name is the header shown above this source's candidates in the unified list.

Two Marginalia registry entries, one per category:

(dolist (cat '(fruit vegetable))
  (add-to-list 'marginalia-annotators
               `(,cat my-annotate-produce none)))

Then the consult command:

(defun consult-produce-picker ()
  "Pick produce with multi-source Consult completion."
  (interactive)
  (consult--multi
   (list my-consult-source-fruit
         my-consult-source-vegetable)
   :prompt "Produce: "))

Run it:

(consult-produce-picker)

When (consult-produce-picker) runs, the prompt opens with the thirty produce items grouped under two bold header lines in the vertical list: Fruits and Vegetables, each followed by the candidates belonging to that source. Every annotation column from Phase 4 is preserved because the annotator is registered against both categories and Consult has tagged each candidate with the right one.

The new affordance by consult is "narrowing", the ability to scope the prompt to a single source with one keystroke. Pressing f followed by SPC hides every non-fruit candidate: the twenty fruits become the entire list, and a small indicator in the prompt header shows the narrow state. Pressing DEL clears the narrow and restores the full thirty-item view. v SPC narrows to vegetables.

The features from earlier phases still apply inside a narrowed view, and this is where the independence of VOMPECCC's constituents really shows. With the list narrowed to fruits, typing @berry further filters to the four berries via the type column we added to the annotator; @red filters to red fruits; ~bry flex-matches the berry suffix of the remaining candidates; !blue excludes anything containing blue. Orderless, Vertico, and Marginalia are all still doing exactly what they did in Phase 4, and they could care less that the candidate source is now two Consult sources instead of one list.

Note we have another classifying property in each candidate. The type column in the annotator means @berry, @citrus, @root, @cruciferous are all valid one-component filters on the prompt, and they compose with the source narrow, so f SPC @citrus gives you exactly the four citrus fruits. The framework keeps type as a searchable axis instead of a narrowing axis.

The amount of code we wrote for the narrowing, grouping, and per-source history is pretty close to zero. I like Consult's declarative API in this way: we declared; Consult did.

We can select a produce item, but we still can't do anything with it.

So far the picker's job has ended at returning a string. Embark is the package that adds a layer of category-contextual actions on top of any completion prompt and provides a keyboard-driven context menu whose contents depend on what kind of candidate is highlighted.

It's useful to think of Embark as similar to a left-click or 'context menu' in traditional UIs.

We'll define the minimum set of actions needed to demonstrate Embark's three headline features:

1. embark-act on a single candidate (the basic case): an inspect action that pops a buffer with the item's full plist.
2. embark-act-all on every visible candidate (multi-cardinality): an add-to-cart action that appends to a *Cart* buffer, which we will invoke against every currently visible item at once.
3. Per-category keymap dispatch (context-sensitivity): vegetables get a roast action that fruits don't; citrus fruits get a juice action that other fruits don't. These are specializations side by side, by two different mechanisms in Embark: the vegetable specialization rides on the Consult source's :category key (forwarded to Embark via Consult's multi-category channel), while the citrus specialization rides on an Embark transformer we write that reads the candidate's type property.

The last concern from the orthogonal six is sorting.

So far, sorting has been incidental. Vertico ships a default sort that draws on minibuffer history, but it ignores frequency entirely and resets when Emacs restarts. Prescient is the dedicated package for this concern: it computes a combined frecency score (recency + frequency) per candidate and hands it to Vertico as the sort function. With prescient-persist-mode the score survives Emacs restarts; even without it, the score updates from the very first selection.

That last point is what makes Prescient demonstrable in a from-scratch walkthrough. The score for a never-selected candidate is zero. Pick a candidate once and its score jumps above zero, putting it at the top of the next prompt. One selection is enough to see the effect.

One wrinkle to acknowledge before the setup. Of the six VOMPECCC packages we are using, Prescient is the only one that bundles two concerns: sorting (the part we want here) and its own filtering style. vertico-prescient-mode toggles both by default — which would replace the Orderless setup from Phase 3 and silently break the custom dispatchers (~, !, backtick, @) we have been relying on for the last four phases. Post 2 flags this same two-concern split and notes the common workaround: keep Orderless for filtering, take Prescient's sort, and disable the filter takeover. That is what we do here:

(setq vertico-prescient-enable-filtering nil)
(vertico-prescient-mode 1)

This is the entire prescient integration. (Adding (prescient-persist-mode 1) would persist scores across Emacs sessions; we leave it off here so the demo's state stays bounded to this single Emacs session.)

This demo is simple. Run the picker once, select an item, then re-run. The item we just picked will be the first in the list.

(consult-produce-picker)

All five layers continue untouched, while a sixth package quietly improves the order in which their candidates land on screen.

The picker we have works because the entire produce corpus is local: my-produce is a literal thirty-item list, and each Consult source's :items callback returns its slice synchronously. Real-world sources are usually remote, and the spot post demonstrates this w/r/t the Spotify API. Filtering at the Emacs side stops being viable once the corpus has thousands or millions of entries, and you have to push the query to the server and let the server tell you which candidates match.

Consult ships consult--dynamic-collection for exactly this case. It wraps a completion function so that each keystroke fires a debounced, cancellable query. The function you write only has to answer "given this query string, what are the candidates?" Consult handles the debouncing (default ~200ms via consult-async-input-debounce), the cancellation of stale responses (via while-no-input), and the display refresh.

Step back and count what each package contributed:

Roughly 90 lines of VOMPECCC-facing emacs-lisp, and we have a categorised, narrowable, annotated, annotation-matchable, action-bindable, transformer-refined, exportable, frecency-sorted produce picker (that's a mouthful!). There is no UI code anywhere in it! Every line fell into one of two buckets: configuring a VOMPECCC package (add-to-list, setq, defvar-keymap) or declaring our data (the propertized corpus, the annotator, the action bodies, the transformer).

The how of the composition, the question Post 2 gestured at and Post 3 answered for a larger application, is a single convention repeated across the six packages. Each candidate is its name as a string, with its full record's fields stamped on as text properties:

(propertize "apple"
            'category 'fruit       ; our internal routing key (filter, exporter)
            'type     'pome        ; read by our Embark transformer
            'color    "red"        ; annotation column
            'season   "fall"       ; annotation column
            'price    1.29)        ; annotation column

That is the entire integration surface. The exporter and our filter helper read the candidate's category property directly; the annotator reads type, color, season, price; the Embark transformer reads type. Vertico, Orderless, and Prescient do their work on the string itself. Marginalia and Embark dispatch off the prompt's completion-metadata category, which Consult populates from each source's :category key (in turn set to match the data's category property by hand — the candidate-as-currency convention paying its dues by keeping our routing key and Consult's source key in lockstep). When Embark wants to dispatch below the granularity of category, e.g.\ with citrus-only juicing inside the broader fruit category, our transformer reads type off the candidate and refines accordingly. These six packages communicate interoperably through Emacs's completion substrate, with one shared currency: the propertized candidate.

A note on shape. We carry the produce fields as individual text properties because the records are shallow and the property bag stays small. Codebases like spot, where each candidate is a Spotify track or playlist with dozens of nested fields, take a different approach and attach the entire record under a single multi-data property and let consumers reach into the plist for deep fields. Both shapes meet the substrate at the same hook (a propertized candidate whose properties happen to encode a typed record) and the choice between them is purely local to the corpus.

Replace my-produce with GitHub issues, S3 buckets, Slack channels, ten thousand Org headings, a music library, or your ticketing system. The integration surface is unchanged. The corpus reshapes; the annotator reads different fields; the Consult sources partition differently; the Embark keymaps and transformer do different things. Critically, none of the framework code moves. This is the architecture behind spot, consult-gh, consult-notes, consult-omni, and the growing ecosystem of ICR-driven packages that can be assembled from the same substrate without rebuilding any of its layers.

A handful of VOMPECCC features are worth pointing at, because you will want them eventually and they are all continuations of the same substrate pattern you just saw:

• Consult preview. A source's :state key accepts a function that fires on candidate navigation, not just selection. consult-line uses it to scroll the current buffer to the highlighted line; consult-theme applies the theme as you scroll. For a produce picker, :state could pop a "tasting notes" buffer that updates as you move through the list.
• More Embark transformers. Phase 6 used a transformer to refine fruit → fruit-citrus based on type. Transformers can refine on any predicate over the candidate's properties — e.g., turn every produce item into produce-expensive if price > 3.00, so you can layer arbitrary fine-grained dispatch on top of the coarse category without inventing new completion categories. There is a huge amount of power there, especially when you understand that Embark's utility expands greatly when you are willing to start typing entities in Emacs, whether they are in the minibuffer or regular buffers.
• prescient-persist-mode. Phase 7 enabled vertico-prescient-mode without persistence to keep the demo bounded; in a real configuration, (prescient-persist-mode 1) writes the frecency table to disk so your most-picked candidates stay at the top across Emacs restarts.
• Corfu and Cape. In-buffer completion, out of scope for a picker. If you have a programming-language buffer open and you want to complete symbols with the same matching style and annotation columns, Corfu and Cape are how.

Each of these is an incremental add on the same foundational Emacs completion substrate.

This post built a 30-item produce picker in Emacs by layering six VOMPECCC packages one at a time on top of stock completing-read. Vertico rendered the candidate list vertically with a one-line mode activation; Orderless added multi-component matching via the completion-styles hook plus four custom style dispatchers (~ flex, backtick initialism, ! negation, @ annotation with a @~ flex variant), each accepting its trigger character at either prefix or suffix position; Marginalia added four metadata columns per candidate (type, color, season, price) by reading text properties attached to each candidate string with propertize, and along the way made the annotation text itself searchable through Orderless's @ dispatcher — including the type column, so @berry and @citrus become valid one-component filters; Consult's consult--multi unified the corpus into two categorised sources (fruit, vegetable) under one prompt with per-source narrow keys and per-source :history variables, with each source's :category matching the value the data declares, and consult-history bound to C-r turning those scoped histories into a recall surface for both prior selections and (via M-RET or a minibuffer-exit-hook) prior Orderless queries; Embark attached contextual actions via per-category keymaps (one for fruits, one for vegetables, one specialized for citrus) plus an Embark transformer registered on multi-category that does both jobs in a single pass — because Embark fires the prompt-category transformer exactly once, the multi-category transformer is the one place to put both source-category extraction (delegating to the built-in helper) and our citrus refinement (reading type off the candidate and refining fruit to fruit-citrus) — and an embark-export path that materialises candidates into a sortable tabulated-list-mode buffer; Prescient then hooked Vertico's sort slot to surface recently and frequently picked candidates first, with the rank visibly shifting after a single selection; finally an async variant swapped :items for consult--dynamic-collection over a faithfully-mocked produce API, demonstrating debounced/cancellable remote queries and discussing when the spot-style cache+mutex pattern is load-bearing (multiple sources sharing one endpoint) versus defensive ceremony (single thread, single source). The entire integration surface across the six packages was one propertized candidate carrying its fields as text properties — category as our internal routing key, kept aligned with each Consult source's :category so the framework's own multi-category channel matches; type read by our Embark transformer; the rest for annotation columns — no package calls another's API, none imports another's internals, and swapping my-produce for any other typed corpus would leave every line of the framework configuration unchanged.