spike(plugins): plugin system prototype + voice-driven meme generator — DO NOT MERGE

[initcore0]

➡️ Superseded by #244

The productionized version is open at #244 (feat/plugin-system-v1),
branched fresh off main and mergeable — no do-not-merge marker.

Everything you tested across these ten iterations is carried byte-identical.
What #244 adds on top:

• PLUGINS ships on by default (PLUGINS=0 is the lean escape hatch), wired
  into build-dmg.sh too so the released DMG isn't the only build with an empty
  Plugins pane. A verify-plugins-binary.sh guard fails the build if the plugin
  symbols are missing.
• MemeTrace and the launch probes are compiled out of consumer builds
  (OPENWHISP_INSTRUMENTATION), verified against real binaries in both
  directions. The missing scripts/meme-runtime-proof.sh now exists.
• MAK-100 contracts landed: clipboardAccess (declared and gated, with
  the plumbing + tests), destination (reserved routes validated and refused
  honestly), and appAffinity — all forward-compatible.
• docs/PLUGINS.md, carrying this PR's hot-swap comparison as a committed
  roadmap, plus CI jobs pinning both sides of the PLUGINS flag.

This PR is left open for you to close, since the iteration log below is the
design record for every decision in #244.

---

DO NOT MERGE. Prototype to make the plugin idea concrete and argue about a real thing instead of a diagram. Quality bar is spike-level: it compiles, it works on the happy path, and the shortcuts are labelled rather than hidden.

---

What this demonstrates

An optional plugin layer. Plugins are not part of the base app: nothing is compiled in by default, nothing is enabled by default, and a stock ./build.sh carries no plugin code at all. Each enabled plugin contributes its own window plus its own configuration in Settings.

The first plugin is a voice-driven meme generator: dictate a description, and it picks a template, writes the captions, renders them, and lets you export or share.

Architecture

Two layers, split on the line the codebase already draws — pure rules in OpenWhispCore (covered by swift test), IO and AppKit in the app.

Core (OpenWhisp/Services/, all tested):

• PluginManifest — id, name, version, SF Symbol, entry kind, and a networkHosts disclosure. Id validation is strict because the id becomes a path component under Application Support, so traversal-shaped ids (.., foo/bar) are refused before they are ever joined onto a URL.
• PluginDiscovery — merges an ordered list of providers into the plugin list. Earlier providers win id collisions.
• PluginEnablement — the enabled set, default-off, with pruning.
• PluginRegistry — the compile-time list of in-repo plugins.

App:

• PluginHost — the provider list, the enabled set, and plugin windows. Not on AppState.
• PluginsPane — Settings → Plugins.
• Menu bar → Plugins submenu, present only when something is enabled.

The provider seam (this is the part that matters)

PluginHost does not know about the compile-time registry. It enumerates providers:

private static var providers: [PluginDiscovery.Provider] {
    [
        .init(source: .builtIn)  { PluginRegistry.builtInManifests },
        .init(source: .external) { PluginDiscovery.loadExternalManifests(in: externalDirectory) },
    ]
}

The registry is one entry in that list. The disk provider re-reads ~/Library/Application Support/OpenWhisp/Plugins/<id>/manifest.json on every reload(), so a manifest dropped there shows up in the pane without a rebuild or a relaunch — the listing half of hot-swap already works today. What is missing is a runner, not a restructure.

Providers are passed in descending trust order and earlier wins, so a writable directory can never shadow a reviewed plugin. That property is worth pinning now even though the spike can't execute external plugins at all, because a future loader inherits it.

The manifest describes an entry point kind (builtIn / dynamicLibrary / externalProcess), never a Swift type name — so the schema does not assume the plugin lives in this binary.

AppState is unchanged in net LOC

Dictation routing needed both call sites in insertCompletedText (the liveChunks branch is the one MAK-49 had to go back and fix — a window wired into only the first branch silently drops text). The MAK-32 ratchet had zero headroom at 7051, so the checks fold into the existing conditionals with || and the surrounding comments were condensed to pay for the wrap. scripts/check-appstate-ratchet.sh still reports exactly 7051.

Path to hot-swappable

The compile-time registry is fine for this spike but must not be the shipping answer. Four realistic options for a signed, notarized, local-first app that holds Accessibility + microphone + clipboard:

1. Out-of-process plugin executables — recommended

A plugin is a helper binary the app launches and speaks to over a local protocol; UI is contributed declaratively or by the plugin's own window.

• Security: the only option with real isolation. The plugin runs as its own process, gets its own sandbox profile, and does not inherit the host's TCC grants — a plugin cannot read the screen or the clipboard just because OpenWhisp can. A crash takes out the plugin, not the dictation pipeline.
• Distribution: the app already ships helper binaries (whisper, llama, the openwhisp CLI at Contents/Helpers/) and already has a local-socket bridge protocol precedent (Agent Bridge + MCP). This reuses both.
• Cost: an IPC surface and a UI-contribution schema. The real work.
• Signing: third-party binaries need their own notarization story, or the host must be willing to run unnotarized helpers behind an explicit consent gate. This is the hard part, and it is a policy problem rather than an architecture one.

2. Script / manifest-driven plugins — recommended as the first shipped tier

Declarative UI plus a constrained action set the host executes (call the LLM, fetch a URL, run a shell script, write a file). ScriptPostProcessor and ConfigPack are already this shape.

• Security: the host owns every capability, so the plugin can only compose things the user already consented to. Reviewable by reading a manifest.
• Cost: lowest. Ships fastest.
• Limit: can't express the meme plugin's live preview. Good for text/actions, weak for custom UI.

3. WKWebView-hosted plugin UIs — middle ground

Plugin ships HTML/JS; the host exposes a narrow message-passing bridge.

• Security: the web sandbox is genuinely good and the bridge is an explicit allowlist. But a web view is also a network egress the user may not expect, so CSP has to be locked down.
• Cost: medium. Buys arbitrary UI without native code.
• Fit: pairs well with (1) — process for logic, web view for UI.

4. Loadable bundles / dylibs — do not do this

• Security: unacceptable. In-process code inherits Accessibility and clipboard rights wholesale — a plugin becomes a keylogger with the app's own consent prompts already granted. docs/ROADMAP.md §6 already rejects this.
• Signing: loading unsigned/third-party code breaks the hardened runtime and library validation; the entitlement to permit it weakens the whole app.
• ABI: Swift has no stable ABI guarantee across a plugin boundary you don't compile together, so every app update risks breaking every plugin.
• Crash isolation: none. A bad plugin crashes dictation.

Recommendation: ship (2) first because it is cheap and covers most asks, then (1) for anything needing custom UI or real compute, with (3) as the UI layer if declarative proves too limiting. Keep (4) closed permanently.

Review model. While plugins are owner-reviewed and in-repo, the trust question is deferred rather than answered — which is exactly why the provider ordering and the "external is never runnable" rule are already in place. The moment plugins come from elsewhere, the host needs: a capability list in the manifest that the user consents to per-plugin, enforcement outside the plugin's own manifest (a manifest cannot be trusted to declare its own limits), a signature/provenance check, and a kill switch. The current networkHosts field is an honest label, not a sandbox — that distinction is called out in the code.

What is real vs stubbed

Real:

• Discovery, merge/precedence, enable/disable, pruning, persistence.
• Settings pane, menu-bar submenu, plugin window lifecycle.
• Dictation lands in a focused plugin window (both AppState branches).
• Meme flow end to end: live imgflip catalog → LLM (given the real template names) → validated ranked candidates → candidate strip / Browse-all override → download → local CoreGraphics captioning from the box model → draggable editor → Export PNG → Share.
• Verified against the live API: all 100 templates decode.
• v2: template candidates are validated against the real catalog, so an invented name can no longer become a confident wrong template. See the v2 section below.

Stubbed / deliberately not done:

• No loader. External plugins are listed but never runnable; the pane says so.
• PLUGINS=1 ./build.sh is a compile-time toggle, not an installer.
• Per-plugin config is a fixed switch on plugin id — a real system needs a declared settings schema.
• The meme plugin has no model picker; it follows Settings → Cleanup.
• The corpus is imgflip's public top 100 — the real ceiling behind the "yoda" report. Expanding it is future work (see v2).
• Edited memes are not persisted; closing the window loses the boxes (the box model is Codable, so this is a decision rather than a blocker).
• No plugin sandbox, no capability enforcement, no signature checking.
• Windows are not literally "tabs" — a menu-bar submenu entry per plugin, which is the cheap equivalent.

In-repo vs separate repo

In-repo was right for the spike and I would keep it for now:

• The plugin needs summarizeResolved, ScratchpadAIModel, SummaryModelResolver, and BridgeWire.ErrorObject. None are a stable public API. A separate repo would have to pin a contract that does not exist yet — the iOS companion already made OpenWhispCore a versioned contract, and doing that a second time before the plugin API has settled would freeze the wrong shape.
• swift test covers the plugin's rules in the same run as everything else. That stops the day it moves out.
• The friction is real though: plugins/ is outside build.sh's glob, so it needed its own flag, and Package.swift's explicit sources: list means every pure file has to be registered by hand. Both are symptoms of the plugin being neither fully in nor fully out.

Once the boundary is an IPC protocol rather than a Swift call, out-of-repo becomes natural — the protocol is the contract, and that is the point at which third-party plugins stop being a security question the owner has to answer by reading every diff.

v2: candidate picker + manual editor

Owner feedback after live testing the first cut:

1. "yoda meme" found nothing in the top-100 and silently fell back to Drake.
2. The AI should think and propose multiple templates to pick from.
3. There should be a manual editor — "AI makes its best guess, human makes it perfect."

Template selection v2 — the model picks from the real corpus

The LLM now receives the actual catalog names and returns a ranked list of up to five, copied verbatim, plus captions. MemeAI.parseRanked validates every name against the catalog and drops the ones that don't exist — a model that answers "Yoda" gets that candidate discarded rather than fuzzy-matched onto something unrelated.

An empty candidate list is a success, not an error: it is the honest "nothing in this corpus fits" answer, and the UI states it.

UI:

• Candidate strip — the ranked picks as thumbnails under the status line. The best one auto-renders; clicking another re-renders the same captions onto it (captions and box positions carry over, which is what normalized geometry buys).
• Browse all… — a searchable grid over the whole catalog, always available (it loads the catalog on demand, so it works before any generate). Search is local, case/punctuation-insensitive, and never falls back: no match shows an empty grid saying so.
• Honest fallback — falling back still happens, because the user asked for a meme. But it now comes with a warning triangle, a status line naming the corpus ("this is imgflip's top 100, and your meme isn't one of them"), and the candidate strip + Browse all visible. The complaint was never that a fallback happened; it was that it was invisible.
• The fallback list itself is ranked against the user's own description first (MemeTemplateMatcher.ranked), with popularity only filling the remaining slots.

v1 code was deleted, not left behind

MemeAI.prompt / userPayload / parse / MemeSpec and MemeTemplateMatcher.bestMatch / Match / minimumScore are gone, along with the fixed top/bottom geometry constants.

bestMatch's built-in "…or the most popular one if nothing scores" is the reported bug — the fallback was baked into the matcher where no caller could see it. Its replacement ranked refuses to guess (no match → empty list) and moves the fallback policy to the call site, where it is visible and can be narrated.

