How explanations work

Guide generates plain-language explanations for UI elements on the fly. When a user hovers over something in Guide mode, the SDK captures the element's identity, sends it to the explanation engine, and renders the response in a card near the cursor. Most of this happens in under 200ms because of aggressive caching.

What the engine sees

Guide doesn't screenshot your page or read its full DOM. It sends a narrow context packet per element:

• Selector and label. The CSS selector Flusterduck already computes for signal tracking, plus the element's accessible name (from aria-label, aria-labelledby, visible text, or title).
• Role and state. The ARIA role (explicit or implicit from the tag), plus whether it's disabled, expanded, checked, or required.
• Parent context. The role and label of the nearest named ancestor. A "Submit" button inside a <form aria-label="Payment details"> is more meaningful than a "Submit" button inside a generic <div>.
• Friction data. If Flusterduck has signals on this element (rage clicks, dead clicks, disabled taps), the engine knows what specifically confused other users. This is the piece that makes Guide precise instead of generic.

No form values. No user-typed text. No page content beyond what's needed to identify the control and its purpose.

Friction-aware explanations

A generic screen reader could tell you a button says "Deploy." Guide tells you what Flusterduck's data tells it:

"Pushes your current changes to production. 43 users clicked this expecting a preview, but it deploys immediately. There's no confirmation dialog. If you want to preview first, use the 'Staging' button to the left."

That second sentence comes from the dead-click and rage-click signals Flusterduck has already clustered on this element. The explanation engine weaves behavioral evidence into the response so users get the warning before they make the same mistake.

Elements with no friction data still get explanations. They're just simpler: what the element does and what to expect when you interact with it.

The cache

Most hovers don't trigger an AI call. Three cache layers sit between the hover event and the model.

Layer 1: In-memory (client-side)

A map in the SDK's JavaScript. Instant. Holds the last 500 explanations the user has seen in this session. If the user hovers the same button twice, the second hover is free. Cleared on full page navigation, preserved across SPA route changes.

Layer 2: Local storage (client-side, persistent)

Explanations persist in the browser's IndexedDB across sessions. When a returning user hovers over an element they saw last week, the explanation loads from local storage with no network request. Entries expire after 7 days or when a deploy invalidates them.

Layer 3: Edge cache (server-side, shared)

Explanations are cached at the edge, keyed by site + page + element fingerprint. When user A hovers over the "Submit" button and gets an explanation, user B hovering the same button on the same page hits the edge cache. No new AI call.

After a handful of users explore a page, every element on it is cached. Expected edge hit rate after warm-up: 90-95%. The AI model only fires for new elements it hasn't seen before or freshly deployed pages.

Invalidation

Caches invalidate on two triggers:

• Deploy. If you use Flusterduck's deploy correlation, explanations for the affected site are cleared automatically. The first user after a deploy re-primes the cache.
• TTL. Explanations expire after 7 days regardless of deploys. This catches sites that don't use deploy correlation.

The data-fd-guide attribute bypasses all caching. Its content is always used verbatim.

Prefetching

On page load, the SDK scans the visible viewport for interactive elements, batches their fingerprints, and requests cached explanations in a single call. This pre-warms the in-memory cache so the first hover on any visible element is instant. Users do not have to wait for a second hover.

Prefetching only requests elements that already have cached explanations on the edge. It doesn't trigger AI generation. The cost is one lightweight network request per page load.

Guide allowance

Guide uses a fast model for generation. Each explanation is roughly 300 input tokens (element context + friction data) and 100-150 output tokens (the explanation itself).

The three-day trial includes a fixed Guide allowance for the lifetime of the trial. It does not reset when the calendar month changes. Paid plans include a monthly Guide allowance that scales with the plan tier.

When the allowance is used, cached explanations still work, but new AI generations pause. During a trial, Billing offers Start my plan now. On a paid plan, generation resumes at the start of the next month or after a plan upgrade. There is no add-on capacity to buy.

What uses the allowance

Only live AI generations use the allowance. Cache hits at any layer (in-memory, local storage, edge) do not. data-fd-guide attribute explanations and prefetch requests also do not use it.

In practice, the cache handles 90%+ of hovers after the first few sessions on each page. The allowance covers cold starts and the long tail of rarely visited elements.

Monitoring usage

The dashboard shows Guide usage alongside your other Flusterduck metrics:

• Total hovers this trial or month
• Cache hit rate (broken down by layer)
• AI generations used vs. allowance remaining
• Top elements by hover count (which elements users ask about most)
• Friction reduction on Guide-explained elements vs. unexplained ones

The last metric is the one that matters. It closes the loop: Flusterduck detected friction, Guide explained it, and the verification engine confirms whether confusion dropped.