From Chrome to Puma: Migrating Extensions and Web Apps to Local-AI Browsers

Stop losing users when browsers go local-AI — a practical migration guide

If you maintain a Chrome extension or a Progressive Web App (PWA), you already feel the pressure: new mobile-first local-AI browsers like Puma are shipping on phones and tablets in 2025–2026 with on-device LLMs, different permission models, and new developer APIs. Users expect privacy-first, offline-capable summaries, assistants, and search enhancements — and they will switch browsers if your tooling breaks. This guide shows exactly how to adapt existing extensions and PWAs for local-AI browsers, with a compatibility checklist, concrete code samples, and a demo migration from a Chrome extension that relied on a cloud LLM to a Puma-friendly, on-device summarizer.

Executive summary — what to do first (most important)

1. Feature-detect local-AI capabilities at runtime and provide a graceful fallback to server-based LLMs.
2. Audit permissions and manifests — local-AI browsers use stricter permission scopes and sometimes new manifest keys.
3. Move heavy compute off the main thread with workers + WebGPU/WebNN to avoid UI jank and battery spikes.
4. Update your data flow so user data stays local by default, and telemetry is opt-in.
5. Test on real devices (Android/iPhone builds of Puma and similar browsers) — emulators don't capture NPUs or thermal throttling.

The 2026 context: Why local-AI browsers matter now

Late 2025 and early 2026 saw mainstream mobile browsers shipping first-class support for on-device models. Several trends converged:

• Accelerators and SDKs matured: WebGPU + WebNN + WebAssembly SIMD provide reliable on-device inference paths.
• Mobile NPUs and Android Neural Networks API improvements made mid-sized LLMs (2–8B params) practical on phones.
• Privacy and regulatory pressure (including evolving EU AI rules and platform transparency standards) pushed vendors to promote local inference.
• Browsers like Puma target privacy-first users by bundling model selection, on-device caching, and explicit model permissions.

For web devs, this means extensions and PWAs must be ready to use local resources, cope with device variability, and survive tighter permission models while delivering fast, reliable AI features.

Compatibility checklist: Quick facts before you dive in

Run this checklist on each project to gauge migration effort.

• API availability: Does the target browser expose a Local AI API (e.g., navigator.localAI or a vendor namespace)?
• Manifest keys: Are there new manifest fields or vendor-specific extension flags? (Optional permissions like localAI or on-device-model.)
• Service worker support: Can background/service workers access local models, or are models callable only from window contexts?
• Compute limits: What are memory, CPU, and battery throttles for local inference on that browser?
• Storage and persistence: Where can models and caches be stored? (IndexedDB, File System Access API, or vendor caches.)
• Security & privacy: Consent flows required for local model use and telemetry opt-in rules.
• PWA install behavior: Does PWA installation grant extra storage or background execution privileges for local AI tasks?

Deep dive: Typical incompatibilities and how to fix them

1. Manifest and permissions

Problem: Your Chrome extension requests broad host permissions for remote LLM calls. Puma and similar browsers prefer fine-grained, named permissions for local models.

Action:

• Refactor the manifest to ask for explicit features like localAI, on-device-model, and the minimum host permissions (use optional_permissions where supported).
• Provide a transparent permissions UI during onboarding that explains model size and resource usage.

{
  'manifest_version': 3,
  'name': 'Page Summarizer',
  'version': '1.0.0',
  'permissions': ['storage', 'scripting', 'activeTab'],
  'optional_permissions': ['localAI', 'on-device-model'],
  'background': { 'service_worker': 'background.js' },
  'content_scripts': [{ 'matches': [''], 'js': ['content.js'] }]
}
  

2. Background workers and model access

Problem: Service workers in MV3-style extensions may not be allowed to hold long-running native inference tasks. Local-AI browsers sometimes restrict model access to window contexts for resource accounting.

Action:

• Move heavy inference to a dedicated WebWorker or an OffscreenCanvas-driven worker which the service worker spawns and the window can keep alive when necessary.
• Design a message-passing boundary and fall back to server inference if the worker cannot run due to policy.

3. Model APIs and feature detection