The alternative — keeping v1 as a "fallback path" — would have left a second parser that tests cover but nothing calls. That is exactly the dead-wiring trap this spike exists to expose, so it wasn't committed.

Manual editor — the box model

Captions are now [MemeCaptionLayout.CaptionBox] rather than a fixed top/bottom pair:

public struct CaptionBox: Equatable, Sendable, Identifiable, Codable {
    public var text: String
    public var centerX: Double       // 0…1, origin TOP-LEFT
    public var centerY: Double
    public var fontSizeShare: Double // share of image HEIGHT, not points
    public var widthShare: Double
    public var fontName: String?
}

Geometry is normalized on purpose. A box dragged on a ~500pt preview renders identically into a 1200px export, and survives being moved to a differently-sized template when the user picks another candidate. Font size is a share of image height for the same reason.

• Drag any caption directly on the preview; positions commit in normalized units on drag end.
• Side panel per box: editable text, size slider + −/+ steppers, width slider, font picker (only faces actually installed, plus the bold system font — a picker offering a font that silently resolves to something else is a lie).
• Add text box / delete. New boxes stack down the middle so successive adds don't land on top of each other.
• Colors were left out to keep the scope sane, as agreed.

The preview IS the export. Both go through MemeRenderer.render(template:boxes:), so WYSIWYG is structural rather than a promise. The AppKit bottom-left coordinate flip happens in exactly one place, which is what stops the editor and the export from disagreeing about which way is up.

Rendering is local CoreGraphics onto an already-downloaded image, so it is cheap enough to redraw per keystroke and per drag — no debounce needed.

The layout math stays pure and host-independent (MemeCaptionLayout, Foundation-only, swift test-covered) per the hot-swap architecture note. The renderer supplies real font metrics and does nothing else. The user's font size is a ceiling: a caption too long for its box still shrinks rather than overflowing.

Design decisions worth arguing about

• The drag handle is a dashed rectangle, not a re-drawn caption. Drawing the text again in SwiftUI would mean two renderers to keep in agreement, and they would drift (different wrapping, different outline weight). The burned-in render is the visual; the handle is a positioned outline you grab. The cost is that the handle is box-shaped rather than glyph-tight.
• Candidates are capped at 5 — the most that fits a strip without scrolling, and the most anyone considers before reaching for Browse all.
• The corpus is still imgflip's public top 100. That is the actual limit behind the "yoda" report, and no amount of prompting fixes it. Future work: memegen.link's template API (much larger, also key-less) or Imgflip premium search would expand the corpus; the parser and picker are already shaped to take a bigger list, and rankedUserPayload already truncates for short-context models.
• Thumbnails use AsyncImage rather than the plugin's own fetch service — the grid can show 100 of them and AsyncImage already handles per-view cancellation and URLCache reuse. Same imgflip CDN GET either way; still nothing uploaded.

Not verified

The rendered output, drag feel, and thumbnail grid have not been visually confirmed — this environment can't screenshot the Mac app (the name resolves to the iOS bundle). The geometry is pinned by tests, but "does the handle sit exactly on the text" and "does the strip look right" are open until someone runs it.

How to test

PLUGINS=1 ./build.sh && ./build/OpenWhisp

1. Enable it — Settings → More features → Plugins → toggle Meme Generator. Note it is off until you do, and that the pane states it fetches template images from imgflip.
2. Open it — menu bar → Plugins → Meme Generator. The description field takes focus on open.
3. Dictate — with that window frontmost, hit your dictation hotkey and say something like "distracted boyfriend, but he's looking at Rust and his girlfriend is Python". The words land in the description field (this is the seam that would otherwise drop them — the focused-app paste path declines while OpenWhisp is frontmost).
4. Generate (⌘↩) — status walks through loading templates → asking the model → downloading → rendered preview, with a candidate strip underneath.
5. Pick another candidate — click any thumbnail in the strip. The same captions re-render onto it; the box positions carry over.
6. The "yoda" case (the regression this section exists for) — generate with "yoda meme, do or do not there is no try". Yoda is not in imgflip's top 100, so expect: a warning triangle, a status line saying the corpus is imgflip's top 100 and yours isn't in it, a candidate strip labelled as a fallback, and no silent Drake.
7. Browse all… — opens the searchable grid. Type drake, two buttons, bling (multi-token search works: drake bling finds Drake Hotline Bling). Type yoda and confirm you get an empty grid that says so rather than a substituted template. Pick anything to override the model entirely.
8. Edit — drag a caption on the preview; it moves and re-renders. Select a box (click it, or click its row in the side panel) and change text, size (slider or −/+), width, and font. Use + to add a box and the trash icon to delete one.
9. WYSIWYG check — Export PNG… after editing and open the file. Caption positions, sizes, and fonts should match the preview exactly, at full template resolution.
10. Export / Share — the suggested filename follows the edited captions, not the AI's originals.
11. Offline — turn off Wi-Fi and generate: it says it couldn't reach imgflip rather than hanging or silently failing.
12. Discovery — Settings → Plugins → Show in Finder, drop in some-id/manifest.json, reopen the pane: it lists, with an honest "can't be loaded" callout.

Gates: swift test 2395 passed, 0 failures · scripts/check-appstate-ratchet.sh OK at exactly 7051 (unchanged — v2 touches no AppState) · ./build.sh (default, no plugins) · PLUGINS=1 ./build.sh · lean (WHISPERKIT=0 PARAKEET=0 SPARKLE=0 PLUGINS=1) all compile, no new warnings in the touched files.

New tests cover the ranked-candidate parser (hallucinated names dropped, case-insensitive catalog matching, dedup, the 5-cap, single-string schema drift, fenced/prose JSON), lexical ranking and the Browse-all search filter (including "neither is allowed to invent a substitute"), and the box model (normalized geometry scaling with image size, clamping, per-box fonts reaching the metrics, shrink-to-fit, empty-box handling, filename derivation, Codable round-trip).

v3: three template providers, a warm model, and a busy state that can't stick

Owner feedback after live-testing v2. Each item below was a defect or a requirement,
not a preference.

1. Templates too limited and America-centric.
2. First Generate failed with "network error and model loading".
3. Stuck loading, and templates couldn't be switched during or after.
4. Deleting every text box left no way to add one back.

1. The corpus is now three providers, merged

One catalog can't fix a corpus problem. imgflip's top 100 is an English-language, US
popularity list, and any curated remote list is someone else's culture. So the
corpus is a merge:

Provider	Count	Key?	Notes
imgflip get_memes	~100	no	popularity-ranked; the corpus the prompt was tuned on
memegen.link /templates	~212	no	verified live; ships keywords
The user's own library	∞	n/a	any image, any language, works offline

MemeTemplateCatalog.merge puts the user first. Their imported "Drake" beats
imgflip's. This is PluginDiscovery's "earlier provider wins" rule pointed the other
way on purpose: there, trust decreases with writability; here the writable source is
the trusted one, because the user put it there deliberately.

De-duplication is by normalized NAME, not id. imgflip and memegen genuinely both
carry Distracted Boyfriend under completely different ids, so a by-id de-dup would
silently do nothing and the grid would show it twice. Ids are source-qualified
(imgflip:181913649, userLibrary:<uuid>) so two providers can never collide into
one image-cache entry — a bug that would present as a rendering glitch rather than as
an id collision.

Search spans names AND keywords, and a query may span both fields. memegen names a
template "Sweet Brown" and puts the phrase people actually type — "Ain't Nobody Got
Time For That" — in keywords; a name-only search misses the exact query a user would
write. Search still never falls back: no match stays empty.

The user library is the real answer to "worldwide." No remote catalog contains a
Russian or Ukrainian meme nobody uploaded to it. Import any image (file picker,
drag-drop onto the template column, or ⌘V) and it becomes a first-class template.

• suggestedName preserves the script: кот-в-шоке.png → кот в шоке. No
  transliteration, no ASCII folding — that would defeat the entire point.
• The user's name never touches the filesystem (opaque UUID filenames), so a name
  with a slash, a colon, or an emoji is fine and renaming is a pure index edit.
• Images are copied into Application Support, not referenced: a template pointing
  at ~/Downloads breaks the first time the user tidies up.
• file values read back off disk are validated before being joined onto a URL —
  the index is a plain JSON file in a user-writable directory, so it is untrusted input
  even though the user owns it. Same rule PluginManifest applies to plugin ids.

A user-library template is a file: URL flowing through the same fetch, merge,
prompt, and render path as a remote one. That is why importing needed no changes
anywhere in the render or export code.

Caching. MemeCatalogCache.decide always paints what is on disk first and treats
the network as a background refresh. Thumbnails are cached as small JPEGs, so a second
open is instant and works offline. A refresh that fails while templates are on
screen returns no message at all — v2's habit of reporting every fetch failure is
what made a cold start look broken. Retry is offered when, and only when, there is
nothing to show.

2. The model is warmed when the window opens

Neither "network error" nor "model loading" exists anywhere in the sources. The report
was a request hitting a llama-server that hadn't started, surfacing
connection-refused as a network error. Nothing warmed the LLM on window open —
Scratchpad doesn't either — so the first Generate always paid the full cold start.

windowDidOpen() now warms the model and opens the catalog. Generate waits behind
an honest "Preparing model…" instead of firing into a dead socket.

AppState.warmLlamaServerIfPossible gained a provider: parameter. The global version
only fires when Settings → Cleanup is itself set to the bundled provider, so a plugin
resolved to bundled would never have warmed — the same split
ensureBundledLLMReady(provider:) already makes for MAK-53.

Ratchet: paid for by folding two comments and dropping one
warmLlamaServerIfPossible() call that ensureLLMModelExists already makes on both
its exit paths. scripts/check-appstate-ratchet.sh still reports exactly 7051.

3. The stuck spinner was structural, so the fix is a type

v2 tracked in-flight work with a Bool cleared by a finish() that several exit paths
never reached. Every superseded-ticket bail read:

guard !self.isCancelled, myTicket == self.ticket else { return }   // isBusy still true

That is correct only when another task owns the flag — true when a newer request
supersedes this one, false after a window close, or when the LLM threw between two
guards. Either case left isBusy == true forever, which disabled Generate and
(because select(template:) began with guard !isBusy) froze the candidate strip and
Browse. Both reported symptoms, one root cause.

MemeGenerationState makes the phase a value with one transition function:

• finish is idempotent, total, and ticket-guarded. A stale result can't un-stick
  newer work; a redundant finish can't overwrite a status that already landed.
• canSelectTemplate is unconditionally true, and says why. Switching templates
  re-renders the same boxes onto a cached-or-one-GET-away image — no LLM round-trip —
  so gating it on the busy flag was pure reflex, and that reflex is what turned a stuck
  flag into a frozen window. Picking a template mid-generation takes its own ticket, so
  the user's explicit choice supersedes the machine's pending guess rather than
  racing it.
• Cancel appears only while work is in flight, and a 120s ceiling recovers a
  hung request. v2 had neither: a model that never answered left the surface busy until
  the window was closed.

Ticket ownership is now explicit too — the background catalog refresh owns no ticket
and never touches the phase, so it can't disturb (or un-stick) whatever the user is
doing while it runs.

4. Editor polish toward the imgflip.com shape

