Provider Fallback Hook

useProviderFallback

Resolve each capability (Summarizer, Translator, AI-edit, fill-mask) to Chrome Built-in AI or Transformers.js. Detection is independent per capability and reads the browser globals directly, so one capability can be Chrome-AI-served while another falls back in the same session. Every provider package is loaded via a dynamic import() inside the resolution path, so @localmode/react gains no hard dependency on @localmode/chrome-ai or @localmode/transformers — nothing about a provider ships until a capability first resolves. Resolution is lazy and session-cached, and each result carries truthful resolution provenance for a badge.

import { useProviderFallback, providerName } from '@localmode/react';

function SummarizeTab() {
  const { resolveSummarizer, resolution, isResolving } = useProviderFallback();

  async function run(text: string) {
    const { model } = await resolveSummarizer({
      chromeStyle: 'key-points',
      length: 'medium',
      fallbackModelId: 'Xenova/distilbart-cnn-6-6',
    });
    return summarize({ model, text });
  }

  return resolution ? <Badge provider={providerName(resolution.provider)} tier={resolution.tier} /> : null;
}

Options

useProviderFallback({
  loadChromeAI: () => import('@localmode/chrome-ai'),
  loadTransformers: () => import('@localmode/transformers'),
});

Return Value

Chrome availability & the download gate

Chrome's built-in AI APIs can exist while their on-device model has not been fetched. In that state availability() reports 'downloadable', and Chrome refuses to start the download outside a user activation — so a button is the only way to trigger it.

const {
  chromeAvailability,
  refreshChromeAvailability,
  requestChromeDownload,
  chromeDownloadProgress,
  downloadingCapability,
} = useProviderFallback({ loadChromeAI, loadTransformers });

// Probing downloads nothing.
useEffect(() => {
  void refreshChromeAvailability('summarize', { chromeStyle: 'tldr', length: 'medium' });
}, [refreshChromeAvailability]);

// Must run from a click.
<button onClick={() => void requestChromeDownload('summarize', { chromeStyle: 'tldr', length: 'medium' })}>
  Download model
</button>;

ChromeAIAvailability is 'available' | 'downloadable' | 'downloading' | 'unavailable' | 'unsupported' (the last is ours, meaning the API is absent). ChromeCapability is 'summarize' | 'translate' | 'edit' — fill-mask has no Chrome equivalent. Translator availability is per language pair, so pass { source, target } and re-probe whenever the pair changes.

The ui/local-first/chrome-ai-download-gate registry primitive renders this state machine — button, progress, and the terminal unsupported / cannot-run states — from exactly these fields.

Resolver Params

Each resolver takes exactly the params its capability needs, so the split Write / Translate / Summarize / Complete surfaces each import only one. resolveFillMask takes a plain modelId: string (no Chrome equivalent).

ResolveSummarizerParams

ResolveTranslatorParams

ResolveEditEngineParams

ResolvedModel and provenance

Every resolver returns a ResolvedModel<M> — the concrete model instance plus the provenance a badge derives from — and updates the hook's resolution, so a badge reflects what actually serves requests, never the detection probe alone.

Standalone detectors and badge helpers

The detection functions are exported standalone (all async, all returning a ProviderId of 'chrome-ai' | 'transformers'). They read the same browser surfaces the @localmode/chrome-ai detectors read, so no provider import is needed to detect.

import { detectPromptProvider, providerName, providerTier } from '@localmode/react';

const provider = await detectPromptProvider(); // 'chrome-ai' only when Gemini Nano is actually 'available'
const label = providerName(provider); // 'Chrome AI' | 'Transformers.js'
const tier = providerTier(provider); // 'built-in' | 'download'

Blocks