Problem: There is no single universal API yet. Vendors differ: some expose navigator.localAI, others expose a vendor namespace like window.puma.

Action: Implement robust feature detection and a tiny adapter layer.

// local-ai-adapter.js
export async function getLocalAI() {
  if (typeof navigator !== 'undefined' && 'localAI' in navigator) return navigator.localAI
  if (typeof window !== 'undefined' && window.puma && window.puma.ai) return window.puma.ai
  return null
}
  

4. Memory & model-size negotiation

Problem: You cannot assume a large model is available on-device. Asking for a 13B model on low-end phones will fail.

Action:

• Query the runtime for supported models and device capabilities, then choose an appropriate model (e.g., 1B, 3B, 7B).
• Offer an option to download a larger model and persist it in IndexedDB or the File System Access API with clear consent and a progress UI.

5. Offline & PWA service-worker patterns

Problem: Your PWA's service worker was written for network fetch falls back but not for local inference.

Action:

• Allow the PWA to call local models from both the window and service worker if supported. If not, queue requests in IndexedDB and resolve them when the app returns to foreground.
• Use a hybrid cache: store summaries locally and keep a server sync job optional.

Demo migration: Convert a Chrome extension 'Page Summarizer' to support Puma local-AI

This walkthrough condenses a full migration. The original extension: content script extracts page text, sends it to background.js, which called a cloud LLM API and returned a summary. We'll adapt it to prefer local models when available.

Step 0 — project structure

page-summarizer/
├─ manifest.json
├─ content.js
├─ background.js
├─ local-ai-adapter.js
├─ worker/inference-worker.js
└─ popup.html (optional)
  

Step 1 — add feature detection and model negotiation

// local-ai-adapter.js (simplified)
export async function getLocalAIInterface() {
  if (typeof navigator !== 'undefined' && 'localAI' in navigator) return navigator.localAI
  if (typeof window !== 'undefined' && window.puma && window.puma.ai) return window.puma.ai
  return null
}

export async function selectModel(ai) {
  // Query vendor for available models
  try {
    const info = await ai.listModels()
    // Prefer small-but-capable models for phones
    const preferred = info.models.find(m => m.size <= 7 && m.latency < 2.0) || info.models[0]
    return preferred
  } catch (err) {
    return null
  }
}
  

Step 2 — refactor background.js to use worker + adapter

// background.js (MV3 service worker)
importScripts('local-ai-adapter.js')

self.addEventListener('message', async event => {
  const { type, text } = event.data
  if (type === 'summarize') {
    const ai = await getLocalAIInterface()
    if (ai) {
      // Forward to an inference worker to avoid long-running work in SW
      const result = await runLocalInference(ai, text)
      event.source.postMessage({ type: 'summary', summary: result })
    } else {
      // Fallback to cloud LLM
      const summary = await fetchCloudSummary(text)
      event.source.postMessage({ type: 'summary', summary })
    }
  }
})

async function runLocalInference(ai, text) {
  const model = await selectModel(ai)
  if (!model) throw new Error('No local model available')
  // Use the ai.generate API (vendor-specific) with streaming or batching
  const resp = await ai.generate({ model: model.name, prompt: 'Summarize:\n' + text, max_tokens: 200 })
  return resp.text
}

async function fetchCloudSummary(text) {
  const r = await fetch('https://api.example.com/llm/summarize', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ text })
  })
  const j = await r.json()
  return j.summary
}
  

Step 3 — content script messaging and UX

Keep the content script minimal: extract selected text and call the background. Show a small in-page UI that indicates whether a local or cloud model was used.

// content.js
function extractText() {
  return window.getSelection().toString() || document.body.innerText.slice(0, 10000)
}

async function requestSummary() {
  const text = extractText()
  const port = chrome.runtime.connect()
  port.postMessage({ type: 'summarize', text })
  port.onMessage.addListener(msg => {
    if (msg.type === 'summary') showSummaryOverlay(msg.summary)
  })
}

function showSummaryOverlay(summary) {
  // simple UI code: omitted for brevity
}
  

Step 4 — gracefully handle capability differences

Always let users know the chosen inference path:

UX tip: Display a badge or small text: "On-device summary (Mistral‑3B)" or "Cloud summary (privacy‑opted‑in)".

