feat(firebase-ai-logic-basics): Web (JavaScript) SDK setup and capability guides

Author: AustinBenoit

skills/firebase-ai-logic-basics/references/sdk/capabilities/chat.md

@@ -83,3 +83,33 @@ final chat = model.startChat(history: [
 final response = await chat.sendMessage(Content.text('What is CBT?'));
 print(response.text);
 ```
+
+## Web (JavaScript)
+
+Maintain history automatically using `startChat`.
+
+```javascript
+import { getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";
+
+const ai = getAI(app, { backend: new GoogleAIBackend() });
+// [AGENT] Replace "<latest_supported_model>" with the latest model from https://firebase.google.com/docs/ai-logic/models.md.txt
+const model = getGenerativeModel(ai, { model: "<latest_supported_model>" });
+
+const chat = model.startChat({
+  history: [
+    {
+      role: "user",
+      parts: [{ type: "text", text: "Hello, I am a developer." }],
+    },
+    {
+      role: "model",
+      parts: [{ type: "text", text: "Great to meet you. How can I help with code?" }],
+    },
+  ],
+});
+
+async function sendMessage(msg) {
+  const result = await chat.sendMessage(msg);
+  return result.response.text();
+}
+```

skills/firebase-ai-logic-basics/references/sdk/capabilities/function_calling.md

@@ -181,3 +181,64 @@ Future<String> askStockPrice() async {
   return response.text ?? 'No text in response';
 }
 ```
+
+## Web (JavaScript)
+
+Declare the tool as a plain object with a `functionDeclarations` array (use the
+`Schema` helpers for the parameters), read `functionCalls()` from the response,
+and send the `functionResponse` part(s) back in a single turn:
+
+```javascript
+import { getAI, getGenerativeModel, GoogleAIBackend, Schema } from "firebase/ai";
+
+// Step 1: the app-side function the model can ask you to run.
+async function getStockPrice({ symbol }) {
+  // TODO(developer): Call a real stock price API. Hardcoded for demo purposes.
+  return { symbol, price: 189.84 };
+}
+
+// Step 2: describe the function to the model.
+const getStockPriceTool = {
+  functionDeclarations: [
+    {
+      name: "getStockPrice",
+      description: "Get the current stock price for a given symbol.",
+      parameters: Schema.object({
+        properties: {
+          symbol: Schema.string({ description: "The stock symbol, e.g. AAPL" }),
+        },
+      }),
+    },
+  ],
+};
+
+// Step 3: provide the declaration when creating the model.
+const ai = getAI(app, { backend: new GoogleAIBackend() });
+const model = getGenerativeModel(ai, {
+  model: "<latest_supported_model>", // [AGENT] Replace with the latest model from https://firebase.google.com/docs/ai-logic/models.md.txt
+  tools: [getStockPriceTool],
+});
+
+async function askStockPrice() {
+  // Step 4: send the prompt in a chat session and run any requested call(s).
+  const chat = model.startChat();
+  let result = await chat.sendMessage("What is the stock price of Apple?");
+
+  const functionResponses = [];
+  for (const call of result.response.functionCalls() ?? []) {
+    if (call.name === "getStockPrice") {
+      const functionResult = await getStockPrice(call.args);
+      functionResponses.push({
+        type: "functionResponse",
+        functionResponse: { id: call.id, name: call.name, response: functionResult },
+      });
+    }
+  }
+
+  // Step 5: return all function results in a single turn so the model can write its final answer.
+  if (functionResponses.length > 0) {
+    result = await chat.sendMessage(functionResponses);
+  }
+  return result.response.text();
+}
+```

skills/firebase-ai-logic-basics/references/sdk/capabilities/image_generation.md

@@ -174,3 +174,83 @@ if (response.inlineDataParts.isNotEmpty) {
   print('Error: No images were generated.');
 }
 ```
+
+## Web (JavaScript)
+
+`ai` is the AI Logic service instance created during setup with
+`getAI(app, { backend: new GoogleAIBackend() })`. This sample requests both
+`TEXT` and `IMAGE`, so the model may return text parts alongside the image;
+`inlineDataParts()` returns only the image parts. Drop `ResponseModality.TEXT`
+for image-only output. To display the result, build a data URL from the part:
+`` `data:${image.mimeType};base64,${image.data}` ``.
+
+```javascript
+import { getGenerativeModel, ResponseModality } from "firebase/ai";
+
+// Create a `GenerativeModel` instance with a model that supports your use case
+const model = getGenerativeModel(ai, {
+  model: "<latest_supported_image_model>", // [AGENT] Replace with the latest image model from https://firebase.google.com/docs/ai-logic/models.md.txt
+  // Configure the model to respond with text and images (required)
+  generationConfig: {
+    responseModalities: [ResponseModality.TEXT, ResponseModality.IMAGE],
+  },
+});
+
+// Provide a text prompt instructing the model to generate an image
+const prompt = 'Generate an image of the Eiffel Tower with fireworks in the background.';
+
+// To generate an image, call `generateContent` with the text input
+const result = await model.generateContent(prompt);
+
+// Handle the generated image
+try {
+  const inlineDataParts = result.response.inlineDataParts();
+  if (inlineDataParts?.[0]) {
+    const image = inlineDataParts[0].inlineData;
+    console.log(image.mimeType, image.data);
+  }
+} catch (err) {
+  console.error('Prompt or candidate was blocked:', err);
+}
+```
+
+### Edit an image
+
+Convert the user's file to an inline data part and pass it with the prompt to
+the same image-capable `model`:
+
+```javascript
+// Prepare an image for the model to edit
+async function fileToGenerativePart(file) {
+  const base64EncodedDataPromise = new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = () => resolve(String(reader.result).split(',')[1]);
+    reader.onerror = reject;
+    reader.readAsDataURL(file);
+  });
+  return {
+    type: "inlineData",
+    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
+  };
+}
+
+// Provide a text prompt instructing the model to edit the image
+const prompt = "Edit this image to make it look like a cartoon";
+
+const fileInputEl = document.querySelector("input[type=file]");
+const imagePart = await fileToGenerativePart(fileInputEl.files[0]);
+
+// To edit the image, call `generateContent` with the image and text input
+const result = await model.generateContent([imagePart, prompt]);
+
+// Handle the generated image
+try {
+  const inlineDataParts = result.response.inlineDataParts();
+  if (inlineDataParts?.[0]) {
+    const image = inlineDataParts[0].inlineData;
+    console.log(image.mimeType, image.data);
+  }
+} catch (err) {
+  console.error('Prompt or candidate was blocked:', err);
+}
+```

skills/firebase-ai-logic-basics/references/sdk/capabilities/multimodal_input.md

@@ -121,3 +121,56 @@ final response = await model.generateContent([
 Cloud Storage for Firebase URL (Agent Platform Gemini API provider only): use
 `FileData('image/jpeg', 'gs://bucket-name/path/image.jpg')` in place of the
 `InlineDataPart` inside `Content.multi`.
+
+## Web (JavaScript)
+
+Firebase AI Logic accepts Base64 encoded data or specific file references.
+
+```javascript
+import { getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";
+
+const ai = getAI(app, { backend: new GoogleAIBackend() });
+// [AGENT] Replace "<latest_supported_model>" with the latest model from https://firebase.google.com/docs/ai-logic/models.md.txt
+const model = getGenerativeModel(ai, { model: "<latest_supported_model>" });
+
+// Helper to convert file to base64 generic object
+async function fileToGenerativePart(file) {
+  const base64EncodedDataPromise = new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = () => resolve(String(reader.result).split(',')[1]);
+    reader.onerror = reject;
+    reader.readAsDataURL(file);
+  });
+
+  return {
+    type: "inlineData",
+    inlineData: {
+      data: await base64EncodedDataPromise,
+      mimeType: file.type,
+    },
+  };
+}
+
+async function analyzeImage(prompt, imageFile) {
+  const imagePart = await fileToGenerativePart(imageFile);
+  const result = await model.generateContent([imagePart, prompt]);
+  return result.response.text();
+}
+```
+
+The same helper handles audio, video, and PDF `File` objects because it reads
+the MIME type from `file.type`. If you already hold base64 data, build the part
+directly with an explicit MIME type:
+
+```javascript
+const pdfPart = { type: "inlineData", inlineData: { data: base64Pdf, mimeType: "application/pdf" } };
+const result = await model.generateContent([
+  pdfPart,
+  "Summarize the important results in this report.",
+]);
+console.log(result.response.text());
+```
+
+Cloud Storage for Firebase URL (Agent Platform Gemini API provider only): pass
+`{ type: "fileData", fileData: { mimeType: "image/jpeg", fileUri: "gs://bucket-name/path/image.jpg" } }`
+in place of the `inlineData` part.

skills/firebase-ai-logic-basics/references/sdk/capabilities/on_device_hybrid.md

@@ -109,3 +109,75 @@ print(response.content)
 Hybrid on-device inference is not available via Firebase AI Logic on Flutter
 (including Flutter web); the `firebase_ai` package always calls the cloud-hosted
 Gemini API. See https://firebase.google.com/docs/ai-logic/hybrid.md.txt.
+
+## Web (JavaScript)
+
+On Web, on-device inference uses Chrome's built-in
+[Prompt API](https://developer.chrome.com/docs/extensions/ai/prompt-api) on
+Chrome Desktop (v139+, with at least 22 GB free storage and >4 GB VRAM or 16 GB
+RAM). For local development, enable
+`chrome://flags/#prompt-api-for-gemini-nano-multimodal-input` and restart
+Chrome; for end users, serve the
+[Prompt API Chrome Origin Trial](https://developer.chrome.com/origintrials/#/view_trial/2533837740349325313)
+token.
+
+Create the hybrid model with `mode: InferenceMode.PREFER_ON_DEVICE`, call
+`await hybridModel.initializeDeviceModel()` on a user gesture to ensure Gemini
+Nano is downloaded and initialized, then call `generateContent` and inspect
+`result.response.inferenceSource`:
+
+```javascript
+import { getGenerativeModel, InferenceMode, InferenceSource } from "firebase/ai";
+
+const hybridModel = getGenerativeModel(ai, {
+  mode: InferenceMode.PREFER_ON_DEVICE,
+});
+
+// Call initializeDeviceModel() on or after an end-user interaction (e.g. button click)
+document.querySelector("#generate").addEventListener("click", async () => {
+  await hybridModel.initializeDeviceModel((progress) => {
+    console.log(`On-device model download progress: ${Math.round(progress * 100)}%`);
+  });
+
+  const prompt = "Write a story about a magic backpack.";
+  const result = await hybridModel.generateContent(prompt);
+
+  // Compare with InferenceSource.ON_DEVICE ("on_device") or InferenceSource.IN_CLOUD ("in_cloud")
+  const usedOnDevice = result.response.inferenceSource === InferenceSource.ON_DEVICE;
+  console.log(`Source: ${result.response.inferenceSource} (onDevice=${usedOnDevice})`);
+  console.log(result.response.text());
+});
+```
+
+To override the default cloud model (`gemini-3.5-flash-lite` in
+`firebase@13.0.0+`; `gemini-2.5-flash-lite` in `firebase@12.x`) or request
+structured output from both paths, configure `inCloudParams` and
+`onDeviceParams` together:
+
+```javascript
+import { getGenerativeModel, InferenceMode, Schema } from "firebase/ai";
+
+const jsonSchema = Schema.object({
+  properties: { name: Schema.string(), species: Schema.string() },
+});
+
+const hybridModel = getGenerativeModel(ai, {
+  mode: InferenceMode.PREFER_ON_DEVICE,
+  // Cloud-hosted model settings (overrides the SDK's default cloud model)
+  inCloudParams: {
+    model: "<latest_supported_model>", // [AGENT] Replace with the latest model from https://firebase.google.com/docs/ai-logic/models.md.txt
+    generationConfig: {
+      responseMimeType: "application/json",
+      responseSchema: jsonSchema,
+    },
+  },
+  // On-device model settings (Chrome Prompt API options)
+  onDeviceParams: {
+    promptOptions: { responseConstraint: jsonSchema },
+  },
+});
+```
+
+For enum output use `Schema.enumString({ enum: [...] })` with
+`responseMimeType: "text/x.enum"` in `inCloudParams` and the same schema as the
+`responseConstraint`.

skills/firebase-ai-logic-basics/references/sdk/capabilities/search_grounding.md

@@ -127,3 +127,44 @@ if (groundingChunks != null) {
   }
 }
 ```
+
+## Web (JavaScript)
+
+Pass `{ googleSearch: {} }` in `tools`. `ai` is the instance returned by
+`getAI(app, { backend: new GoogleAIBackend() })` during setup. Insert
+`renderedContent` into the DOM as-is (it already includes its CSS).
+
+```javascript
+import { getGenerativeModel } from "firebase/ai";
+
+const model = getGenerativeModel(ai, {
+  model: "<latest_supported_model>", // [AGENT] Replace with the latest model from https://firebase.google.com/docs/ai-logic/models.md.txt
+  // Provide Google Search as a tool that the model can use to generate its response
+  tools: [{ googleSearch: {} }]
+});
+
+const result = await model.generateContent("Who won the euro 2024?");
+
+// Get the model's text response
+const text = result.response.text();
+
+// Get the grounding metadata
+const groundingMetadata = result.response.candidates?.[0]?.groundingMetadata;
+
+// REQUIRED - display Google Search suggestions
+// (renderedContent contains HTML and CSS for the search widget)
+const renderedContent = groundingMetadata?.searchEntryPoint?.renderedContent;
+if (renderedContent) {
+  // TODO(developer): render this HTML and CSS in the UI
+}
+
+// REQUIRED - display sources
+const groundingChunks = groundingMetadata?.groundingChunks;
+if (groundingChunks) {
+  for (const chunk of groundingChunks) {
+    const title = chunk.web?.title;  // for example, "uefa.com"
+    const uri = chunk.web?.uri;  // for example, "https://vertexaisearch.cloud.google.com..."
+    // TODO(developer): show sources in the UI
+  }
+}
+```

skills/firebase-ai-logic-basics/references/sdk/capabilities/streaming.md

@@ -60,3 +60,22 @@ await for (final chunk in response) {
   print(chunk.text); // Update UI incrementally
 }
 ```
+
+## Web (JavaScript)
+
+For real-time UI updates (like a typing effect), `generateContentStream`
+resolves to a result whose `stream` is an async iterable of chunks; read each
+chunk's `text()`. After the loop, `await result.response` gives the aggregated
+final response if you also need the complete text. For a chat session call
+`chat.sendMessageStream(msg)` and iterate `result.stream` the same way.
+
+```javascript
+async function streamResponse(prompt) {
+  const result = await model.generateContentStream(prompt);
+  for await (const chunk of result.stream) {
+    const chunkText = chunk.text();
+    console.log("Stream chunk:", chunkText);
+    // Update UI here
+  }
+}
+```