"Add text" is now outside every conditional. v2 rendered the whole editor panel
only when boxes was non-empty, so deleting the last box removed the only control that
could add one back — a dead end with no way out but regenerating. The empty canvas and
the empty box list both say what to do next.

The window is three columns:

┌──────────────┬─────────────────────────┬──────────────┐
│ TEMPLATES    │        CANVAS           │  TEXT BOXES  │
│ search +     │   (the rendered meme,   │  add/delete, │
│ grid+import  │    drag the captions)   │  size, font  │
└──────────────┴─────────────────────────┴──────────────┘

Template search and browse are prominent rather than behind a sheet, because
picking the template is the decision the corpus expansion exists to serve. User
templates carry a badge so a mixed grid is legible at a glance. Nothing local shows a
spinner.

All v2 wins are kept: ranked candidates, honest no-match, the normalized box model, the
single render path (preview is the export), and the -4.0 stroke.

Notes for MAK-100 (plugin API contracts) — design only, not implemented here

The research ticket's three constraints were checked against this spike's manifest
schema. All three are additive; none require a breaking change:

1. Clipboard as an implicit argument. Safe. PluginManifest describes an
   entry point kind, never an input type — nothing in the schema says
   "dictated text". The meme plugin's own importFromPasteboard() already reads the
   clipboard, so the pattern has a working precedent. What's missing is declaration:
   clipboard access should become a declared capability, since the current
   networkHosts field is the only disclosure the manifest carries and an undeclared
   clipboard read is a bigger privacy fact than a network host.
2. Declared destination via the existing OutputTarget protocol. Safe, and worth
   doing: PluginDictationSink currently hard-codes "the plugin's own window" as both
   input and output. A destination field defaulting to .ownWindow would preserve
   every existing plugin while letting new ones target cursor/file/webhook/Shortcut.
   The meme plugin would plausibly declare .file.
3. Voice-router metadata + the ~15-tool cap. Safe — additive optional fields
   (trigger phrases, app affinity). One caution worth recording now: the cap makes tool
   surface a scarce, host-arbitrated resource, so the manifest must not let a
   plugin self-assign priority. Trigger phrases belong in the manifest as hints; the
   ranking and the cap must be enforced host-side, for the same reason networkHosts
   is an honest label rather than a sandbox — a manifest can never be trusted to
   declare its own limits.

The one schema pressure worth flagging: all three point at a capability list the
user consents to per-plugin (clipboard, destination, trigger registration). That is
already the direction the PR's security section argues for, so it's convergent rather
than a new constraint.

Not verified

Same honest caveat as v2, plus more surface: none of the v3 UI has been visually
confirmed — this environment can't screenshot the Mac app (the name resolves to the
iOS bundle). Specifically open until someone runs it:

• The three-column split-view proportions and whether the template grid is comfortable
  at the minimum window width.
• Drag-drop import — the onDrop provider resolution is written but never
  exercised against a real Finder drag.
• The warm actually removing the cold-start failure. The mechanism is verified
  (warmLlamaServerIfPossible starts the server with no completion), but the original
  symptom was reported live and has not been reproduced-then-fixed under observation.
  The 2.5s warm window is a guess, not a measurement.
• memegen's ~212 templates were verified live via curl (shape, count, keywords), but
  not through the app's own decode path against the live endpoint.

The pure layer is pinned by tests; everything above is a UI/integration claim that
tests can't make.

How to test v3

PLUGINS=1 ./build.sh && ./build/OpenWhisp

Settings → More features → Plugins → enable Meme Generator, then menu bar →
Plugins → Meme Generator.