Step 5 — optimize for resource constraints

• Use shorter prompts and token limits for on-device models.
• Batch multiple small requests into one call when possible.
• Use streaming where the API supports it to show a progressive result.

PWA-specific migration notes

If you maintain a PWA instead of an extension, these are the main differences:

• Installation grants: Some local-AI browsers allocate extra persistent storage for installed PWAs; use that for model caches.
• Service worker restrictions: Some browsers disallow long-running compute inside service workers. Use window-scoped workers or background sync techniques with IndexedDB queues.
• Progressive enhancement: Build a single code path that works offline with local models and gracefully falls back when network-only features are required.

Testing and validation checklist

1. Run on low, mid, and high-end devices to see throttling behavior.
2. Validate permission prompts and confirm the user can revoke local model access.
3. Measure latency and battery impact; add a telemetry opt-in and clear privacy policy.
4. Test cold-start (first-run model download) and resume behaviors.
5. Confirm graceful fallback paths to cloud LLMs with unit tests and e2e tests.

Advanced strategies and future-proofing (2026+)

Plan beyond an initial migration:

Model-agnostic orchestration

Build an adapter layer that maps your app's prompt templates to multiple model families and sizes. Maintain a capability matrix so you can choose compute-efficient options on the fly.

Leverage WebGPU and WebNN

Where vendor local-AI APIs are unavailable, consider running optimized models via WebGPU or WebNN using WebAssembly runtimes (ONNX.js, TensorFlow.js, or custom runtimes). This is heavier to implement but increases compatibility.

Edge-cache and sync

Support a hybrid model: keep a compact local model for instant responses, and optionally route to larger remote models for higher accuracy with user consent. Cache improved results locally to reduce repeated network calls.

Privacy-first defaults

By 2026 users and regulators expect privacy by default. Make local inference the default path and require explicit consent before sending user data off-device. Provide clear, machine-readable policy info (e.g., manifest fields) to help browser store managers and enterprise admins.

Common pitfalls and how to avoid them

• Assuming model parity: A local 7B model won't match a remote 70B model. Be explicit in UX about expected quality differences.
• Ignoring battery usage: Schedule heavy operations for charging or while plugged in; provide a "low power" mode.
• Not testing revocation: Users must be able to revoke local-model access; confirm your extension recovers cleanly.

Resources & starter checklist (copyable)

Use this minimal checklist when preparing a release:

1. Run node migrate-manifest.js to insert optional localAI keys.
2. Implement local-ai-adapter.js with feature detection.
3. Refactor background work into a worker; add streaming handler.
4. Add UI to show inference path and model size.
5. Test on at least two devices with a Puma build and one other local-AI browser.

Final takeaways — what I want you to remember

• Detect then adapt: Never assume a single Local-AI API — feature-detect and provide fallbacks.
• Keep data local-first: Default to on-device inference for privacy and speed; fall back to cloud with consent.
• Design for heterogeneity: Offer model-choice, progressive enhancement, and resource-aware behavior.
• Test on real hardware: Emulators won't expose thermal throttling or NPU availability.

By adapting now you'll keep your users, reduce latency and bandwidth costs, and position your product as privacy-forward in the new era of local-AI browsers.

Call to action

Ready to migrate? Start with the demo repository and checklist in this article: implement the local-ai-adapter, run the summarizer on a Puma build, and share results with the community. If you maintain extensions or PWAs, open an issue on your repo describing how you plan to support local AI and tag it #local-ai-migration. Need help auditing your app? Join our developer office hours or request a migration checklist review — ship faster and keep your users as browsers go local-AI.

Related Reading

• Ethical Social Media for Teachers: Handling Allegations, Reputation, and Student Privacy
• Asda Express Expansion and the Future of Convenience for Drivers: Micro-Services, EV Charging and On-the-Go Needs
• Checklist: Tech to Pack for Move‑In Day (and What You Can Skip)
• DIY Micro-Apps for Self-Care: Build Fast Tools to Simplify Your Day
• From Stove to Global Bars: How DIY Cocktail Culture Can Elevate Villa Welcome Kits