DEV Community: Vitor Ferreira

Building an On-Device Q&A Agent with Chrome Built-in AI and the Prompt API

Vitor Ferreira — Thu, 13 Aug 2026 20:56:55 +0000

Running large language models typically involves cloud API endpoints, paying per token, managing rate limits, and transmitting sensitive user queries across the network.

With Chrome's Built-in AI initiatives (via the WICG Prompt API and Gemini Nano), browsers can now execute small language models (SLMs) directly on the user's hardware. Inference happens entirely on-device: zero API keys to expose in frontend bundles, zero cloud infrastructure bills, zero network latency after weight loading, and complete client-side data privacy.

This article walks through the technical mechanics of integrating Chrome's Prompt API into a modern JavaScript/TypeScript application, including capability detection, session lifecycle, streaming token consumption, in-context grounding, and deterministic parameter tuning.

1. The Prompt API Architecture

Chrome exposes on-device capabilities through the window.ai namespace (and globally as LanguageModel). Under the hood, Chromium interfaces with an optimized on-device foundation model (Gemini Nano) managed by the browser's Optimization Guide component.

The API contract consists of three primary phases:

Availability Assessment: Probing whether hardware and browser flags support on-device execution.
Session Creation & Model Download: Initializing a session with optional system instructions and monitoring download progress if weights are not yet cached.
Execution & Token Streaming: Dispatching prompts via single-shot promises or asynchronous streams, followed by explicit resource teardown.

2. Feature Detection and Availability Checking

Before invoking any inference methods, you must verify that the browser supports the API and determine whether model weights are already loaded or require downloading.

export type AIAvailabilityStatus =
  | 'readily'
  | 'available'
  | 'after-download'
  | 'downloadable'
  | 'downloading'
  | 'unavailable'
  | 'no'
  | 'unsupported';

export function getLanguageModelAPI() {
  if (typeof window === 'undefined') return null;

  const anyWin = window as unknown as {
    ai?: { languageModel?: any; assistant?: any };
    LanguageModel?: any;
  };

  return (
    anyWin.ai?.languageModel ||
    anyWin.ai?.assistant ||
    anyWin.LanguageModel ||
    null
  );
}

export async function checkAIAvailability(): Promise<AIAvailabilityStatus> {
  const api = getLanguageModelAPI();
  if (!api) return 'unsupported';

  if (typeof api.availability === 'function') {
    const status = await api.availability();
    return status || 'unsupported';
  }

  if (typeof api.capabilities === 'function') {
    const caps = await api.capabilities();
    return caps?.available || 'unsupported';
  }

  return 'unsupported';
}

The status values dictate UI state:

readily / available: Model weights exist in memory/disk cache; execution starts immediately.
after-download / downloadable: Model execution is supported, but Chrome must fetch the weights (~1.5GB - 2.5GB). You should track and render download progress.
no / unsupported: The host machine does not satisfy minimum hardware requirements (GPU/VRAM) or the browser flags are disabled.

3. Session Initialization and Weight Download Monitoring

When calling create(), you can pass configuration options:

systemPrompt: High-level persona and constraints.
temperature: Sampling temperature (0.0 to 1.0). Lower values yield deterministic, factual output.
topK: Number of highest-probability tokens considered.
monitor: An event listener callback tracking download bytes.
signal: An AbortSignal to cancel session instantiation.

const api = getLanguageModelAPI();

const session = await api.create({
  systemPrompt: 'You are a technical assistant specializing in software engineering telemetry.',
  temperature: 0.1,
  topK: 1,
  signal: abortController.signal,
  monitor: (monitorTarget: EventTarget) => {
    monitorTarget.addEventListener('downloadprogress', (event: Event) => {
      const prog = event as ProgressEvent;
      if (prog.total > 0) {
        const percentage = Math.round((prog.loaded / prog.total) * 100);
        console.log(`Downloading model weights: ${percentage}%`);
      }
    });
  },
});

4. Grounding Small On-Device Models (In-Context Prompting)

Gemini Nano is a lightweight model (~3 billion parameters). Unlike cloud models with massive parameter counts (such as Gemini 1.5 Pro or GPT-4), on-device SLMs have narrower context windows and tend to suffer from attention attenuation if domain context is provided strictly as a detached system prompt.

If you pass domain knowledge solely in systemPrompt during create(), the model may drift or produce generic answers when the conversation advances.

To achieve strict factual fidelity (e.g., answering questions exclusively from a structured career timeline or technical dataset), format the verified knowledge directly into the prompt envelope at query time:

export function buildGroundedPrompt(
  facts: string,
  userQuery: string,
  history: { role: string; content: string }[] = []
): string {
  let conversationBlock = '';
  if (history.length > 0) {
    const recent = history.slice(-3);
    conversationBlock = `RECENT CONVERSATION:\n${recent
      .map((m) => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}`)
      .join('\n')}\n\n`;
  }

  return `You are a verified technical assistant. Answer the user question accurately, concisely, and factually using ONLY the verified facts below. If the answer is not contained in the facts, explicitly state that the information is unavailable.

VERIFIED FACTS:
${facts}

${conversationBlock}USER QUESTION: ${userQuery}