1. Warm, not broken (the Fix WhisperEngine: serverLock main-thread hang, pipe deadlock, transcript logging #2 regression). Open the window and press ⌘↩
   immediately. Expect a status of "Preparing model…" and then a normal
   generation — not a network error. This is the exact moment that failed before.
2. The corpus grew. The left column should report ~300 templates, not 100.
   Search sweet brown and nobody got time — both find the same memegen template
   (name vs keyword).
3. Import a Russian template (the Fix audio capture: 16kHz resample, scoped mic device, streaming races #1 headline).
   • Save any Russian meme image as e.g. кот-в-шоке.png.
   • Drag it onto the template column (or Import → Import images…, or ⌘V).
   • It appears immediately, badged as yours, named кот в шоке — Cyrillic
     intact, not transliterated.
   • Search кот and шоке — both find it. Search kot finds it too (the filename
     rides along as a keyword).
   • Click it: it renders, and you can caption it like any other template.
   • Dictate "кот в шоке, когда увидел счёт" and Generate — the model can now pick
     your template, because user templates sort first into the prompt.
4. Offline (the cache). Turn Wi-Fi off and reopen the window. The grid still
   fills from cache, your imported templates still work end to end, and there is no
   error — the cache is doing its job. Now delete
   ~/Library/Application Support/OpenWhisp/Plugins/MemeGenerator/catalog-cache.json,
   stay offline, and reopen: now you get an error with a Retry button, plus the
   hint to import your own.
5. Nothing sticks (the Fix KeyboardSynthesizer: move paste off main actor, preserve non-string clipboard #3 regression). Start a Generate and, while it runs:
   • Click a candidate thumbnail — it switches instantly. v2 ignored this.
   • Click a Browse grid template — same.
   • Press Cancel — the spinner clears and the surface is immediately usable.
     Then force a failure (unplug the network mid-generate, or point Cleanup at a dead
     endpoint): the spinner must clear and Generate must be pressable again. It must
     never be necessary to close the window to recover.
6. Add text back (the Fix streaming pipeline & session lifecycle in AppState #4 regression). Delete every text box with the trash
   icons. The right panel must still show "Add text", and the canvas a hint. Press
   it — a box appears and renders. v2 left you stuck here.
7. v2 wins still hold. Generate "yoda meme, do or do not there is no try": expect
   the warning triangle, the honest status, the candidate strip, and no silent
   Drake. Search yoda in the grid → empty, and it says so. Edit a caption, then
   Export PNG… — the file must match the preview exactly at full resolution.
8. Delete a user template. Right-click one of yours → Delete. It leaves the grid,
   and if it was on screen the canvas clears rather than showing a meme built on a
   template that no longer exists.

Gates: swift test 2456 passed, 0 failures · scripts/check-appstate-ratchet.sh
OK at exactly 7051 · PLUGINS=1 ./build.sh · plain ./build.sh (no plugin code) ·
lean (WHISPERKIT=0 PARAKEET=0 SPARKLE=0 PLUGINS=1) — all compile, no new warnings
in the touched files (the AppState warnings that remain are pre-existing and at
untouched lines).

New tests (60, in MemeProviderTests.swift): merge precedence and the user-first
rule, cross-source name collisions with differing ids, keyword/cross-field/Cyrillic
search, the live memegen wire shape, older-cache decoding, cache staleness including a
skewed clock and a future-version cache, silent-vs-reported refresh failure, library
naming/uniqueness/pruning, traversal-shaped filename refusal, and the busy-state
machine's out-of-order, duplicate, superseded, cancel, warming, and
always-selectable orderings. Plus one in PluginSystemTests pinning the new
api.memegen.link disclosure string.

Open questions

1. Is a window per plugin the right surface, or should plugins contribute a pane inside the existing Settings window?
2. How much UI should a plugin be able to express? Declarative (safe, limited) vs its own window (flexible, needs process isolation) decides between tiers 1 and 2 above.
3. Should plugins be able to register a hotkey / voice action? The meme plugin would obviously want "make a meme about…" as a spoken command, which means plugins need into the trigger layer, not just the window layer. MAK-100 sharpens this: the voice router will cap the exposed tool surface at ~15, so trigger registration is a scarce resource the host must arbitrate — a plugin cannot be allowed to self-assign priority.
4. Does a plugin get its own model config, or always follow Cleanup? v3 makes this more pressing: the plugin now warms a model on window open, so "which model" has a cost attached rather than being purely a routing question.
5. Is plugins/ in this repo the long-term home, or a staging area until the IPC contract exists?
6. Is imgflip's top 100 enough? Answered in v3: no. The corpus is now imgflip + memegen.link + a user-importable library. The remaining question is narrower — should the plugin ship a starter pack of non-English templates, or is user import the right and only answer? v3 bets on import, on the grounds that any curated list is somebody's culture and the shipped one would be wrong for most users.
7. Should edited memes be saveable/reopenable? The box model is already Codable — persisting it would make the editor a document surface rather than a one-shot. v3 raises the stakes: a user who imported a template and captioned it has done real work that closing the window still discards.
8. New in v3 — should the user template library be a plugin-owned store or an app-level one? It currently lives under the plugin's Application Support directory, which is right for a spike. But "images the user imported" is plausibly a shared resource (Scratchpad attachments, future plugins), and moving it later means migrating user-owned files that are not re-downloadable.

---

v4 — three defects from the owner's live pass on v3

All three were reported against a running build. Each one turned out to be a
signal that already existed and was being discarded — which is the theme worth
taking out of this round.

1. Search couldn't find a template by describing it

Report: "the worst day for the planet" / "the worst day so far" does not
surface the Bart Simpson Worst Day Of My Life So Far template, even though it
is in the corpus.

Root cause. Both search entry points required EVERY query token to appear:

needles.allSatisfy { haystack.contains($0) }

"planet" appears in neither that template's name nor its keywords, so one
unmatched token vetoed the three that matched perfectly, and the result was
empty. A description of a meme's content can essentially never satisfy an
all-tokens rule — which made describing a meme the one thing search couldn't do.
v3 had pinned this as intended behaviour in testSearchRequiresEveryTokenToAppear.

Fix. Matching is now SCORED over name + keywords
(MemeTemplateCatalog.score), ordered best-first:

tier	score	why
exact name	10 000	typing a name means you want that template
whole-phrase containment	5 000 + closeness	"drake" ⊂ "Drake Hotline Bling"
token in name	100	strongest per-token evidence
token in keyword	60	an alias is real, but weaker than a name
prefix hit (name / keyword)	25 / 15	partial matches count, and count less
coverage bonus	≤ 50	matching more of what the user actually said

Ties break on the catalog's own order, which is the popularity ranking. What did
not change: a query matching nothing at all still returns an empty list.
Ranking partial matches and inventing a match are different things, and the
silent substitution is the bug this spike exists to fix.

The LLM path benefits from the same scoring. v3 sent the model
promptNames(catalog, limit: 100) — the first hundred by popularity, names only.
That fails twice: the relevant template can sit at position 180 of a merged ~300
corpus and never enter the prompt, and bare names give a model nothing to connect
a content description to. v4 prefilters locally first
(MemeTemplateCatalog.prefilter, top 30 by score against the user's own words)
and sends those with their keywords (promptLines), so the model ranks a
shortlist that is guaranteed to contain the right answer and is small enough for
a tiny local model to attend to. The name stays first and unadorned on each line
so MemeAI.validate still rejects hallucinations.

2. Template download stuck on "Downloading " forever

Root cause. renderTemplate had two bare returns on a stale/cancelled
ticket that never touched the state machine, and select() began a
.downloading ticket with no timeout at all (only generate() armed one).
The ordering that strands it: close the window (cancel() sets isCancelled),
reopen it (windowDidOpen clears isCancelled while the phase survives) — now
the surface is busy with no task, no timer and no Retry behind it.

This is the same bug class v3's own MemeGenerationState doc comment identified
and then reintroduced two call sites later: a bail that returns without clearing
the phase is only safe if some other task owns it, and here nothing did.

Fix.

• Every exit — cache hit, fetch failure, decode failure, stale ticket,
  cancellation — ends at a ticket-guarded, idempotent finish. Finishing a
  superseded ticket is a harmless no-op, so this cannot unstick newer work; what
  it can no longer do is leave a phase with nobody responsible for it.
• Downloads get their own finite ceiling (downloadTimeout, 30 s — well under
  the 120 s generate ceiling, because an image is not a model load), plus a
  shorter per-request transport timeout so the real reason surfaces first.
• windowDidOpen calls the new state.reset(), so a reopened window can never
  inherit a phase.
• An image failure now surfaces an honest error and its own Retry
  (imageFailed / retryTemplate) — distinct from the catalog's Retry, which
  re-fetches the catalog and does nothing for a failed image.

3. The first generates still failed with a raw network error

Root cause. v3 gated Generate behind a guessed 2.5 s sleep. A cold
llama-server takes far longer than that to bind its port, so the guess expired
while the socket was still refusing connections and the UI fired into it.

The readiness signal existed the whole time and was being thrown away:
LlamaServerEngine.ensureRunning polls the server's /health endpoint and calls
back only once it answers, but AppState.warmLlamaServerIfPossible discarded
that completion ({ _ in }).

Fix. No timing guesses anywhere in this path.

• warmLlamaServerIfPossible(provider:completion:) forwards real readiness.
• The plugin's warm seam carries it, so "Preparing model…" lasts exactly
  until the model can take a request — instant on a warm server, a minute on a
  cold one. A warm that fails says so rather than presenting an
  available-looking button in front of a model that isn't there.
• A request that still hits a refused connection (the server can pass a health
  check and refuse the next connection mid-restart) retries with backoff —
  MemeGenerateRetry, 3 attempts, 0 / 0.75 / 2.0 s. Matched on URL error
  codes, not message text, so a non-English Mac doesn't silently stop
  retrying.
• The warm itself has a ceiling too, so a server that never becomes healthy can't
  park Generate behind "Preparing model…" forever — that would just be defect 2
  wearing a different hat.

AppState got smaller

Warm policy moved into the pure LLMWarmReadiness resolver (which providers
need a local server; why an explicitly-resolved provider bypasses the Cleanup
toggle, per MAK-53) and the engine call into an AppState extension. Net effect:
AppState shrank by 15 lines, and scripts/appstate-loc-budget.txt drops
7051 → 7036 to lock the win in.

Gates

• swift test — 2485 passing, 0 failures (2456 baseline + 29 new).
• AppState ratchet — OK, budget lowered to 7036.
• PLUGINS=1 ./build.sh, plain ./build.sh, and lean
  (WHISPERKIT=0 PARAKEET=0) all compile. No new warnings in any touched file.

New tests

The repro is pinned directly, and was verified to fail against the v3
all-tokens rule before the fix (both "worst day" tests returned nil):

• testWorstDayDescriptionFindsTheBartTemplate — the owner's exact query.
• testWorstDaySoFarDescriptionFindsTheBartTemplate — his second phrasing.
• testARelevantTemplateOutranksPopularOnesThatDoNotMatch,
  testANameMatchOutranksAKeywordMatch,
  testAPrefixMatchScoresBelowAWholeTokenMatch,
  testAPartialTokenMatchStillSurfacesTheTemplate,
  testMoreMatchedTokensRanksHigher,
  testEquallyScoringHitsKeepPopularityOrder,
  testAStopwordOnlyQueryStillFilters,
  testRankedSearchStillReturnsNothingWhenNothingMatchesAtAll — the scoring
  contract, including the no-fallback guarantee.
• testPrefilterPutsTheRelevantTemplateInFrontOfTheModel,
  testPrefilterFallsBackToPopularityWhenNothingMatches,
  testPrefilterNeverRepeatsATemplateWhenToppingUp,
  testPromptLinesCarryKeywordsAfterAnUnadornedName,
  testAModelCopyingTheNameOffAPromptLineValidates — the LLM shortlist.
• testAReopenedWindowNeverInheritsADownloadingPhase,
  testResetRefusesTheAbandonedDownloadsLateResult,
  testFinishingASupersededDownloadCannotDisturbTheNewerOne,
  testADownloadHasItsOwnFiniteCeilingShorterThanAGenerates,
  testDownloadTimeoutMessageNamesTheTemplateAndOffersRetry — the stuck-download
  orderings.
• testARefusedConnectionIsTreatedAsNotReadyYet, testARealFailureIsNotRetried,
  testRetriesAreBoundedAndThenReportHonestly, testRetryDelaysBackOff,
  testNotReadyDetectionDoesNotDependOnLocalizedText,
  testRetryStatusNamesTheAttempt,
  testAWarmThatNeverCompletesCannotBlockGenerateForever — the retry policy.
• testTheBundledProviderIsWarmedByWaitingForItsLocalServer,
  testANonBundledProviderIsReadyImmediately,
  testTheBundledProviderWithoutItsModelIsUnavailable,
  testAnExplicitlyResolvedProviderBypassesTheCleanupToggle — warm policy.

testSearchRequiresEveryTokenToAppear was replaced, not deleted quietly — it
encoded the defect as intended behaviour, and its successors state the new
intention.

Not verified in this round

The fixes are pinned by unit tests and the app compiles, but v4 has not been
exercised against a running app + live llama-server. The readiness gate, the
connection-refused retry, and the download timeout all depend on real transport
behaviour that swift test stubs. The next live pass should specifically check
that the first Generate after opening the window succeeds (or honestly says
it is still preparing), and that a template whose image 404s shows the error plus
a working Retry.

---

v5 — the day-long soak

The owner left the app running for a day and reported two things: template
downloads had stopped working entirely, and there was no way to start a meme
from scratch. A third item (a menu shortcut) came in alongside them.

1. Downloads stop working after ~a day of uptime

Two independent causes. Both need uptime and a window close to appear, which
is why they survived every previous round — v3 and v4 were both tested by opening
the window and using it, never by closing it and coming back.

Root cause A (primary) — the window lifecycle was unbalanced

PluginHost.open() caches a plugin's window controller for the app's lifetime
and reuses it on every subsequent open. MemeGeneratorWindowController.init was
the only caller of model.windowDidOpen(), so that ran exactly once. But
windowWillClose ran on every close, and it calls model.cancel(), which
sets isCancelled = true. Only windowDidOpen clears that flag.

So the first time the user closed the window, isCancelled latched true for the
rest of the launch, and every async result afterwards was dropped:

guard !self.isCancelled, self.state.accepts(ticket: ticket) else { return }

The downloads were not hanging. They were completing and being thrown away —
which matches the report exactly: fine all day, then permanently dead, with a
relaunch as the only cure.

Note this is the same bug class v4's own doc comments described and believed they
had fixed. v4 correctly identified that windowDidOpen had to reset the state,
and added state.reset() to it — but never checked whether windowDidOpen was
still being called. The reset was right; it was unreachable.

Fix: a PluginWindowLifecycle seam. PluginHost tells a cached controller it
is being shown again, and the meme controller re-runs windowDidOpen(). Setup
and teardown are now balanced however many times the window is opened and closed.
The seam is on the host, not the plugin, because every cached plugin window has
this hazard the moment it does anything on close.

Root cause B — the session was unreplaceable, which made Retry a no-op

MemeTemplateService.session was a process-lifetime static let. A URLSession
is a connection pool, and a pooled connection can outlive its own validity — the
Mac sleeps and wakes on a different network, a VPN comes up, a captive portal's
lease expires. After that, every request through that session fails identically
until relaunch.

This is also why Retry did nothing: it re-ran the request through the same
session, inheriting exactly the pool that was broken. A no-op by construction,
however many times it was pressed.

Fix: the session is rebuildable. A transport-shaped failure invalidates it
(invalidateAndCancel, so the connections actually go away) and the next request
builds a fresh pool. Both Retry paths — image and catalog — invalidate first, so
a retry is always a fresh session and a fresh URLRequest rather than a
replay of the attempt that hung. Every network read funnels through one get
helper so no path can skip the rule.

Which failures count is the pure, tested MemeGenerationState.isTransportFailure,
matched on NSURLErrorDomain codes (not localized message text). Narrow on
purpose: a 404 or an undecodable image says nothing about the transport and keeps
the pool.

Audited and cleared — the catalog cache TTL

Suspect (a) from the report was investigated and is not a cause. An expired
cache resolves to .useCacheAndRefresh — show it, refresh behind it — never to a
wedge, and a week-old cache still serves rather than degrading to .fetchNow. A
background refresh failure is silent only while templates are on screen, which
is correct; with nothing on screen it surfaces the error and names Retry. Pinned
with clock-injected tests at both TTL boundaries so it stays true.

2. "New meme" — starting from scratch

A New meme button (SF Symbol arrow.counterclockwise, ⌘N) clears the
description, caption boxes, candidate strip, selected template, rendered meme,
search text, and every error state. It calls state.reset() first, so
anything in flight is refused by the existing ticket guard rather than landing on
the surface the user just cleared.

The clearing is a pure MemeComposition value whose reset() returns .empty
wholesale. That matters: a reset written as a dozen assignments passes its test
while silently missing the field someone adds next month. Here the test asserts a
fully-populated composition comes back exactly equal to .empty — the
property a partial reset actually fails.

Deliberately survives the reset: the template catalog (a corpus, not part of
this meme — clearing it would turn New meme into a network round-trip and a
spinner) and the downloaded image cache (keyed by template id, holds nothing
about this meme).

The button is always present but disabled on an untouched window, rather than
appearing when there's something to clear — a control that materializes is harder
to find than one that's dimmed, and this is the button someone reaches for when
the surface is in a state they don't understand. An error alone counts as
something to clear. The empty canvas now invites the next action instead of just
being blank.

3. ⌘M opens the Meme Generator

Manifests carry an optional keyEquivalent. The plugin asks; the host
decides (PluginKeyEquivalent) — only the host can see the whole menu, and a
plugin that could silently shadow ⌘Q would be a genuine hazard rather than a
papercut.

Collisions resolve against the app's reserved set (q s , c x v a z — what
AppMain really binds, not a padded guess) and then by list order, first-wins,
matching the precedence PluginDiscovery already uses for id collisions. A
refusal is silent and costs only the shortcut, never the menu row. The
Plugins pane shows the granted shortcut, resolved through the same pass, so
it can never advertise a key the menu refused.

Decode is forward-compatible (an older manifest still decodes), and a malformed
shortcut is reported by validate() but is not fatal — losing a working
plugin over a cosmetic field would be the wrong trade.

This is the MAK-100 "manifests carry host metadata" direction: a second plugin
wanting a shortcut needs no change in AppMain at all.

Tests (35 new, Tests/OpenWhispCoreTests/MemeRecoveryTests.swift)

Clock-injected staleness:

• testCacheOneSecondPastTheTTLIsShownAndRefreshedRatherThanDiscarded
• testCacheOneSecondBeforeTheTTLStillAvoidsTheNetwork
• testAWeekOldCacheIsStillServedRatherThanForcingAFetch
• testAFailedRefreshBehindAStaleCacheStaysSilent
• testAFailedRefreshWithNothingCachedSurfacesTheErrorAndTheRetry

Session recycling:

• testSleepWakeTransportFailuresRecycleTheSession
• testNonTransportFailuresKeepTheSession
• testForeignErrorDomainsAreNotTreatedAsTransportFailures

Failure-then-recovery and the stranded phase:

• testResetClearsAStrandedDownloadingPhaseWithoutATicket
• testWorkStrandedByAResetCannotFinishOverTheFreshState
• testADownloadFailureThenRetryRecoversTheSurface
• testTheDownloadCeilingIsFiniteAndTighterThanTheGenerateCeiling
• testTemplateSelectionSurvivesAFailedDownload

Reset totality:

• testResetReturnsEveryFieldToTheInitialEmptyState
• testResetClearsThePromptCaptionsCandidatesAndErrors
• testResetIsIdempotent, testAnUntouchedCompositionIsEmpty
• testACompositionHoldingOnlyAnErrorIsNotEmpty
• testACompositionHoldingOnlyADictatedDescriptionIsNotEmpty

Shortcuts: PluginKeyEquivalentTests (9) + PluginManifestKeyEquivalentTests (6),
covering normalization, the reserved set, list-order collisions, forward-compatible
decode, and non-fatal malformed shortcuts.

Gates

• swift test — 2520 passing (2485 baseline + 35 new), 0 failures
• AppState ratchet — 7036 / 7036, unchanged (nothing added to AppState)
• PLUGINS=1 ./build.sh, plain ./build.sh, and lean all compile
• No new warnings in any touched file

Not verified in this round

• No screenshots — the Mac app can't be screenshotted in this environment.
• The day-long idle can only be simulated. The reopen bug is proved by code
  inspection and pinned by the state-machine tests, but the actual
  close-wait-a-day-reopen sequence was not performed. The specific live check
  worth running: open the plugin, close it, reopen it, and confirm a template
  download still completes — that alone exercises root cause A, and needs
  seconds rather than a day.
• The wedged connection pool is inferred, not observed. isTransportFailure
  and the recycling are unit-tested, but no real sleep/wake cycle was performed
  against the live CDNs, and MemeTemplateService sits behind PLUGINS=1 so it
  is outside the swift test target. sessionGeneration is surfaced in the
  failure status line specifically so the next report can distinguish "never
  recycled" from "recycled and still failing".
• ⌘M and ⌘N were not exercised on a running app. Note ⌘M is a menu-bar
  menu shortcut (it fires with the menu open), the same as the Scratchpad's
  existing ⌘S — not a global hotkey.

---

v6 — the AI pipeline, critiqued

v5 fixed the plumbing (stuck states, dead retries, a recyclable session). v6 goes
after the algorithm, which had two assumptions baked in since v1: every meme is
a top line and a bottom line, and the model should copy template names verbatim.
Both are wrong for most of the corpus, and both had the data to do better sitting
unused on the wire.

1. Per-template caption structure — the biggest quality fix

Templates aren't all top/bottom. Drake is two side labels, Distracted Boyfriend is
three, Expanding Brain is four. Rendering a four-panel meme with a top line and a
bottom line isn't a stylistic choice — the joke lives in the per-panel captions, so
the meme is simply broken.

Both sources carried the structure and v5 discarded it:

Source	Field	Verified shape
imgflip get_memes	box_count	100 templates: 1×1, 66×2, 23×3, 9×4, 1×5
memegen /templates	lines	212 templates: 7×1, 166×2, 23×3, 7×4, 4×5, 3×6, 2×8

Both now decode into MemeTemplate.captionSlots, clamped to 1...8
(MemeCaptionSlots) and defaulting to 2 — so a v5 disk cache, a user-library
import, and any source that doesn't report it all behave exactly as before.

The LLM contract changes with it: the shortlist annotates each non-default template
[N captions], and the model returns a captions ARRAY sized to its top pick's
slot count instead of top_text/bottom_text. The parser keeps accepting the legacy
pair as a 2-slot response, so a model that ignores the new schema is no worse off.

Slot geometry: synthesized, not sourced — the decision

The brief hoped memegen would supply real box positions. It does not. Verified
against both live APIs on 2026-08-03:

• GET https://api.memegen.link/templates and GET /templates/<id> both return
  {id, name, lines, overlays, styles, blank, example, source, keywords, _self}.
  lines is a count. There is no geometry field anywhere in either payload.
• imgflip's key-less get_memes is the same story: box_count, no rectangles.
  imgflip does expose per-box geometry — but only through the authenticated
  caption_image endpoint, which is a server-side captioning API this plugin
  deliberately does not use. Routing the user's words through it would put their
  text on someone else's server, which is the local-first line the whole plugin holds.

So every position is synthesized from the count, and the doc comment on
MemeCaptionLayout.slotCenters says so plainly rather than implying template
accuracy — a wrong claim about provenance is how the next person "fixes" a fallback
that was never a fallback.

The fallback layouts:

Slots	Layout	Why
1	One centered caption near the top	The impact-font one-liner
2	Classic top/bottom at 0.12 / 0.88	Unchanged from v1 — two thirds of the corpus. Regressing the common case to win the rare one is a bad trade
3–4	Stacked left column (x = 0.30), narrower boxes, smaller type	The spike-grade compromise — see below
5+	Even full-width column	Past four slots there's no dominant convention left to approximate

The 3–4 case is an explicit compromise and worth naming as one. The templates
that matter here (Drake, Distracted Boyfriend, Expanding Brain, Galaxy Brain) are
panel memes: captions belong beside or inside stacked panels, never spread
top-to-bottom across the frame. A stacked column is roughly right for a
vertically-panelled template (Drake, Expanding Brain — the most common panel layout
by far) and only approximately right for a horizontally-panelled one (Distracted
Boyfriend). That trade is deliberate: approximately-right and draggable beats
confidently-wrong and invisible. The user sees N captions in N distinct places and
moves them, instead of getting two captions for a four-panel joke.

The real fix is per-template geometry, which needs a data source none of the key-less
APIs provide — a bundled table of hand-measured boxes for the top ~30 templates would
do it, and that is a deliberate non-goal for a spike.

2. Numbered candidate references

The shortlist has been numbered since v4 and the numbers went unused: v5 asked the
model to copy names "EXACTLY", then dropped anything that didn't match. That is a
transcription task, and it is the single most fragile thing you can ask a tiny local
model to do — it re-capitalizes, expands "Y U No" to "Why You No", drops or folds in
the parenthesized keywords, and every one of those was a silently discarded
candidate.

The model now answers {"templates": [3, 17, 1]}. MemeAI.resolve accepts:

• numbers — 1-based (firstCandidateNumber), indexing the shortlist it was shown
• numeric strings — ["3"] means the third template, not a template named "3"
• exact names — the v5 path, kept verbatim for backward compatibility
• any mix of the above in one answer

Out-of-range numbers are DROPPED, never clamped. Quietly handing back the last
template for 47 would be v1's confident-Drake bug wearing a number. Dedupe is on the
resolved template, so a number and its own name can't occupy two of the five strip
slots. An element of an unrecognized shape (an object, a null) is skipped rather
than failing the decode — one weird element must not cost the user the four good
candidates beside it.

3a. Captions re-fit on a candidate switch

The strip's promise is "same joke, different template". That held while everything was
two-slot and breaks the moment structure varies: Drake (2) → Expanding Brain (4) left
two captions on a four-panel meme; the reverse stacked four captions on two panels.

Redistributing locally can't work — going 2 → 4 needs two new lines invented in the
user's language and the joke's voice. So a small second LLM call ("same joke,
refit to N slots"), with no catalog in the payload and no ranking.

What keeps it from becoming the next stuck-state bug:

• Own ticket through the existing MemeGenerationState, so Cancel works and a
  superseded refit can't overwrite a newer one.
• Never blocks the strip. The template has already rendered when the refit starts;
  the user can click straight past it and the in-flight refit is refused when it lands.
• Every exit path — no-op, no LLM configured, parse failure, transport failure, stale
  ticket, timeout — ends at finish for its own ticket.
• Failure is silent and leaves the previous captions in place. The switch itself
  succeeded, so surfacing an error would make a working action look broken.
• Fast path: same slot count reuses the captions instantly with no round-trip.
  That's the common case (two thirds of the corpus is 2-slot), so the strip does not
  get slower than v5.

3b. Regenerate no longer clobbers manual work — the rule

Generate replaces AI-seeded boxes and PRESERVES boxes the user added.

v5 assigned boxes = seedBoxes(...) outright, so a user who pressed "Add text", typed
a third caption and positioned it lost it the moment they tweaked the description and
regenerated. Silent destruction of manual work is the worst class of editor bug, and
there is no undo here.

Of the two options in the brief, this takes preserve-user-boxes over confirm-first:

• A dialog charges every regenerate (the common, harmless case: nothing was
  hand-added) to protect the rare one. Generate is the plugin's primary verb.
• "Your boxes survive, the AI's are rewritten" is a rule a user can hold in their head
  and predict; a dialog they dismiss reflexively is not.
• It's reversible in the direction that matters: an unwanted surviving box is one
  click on the trash, a destroyed caption is retyped and repositioned from memory.

Edits to a seeded box are still replaced — that box is the AI's answer to the old
description, and a regenerate asks for a new one. Keeping the old text would make
Generate look broken. Boxes typed before the first generate count as user-added and
survive.

4. Cheap learning signal

Clicking past the model's first pick is a correction — unambiguous, free, and produced
by an action the user was taking anyway. v5 discarded all of it.

MemeTemplateAffinity adds a small persisted boost per template, applied in the
prefilter ranking. The bounds matter more than the signal, because an unbounded
boost is a personalized version of the confident-Drake bug:

• 12 per pick — smaller than one keyword-token match (60), far smaller than a
  name-token match (100). One correction reorders near-ties and nothing else.
• Ceiling 120 — roughly two name-token matches, reached after ten picks. Past that
  the signal saturates instead of compounding, so a long-lived store can't slowly
  take over the ranking. Still far below the whole-phrase (5,000) and exact-name
  (10,000) tiers, so typing a template's name always wins.
• Only boosts templates that ALREADY match. Applied inside ranked to templates
  whose lexical score is already > 0, never to a zero-scoring one. This is the
  load-bearing rule: "no template matches" stays reachable however much the store
  has learned, and a favourite can never appear for an unrelated query.
• Does not reorder an unfiltered Browse grid — that grid is the corpus in
  popularity order, and floating favourites into it would make its order mean two
  different things depending on whether the search box was empty.
• Agreement doesn't count: clicking the candidate already ranked first is not a
  correction, and boosting it would be a feedback loop rather than a lesson.
• The decoder re-applies the cap, so the hand-inspectable JSON can't inject a
  dominating boost.

Affinity survives New meme deliberately — it isn't part of this meme, it's what the
user has taught the ranker across all of them.

Also: the discarded "think first" invitation

v5's prompt said "Think about which ones could carry the joke, then rank your best
options" — reasoning the parser then threw away. Pure token cost with no consumer,
on the models least able to afford it.

Of the two options in the brief, this takes surface the reason over drop it. The
model now returns one short reason, shown as an info tooltip on the candidate strip.
Same request for reasoning, routed somewhere the user can read it: if the model picked
Drake for a bad reason, the user reads the bad reason instead of guessing why the
thumbnail is there. Reasoning that is displayed earns its tokens; reasoning that is
discarded does not. It's attached only to the first candidate, since that's the
pick the model was asked to justify. Thumbnails also now show the slot count, so a
switch that's about to reshape the captions is visible before the click.

All v5 wins are kept: scored search, the lifecycle seam, session rebuild, reset, ⌘M.

Tests (73 new, MemeStructureTests)

Slot counts off the wire: testImgflipBoxCountBecomesCaptionSlots,
testMemegenLinesBecomeCaptionSlots, testImgflipWithoutBoxCountDefaultsToTwoSlots,
testMemegenWithoutLinesDefaultsToTwoSlots,
testZeroAndNegativeSlotCountsAreClampedUp, testAbsurdSlotCountIsClampedDown,
testAV5CacheWithoutSlotsStillDecodesAtTheDefault,
testCaptionSlotsRoundTripThroughTheCache

Slot geometry + seeding: testTwoSlotsKeepTheClassicTopAndBottomLayout,
testOneSlotIsASingleCenteredCaption,
testPanelSlotsAreDistinctEvenlySpacedAndInsideTheFrame,
testPanelLayoutsUseNarrowerBoxesAndSmallerTypeThanTheClassicPair,
testSlotGeometryIsClampedLikeEveryOtherSlotCount,
testSeedingProducesOneBoxPerSlotInPanelOrder,
testExtraCaptionsBeyondTheSlotCountAreDropped,
testTooFewCaptionsStillFillEverySlotWithAnEmptyBox,
testTheClassicTopBottomSeedIsTheTwoSlotCase

Numbered references: testNumberedCandidatesResolveToTheShortlistEntriesTheyIndex,
testTheNumberingIsOneBasedMatchingWhatThePayloadPrints,
testOutOfRangeNumbersAreDroppedRatherThanClamped,
testAnAllOutOfRangeAnswerLeavesNoUsableTemplate,
testExactNamesAreStillAccepted, testNumbersAndNamesMayBeMixedInOneAnswer,
testANumericStringIsTreatedAsAnIndexNotAName,
testANumberAndItsNameCollapseToOneCandidate,
testNumberedCandidatesAreCappedAtFive,
testAnUnparseableElementIsDroppedWithoutFailingTheWholeAnswer,
testAnEmptyShortlistResolvesNothingRatherThanCrashing

Caption arrays + legacy shape: testCaptionsArriveAsAnArrayInPanelOrder,
testLegacyTopAndBottomTextDecodeAsATwoSlotResponse,
testACaptionsArrayWinsOverStrayLegacyKeys, testATrailingEmptyCaptionIsDropped,
testAnInteriorEmptyCaptionIsKeptSoPanelsDoNotShift,
testTheModelsReasonSurvivesForTheStripTooltip, testAMissingReasonIsNotAFailure,
testAnAnswerWithNeitherTemplateNorCaptionIsStillRejected

Prompt + payload: testThePromptAsksForNumbersACaptionArrayAndAVisibleReason,
testOnlyNonDefaultSlotCountsAreAnnotatedInThePrompt,
testASlotArrayShorterThanTheLinesDegradesToTheDefault,
testThePayloadCarriesTheSlotCountsAndExplainsTheUnmarkedCase,
testPromptSlotsAlignPositionallyWithPromptLines,
testPromptSlotsRespectTheSameLimitAsTheLines

Refit: testNoRefitIsNeededWhenTheSlotCountMatches,
testARefitIsNeededWhenTheSlotCountDiffers,
testNoRefitForCaptionsThatAreAllEmpty,
testRefitNeedIsJudgedAgainstTheClampedSlotCount,
testTheRefitPayloadCarriesTheJokeTheCurrentCaptionsAndTheTarget,
testTheRefitPromptPinsTheLanguageAndForbidsPadding,
testARefitIsPaddedUpToTheSlotCount, testARefitIsTruncatedDownToTheSlotCount,
testARefitDigsItsJSONOutOfProse,
testAnUnusableRefitReplyIsRefusedRatherThanBlankingTheCaptions

Regenerate preservation: testRegenerateReplacesTheAISeededBoxes,
testRegeneratePreservesABoxTheUserAdded,
testUserBoxesAreAppendedAfterTheNewSeedWhateverTheSlotCount,
testAnEditedSeededBoxIsStillReplaced,
testTheFirstGenerateOnAnEmptyCanvasJustSeeds,
testBoxesTypedBeforeTheFirstGenerateAreTreatedAsUserAdded

Affinity + its caps: testAPickBoostsThatTemplate, testRepeatedPicksAccumulate,
testTheBoostSaturatesAtTheCapAndNeverExceedsIt,
testSaturationTakesTheDocumentedNumberOfPicks,
testOneBoostIsWorthLessThanOneKeywordMatch, testDecodingReAppliesTheCap,
testAffinityRoundTripsThroughJSON, testAnEmptyIDIsNotRecorded,
testResetForgetsEverything, testABoostPromotesATemplateOverAnEquallyScoringOne,
testASaturatedBoostCannotMakeANonMatchingTemplateAppear,
testASaturatedBoostCannotOutrankAnExactNameMatch,
testAnEmptyQueryKeepsPopularityOrderRegardlessOfAffinity,
testThePrefilterHonoursTheLearnedBoost,
testRankingWithoutAnAffinityIsUnchanged

One v5 test renamed: testRankedPromptForbidsInventingNamesAndPinsCaptionLanguage →
…ForbidsInventingCandidatesAndPinsCaptionLanguage. It pinned the literal "copied
exactly" wording; the anti-invention guard it protects is now the numbering, so the
assertion moved rather than being dropped. The language guard is untouched.

v6 gates

• swift test — 2593 passing (2520 baseline + 73 new), 0 failures
• AppState ratchet — 7036 / 7036, unchanged (nothing added to AppState)
• PLUGINS=1 ./build.sh, plain ./build.sh, and lean (WHISPERKIT=0 PARAKEET=0)
  all compile
• No new warnings in any touched file

v6 — not verified

• No real-LLM round-trip was run. The new prompts (rankedPrompt, refitPrompt)
  and the parser are pinned by unit tests against synthetic replies, but no actual
  local model was asked to produce a numbered array or a refit. Whether a small
  local model reliably returns [3, 17, 1] and exactly N captions is precisely the
  claim tests can't make. This is the highest-value live check:
  ./scripts/e2e-app-features.sh with the app running and llm=configured, then
  generate a 4-slot meme (e.g. "expanding brain about deploys") and confirm four
  captions land in four boxes.
• The 3–4 slot layout was not eyeballed on a real template. The geometry is
  pinned as distinct, ordered, evenly spaced, inside the frame; whether the stacked
  left column actually sits well on Distracted Boyfriend is a visual judgement no test
  makes, and the Mac app can't be screenshotted in this environment.
• The refit's cancellation ordering was not exercised live. Clicking rapidly
  through candidates with differing slot counts should supersede each refit; the
  ticket guards are the same ones v5's tests cover, but the specific
  click-through-mid-refit sequence was not performed against a running model.
• Affinity persistence is untested on disk. MemeTemplateAffinity is fully
  covered as a pure value, but MemeLibraryStore.loadAffinity/saveAffinity sit
  behind PLUGINS=1, outside the swift test target — the same structural limit the
  rest of the store has.
• API shapes were verified on 2026-08-03 only. The box_count / lines
  distributions quoted above are from live calls that day. Both fields are optional in
  the decoders, so a schema change degrades to 2-slot rather than breaking the catalog.

---

v7 — the model shouldn't have been writing those captions at all

The v6 live failure, from the owner's screenshot. Prompt:

expanding brain: typing, dictating, dictating memes, dictating memes by voice

Expanding Brain was picked correctly (4 slots) and only TWO captions rendered,
seeded as a classic top/bottom pair. Root cause, confirmed by reading the v6 code
rather than guessing:

1. The local model answered in the legacy top_text/bottom_text form.
2. RankedWire's backward-compat branch accepted it — that branch can only ever
   produce exactly two captions.
3. Nothing compared the caption count to the chosen template's slot count.
   applyRanked handed two captions to a 4-slot seedBoxes, which padded with
   blanks and rendered.

v6 had already tightened this prompt twice. A third tightening would have been
treating the symptom, so v7 changes the algorithm in three places.

1. Read the captions the user already said (highest leverage)

Look again at the prompt: the four captions are right there, comma-separated,
in order, after a colon. Asking a 1.5B local model to re-derive four strings it was
just handed is inventing a language task where none exists — and every such
round-trip is a chance to get two back instead of four.

MemeCaptionExtraction (new, Foundation-only, in core) reads list-shaped
descriptions directly and uses the items verbatim as captions, skipping LLM
caption-writing entirely. The LLM keeps the one job it is actually needed for:
picking a template. A model cannot return the wrong number of captions for a
request that was never made.

Recognised shapes: colon lists (theme: a, b, c), numbered runs (1. a 2. b),
newline/bulleted lists, and the spoken final joiners (a, b and c, then, plus
и/затем/und).

The negative cases matter more than the positive ones. This runs before the LLM
on every generate, so a false positive would hijack ordinary prose and caption the
meme with sentence fragments. Three independent gates:

• An enumeration signal is required. A bare comma run inside a sentence is not
  enough — that is how people write prose. make me a drake meme about rust, python and go is prose about three things and is not extracted (pinned by a test).
• The item count must be 2…8. One item is a phrase; past eight no template could
  hold it.
• Every item must be caption-sized (≤ 6 words). steps: first you plan the whole thing out carefully, then you throw it away entirely is prose with a colon, and
  falls through.

Anything failing a gate goes down the v6 LLM path completely unchanged.

The extracted theme (expanding brain) is also split off and used as the template
query instead of the whole sentence, so the caption words don't pollute the search.

2. Host-side slot enforcement

MemeAI.fit is now the single rule for whether captions may be rendered:

Situation	v6	v7
count == slots	render	render
count != slots	silently padded and rendered	refit — "Model wrote 2 of 4 — refitting…"
legacy top/bottom on a 2-slot template	accepted	accepted (correct here)
legacy top/bottom on an N≠2 template	accepted → the bug	refit

The refit uses the ticket-guarded call that already existed ("same joke, exactly N
captions") — v6 built it for template switches and never reached for it on the
generate path. refitCaptions is now extracted so both entry points share one
implementation and can't drift; the status line differs because the two moments mean
different things to the user.

RankedSpec.wasLegacyShape records which wire shape produced the captions, so the
host can tell a deliberate 2-slot answer from a model that never engaged with the
slot count. The count is what decides today — the flag is what makes the
distinction legible without re-parsing.

Slot geometry is now unconditional, which is the screenshot's second bug: boxes
always seed into the template's own layout, so a 4-slot template gets four
panel-positioned boxes no matter what the model wrote. Ordering is deliberate — the
template renders first, then the refit runs, so the correction is visible rather
than a longer wait.

3. Constrained decoding — grammar enforcement DID land

Yes, this works. Every other guard in this file is a parser deciding after the
fact, which is a losing game against a small local model one shape at a time.

llama-server implements OpenAI-compatible response_format: {"type": "json_schema"}
by compiling the schema to a GBNF grammar and constraining the sampler. So the
bad shapes become unrepresentable rather than rejected downstream:

• templates is typed integer → an invented template name is not a reachable
  token sequence. v6's numbered-reference idea becomes airtight rather than
  best-effort.
• The refit schema pins minItems == maxItems == N → "wrote 2 of 4" cannot be
  emitted. The refit is the one call where the required count is known up front.
• The legacy keys are absent from the schema entirely, so a constrained model cannot
  reach for them. The v6 bug's entry point is closed at the sampler.

The plumbing turned out to be tractable. ChatCompletionRequest gained an optional
response_format (encoded with encodeIfPresent, so every existing caller's
request bytes are byte-identical to v6); processFinalText and summarizeResolved
gained a defaulted-nil parameter; the plugin's AICall seam carries the schema
because only the model knows which of the two shapes a given call expects. Schemas
are built as JSONValue values in core rather than raw strings — a schema stored as
a string literal would be exactly the untested wiring this spike exists to avoid.

AppState grew zero net lines — the ratchet is still at exactly 7036.

Host-side fit is kept regardless: not every endpoint enforces schemas, and the
parser must stay correct for the ones that don't.

Also: slot-count-aware template search

When the item count is known, prefilter stably reorders exact-slot matches first.
Reordering, never filtering — a 4-item list whose best lexical match is a 2-slot
template should still see it (the refit path handles the mismatch); hiding a template
the user described would be the confident-Drake bug in a new costume.

v7 tests (31 new, MemeSlotEnforcementTests + 2 in MemeStructureTests)

• testTheScreenshotPromptYieldsExactlyFourCaptionsInOrder — the exact repro
  string → exactly 4 captions, in order, theme split off.
• testTheReproEndsWithFourFilledBoxesAndNoRefit — end-to-end minus the network:
  extract → replace → fit → seed, with the model answering in the legacy shape.
• testTwoCaptionsOnAFourSlotTemplateRefitRatherThanRender — the v6 bug, now caught.
• testTheLegacyShapeIsAcceptedAsFinalOnATwoSlotTemplate /
  testACaptionsArrayOfTwoIsNotFlaggedAsTheLegacyShape — the 2-slot-only rule.
• testTwoCaptionsOnAFourSlotTemplateStillSeedFourPanelBoxes — asserts the boxes are
  not at the classic top/bottom centers.
• testProseWithCommasIsNotTreatedAsAList and four more negative cases — the
  false-positive guard.
• testTheRefitSchemaPinsExactlyTheRequestedCaptionCount,
  testTheRankedSchemaForcesNumericTemplateReferences — schema contents, including
  that top_text/bottom_text appear nowhere.
• The two v6 tests that pinned legacy acceptance were updated to the new
  2-slot-only rule rather than deleted.

v7 gates

• swift test — 2624 passing (2593 baseline + 31), 0 failures.
• AppState ratchet — PASS at exactly 7036 (zero net growth).
• PLUGINS=1 ./build.sh, plain ./build.sh, and WHISPERKIT=0 PARAKEET=0 ./build.sh
  — all succeed.
• Warnings: 112 with the change vs 113 on baseline — no new warnings in touched
  files.

v7 — not verified

• No live model ran against the schema-constrained request. The schema is pinned
  by tests and the plumbing compiles, but whether this llama-server build accepts
  this response_format shape and honours the grammar is exactly the claim a unit
  test cannot make. This is the highest-value live check — run
  ./scripts/e2e-app-features.sh with llm=configured, generate with the repro
  prompt, and confirm four captions. If the endpoint rejects the key, the host-side
  fit still catches the mismatch and refits, so the failure mode is v6-with-a-refit
  rather than a break — but that fallback path was not exercised live either.
• The refit-after-generate ordering was not watched on screen. Tests pin that a
  mismatch produces .refit and that the seed happens first; that the status line
  reads well as the captions visibly change is a judgement no test makes.
• List extraction was tuned against the repro and constructed cases, not a corpus
  of real dictations. The 6-word caption ceiling and the colon requirement are
  judgement calls. A user who dictates lists differently (semicolons, "first… second…")
  falls through to the LLM path — correct but unproven against real speech.
• Non-Latin joiners are covered by inspection only. и/затем/und are in the
  splitter, but no test dictation exercises them.
• The Mac app still can't be screenshotted in this environment, so the four-panel
  render was verified through box geometry assertions rather than by looking at it.

---

v8 — the tests passed and the app was still broken

Root cause of the live failure: it was v6 code

The owner's screenshot (Expanding Brain, four spoken items, two boxes carrying
"typing" and "dictating memes by voice" seeded top/bottom) was produced by v6,
not by v7. MemeCaptionExtraction.swift — the whole v7 caption fix — first appears in
e0386cf, committed at 14:51 today; the build in the screenshot predates it.

Reproduced exactly against v6's applyRanked:

// 3247bdf plugins/MemeGenerator/MemeGeneratorModel.swift:657-658
let slots = picks.first?.captionSlots ?? MemeCaptionSlots.default
seedBoxes(captions: spec.captions, slots: slots)   // no extraction, no fit

Those are the lines that collapsed 4 → 2. slots was already correctly 4 (imgflip
really does ship box_count: 4 for Expanding Brain — verified against the live API), but
spec.captions came from the legacy top_text/bottom_text branch of RankedWire,
which can only ever yield two. seedBoxes padded the rest, and nothing compared the
count to the template:

spec.captions -> ["typing", "dictating memes by voice"]   legacy: true
v6 boxes      -> ["typing", "dictating memes by voice", "", ""]
v6 FILLED     -> 2

That is the screenshot, character for character.

The defect that outlived the fix

The v7 fix was real, but the reason v7 could ship a passing test suite over a broken app
is still present, and that is what this section actually addresses.

testTheReproEndsWithFourFilledBoxesAndNoRefit re-implements the app's sequence inside
the test body — extract, then replacingCaptions, then fit, with slots: 4 written as
a literal. Every core piece was proved in isolation. But the code that chains them
lived in plugins/MemeGenerator/MemeGeneratorModel.swift, which compiles only under
PLUGINS=1 and sits outside the swift test target. So the chain was untested by
construction, and a test that spells out the right sequence proves nothing about an app
that performs a different one — which is exactly what v6 did.

Per the wiring-review lesson in CLAUDE.md: the wiring, not the rule, is what shipped broken.

The structural fix

New OpenWhisp/Services/MemeCaptionSeeding.swift (registered in Package.swift) owns
the entire captions→boxes decision:

MemeCaptionSeeding.resolve(
    description:, specCaptions:, wasLegacyShape:, templateSlots:) -> Seed

Three rules, each closing one way the bug returns:

1. The user's own list beats the model's captions. A list-shaped description supplies
   the captions verbatim; a model can't return the wrong count for a question never asked.
2. The geometry always comes from the TEMPLATE's slot count, never from the caption
   count — an N≠2 template cannot render as a classic two-liner.
3. A count mismatch refits rather than padding blanks.

templateQuery(for:) shares that same single extraction with the template search, so the
query and the slot preference can't disagree about whether the description was a list.

applyRanked is now a call to resolve plus UI glue. apply(seed:) is the only place
boxes is assigned; no description-reading logic remains in plugins/.

Two-caption entry points closed

• MemeRenderer.render(template:topText:bottomText:) → @available(*, unavailable). It had
  no callers; leaving a top/bottom-shaped overload in reach is precisely how a 4-slot
  template gets collapsed at the boundary without failing a test.
• MemeCaptionLayout.seedBoxes(topText:bottomText:) and
  RankedSpec(templateNames:topText:bottomText:) → @available(*, deprecated). No
  production callers remain; kept (deprecated, not unavailable) because several test
  assertions are legitimately about the 2-slot layout and rewriting them would lose that
  coverage.

The test that would have caught it

Tests/OpenWhispCoreTests/MemeCaptionSeedingTests.swift — 10 tests driving the same
function the app calls, from a raw legacy-shape model reply through to boxes: caption
text and order, slot geometry (four distinct stacked centers, not the classic
0.12/0.88 pair), refit reachability, and the negative assertion that the first-and-last
pair never appears.

Verified these fail against the v6 behaviour rather than passing vacuously — with
extraction disabled the repro test reports exactly
["typing", "dictating memes by voice", "", ""].

Re-verified v7's other wiring claims against the app path

• Schema is genuinely attached. Both aiCall sites pass one, and it survives the full
  chain: configureAI → ResponseFormat.jsonSchema → AppState.summarizeResolved
  → processFinalText → encodeIfPresent(responseFormat) on the wire.
• The refit is reachable from applyRanked's real caller, now via seed.refit.

Remaining un-testable surface (honest)

• renderTemplate, image download, redraw, ticket/timeout state — AppKit + network,
  reachable only under PLUGINS=1. They carry no caption-count decisions.
• refitCaptions is still app-layer: the decision (MemeAI.fit, parseRefit,
  refitStatus) is core-tested, but the async round-trip, ticket guards and status writes
  are not. Extracting it needs an injectable LLM seam — worth doing, out of scope here.
• seedBoxes(captions:slots:)'s two remaining callers (pick-a-template-before-generating
  and apply-a-completed-refit) legitimately have no description to read; both route through
  the same core layout and the single apply path.
• Still not run live. No real four-panel render was put on screen; the Mac app can't be
  screenshotted in this environment, so geometry is asserted numerically.

Gates

swift test 2634 green (2624 baseline + 10 new) · ratchet 7036/7036 ·
PLUGINS=1 ./build.sh, plain ./build.sh, and lean all compile · no new warnings in
touched files. Not merged.

---

v10 — refine-mode voice commands route to the plugin (first MAK-100 trigger layer)

Until now the plugin was something you opened. v10 makes it something you can ask
for mid-dictation: with refine armed, an instruction that starts with a phrase the
plugin declared is handed to the plugin instead of to the refine LLM.

The owner's two flows, both working:

	you do	material
CASE 1	select text anywhere → Fn (dictate) → Refine key → "create a meme based on that"	the selection (the refine content snapshot)
CASE 2	Refine with nothing selected → "create a meme expanding brain: typing, dictating, dictating memes, dictating memes by voice"	the spoken remainder

What CASE 2 required (it was genuinely broken)

Refine with no content never armed. armRefineMidSession bailed with "Nothing to
refine yet — dictate first, then tap Refine" whenever there was no in-session text, no
selection, and no last dictation. So refineContentSnapshot stayed nil,
deliverFinalText's refine branch never ran, and a spoken command could not reach a
router no matter how good the router was.

It now arms with an empty snapshot — but only when an enabled plugin actually
declares triggers (PluginHost.armsWithoutContent). With no such plugin the old status
string is byte-for-byte what it was. And when the instruction turns out not to be a
command, RefineFlow's existing empty-content rule produces exactly the same "Nothing
to refine" outcome as before. InstructionChain.instructionSuffix needed no change:
with empty content, hasPrefix("") is true, so the whole utterance becomes the
instruction.

Architecture — declared, not hardcoded

PluginManifest.voiceTriggers: [String] (forward-compat decode; normalized to trimmed,
lowercased, de-duped phrases). An all-empty list is reported as .emptyVoiceTriggers
but is never fatal — the same trade keyEquivalent already makes. That
normalization is load-bearing: an empty prefix would otherwise match every
instruction the user ever spoke.

PluginVoiceCommandRouter.match(instruction:enabledPlugins:) -> Match? is pure core.
The matching is deliberately strict, because a match redirects a dictation away from
the user's editor and a false positive costs them text:

• prefix only — "summarize this, then create a meme" stays a normal refine
• word boundary — "create a memo about Q3" does not match "create a mem"+"o"
• exact phrases, case/whitespace-insensitive; no fuzzy/edit-distance matching
• longest trigger wins, so a specific phrase can't be shadowed by a general one

The remainder is sliced from the original text (not the lowercased form) so the
user's capitalization reaches the rendered captions, and only leading separator
punctuation is trimmed — the interior commas in "typing, dictating, …" are the
list the extraction step later reads.

The meme manifest declares EN + RU — create a meme, make a meme, generate a meme,
сделай мем, создай мем — because the owner dictates in both. The checked-in
manifest.json matches the registry literal (the existing parity test pins this).

No insertion, and failure never eats the dictation

The route is consulted in deliverFinalText before runLLM and before any
insert. A claimed command returns RefineFlow.Effect.finishQuietly — the same
teardown a contentless refine already uses — so the session ends through one auditable
no-insert path rather than a second hand-rolled one. Verified against the real delivery
path: nothing reaches insertCompletedText, so nothing lands in the focused app.

A non-match, a disabled plugin, or a window that can't take the command all fall
through to the untouched normal refine. The disabled case additionally sets a one-line
hint, and only when the trigger matched exactly (matchIgnoringEnablement) — so it
can never fire on an unrelated refine.

Overlay: the acknowledgment names the plugin ("Meme Generator — creating…") and
reaches the overlay through statusMessage, which FinalizingCaption.resolve already
surfaces verbatim — no new OverlayPhase case and no view change. A core test pins
that the two agree.

AppState touch: ~10 lines (one if let, one guard, both delegating to PluginHost).
The ratchet budget drops 7036 → 7024: the consent-decision, dictation-stats-event,
rules-firing, and refinement-mode constructions moved into the pure core, so AppState
net shrank while gaining the feature.

Runtime proof

swift test proves the router but cannot prove the pipeline reaches it — the refine
path lives on AppState, which the core test target doesn't compile. So the launch-gated
probe now drives PluginHost.routeVoiceCommand, the same call
AppState.deliverFinalText makes when a mid-dictation refine finalizes, with the same
(instruction, content) pair. scripts/meme-voice-command-proof.sh [case1|case2|nearmiss|all].

Harness gotcha worth recording: the probe must run from a bundle. build.sh
emits a loose executable and AppKit never services the main run loop for one, so every
asyncAfter — the v9 probe's included — sits queued forever and the run looks like
a silent hang. The script hand-assembles a minimal ad-hoc-signed .app; no third_party
runtime matters to the trigger layer.

CASE 1 — selection is the material:

[MemeGen] refine-route probe requested: instruction="create a meme based on that" content="Our deploy pipeline takes 45 minutes and fails on the last step half the time."
[MemeGen] voice command MATCHED plugin=meme-generator trigger="create a meme" remainder="based on that" content=78 chars
[MemeGen] runVoiceCommand material="based on that
[MemeGen] voice command dispatched to meme-generator, material="based on that
[MemeGen] refine-route probe: ROUTED, refine effect=finishQuietly(status: "Meme Generator — creating…")
[MemeGen] LLM path, schema=true, captions=2, legacyShape=false
[MemeGen] seeding 3 boxes (canvas now 3)
[MemeGen] probe result: 3 boxes on canvas, texts=["Deploy pipeline takes 45 minutes", "Fails on the last step", "Half the time"]
[MemeGen] probe done

CASE 2 — the owner's exact expanding-brain prompt, all four items survive:

[MemeGen] refine-route probe requested: instruction="create a meme expanding brain: typing, dictating, dictating memes, dictating memes by voice" content=nil
[MemeGen] voice command MATCHED plugin=meme-generator trigger="create a meme" remainder="expanding brain: typing, dictating, dictating memes, dictating memes by voice" content=0 chars
[MemeGen] voice command dispatched to meme-generator, material="expanding brain: typing, dictating, dictating memes, dictating memes by voice"
[MemeGen] refine-route probe: ROUTED, refine effect=finishQuietly(status: "Meme Generator — creating…")
[MemeGen] extraction fired: 4 items, theme: "expanding brain"
[MemeGen] resolve(prompt: "expanding brain: typing, dictating, dictating memes, dictating memes by voice", specCaptions: 4, slots: 4) -> 4 boxes, captions: 4, fromUser: true, refit: none
[MemeGen] seeding 4 boxes (canvas now 4)
[MemeGen] probe result: 4 boxes on canvas, texts=["typing", "dictating", "dictating memes", "dictating memes by voice"]
[MemeGen] probe done

Near miss — "create a memo…" must stay a normal refine:

[MemeGen] refine-route probe requested: instruction="create a memo about the Q3 numbers" content="Revenue was up 12 percent."
[MemeGen] refine-route probe: NOT ROUTED -> normal refine (status="Ready")
[MemeGen] refine-route probe done (no meme window was opened)

Plugin disabled — matched, but falls back with the hint (run under a separate bundle
id so the real user defaults were never touched):

[MemeGen] voice command matched but plugin disabled -> normal refine
[MemeGen] refine-route probe: NOT ROUTED -> normal refine (status="Meme Generator plugin is disabled")
[MemeGen] refine-route probe done (no meme window was opened)

Still true / still shortcuts

• The router is prefix-exact, so a user who says "can you create a meme about X"
  gets a normal refine. Deliberate for now — leading-filler tolerance is the first thing
  worth adding, and it should be tested against the negatives above before it ships.
• Trigger collisions between plugins resolve by longest-then-list-order. Fine for one
  plugin; a real system probably wants the user to arbitrate.
• The disabled-plugin hint is best-effort UI copy, not a prompt to enable the plugin.
• CASE 1 joins remainder + selection with a newline and lets the plugin sort it out;
  there is no notion of "the selection is the subject, the remainder is the style."

Gates

swift test 2670 green (2645 baseline + 25 new) · ratchet OK, budget lowered
7036 → 7024 · PLUGINS=1 ./build.sh, plain ./build.sh, and lean all compile ·
no new warnings in touched files. Not merged.

New tests: PluginVoiceCommandRouterTests — trigger matching (bare prefix, selection
phrasing, the owner's colon-list prompt, casing/whitespace, original-casing remainder,
RU), negatives (create a memo, create a memes, mid-sentence mention, unrelated,
empty), enablement gating + matchIgnoringEnablement, longest/list-order precedence,
trigger normalization incl. the empty-prefix trap, forward-compat decode, the shipping
manifest, and the overlay acknowledgment/disabled-hint strings incl. their round-trip
through FinalizingCaption.

---

🤖 Generated with Claude Code

[initcore0]

v9 — the captions were never the bug

You ran a hash-verified v8 binary with the exact prompt and still got two boxes. That
was the right call to insist on: v7 and v8 each traced the caption wiring by reading it,
found it correct, and shipped. The caption wiring was correct. It was being handed
slots: 2.

The divergent line

MemeTemplate.captionSlots arrived in v6 without bumping MemeCatalogCache.currentVersion,
and decide admitted anything at or below the current version:

guard let cached, cached.version <= currentVersion, !cached.templates.isEmpty else {

So a catalog cached by a v5-era build stayed version: 1 and was accepted as current,
while MemeTemplate.init(from:) — deliberately tolerant so an old cache still loads —
defaulted the missing field:

captionSlots = MemeCaptionSlots.clamp(
    (try? c.decode(Int.self, forKey: .captionSlots)) ?? MemeCaptionSlots.default)  // 2

Your actual cache file, before this fix:

version: 1 | 285 templates | entries with captionSlots: 0
Expanding Brain | slots = None

Every template in the corpus reported two caption slots. Extraction read your four items
correctly, matched the right template, and then the count-mismatch rule did exactly what
it is supposed to do with four captions for a two-slot template: refit them down to
two. An LLM compressing a four-step progression keeps the endpoints — hence "typing" and
"dictating memes by voice", the first and last, which is the signature you reported.

No amount of reading the caption code could find this, because the caption code was
right. The bad input came from a file older than the feature.

Runtime proof

Reading had failed twice, so this round is evidence from the running binary.
MemeTrace logs each decision, and a launch-gated probe drives the real generate()
through PluginHost — same window the menu item opens, same method the button calls.

Before, PLUGINS=1 build against your own stale cache:

[MemeGen] probe start, prompt="expanding brain: typing, dictating, dictating memes, dictating memes by voice"
[MemeGen] LLM path, schema=true, captions=4, legacyShape=false
[MemeGen] extraction fired: 4 items, theme: "expanding brain"
[MemeGen] resolve(prompt: "expanding brain: ...", specCaptions: 4, slots: 2) -> 2 boxes, captions: 4, fromUser: true, refit: 4->2
[MemeGen] seeding 2 boxes (canvas now 2)
[MemeGen] probe result: 2 boxes on canvas, texts=["typing", "dictating memes by voice"]

Your bug, reproduced exactly. Note slots: 2 — that is the whole fault, and note that
extraction fired with 4 items, so v7/v8's work was doing its job all along.

After, same binary with the version gate, cache refetched:

[MemeGen] LLM path, schema=true, captions=4, legacyShape=false
[MemeGen] extraction fired: 4 items, theme: "expanding brain"
[MemeGen] resolve(prompt: "expanding brain: ...", specCaptions: 4, slots: 4) -> 4 boxes, captions: 4, fromUser: true, refit: none
[MemeGen] seeding 4 boxes (canvas now 4)
[MemeGen] probe result: 4 boxes on canvas, texts=["typing", "dictating", "dictating memes", "dictating memes by voice"]

Four boxes, your words verbatim and in order, no refit round-trip. The cache on disk is
now version: 2 | 285 templates | with slots: 285, and Expanding Brain | captionSlots = 4.

The fix is a version bump plus gating on equality rather than <=. There is nothing to
migrate — the slot counts were never written to that file — so refetching is the only
honest option, and it is one key-less GET behind the existing offline fallback.

The probe and the breadcrumbs are permanent but inert: both are env-gated
(OPENWHISP_MEME_TRACE=1, OPENWHISP_MEME_PROBE_PROMPT=...), so a normal launch is
unchanged.

Drag

The caption is burned into the preview image, so dragging moved an empty dashed outline
while the text sat at the old position until drop. The dragged box now renders empty
(MemeCaptionLayout.hidingText) while the handle draws a live copy that travels with the
cursor. The duplication is explicit and lasts only for the gesture — on drop the mask
lifts and the real renderer's output is what remains, so the SwiftUI approximation can
never reach the export. Re-rendering per frame was the alternative and is worse: it would
tie the drag's smoothness to the template's pixel count.

What would have caught it

The cache-policy tests all built their fixture with a literal version: 1, so when the
format really did change the suite was actively asserting the stale-cache behaviour was
correct. That helper now defaults to currentVersion, plus regressions for the
older-version gate, the tolerant decode, a slot-count round-trip, your prompt at 4 slots
and at 2, and the drag helper.

Gates

• swift test — 2645 pass, 0 failures (2634 baseline + 11 new)
• PLUGINS=1 ./build.sh, plain ./build.sh, lean — all clean
• No new warnings (25 pre-existing actor-isolation ones, none in touched files)
• AppState LOC 6894 / 7036 ratchet