CONCISE FACTUAL ANSWER:`;
}

Deterministic Parameter Tuning

For retrieval and Q&A tasks where hallucinations must be avoided:

Set temperature: 0.1 or 0.0.
Set topK: 1.

This forces the model to select the highest-confidence token at each step, preventing speculative drift.

5. Streaming Token Consumption and Lifecycle Management

To avoid blocking UI rendering while generating output, consume the streaming interface (promptStreaming). Depending on the exact Chromium version and specification draft, promptStreaming returns an AsyncIterable<string> or a ReadableStream<string>.

Here is a normalization handler that supports both paradigms and cleans up the session after execution:

export async function executePromptStreaming({
  session,
  prompt,
  onChunk,
  signal,
}: {
  session: any;
  prompt: string;
  onChunk: (accumulated: string, delta: string) => void;
  signal?: AbortSignal;
}): Promise<string> {
  if (typeof session.promptStreaming === 'function') {
    const streamResult = session.promptStreaming(prompt, { signal });
    let accumulated = '';

    // Case 1: AsyncIterable
    if (
      streamResult &&
      typeof streamResult[Symbol.asyncIterator] === 'function'
    ) {
      for await (const chunk of streamResult) {
        if (signal?.aborted) break;
        accumulated += chunk;
        onChunk(accumulated, chunk);
      }
      return accumulated;
    }

    // Case 2: ReadableStream
    if (
      streamResult &&
      typeof streamResult.getReader === 'function'
    ) {
      const reader = streamResult.getReader();
      try {
        while (true) {
          if (signal?.aborted) break;
          const { done, value } = await reader.read();
          if (done) break;
          if (value) {
            accumulated += value;
            onChunk(accumulated, value);
          }
        }
      } finally {
        reader.releaseLock();
      }
      return accumulated;
    }
  }

  // Fallback: Non-streaming execution
  const singleShotResult = await session.prompt(prompt, { signal });
  onChunk(singleShotResult, singleShotResult);
  return singleShotResult;
}

Critical: Resource Disposal

Each active session retains model state and memory allocations in the browser process. Always invoke session.destroy() inside a finally block or when unmounting React components to prevent memory leaks:

try {
  const result = await executePromptStreaming({ session, prompt, onChunk, signal });
  return result;
} finally {
  try {
    session.destroy();
  } catch (err) {
    // Suppress teardown errors
  }
}

6. React Integration Pattern

In a React or Next.js SPA, wrap the session logic in custom hooks or state handlers. Below is an example pattern maintaining conversation state and abort signals:

import React, { useState, useRef, useEffect } from 'react';
import {
  checkAIAvailability,
  getLanguageModelAPI,
  buildGroundedPrompt,
  executePromptStreaming,
} from './aiAssistant';

export const OnDeviceChat: React.FC<{ datasetContext: string }> = ({ datasetContext }) => {
  const [messages, setMessages] = useState<{ role: string; content: string }[]>([]);
  const [input, setInput] = useState('');
  const [isGenerating, setIsGenerating] = useState(false);
  const [downloadProgress, setDownloadProgress] = useState<number | null>(null);
  const abortControllerRef = useRef<AbortController | null>(null);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!input.trim() || isGenerating) return;

    const userText = input.trim();
    setInput('');
    setIsGenerating(true);

    const abortController = new AbortController();
    abortControllerRef.current = abortController;

    const newMessages = [
      ...messages,
      { role: 'user', content: userText },
      { role: 'assistant', content: '' },
    ];
    setMessages(newMessages);

    try {
      const api = getLanguageModelAPI();
      if (!api) throw new Error('Prompt API not supported on this browser.');

      const session = await api.create({
        systemPrompt: 'You are a factual Q&A assistant.',
        temperature: 0.1,
        topK: 1,
        signal: abortController.signal,
        monitor: (m: EventTarget) => {
          m.addEventListener('downloadprogress', (e: any) => {
            if (e.total) setDownloadProgress(Math.round((e.loaded / e.total) * 100));
          });
        },
      });

      try {
        const fullPrompt = buildGroundedPrompt(datasetContext, userText, messages);

        await executePromptStreaming({
          session,
          prompt: fullPrompt,
          signal: abortController.signal,
          onChunk: (accumulated) => {
            setMessages((prev) => {
              const updated = [...prev];
              updated[updated.length - 1] = { role: 'assistant', content: accumulated };
              return updated;
            });
          },
        });
      } finally {
        session.destroy();
      }
    } catch (err: any) {
      if (!abortController.signal.aborted) {
        console.error('Inference error:', err);
      }
    } finally {
      setIsGenerating(false);
      setDownloadProgress(null);
    }
  };

  const handleAbort = () => {
    abortControllerRef.current?.abort();
    setIsGenerating(false);
  };

  return (
    <div>
      {downloadProgress !== null && (
        <div>Downloading on-device weights: {downloadProgress}%</div>
      )}

      <div>
        {messages.map((m, idx) => (
          <div key={idx} className={m.role}>
            <strong>{m.role}:</strong> {m.content}
          </div>
        ))}
      </div>

      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Ask a question..."
          disabled={isGenerating}
        />
        {isGenerating ? (
          <button type="button" onClick={handleAbort}>Stop</button>
        ) : (
          <button type="submit">Submit</button>
        )}
      </form>
    </div>
  );
};

7. How to Enable the Prompt API in Chrome

Because the WICG Prompt API is rolling out across Chromium channels, testing locally requires enabling experimental flags:

Open Google Chrome (version 128+ or Chrome Canary).
Go to chrome://flags/#prompt-api-for-gemini-nano and set to Enabled.
Go to chrome://flags/#optimization-guide-on-device-model and set to Enabled BypassPerfRequirement.
Relaunch Chrome.
Visit chrome://components and find Optimization Guide On Device Model. Click Check for update to ensure weights are fully fetched.

Summary

Chrome's Built-in AI and Prompt API represent a fundamental shift in client-side web capabilities. By moving baseline reasoning, extraction, and Q&A workloads directly onto client hardware:

Network egress costs and backend server bills drop to zero.
User data never leaves the client boundary.
Web apps can provide offline and zero-latency interactive features.

By pairing small on-device models with strict in-context grounding and low-temperature sampling, you can build production-ready, highly reliable Q&A agents directly in the browser.

Supercharge Your Blog with Chrome's Built-in AI Summarizer API

Vitor Ferreira — Wed, 12 Aug 2026 16:29:59 +0000

I recently wanted to add a summarization feature to my personal engineering blog so readers could get quick key takeaways or a TL;DR before diving into a long post.

The traditional approach would be setting up an API route, managing an OpenAI or Anthropic API key, handling rate limits, and paying per token. But Chrome (starting with version 138) now exposes built-in, on-device AI capabilities powered by Gemini Nano.

One of those capabilities is the Summarizer API. Because inference runs locally in the browser:

There are no API keys or backend servers to maintain.
User data never leaves their machine.
It costs nothing to run.
It works offline once the model weights are downloaded.

Here is how I implemented it in React and TypeScript, along with how to handle streaming, model download states, and graceful degradation for browsers that do not support the API yet.

1. Getting TypeScript Support

Chrome's Built-in AI APIs follow the emerging W3C Web Incubator Community Group (WICG) specifications. To avoid typing (window as any) everywhere, install the official community definitions:

npm install -D @types/dom-chromium-ai

Then add dom-chromium-ai to your tsconfig.app.json (or tsconfig.json):

{
  "compilerOptions": {
    "types": ["vite/client", "dom-chromium-ai"]
  }
}

This pulls in the global declarations for Summarizer, CreateMonitor, Availability, and related types.

2. Feature Detection and Graceful Degradation

Since this is currently a Chromium-specific capability behind flags or in newer versions, your code needs to detect whether the API is available and degrade gracefully. If a reader visits your site on Firefox, Safari, or an unsupported Chrome build, the feature should simply not appear rather than throwing runtime errors.

The API exposes an availability() check. Depending on the runtime state, it returns:

'available' / 'readily': The model is on disk and ready to summarize immediately.
'downloadable' / 'after-download': The browser supports the API, but the Gemini Nano model needs to download first.
'downloading': The model is actively downloading.
'unavailable' / 'no': The device or browser does not meet requirements.

Here is a helper module to handle detection and compatibility:

// src/lib/summarizer.ts
/// <reference types="dom-chromium-ai" />

export type SummarizerStyleType = 'key-points' | 'tldr' | 'teaser' | 'headline';
export type SummarizerLengthType = 'short' | 'medium' | 'long';

export type AvailabilityStatus =
  | 'readily'
  | 'after-download'
  | 'available'
  | 'downloadable'
  | 'downloading'
  | 'unavailable'
  | 'no'
  | 'unsupported';

export function getSummarizerFactory() {
  if (typeof window === 'undefined') return null;

  const win = window as any;
  const workerSelf = typeof self !== 'undefined' ? (self as any) : null;

  return (
    win.ai?.summarizer ||
    workerSelf?.ai?.summarizer ||
    win.Summarizer ||
    workerSelf?.Summarizer ||
    null
  );
}

export async function checkSummarizerSupport(
  options?: SummarizerCreateOptions
): Promise<AvailabilityStatus> {
  try {
    const factory = getSummarizerFactory();
    if (!factory) return 'unsupported';

    if (typeof factory.availability === 'function') {
      return (await factory.availability(options)) as AvailabilityStatus;
    }

    if (typeof factory.capabilities === 'function') {
      const caps = await factory.capabilities();
      return (caps?.available as AvailabilityStatus) || 'unsupported';
    }

    return 'unsupported';
  } catch {
    return 'unsupported';
  }
}

export function isUsableStatus(status: AvailabilityStatus): boolean {
  return ['readily', 'available', 'after-download', 'downloadable', 'downloading'].includes(status);
}

3. Session Creation, Download Monitoring, and Streaming

When creating a summarizer instance via create(), you can configure:

type: 'key-points', 'tldr', 'teaser', or 'headline'
format: 'markdown' or 'plain-text'
length: 'short', 'medium', or 'long'
monitor: A callback receiving a CreateMonitor object to track download progress if the browser needs to fetch model weights first.

The summarizeStreaming() method returns a readable stream. Iterating over the stream yields incremental text deltas, allowing you to update state as words appear.

// src/lib/summarizer.ts
export interface GenerateSummaryParams {
  content: string;
  type: SummarizerStyleType;
  length: SummarizerLengthType;
  sharedContext?: string;
  onChunk?: (accumulatedText: string, delta: string) => void;
  onDownloadProgress?: (percentage: number) => void;
  signal?: AbortSignal;
}

export async function runSummarization({
  content,
  type,
  length,
  sharedContext,
  onChunk,
  onDownloadProgress,
  signal,
}: GenerateSummaryParams): Promise<string> {
  const factory = getSummarizerFactory();
  if (!factory) {
    throw new Error('Summarizer API is not available.');
  }

  const createOptions: SummarizerCreateOptions = {
    type,
    format: 'markdown',
    length,
    outputLanguage: 'en',
    sharedContext: sharedContext || 'Technical software article',
    signal,
    monitor: (monitor: CreateMonitor) => {
      monitor.addEventListener('downloadprogress', (e: ProgressEvent) => {
        if (e.total && e.total > 0) {
          const percent = Math.min(100, Math.round((e.loaded / e.total) * 100));
          onDownloadProgress?.(percent);
        } else if (e.loaded > 0) {
          onDownloadProgress?.(Math.min(99, Math.round(e.loaded * 100)));
        }
      });
    },
  };

  const instance = await factory.create(createOptions);

  try {
    if (signal?.aborted) {
      throw new Error('Aborted by user.');
    }

    if (typeof instance.summarizeStreaming === 'function') {
      const stream = instance.summarizeStreaming(content, { signal });
      let accumulated = '';

      // Handle async iterable stream
      if (stream && typeof (stream as any)[Symbol.asyncIterator] === 'function') {
        for await (const delta of stream as AsyncIterable<string>) {
          if (signal?.aborted) break;
          accumulated += delta;
          onChunk?.(accumulated, delta);
        }
        return accumulated;
      }

      // Handle ReadableStream with Reader
      if (stream && typeof (stream as ReadableStream<string>).getReader === 'function') {
        const reader = (stream as ReadableStream<string>).getReader();
        try {
          while (true) {
            if (signal?.aborted) break;
            const { done, value } = await reader.read();
            if (done) break;
            if (value) {
              accumulated += value;
              onChunk?.(accumulated, value);
            }
          }
        } finally {
          reader.releaseLock();
        }
        return accumulated;
      }
    }

    // Non-streaming fallback
    const result = await instance.summarize(content, { signal });
    onChunk?.(result, result);
    return result;
  } finally {
    instance.destroy();
  }
}

4. Building the React Component

Here is the React component. It checks availability on mount. If the browser does not support on-device AI, it returns null so the page layout remains untouched.

When available, it renders an interactive drawer allowing the user to select their preferred summary style and length, displays a download bar if the model is loading, and streams the output directly into the UI.

// src/components/ArticleSummarizer.tsx
import React, { useState, useEffect, useRef } from 'react';
import {
  checkSummarizerSupport,
  isUsableStatus,
  runSummarization,
  type SummarizerStyleType,
  type SummarizerLengthType,
  type AvailabilityStatus,
} from '../lib/summarizer';

interface Props {
  content: string;
  articleTitle?: string;
}

const TYPE_OPTIONS: { id: SummarizerStyleType; label: string }[] = [
  { id: 'key-points', label: 'Key Points' },
  { id: 'tldr', label: 'TL;DR' },
  { id: 'teaser', label: 'Teaser' },
  { id: 'headline', label: 'Headline' },
];

const LENGTH_OPTIONS: { id: SummarizerLengthType; label: string }[] = [
  { id: 'short', label: 'Short' },
  { id: 'medium', label: 'Medium' },
  { id: 'long', label: 'Long' },
];

export const ArticleSummarizer: React.FC<Props> = ({ content, articleTitle }) => {
  const [availability, setAvailability] = useState<AvailabilityStatus | null>(null);
  const [isOpen, setIsOpen] = useState(false);
  const [type, setType] = useState<SummarizerStyleType>('key-points');
  const [length, setLength] = useState<SummarizerLengthType>('medium');
  const [summary, setSummary] = useState('');
  const [loading, setLoading] = useState(false);
  const [downloadProgress, setDownloadProgress] = useState<number | null>(null);
  const [copied, setCopied] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const abortRef = useRef<AbortController | null>(null);

  useEffect(() => {
    let active = true;
    void checkSummarizerSupport().then((status) => {
      if (active) setAvailability(status);
    });
    return () => { active = false; };
  }, []);

  // Return nothing if the client does not support the API
  if (!availability || !isUsableStatus(availability)) {
    return null;
  }

  const handleGenerate = async () => {
    if (loading) return;

    setError(null);
    setSummary('');
    setDownloadProgress(null);
    setLoading(true);
    setIsOpen(true);

    const controller = new AbortController();
    abortRef.current = controller;

    try {
      await runSummarization({
        content,
        type,
        length,
        sharedContext: articleTitle ? `Article: ${articleTitle}` : undefined,
        signal: controller.signal,
        onDownloadProgress: (pct) => setDownloadProgress(pct),
        onChunk: (accumulated) => {
          setSummary(accumulated);
          setDownloadProgress(null);
        },
      });
    } catch (err: any) {
      if (!controller.signal.aborted) {
        setError(err?.message || 'An error occurred during summarization.');
      }
    } finally {
      setLoading(false);
      setDownloadProgress(null);
    }
  };

  const handleStop = () => {
    abortRef.current?.abort();
    setLoading(false);
  };

  const handleCopy = () => {
    void navigator.clipboard.writeText(summary);
    setCopied(true);
    setTimeout(() => setCopied(false), 2000);
  };

  return (
    <div className="border border-neutral-800 bg-neutral-950 rounded-xl p-5 text-neutral-200 my-6">
      <div className="flex items-center justify-between">
        <div>
          <span className="text-xs font-mono font-semibold uppercase text-emerald-400">
            Local AI Summarizer
          </span>
          <p className="text-xs text-neutral-400 mt-0.5">
            Summarize this article on-device using Chrome's built-in model.
          </p>
        </div>

        <div className="flex items-center gap-2">
          {!summary && !loading && (
            <button
              onClick={() => void handleGenerate()}
              className="px-3.5 py-1.5 rounded-lg bg-emerald-400 text-black text-xs font-medium hover:bg-emerald-300 transition-colors"
            >
              Summarize Article
            </button>
          )}

          {loading && (
            <button
              onClick={handleStop}
              className="px-3 py-1.5 rounded-lg border border-red-500/40 bg-red-500/10 text-red-300 text-xs"
            >
              Stop
            </button>
          )}

          <button
            onClick={() => setIsOpen(!isOpen)}
            className="px-2.5 py-1.5 rounded-lg border border-neutral-800 text-xs text-neutral-400 hover:text-neutral-200"
          >
            {isOpen ? 'Hide' : 'Options'}
          </button>
        </div>
      </div>

      {isOpen && (
        <div className="mt-4 pt-4 border-t border-neutral-900 space-y-4">
          <div className="flex flex-wrap gap-4 text-xs font-mono">
            <div className="flex items-center gap-2">
              <span className="text-neutral-500">STYLE:</span>
              {TYPE_OPTIONS.map((opt) => (
                <button
                  key={opt.id}
                  disabled={loading}
                  onClick={() => setType(opt.id)}
                  className={`px-2.5 py-1 rounded border transition-colors ${
                    type === opt.id
                      ? 'border-emerald-400/80 bg-emerald-950/40 text-emerald-300'
                      : 'border-neutral-800 text-neutral-400 hover:text-neutral-200'
                  }`}
                >
                  {opt.label}
                </button>
              ))}
            </div>

            <div className="flex items-center gap-2">
              <span className="text-neutral-500">LENGTH:</span>
              {LENGTH_OPTIONS.map((opt) => (
                <button
                  key={opt.id}
                  disabled={loading}
                  onClick={() => setLength(opt.id)}
                  className={`px-2 py-1 rounded border transition-colors ${
                    length === opt.id
                      ? 'border-emerald-400/80 bg-emerald-950/40 text-emerald-300'
                      : 'border-neutral-800 text-neutral-400 hover:text-neutral-200'
                  }`}
                >
                  {opt.label}
                </button>
              ))}
            </div>
          </div>

          {downloadProgress !== null && (
            <div className="space-y-1.5 text-xs font-mono text-emerald-400">
              <div className="flex justify-between">
                <span>Downloading model weights...</span>
                <span>{downloadProgress}%</span>
              </div>
              <div className="w-full bg-neutral-900 h-1.5 rounded-full overflow-hidden">
                <div
                  className="bg-emerald-400 h-full transition-all duration-200"
                  style={{ width: `${downloadProgress}%` }}
                />
              </div>
            </div>
          )}

          {error && (
            <p className="text-xs font-mono text-red-400 bg-red-950/30 p-3 rounded-lg border border-red-900/50">
              {error}
            </p>
          )}

          {summary && (
            <div className="space-y-3">
              <div className="p-4 bg-neutral-900/70 border border-neutral-800 rounded-lg text-sm text-neutral-200 leading-relaxed whitespace-pre-wrap">
                {summary}
              </div>

              <div className="flex items-center justify-between text-xs font-mono">
                <button
                  onClick={() => void handleGenerate()}
                  disabled={loading}
                  className="text-neutral-400 hover:text-neutral-200"
                >
                  Regenerate
                </button>

                <button
                  onClick={handleCopy}
                  className="px-3 py-1.5 rounded border border-neutral-800 text-neutral-300 hover:text-white"
                >
                  {copied ? 'Copied' : 'Copy Summary'}
                </button>
              </div>
            </div>
          )}
        </div>
      )}
    </div>
  );
};

5. Testing Locally in Chrome

If you want to test this during local development:

Use Chrome Canary, Dev, or Beta (version 138 or newer).
Navigate to chrome://flags in the address bar and enable:
- Enables optimization guide on device: Set to Enabled BypassPrefRequirement.
- Summarization API for Gemini Nano: Set to Enabled.
Restart Chrome.
Go to chrome://components and click Check for update under Optimization Guide On Device Model to ensure the model binaries are fetched.

Conclusion

The ability to run Gemini Nano directly in the browser opens up a lot of practical use cases without incurring infrastructure costs or dealing with backend latency.

By checking availability upfront and supporting streaming and download events, you can build a seamless progressive enhancement for your readers while ensuring non-Chromium users continue to have an uninterrupted reading experience.

How I Built a Timeline Portfolio using Canvas 2D

Vitor Ferreira — Tue, 04 Aug 2026 20:47:18 +0000

How I Built a Procedural Topographical Timeline Portfolio using Canvas 2D, React & GSAP

When designing a developer portfolio, standard grid layouts and vertical timeline cards can often feel repetitive. I wanted to build something that felt alive, immersive, and visually unique—a "Topographical Timeline" where a developer's career journey is depicted as a glowing trail across a procedurally generated mountain landscape.

In this article, I will break down the engineering architecture behind this project: how to generate procedural terrain contours in the browser, optimize HTML5 Canvas performance with offscreen caching, draw multi-layered glowing neon paths, and sync scroll progress with interactive HTML overlay cards.

🏗 Architecture & Layering Strategy

To achieve 60 FPS performance while keeping interactive UI elements accessible, the application uses a hybrid 3-layer architecture:

 ┌─────────────────────────────────────────────────────────┐
 │ Layer 3: Interactive HTML/CSS Cards (Fixed Overlays)    │
 ├─────────────────────────────────────────────────────────┤
 │ Layer 2: Main Canvas (Glowing Bezier Trail & Bullet)    │
 ├─────────────────────────────────────────────────────────┤
 │ Layer 1: Offscreen Cached Canvas (Procedural Terrain)   │
 └─────────────────────────────────────────────────────────┘

Procedural Terrain Layer (Offscreen Canvas Snapshot): Renders multi-octave 2D elevation noise converted to elevation iso-contour vectors via d3-contour.
Glowing Trail & Scroll Layer (Visible Canvas 2D): Clears and draws the cached terrain image, then draws a responsive cubic Bezier trail with multi-layered neon glow strokes and an animated scroll tracker bullet.
Interactive Waypoint Layer (HTML/CSS Overlays): HTML cards positioned absolutely using pixel coordinates calculated by sampling points along the SVG Bezier path string.

⛰ 1. Generating Procedural Terrain with Simplex Noise & D3-Contour

Topographic maps represent height variations using contour lines (iso-lines). To create natural, continuous mountain terrain:

We sample height values across a 2D grid using Simplex Noise.
We combine multiple noise frequencies (octaves) so terrain has both large mountain peaks and subtle ridge details.
We feed the 2D heightmap matrix into d3-contour to compute vector contour coordinates.

Here is the core terrain generation function:

import { createNoise2D } from 'simplex-noise';
import { contours } from 'd3-contour';

export const buildTerrain = (width: number, height: number) => {
  const terrainCanvas = document.createElement('canvas');
  terrainCanvas.width = width;
  terrainCanvas.height = height;
  const context = terrainCanvas.getContext('2d');
  if (!context) return terrainCanvas;

  // Dark topographic base fill
  context.fillStyle = '#121510';
  context.fillRect(0, 0, width, height);

  // 1. Generate Simplex Noise Grid
  const resolution = 12; // Grid step size in pixels
  const cols = Math.ceil(width / resolution) + 1;
  const rows = Math.ceil(height / resolution) + 1;
  const values = new Float64Array(cols * rows);
  const noise2D = createNoise2D();

  const noiseScale = 0.0025;
  for (let y = 0; y < rows; y++) {
    for (let x = 0; x < cols; x++) {
      const worldX = x * resolution;
      const worldY = y * resolution;

      // Multi-octave noise for realistic elevation variation
      const n1 = noise2D(worldX * noiseScale, worldY * noiseScale);
      const n2 = noise2D(worldX * noiseScale * 2, worldY * noiseScale * 2) * 0.5;
      const n3 = noise2D(worldX * noiseScale * 4, worldY * noiseScale * 4) * 0.25;

      values[y * cols + x] = (n1 + n2 + n3 + 1.75) / 3.5; // Normalized ~[0, 1]
    }
  }

  // 2. Extract Vector Iso-Lines using d3-contour
  const contourGenerator = contours()
    .size([cols, rows])
    .thresholds(22);

  const contourData = contourGenerator(Array.from(values));

  // 3. Render Contour Vectors onto Offscreen Canvas
  context.save();
  context.lineWidth = 1.2;

  contourData.forEach((contour, idx) => {
    // Opacity scales with height elevation
    const alpha = 0.05 + (idx / contourData.length) * 0.16;
    context.strokeStyle = `rgba(140, 165, 120, ${alpha})`;

    context.beginPath();
    contour.coordinates.forEach((polygon) => {
      polygon.forEach((ring) => {
        ring.forEach(([x, y], i) => {
          const px = x * resolution;
          const py = y * resolution;
          if (i === 0) context.moveTo(px, py);
          else context.lineTo(px, py);
        });
      });
    });
    context.stroke();
  });

  context.restore();
  return terrainCanvas;
};

⚡ 2. Performance Optimization: Offscreen Canvas Snapshot Caching

Generating Simplex Noise across thousands of grid points and computing 22 threshold contour polygons is CPU-intensive. If you run buildTerrain on every single scroll frame (requestAnimationFrame), frame rates will drop below 15 FPS.

The Solution:

On Window Resize: Compute buildTerrain(width, height) once and store the offscreen canvas element in a useRef.
On Scroll Update: Clear the main screen canvas and draw the cached offscreen snapshot instantly using ctx.drawImage(snapshotRef.current.terrainCanvas, 0, 0).

const drawRoute = () => {
  const canvas = canvasRef.current;
  if (!canvas || !snapshotRef.current || !pathElementRef.current) return;
  const context = canvas.getContext('2d');
  if (!context) return;

  // ⚡ 1. Clear visible canvas
  context.clearRect(0, 0, canvas.width, canvas.height);

  // ⚡ 2. Blit pre-rendered terrain image instantly (0 CPU noise calculations!)
  context.drawImage(snapshotRef.current.terrainCanvas, 0, 0);

  // ⚡ 3. Draw active scroll trail & glowing bullet on top
  drawAuxiliaryRouteLines(context, pathElementRef.current);
  drawActiveRouteLine(context, pathElementRef.current, scrollProgress);
  drawScrollBullet(context, pathElementRef.current, scrollProgress);
};

This simple caching pattern keeps canvas rendering at a rock-solid 60 FPS regardless of screen size!

🛣 3. Creating the Glowing Trail & Multi-Layer Neon Effects

To give the route a futuristic, tactical HUD feel, the active trail isn't drawn with a single stroke. Instead, we render 4 overlapping line passes with varying stroke widths, opacities, and canvas shadow blurs:

const drawActiveRouteLine = (
  context: CanvasRenderingContext2D,
  path: SVGPathElement,
  progress: number
) => {
  if (progress <= 0) return;

  const totalLength = path.getTotalLength();
  const activeLength = totalLength * progress;
  const step = 4;

  context.save();
  context.beginPath();
  let first = true;

  // Sample path points up to active scroll length
  for (let l = 0; l <= activeLength; l += step) {
    const pt = path.getPointAtLength(l);
    if (first) {
      context.moveTo(pt.x, pt.y);
      first = false;
    } else {
      context.lineTo(pt.x, pt.y);
    }
  }

  // Layered glowing stroke configurations
  const lineConfigs = [
    { strokeStyle: 'rgba(202, 250, 92, 0.25)', lineWidth: 16, blur: 16 }, // Ambient Outer Glow
    { strokeStyle: 'rgba(202, 250, 92, 0.6)',  lineWidth: 6,  blur: 8  }, // Medium Glow
    { strokeStyle: '#caef5c',                  lineWidth: 2.5, blur: 2  }, // Core Neon Lime Line
    { strokeStyle: '#ffffff',                  lineWidth: 1.2, blur: 0  }  // Sharp White Core Highlight
  ];

  for (const config of lineConfigs) {
    context.save();
    context.strokeStyle = config.strokeStyle;
    context.lineWidth = config.lineWidth;
    context.lineCap = 'round';
    context.lineJoin = 'round';
    if (config.blur > 0) {
      context.shadowColor = '#caef5c';
      context.shadowBlur = config.blur;
    }
    context.stroke();
    context.restore();
  }

  context.restore();
};

🎯 4. Syncing Scroll & Positioning HTML Waypoint Overlays

To map viewport scrolling to the route trail, we use GSAP ScrollTrigger:

A wrapper <main> container is given a large virtual scroll height (e.g., min-h-[400vh]).
GSAP calculates a normalized scrollProgress between 0.0 (top of page) and 1.0 (bottom of page).
We convert each milestone's routeProgressPercentage into exact (X, Y) screen pixel coordinates using an SVG Path's .getPointAtLength() API.

// Calculate exact pixel positions for each waypoint along the bezier path
const positions = useMemo(() => {
  if (!routePath || !viewport.width || !viewport.height) return [];

  const pathEl = document.createElementNS('http://www.w3.org/2000/svg', 'path');
  pathEl.setAttribute('d', routePath);
  const totalLength = pathEl.getTotalLength();

  return timeline.map((entry) => {
    const point = pathEl.getPointAtLength(entry.routeProgressPercentage * totalLength);
    return {
      id: entry.id,
      x: point.x,
      y: point.y,
    };
  });
}, [routePath, viewport.width, viewport.height]);

Each <WaypointCard /> is rendered inside a pointer-events-none fixed inset-0 wrapper, positioned using style={{ top: '${y}px', left: '${x}px' }} with pointer-events-auto on individual cards for full interactivity!

📱 5. Mobile Responsiveness & Polish

Canvas animations can behave differently on touchscreens. To ensure a seamless user experience across all devices:

High DPI Displays (devicePixelRatio): The canvas width and height scale with window.devicePixelRatio to maintain razor-sharp graphics on Retina displays.
Mobile Viewport Optimization: On mobile devices (< 768px), the site automatically adjusts layout to a compact timeline feed (<MobileTimelineView>), preventing horizontal clipping while preserving background canvas rendering.
Dev.to API Integration: Live technical posts and engineering logs are dynamically fetched from the Dev.to REST API and formatted within the site's dark tactical aesthetic.

💡 Key Takeaways

Separate Heavy Computation from Render Frames: Offscreen canvas buffering is essential when combining complex mathematical noise/vector generation with interactive animations.
Combine Vector Math with HTML DOM: HTML5 Canvas is great for background graphics and glows, while HTML overlay cards provide accessibility, crisp typography, and easy event handling.
Layered Canvas Effects: Combining multiple strokes with varying blur radii creates impressive neon lighting effects without WebGL overhead.

🌐 Links & Source Code

Tech Stack: React 19, TypeScript, Vite, Tailwind CSS v4, HTML5 Canvas 2D API, GSAP ScrollTrigger, Simplex-Noise, D3-Contour, Lucide React.
Author: Vitor (@vitorstick)

What are your thoughts on combining Canvas 2D with GSAP and HTML overlays? Feel free to drop questions or feedback in the comments below!

How did I made a circle withing another circle

Vitor Ferreira — Thu, 21 Dec 2023 15:44:51 +0000

In our recent sprint, biGENIUS design team embarked on an exciting journey to enhance user interaction by introducing a sleek stepper view, complete with eye-catching stepper elements. Picture this: a single circle adorned with a numerical indicator and a stylish outer border—cool, right?

Now, the challenge was to bring this vision to life using CSS. Here's the breakdown of my approach:

Firstly, the color scheme and border of the stepper are intricately tied to its current status—whether it's active or not. While various methods, including different SVGs, crossed my mind, I opted for a more elegant solution: leveraging the power of pure CSS.

And so, the question arose: how to achieve this visually appealing effect? Let's dive into the process, starting with the creation of the circle containing the numerical identifier—seemingly simple, yet a crucial step in realizing the desired aesthetic.

<div class="stepper-step__number">1</div>

.stepper-step__number {
  display: flex;
  align-items: center;
  justify-content: center;

  font-size: 24px;
  color: #f3f3f3;
  height: 48px;
  width: 48px;
  min-width: 48px;
  border-radius: 50%;
  background-color: #44a5d8;
}

The outcome:

Now, onto the more challenging aspect—the creation of that elusive white inner circle.

My initial pondering led me down the path of considering another circle element with a simple white border, nested within the outer circle. However, I realized I was unnecessarily complicating the process.

It dawned on me: why not employ the subtle power of box-shadow to achieve the desired effect? The solution revealed itself through the use of a pseudo-element, a moment of coding clarity that filled me with a sense of pride. This revelation became the driving force behind sharing my experience in this post, a testament to the joy of overcoming coding challenges and discovering elegant solutions.

<div class="stepper-step__number active">2</div>

.stepper-step__number.active {
  position: relative;
}

.stepper-step__number.active::after {
  content: '';
  position: absolute;
  width: calc(100% - 6px);
  height: calc(100% - 6px);
  border-radius: 50%;
  box-shadow: inset 0 0 0 2px #fff;
}

I am so proud of myself

If you want to try it, check it out on stackblitz

Would you have done this differently?
Tell me how on the comments
(probably with tailwind this could be done with some simple things right?)

Using browser Speech Synthesis capabilities (on an Angular App)

Vitor Ferreira — Sat, 10 Jun 2023 22:05:49 +0000

Guess what?
I've been traveling around Germany! But here's the kicker: instead of diligently learning Deutsch like a responsible adult, I've decided to take a shortcut and create my own app to handle everything for me. Genius or madness? We'll see!

So, the first obstacle I encountered was the pronunciation of those tongue-twisting German words. Seriously, they sound like a bunch of cats having a karaoke session. But fear not, for my app comes to the rescue! Not only does it provide translations, but it also teaches me how to pronounce those words correctly. I'll be mastering German like a pro in no time, or at least pretending to while giggling at my own attempts..

For that, and to have it working offline, I went for the browser capabilities and Web Speech API

I decided to go all-in and use Angular for this app. Why? Well, let's just say I have a soft spot for Angular's sleekness and charm. But hey, don't fret if you're not an Angular enthusiast like me! The beauty of this project is that it's written in good ol' JavaScript, so you can take this linguistic journey with any framework you fancy. It's a choose-your-own-adventure kind of deal!

First step: just created a service to handle this:

export class SpeechService {
  synthesis = window.speechSynthesis;

  start(text: string, rate = 1) {
    const textToSpeech = new SpeechSynthesisUtterance(text);
    textToSpeech.lang = "de-DE";
    textToSpeech.text = text;
    textToSpeech.rate = rate;

    const voice = speechSynthesis.getVoices().filter((voice) => {
      return voice.name === "Google Deutsch";
    })[0];
    textToSpeech.voice = voice;

    this.synthesis.speak(textToSpeech);
  }
}

The bad part of that from my experience, this only work properly (with a correct accent) in Chrome ...
To see what voices are available, you can check here

And it's used for this part (I only care about Deutsch):

    const voice = speechSynthesis.getVoices().filter((voice) => {
      return voice.name === "Google Deutsch";
    })[0];

To use this, I have a simple component that calls this service

@Component({
  selector: 'app-speech',
  standalone: true,
  template: `
  <form class="speech-form" [formGroup]="formGroup">
    <label style="margin-bottom: 10px">Please Insert German Word</label>
    <input formControlName="text" style="margin-bottom: 20px" />
    <button
      style="margin-bottom: 20px"
      (click)="handleButtonStartClick($event, 1)"
    >
      Say It
    </button>
    <button (click)="handleButtonStartClick($event, 0.4)">Say It Slowly</button>
  </form>
  `,
  styleUrls: ['./speech.component.css'],
  imports: [ReactiveFormsModule],
})
export class SpeechComponent {
  formGroup = new FormGroup({
    text: new FormControl('', [Validators.required]),
  });

  constructor(private speechService: SpeechService) {}

  handleButtonStartClick(e: Event, speed: number) {
    e.preventDefault();
    if (!!this.formGroup.controls?.text?.value) {
      this.speechService.start(this.formGroup.controls.text.value, speed);
    }
  }
}

There is a button to allows it to speak, and other that is set to say it slowly (0.4 speed), and believe me, to understand **Deutsch **words, I need it.

If you want to test it, just for it here on stackblitz

In the real app, it also have SpeechRecognition capabilities, maybe in the future I can share it as well.

Tell me what you thing, and if you find it interesting fell free to fork it and try it yourself.

Sharing styles between apps inside Nx workspace

Vitor Ferreira — Tue, 02 Jun 2020 10:11:14 +0000

In my current job we have decided to make the change into Nx workspace and with that we decided to create our very own Design System.

But I didn't want to maintain the same styles in more than one application.

Creating a lib for styles

The best solution for my case was to create a lib named ui for the styles:

nx generate @nrwl/angular:library ui

Then I moved the sass files into the library:

The problem now, is the @import in all the scss files.
How to make them recognize the correct files?
On angular.json on every project the path will have to be included.

"projects": {
    "ds-project": {
        "projectType": "application",
        ...
        "architect": {
            "build": {
                ...
                "stylePreprocessorOptions": {
                    "includePaths": [ "libs/ui/src/lib/styles" ]
                },
                "extractCss": true,
                ...

Now you can import the mixins on the scss files of your project just like if they were still part of the project:

@import "mixins/list_mixin";
@import "variables";

@include list_layout;

Even the base style, like font-family are importable.

Inside the style.scss of the project to became the global styles (for this case the module contains the global styles).

// styles.scss
/* You can add global styles to this file, and also import other style files */

@import 'module';

Conclusion

This solves easily a problem that could be an issue and I was somehow afraid to tackle, that is having global scss files shared between applications and easily maintainable with only one source of truth (the library).

If you have any suggestion of how I could do this differently, please share your ideas.

Dockerize Angular app and deploy on OpenShift

Vitor Ferreira — Sun, 03 May 2020 20:57:27 +0000

I've been experimenting with several tools and would like to share my latest experience:
Deploy an Angular application created with SSR inside a Nwrl Nx workspace, and then dockerize it and deploy on RedHat OpenShift.

Why use Angular with SSR?
I wanted to try to have a 100% lighthouse audit application, and despite my Angular experience, never worked on an angular project using server side rendering, so, building a personal website, was a good opportunity to experiment and have that 100% on performance.

Why chose RedHat OpenShift?
Simple, I like the red hat that the girls that promote the service use, and I have used AWS and Azure solutions. Also very important, they have a free option.

First Step (assuming the application already exist), creating the Dockerfile

### STAGE 1: Build ###
FROM node:lts-alpine AS build

#### make the 'app' folder the current working directory
WORKDIR /usr/src/app

#### copy both 'package.json' and 'package-lock.json' (if available)
COPY package*.json ./

#### install angular cli
RUN npm install -g @angular/cli

#### install project dependencies
RUN npm install

#### copy things
COPY . .

#### generate build --prod
RUN npm run build:ssr

### STAGE 2: Run ###
FROM nginxinc/nginx-unprivileged

#### copy nginx conf
COPY ./config/nginx.conf /etc/nginx/conf.d/default.conf

#### copy artifact build from the 'build environment'
COPY --from=build /usr/src/app/dist/vitorspace/browser /usr/share/nginx/html

#### don't know what this is, but seems cool and techy
CMD ["nginx", "-g", "daemon off;"]

Remarks:
Had to use nginxinc/nginx-unprivileged due to problems on OpenShift with nginx permissions (thank you random stranger on stackoverflow that suggested it).

On package.json the script for build:ssr is
"build:ssr": "ng build --prod vitorspace && ng run vitorspace:server:production", remember, this is an angular application with server side rendering.

The nginx.conf configuration (I am trying a lighthouse 100% angular application, so I needed that):

server {
    listen 0.0.0.0:8080;
    listen [::]:8080;
    default_type application/octet-stream;

    gzip                    on;
    gzip_comp_level         6;
    gzip_vary               on;
    gzip_min_length         1000;
    gzip_proxied            any;
    gzip_types              text/plain text/css application/json application/x-javascript text/xml application/xml application/xml+rss text/javascript;
    gzip_buffers            16 8k;
    gunzip on;
    client_max_body_size    256M;

    root /usr/share/nginx/html;

    location / {
        try_files $uri $uri/ /index.html =404;
    }
}

Second Step - sending docker image to dockerhub

You need a dockerhub account

Build the image
docker build -t vitorspace-image .

Run the image to test it
docker run --name vitorspace-container -d -p 8888:80 vitorspace-image

browser it http://localhost:8888/

Commit image
docker commit 21737e7ab73b vitorstick/vitorspace:v1

Tag image
docker tag vitorspace-image vitorstick/vitorspace

Push image
docker push vitorstick/vitorspace

Third Step - publishing it on RedHat OpenShift

Assuming you already have a account

Create OpenShift Project

Chose Workload Option and Select Container Image

Don't forget the docker image path, and then just say what will be your application path

On the bottom of the same form, on Advanced Options, just pick the Create a route to the application and you will have an url to try and share your application.

Conclusions

OpenShift have a lot of options, about pods, configurations, and a lot of other things, but honestly I am a developer, not a devops, and spending a lot of time changing yaml files does not bring me any joy, and that's what I really liked in OpenShift, it's super easy to use (after doing it the first time)

The main reason for me to create and share this article, was the pain I felt doing some of this things for the first time, and like me, maybe I can help some of you.

If you have any suggestion about anything, please share.