npm - @yuktishaalaa/yuktai - Versions diffs - 5.0.1 → 5.1.0 - Mend

@yuktishaalaa/yuktai 5.0.1 → 5.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,121 +1,93 @@
 # @yuktishaalaa/yuktai
-> Universal Next.js plugin for accessibility, AI, and data. One install brings WCAG 2.2 auto-fix, in-browser RAG, an AI agent, code generation, and an accessible data grid with Agentic AI + WebMCP — zero API keys, zero cost, works offline.
+> Universal Next.js plugin for accessibility, AI, and data. One install brings WCAG 2.2 auto-fix, in-browser RAG, an AI agent, code generation, and an accessible data grid with Agentic AI + WebMCP. Zero API keys, zero cost, works offline.
 [![npm](https://img.shields.io/npm/v/@yuktishaalaa/yuktai)](https://www.npmjs.com/package/@yuktishaalaa/yuktai)
 [![downloads](https://img.shields.io/npm/dm/@yuktishaalaa/yuktai)](https://www.npmjs.com/package/@yuktishaalaa/yuktai)
 [![license](https://img.shields.io/badge/license-ISC-brightgreen)](./LICENSE)
 [![node](https://img.shields.io/badge/node-%3E%3D18-blue)](https://nodejs.org)
+[![Next.js](https://img.shields.io/badge/Next.js-13%2B-black)](https://nextjs.org)
-[![Next.js](https://img.shields.io/badge/Next.js-16%2B-black)](https://nextjs.org)
+**7,000+ developers** have already installed yuktai. Built entirely in free time by [Sandeep Miriyala](https://github.com/sandeepmiriyala03).
-**7,000+ developers** already installed yuktai. Built entirely in free time by [Sandeep Miriyala](https://github.com/sandeepmiriyala03) with help from Claude, GPT, and Gemini.
-Live demo → [https://aksharatantra.miriyala.in/staffdirectory](https://aksharatantra.miriyala.in/staffdirectory)
+**Live demos:**
+- Staff directory: https://aksharatantra.miriyala.in/staffdirectory
+- Ratnalabala, a Telugu poetry app built on YuktAI Grid: https://ratnalabala.vercel.app/poems?view=grid
 ---
 ## The story
-I have been building web apps since 2013. In all those years the same things kept breaking on almost every website I touched. Missing ARIA labels. No keyboard navigation. Forms that senior citizens couldn't figure out. Data grids that broke on mobile. Accessibility tools that cost money. AI tools that needed API keys.
-I wanted something without any of those barriers.
+I have been building web apps since 2013. In all those years, the same things kept breaking on almost every website I touched: missing ARIA labels, no keyboard navigation, forms that senior citizens couldn't figure out, data grids that broke on mobile, accessibility tools that cost money, and AI tools that needed API keys.
-Free. Open source. One install. Works on every device. No account. No key. No server.
+I wanted something without any of those barriers. Free. Open source. One install. Works on every device. No account. No key. No server.
-So I built yuktai — one weekend and one late-night at a time. This README is the map of everything that shipped.
+So I built yuktai, one weekend and one late night at a time.
 ---
 ## What's inside
-Five modules ship in the single npm package:
+Five modules ship in a single npm package:
 | Module | Features | What it does |
 |---|---|---|
 | **1. Accessibility Engine** | 16 | WCAG 2.2 auto-fix, speak on focus, colour-blind modes, dyslexia font, skip links |
-| **2. YuktaiGrid** ⭐ NEW | 12 | Accessible data grid with 5 WCAG themes, search, sort, pagination, mobile card view |
-| **3. In-Tab RAG** | 11 | Ask questions about any page — offline, no API |
-| **4. Autonomous AI Agent** | 13 | Natural-language browser automation |
+| **2. YuktaiGrid** ⭐ | 19 | Accessible data grid with Agentic AI, WebMCP, 5 WCAG themes, English/Telugu UI |
+| **3. In-Tab RAG** | 11 | Ask questions about any page, offline, no API |
+| **4. Autonomous AI Agent** | 13 | Natural-language browser guidance |
 | **5. Vibe Coder** | 19 | Generate full Next.js projects from plain English |
-Plus Grid Assistant capabilities, Grid Agent tools, WebMCP integration, 7 custom SVG icons, and a voice + chat assistant.
 ---
-## What's new
-### v4.6.4 — YuktaiGrid Agentic AI + WebMCP
-YuktaiGrid now brings Grid UI, Grid AI Assistant, reusable Grid Tools, Agent execution, and WebMCP registration together.
-- Shared Grid Tools for Agent and WebMCP execution
-- Search grid rows
-- Count grid rows
-- Get grid columns
-- Get a row by ID
-- Highlight rows
-- Select a row
-- Open a row
-- WebMCP registration through document.modelContext
-- useYuktaiGridAgent for programmatic Grid tool execution
+## What's new in v4.6.4: YuktaiGrid Agentic AI + WebMCP
+- Shared Grid Tools used by both the Agent and WebMCP
+- Tools: search, count, columns, get row, highlight, select, open
+- WebMCP registration through `document.modelContext`
+- `useYuktaiGridAgent` hook for programmatic tool execution
 - Embedded Grid AI Assistant inside YuktaiGrid
+- English and Telugu AI UI, with English or Telugu voice input
+- Working page-size switching (10 → 20 → 50 → 100)
+- Seven inline SVG icons, no external icon dependency
-- English and Telugu AI UI
-- English voice input by default with Telugu voice-input support
-- language, inputLanguage, and embedded AI options
+**Architecture:** User → Agent / WebMCP → Grid Tools → YuktaiGrid → Data
-- Functional page-size switching such as 10 → 20 → 50 → 100
-- Inline SVG Grid icons with no external icon dependency
-- Public seven-icon package API
+---
-Architecture: User → Agent → WebMCP → YuktaiGrid → Data
+## Works on every device
-### v4.6.3
+| Device | Browser | Core features | AI engine |
+|---|---|---|---|
+| 🖥 Desktop | Chrome 147+ | ✅ All | Gemini Nano |
+| 🖥 Desktop | Firefox / Edge / Safari | ✅ All | Transformers.js |
+| 📱 Android | Chrome Mobile | ✅ All | Transformers.js |
+| 📱 iOS | Safari Mobile | ✅ All | Transformers.js |
+| 📲 PWA offline | All browsers | ✅ All | Offline after first load |
-Previous published release before the v4.6.4 Grid fixes and polish.
+yuktai picks the best AI engine automatically. Users never need to know which one is running.
 ---
 ## Install
-### Next.js 16 + React 19 (recommended)
+**Next.js 16 + React 19 (recommended)**
 ```bash
 npm install @yuktishaalaa/yuktai --legacy-peer-deps
 ```
-### Older Next.js (13, 14, 15)
+**Next.js 13, 14, 15**
 ```bash
 npm install @yuktishaalaa/yuktai
+```
+**Yarn / pnpm**
+```bash
+yarn add @yuktishaalaa/yuktai
+pnpm add @yuktishaalaa/yuktai
 ```
 Requirements: Node.js 18+, npm 8+, Next.js 13+.
@@ -124,771 +96,511 @@ Requirements: Node.js 18+, npm 8+, Next.js 13+.
 ## Quick start
-### Step 1 — `next.config.js`
+### Step 1: `next.config.js`
 ```js
 const nextConfig = {
-  transpilePackages: ["@yuktishaalaa/yuktai"],
+  transpilePackages: ["@yuktishaalaa/yuktai"],
+  async headers() {
+    return [
+      {
+        source: "/(.*)",
+        headers: [
+          // Needed for voice control and voice input
+          { key: "Permissions-Policy", value: "microphone=*, speaker=*" },
+        ],
+      },
+    ];
+  },
 };
 module.exports = nextConfig;
 ```
-### Step 2 — Client wrapper
+### Step 2: Client wrapper
 ```tsx
 // components/YuktaiClient.tsx
 "use client";
 import { useState, useEffect, type ReactNode } from "react";
 import { YuktAIWrapper } from "@yuktishaalaa/yuktai";
 export default function YuktaiClient({ children }: { children: ReactNode }) {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
-  const [mounted, setMounted] = useState(false);
-  useEffect(() => setMounted(true), []);
-  if (!mounted) return <>{children}</>;
-  return (
-    <YuktAIWrapper position="left">
-      {children}
-    </YuktAIWrapper>
-  );
+  if (!mounted) return <>{children}</>;
+  return (
+    <YuktAIWrapper position="left" showRag showAgent>
+      {children}
+    </YuktAIWrapper>
+  );
 }
 ```
-### Step 3 — `app/layout.tsx`
+### Step 3: `app/layout.tsx`
 ```tsx
 import YuktaiClient from "@/components/YuktaiClient";
 export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <body>
-        <YuktaiClient>
-          <main>{children}</main>
-        </YuktaiClient>
-      </body>
-    </html>
-  );
+  return (
+    <html lang="en">
+      <body>
+        <YuktaiClient>
+          <main>{children}</main>
+        </YuktaiClient>
+      </body>
+    </html>
+  );
 }
 ```
-That's it. Three AI-powered buttons appear on every page. Click the ♿ button bottom-right to open the accessibility panel.
----
-## Module 1 — Accessibility Engine
-Scans every element and injects missing accessibility attributes automatically.
-Covers: headings, images, forms, tables, lists, landmarks, ARIA widgets. Watches for new DOM elements via `MutationObserver`.
+That's it. Floating buttons appear on every page: ♿ opens the accessibility panel, 💬 opens "Ask this page", and the agent button opens the AI agent.
-### Features (16)
+### Wrapper props
-- WCAG 2.2 auto-fix — ARIA, roles, tabindex, scope, autocomplete
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `position` | `"left" \| "right"` | `"left"` | Which side the buttons appear on |
+| `showRag` | `boolean` | `false` | Show the 💬 Ask-this-page button |
+| `showAgent` | `boolean` | `false` | Show the AI agent button |
+| `config` | `Partial<A11yConfig>` | `undefined` | Accessibility config overrides |
+| `children` | `ReactNode` | required | Your app content |
-- Speak on focus — browser speech synthesis
-- Voice control — say commands to navigate
-- High contrast · Dark mode · Reduce motion · Large targets (44×44)
-- Colour-blind modes — Deuteranopia, Protanopia, Tritanopia, Greyscale
+---
-- Dyslexia font — Atkinson Hyperlegible (research-backed)
+## Module 1: Accessibility Engine
-- Local font picker, font scaling 80–130%
+Scans every element and injects missing accessibility attributes automatically. Covers headings, images, forms, tables, lists, landmarks, and ARIA widgets. Watches for new DOM elements with `MutationObserver`.
-- Audit badge — WCAG score 0–100 (localhost only)
+**Features**
-- Skip links, focus trap, preference persistence, reset
+- WCAG 2.2 auto-fix: ARIA, roles, tabindex, scope, autocomplete, alt text
+- Speak on focus using browser SpeechSynthesis
+- Voice control using the SpeechRecognition API
+- Visual alerts for deaf and hard-of-hearing users
+- High contrast, dark mode, reduce motion, large targets (44×44)
+- Colour-blind modes: Deuteranopia, Protanopia, Tritanopia, Greyscale
+- Dyslexia font: Atkinson Hyperlegible
+- Local font picker and font scaling from 80% to 130%
+- Audit badge with a WCAG score from 0 to 100 (localhost only)
+- Skip links, focus trap, saved preferences, reset
-### Direct API
+**Direct API**
 ```ts
+import { wcagPlugin, type A11yConfig } from "@yuktishaalaa/yuktai";
-import { wcagPlugin } from "@yuktishaalaa/yuktai";
-// Apply fixes
-const report = wcagPlugin.applyFixes({
-  enabled:       true,
-  highContrast:  false,
-  darkMode:      false,
-  reduceMotion:  false,
-  largeTargets:  false,
-  speechEnabled: false,
-  colorBlindMode:"none",
-  autoFix:       true,
-});
+const config: A11yConfig = {
+  enabled: true,
+  highContrast: false,
+  darkMode: false,
+  reduceMotion: false,
+  largeTargets: false,
+  speechEnabled: false,
+  colorBlindMode: "none", // none | deuteranopia | protanopia | tritanopia | achromatopsia
+  autoFix: true,
+  showPreferencePanel: true,
+  showSkipLinks: true,
+  showAuditBadge: false, // dev only (localhost)
+  fontSizeMultiplier: 1,
+  timeoutWarning: 0, // seconds, 0 = off
+};
-console.log(report.fixed);   // number of fixes applied
+const report = wcagPlugin.applyFixes(config);
+console.log(report.fixed); // number of fixes applied
+console.log(report.score); // 0–100
+```
-console.log(report.score);   // 0–100
+### WCAG coverage
-```
+| Standard | Criteria | Examples |
+|---|---|---|
+| WCAG 2.0 | 19 | Alt text, roles, labels, tables, landmarks, focus |
+| WCAG 2.1 | 7 | Touch targets, reflow, motion, orientation |
+| WCAG 2.2 | 3 | Focus appearance, target size, timeout warning |
+| Beyond WCAG | Extras | Speech, visual alerts, colour-blind modes, dyslexia font, audit score |
 ---
-## Module 2 — YuktaiGrid ⭐
+## Module 2: YuktaiGrid ⭐
-An accessible data grid built for Next.js. Handles small tables and large datasets. Works with any API. Ships with the 5 accessibility themes.
+An accessible data grid for Next.js, with an embedded AI assistant, agent tools, and WebMCP support.
-### Usage
+### Basic usage
 ```tsx
 "use client";
 import { YuktaiGrid } from "@yuktishaalaa/yuktai";
 const data = [
-{ id: 1, name: "Sandeep", role: "Developer", salary: 85000 },
-{ id: 2, name: "Priya", role: "Designer", salary: 90000 },
+  { id: 1, name: "Sandeep", role: "Developer", salary: 85000 },
+  { id: 2, name: "Priya", role: "Designer", salary: 90000 },
 ];
 export default function EmployeesPage() {
+  return (
+    <YuktaiGrid
+      data={data}
+      rowKey="id"
+      columns={[
+        { key: "name", label: "Name", sortable: true },
+        { key: "role", label: "Role" },
+        { key: "salary", label: "Salary", type: "number", align: "right" },
+      ]}
+      theme="default" // default | high-contrast | dark | color-blind | dyslexia
+      locale="en-US" // en-US | te-IN
+      view="auto" // auto | table | card
+      search
+      ai
+      pagination={{
+        pageSize: 20,
+        showSizeChanger: true,
+        sizeOptions: [10, 20, 50, 100],
+      }}
+    />
+  );
+}
+```
-return (
-\<YuktaiGrid
-  data={data}
-  columns={[
-    { key: "name", label: "Name", sortable: true },
-    { key: "role", label: "Role" },
-    { key: "salary", label: "Salary", type: "number", align: "right" },
-  ]}
-  theme="default"                         // default | high-contrast | dark | color-blind | dyslexia
-  locale="en-US"                          // en-US | te-IN
-  search={true}                           // real-time filtering
+### Grid features
-  ai={true}                               // embedded Grid AI Assistant
+- Real-time search, column sorting, client-side pagination with page-size switching
+- Mobile card view below a configurable breakpoint
+- Loading and empty states
+- 5 WCAG themes
+- Row selection, custom cell render, `rowKey`
+- Row highlighting with optional auto-scroll
+- Keyboard navigation, ARIA grid semantics, 44×44 targets
+- English and Telugu UI
+- Embedded Grid AI Assistant with voice and chat
-  view="auto"                             // auto | table | card
+### Grid AI Assistant
-  pagination={{
-    pageSize: 20,
-    showSizeChanger: true,
-    sizeOptions: [10, 20, 50, 100],
-  }}
+Runs embedded in the grid or as a standalone component. Intent parsing runs locally and supports search, sort, count, highest, lowest, average, total, and row lookup.
+```tsx
+<YuktaiGridAI
+  data={data}
+  columns={columns}
+  onSearch={handleSearch}
+  onSort={handleSort}
+  language="te-IN" // AI UI and responses: en-US | te-IN
+  inputLanguage="te-IN" // voice input: en-US | te-IN
+  embedded
 />
-);
-}
 ```
-### Grid features
+Voice recognition depends on browser Web Speech API support.
-- Search bar with inline SVG icon
+### Agent tools
-- Sort — click a column header to toggle ascending / descending
+Generic, reusable grid operations shared by the Agent and WebMCP:
-- Functional client-side pagination
+```ts
+import {
+  searchGrid,
+  countGrid,
+  getColumns,
+  getRow,
+  highlightRows,
+  selectRow,
+  openRow,
+} from "@yuktishaalaa/yuktai";
+```
-- Configurable page-size switching such as 10, 20, 50, 100
+Run tools programmatically:
-- Mobile card view below the configured breakpoint
+```tsx
+import { useYuktaiGridAgent, type GridAgentTool } from "@yuktishaalaa/yuktai";
-- Loading and empty states
+const tools: GridAgentTool[] = [
+  {
+    name: "search",
+    description: "Search grid rows by a text query",
+    execute: async ({ query }) => searchGrid(data, query),
+  },
+];
-- 5 WCAG themes
+const { executeTool, loading } = useYuktaiGridAgent({ tools });
+```
-- Row selection, custom render, and rowKey
+**Design principle:** keep generic tools in the package and put app-specific rules in your app.
-- Row highlighting and optional auto-scroll to highlighted rows
+```text
+Generic YuktAI tools  +  Your domain rules  =  Your application agent
+```
-- Embedded Grid AI Assistant
+### WebMCP
-- English and Telugu Grid UI
+Exposes grid tools to browser AI agents through `document.modelContext`, so agents call real operations instead of guessing from the DOM. Registration is invisible in the UI.
+```tsx
+<YuktaiGrid
+  data={rows}
+  columns={columns}
+  ai
+  webmcp
+  toolName="my_grid"
+  toolDescriptions={TOOL_DESCRIPTIONS}
+  onWebMCPStatusChange={setStatus} // unsupported | registering | ready | partial | error
+/>
+```
-- Inline SVG search, sort, selection, and pagination icons
+Or standalone:
-- No external icon dependency
+```tsx
+<YuktaiGridWebMCP data={data} columns={columns} />
+```
-### Handling large datasets (100K, 200K, 300K rows)
+WebMCP is not available in every browser, so always handle the `unsupported` status gracefully.
-**Client-side pagination handles a few thousand rows well.** For anything larger, use **server-side pagination** — fetch only the page you need.
+### Large datasets (100K+ rows)
-Here's the pattern with a Next.js API proxy that also solves CORS.
+Client-side pagination handles a few thousand rows well. For anything larger, use server-side pagination and disable the grid's built-in search and pagination.
-**`src/app/api/employees/route.ts`** — the proxy:
+`src/app/api/employees/route.ts`:
 ```ts
 import { NextRequest, NextResponse } from "next/server";
 let cachedData: any[] | null = null;
 let cacheTime = 0;
 const TTL_MS = 60_000;
 async function fetchAll(): Promise<any[]> {
-  const now = Date.now();
-  if (cachedData && now - cacheTime < TTL_MS) return cachedData;
-  const res  = await fetch("https://your-api.com/employees", { cache: "no-store" });
-  const json = await res.json();
-  cachedData = Array.isArray(json) ? json : (json.employees ?? json.data ?? []);
-  cacheTime  = now;
-  return cachedData;
+  const now = Date.now();
+  if (cachedData && now - cacheTime < TTL_MS) return cachedData;
+  const res = await fetch("https://your-api.com/employees", { cache: "no-store" });
+  const json = await res.json();
+  cachedData = Array.isArray(json) ? json : json.employees ?? json.data ?? [];
+  cacheTime = now;
+  return cachedData;
 }
 export async function GET(req: NextRequest) {
-  const p = req.nextUrl.searchParams;
-  const page     = Math.max(1, parseInt(p.get("page")     || "1"));
-  const pageSize = Math.max(1, parseInt(p.get("pageSize") || "5000"));
-  const search   = (p.get("search") || "").toLowerCase().trim();
-  const all      = await fetchAll();
-  const filtered = search
-    ? all.filter(r => Object.values(r).some(v => String(v).toLowerCase().includes(search)))
-    : all;
-  const total = filtered.length;
-  const rows  = filtered.slice((page - 1) * pageSize, page * pageSize);
-  return NextResponse.json({
-    rows,
-    pagination: { page, pageSize, totalRows: total, totalPages: Math.ceil(total / pageSize) },
-  });
+  const p = req.nextUrl.searchParams;
+  const page = Math.max(1, parseInt(p.get("page") || "1"));
+  const pageSize = Math.max(1, parseInt(p.get("pageSize") || "5000"));
+  const search = (p.get("search") || "").toLowerCase().trim();
+  const all = await fetchAll();
+  const filtered = search
+    ? all.filter((r) => Object.values(r).some((v) => String(v).toLowerCase().includes(search)))
+    : all;
+  const total = filtered.length;
+  const rows = filtered.slice((page - 1) * pageSize, page * pageSize);
+  return NextResponse.json({
+    rows,
+    pagination: { page, pageSize, totalRows: total, totalPages: Math.ceil(total / pageSize) },
+  });
 }
 ```
-**Page — call the paginated API and disable the grid's built-in pagination:**
+Page:
 ```tsx
-const [apiResp, setApiResp]     = useState<any>(null);
-const [currentPage, setPage]    = useState(1);
+const [apiResp, setApiResp] = useState<any>(null);
+const [currentPage, setPage] = useState(1);
 useEffect(() => {
-  fetch(`/api/employees?page=${currentPage}&pageSize=5000`)
-    .then(r => r.json())
-    .then(setApiResp);
+  fetch(`/api/employees?page=${currentPage}&pageSize=5000`)
+    .then((r) => r.json())
+    .then(setApiResp);
 }, [currentPage]);
 <YuktaiGrid
-  data={apiResp?.rows ?? []}
-  columns={columns}
-  search={false}         // disable — we handle search server-side
-  pagination={false}     // disable — we handle pagination server-side
-  loading={!apiResp}
-/>
+  data={apiResp?.rows ?? []}
+  columns={columns}
+  search={false} // handled server-side
+  pagination={false} // handled server-side
+  loading={!apiResp}
+/>;
 ```
-Then render your own pagination bar backed by `apiResp.pagination`. This pattern works for 100K, 200K, 300K rows — the browser only ever holds 5,000 rows in memory.
+Render your own pagination bar from `apiResp.pagination`. The browser only ever holds one page in memory.
 ---
----
+## Showcase: Ratnalabala (Telugu poetry)
-## Grid Agentic AI + WebMCP
-YuktaiGrid exposes reusable Grid operations so an Agent can work with grid data through a shared tool layer and WebMCP.
-### Grid tools
-```ts
-import {
-searchGrid,
-countGrid,
-getColumns,
-getRow,
-highlightRows,
-selectRow,
-openRow,
-} from "@yuktishaalaa/yuktai";
-```
-These operations form the common execution layer for programmatic Agent tools and WebMCP.
-### Agent execution
-```tsx
-import {
-useYuktaiGridAgent,
-type GridAgentTool,
-} from "@yuktishaalaa/yuktai";
-const tools: GridAgentTool[] = [
-{
-name: "search",
-description: "Search grid rows",
-execute: async ({ query }) => {
-return { query };
-},
-},
-];
-const { executeTool, loading } =
-useYuktaiGridAgent({ tools });
-```
-### WebMCP
-```tsx
-import {
-YuktaiGridWebMCP,
-} from "@yuktishaalaa/yuktai";
-<YuktaiGridWebMCP
-data={data}
-columns={columns}
-/>
+[Ratnalabala](https://ratnalabala.vercel.app/poems?view=grid) shows that an agentic grid is more than a chatbot next to a table. Users type or speak in Telugu, and the grid acts.
+| User says | Agent action |
+|---|---|
+| `ఎన్ని పద్యాలు` (how many poems) | `count` → "మొత్తం 36 పద్యాలు ఉన్నాయి." |
+| `గర్వం తెరువు` (open "Garvam") | `open` |
+| `"బుద్ధి" ఉన్న పద్యాలు` (poems with "buddhi") | `search` + highlight |
+| `అక్షర క్రమంలో` (alphabetical) | `sort(title, asc)` |
+| `ఈరోజు పద్యం` (poem of the day) | custom rule + highlight |
+**Stack:** Next.js · React + TypeScript · MUI · YuktAI Grid · FastAPI (Python) · PostgreSQL on Neon · Vercel · Web Speech API · WebMCP
+```text
+PostgreSQL → FastAPI → Next.js API proxy → Ratnalabala UI → YuktAI Grid
+                                                              ├── Agent
+                                                              └── WebMCP
 ```
-WebMCP registration is invisible in the UI and uses document.modelContext when available.
-### Embedded Grid AI Assistant
 ```tsx
-<YuktaiGrid
-data={data}
-columns={columns}
-locale="te-IN"
-ai={true}
-pagination={{
-pageSize: 20,
-showSizeChanger: true,
-sizeOptions: [10, 20, 50, 100],
-}}
+<YuktaiGrid<PoemRow>
+  data={rows}
+  columns={COLUMNS}
+  rowKey="id"
+  locale="te-IN"
+  inputLanguage="te-IN"
+  customRules={POEM_RULES}
+  search
+  highlightIds={highlightIds}
+  autoScrollToHighlight
+  onRowClick={(row) => onOpenPoem(row.title)}
+  ai
+  webmcp
+  toolName="ratnalabala_poems"
+  toolDescriptions={TOOL_DESCRIPTIONS}
+  onWebMCPStatusChange={setWebmcp}
 />
 ```
-Grid AI supports:
-- language="en-US" or language="te-IN" for AI UI and responses
-- inputLanguage="en-US" or inputLanguage="te-IN" for voice input
-- embedded mode for rendering AI inside the Grid
-- Local intent parsing for search, sort, count, highest, lowest, average, total, and lookup
 ---
-## Module 3 — In-Tab RAG (Ask This Page)
-Retrieval-Augmented Generation running entirely in the browser. Extracts semantic chunks from the current DOM, embeds them, finds the best match for the user's question, and answers — offline, no API key.
-### Features (11)
+## Module 3: In-Tab RAG (Ask This Page)
-- Ask any question about any page
+Retrieval-Augmented Generation running entirely in the browser. It extracts text chunks from the current page, embeds them, finds the best match for the question, and answers. Offline, no API key.
-- Gemini Nano on desktop Chrome — zero download, zero API
-- Transformers.js on mobile — 30 MB one-time model load
-- Auto engine detection and switching
-- Works offline after first load
-- q4 quantization on mobile (32-bit → 4-bit weights)
-- `flan-t5-small` for full-sentence answers
-- Cosine similarity semantic search
-- Deduped DOM text extraction
+| Device | Engine | How it works |
+|---|---|---|
+| Desktop Chrome with Gemini Nano | `window.LanguageModel` | Page text sent as context, instant answer |
+| Mobile and all other browsers | Transformers.js | Embeddings + `flan-t5-small`, q4 quantized |
-### What I learned
+- About 30 MB one-time model download on mobile, cached in IndexedDB
+- Works fully offline after first load
+- All processing on device, no data sent anywhere
-The hardest part was mobile. Transformers.js kept crashing on iOS Safari with out-of-memory errors. Learning about quantization — same model, 75% smaller — fixed it. DistilBERT gives short useless spans; flan-t5-small gives real sentences. None of that was in any tutorial. Found on a Saturday by breaking things until something worked.
+**What I learned:** Transformers.js kept crashing on iOS Safari with out-of-memory errors. Quantization (same model, 75% smaller) fixed it. DistilBERT gave short, useless spans; `flan-t5-small` gives real sentences.
 ---
-## Module 4 — Autonomous AI Agent
-User types a goal in plain English. Yuktai reads the DOM, finds the right elements, plans steps, and highlights what to do.
-### Features (13)
-- Plain-English goal input
+## Module 4: Autonomous AI Agent
-- Reads full page DOM — 9 traversal strategies
-- Scans all form fields — 11 label strategies
+Type a goal in plain English. yuktai reads the page, finds the right elements, plans the steps, and highlights what to do.
+- 9 DOM traversal strategies and 11 form-label strategies
 - Works on static HTML, React, WordPress, and old government portals
+- Gemini Nano planning on desktop, Transformers.js on mobile, rule-based fallback
+- Highlights target fields, scrolls to sections, shows a numbered plan, handles iframes
-- Gemini Nano planning on desktop, Transformers.js on mobile
-- Rule-based fallback if AI fails
-- Highlights target field with teal outline
-- Scrolls to relevant section by keyword
-- Numbered step-by-step plan
-- Handles iframes
-The 11 label strategies came from real websites — old government portals put labels in the previous table cell, modern apps use `aria-label`, static pages use `placeholder`. Every strategy solved a problem I had actually hit.
+Every label strategy came from a real website: old portals put labels in the previous table cell, modern apps use `aria-label`, static pages use `placeholder`.
 ---
-## Module 5 — Vibe Coder
-Type a business requirement. Yuktai generates a full Next.js 16 project as a downloadable ZIP.
-### Features (19)
+## Module 5: Vibe Coder
-- Detects website type (12 types), pages needed (21 types), features (14 types)
-- Detects theme colour (8), extracts site name
+Type a business requirement and download a full Next.js 16 project as a ZIP.
+- Detects website type (12), pages (21), features (14), theme colour (8), and site name
 - Preview before generating
+- TypeScript, Tailwind + CSS Modules, mobile responsive
+- Navbar, Footer, Home, About, Contact, Services, Pricing, Auth, Dashboard
+- `npm run dev` works immediately
-- Full Next.js 16 project — Tailwind + CSS Modules, TypeScript, mobile responsive
-- Navbar, Footer, Home, About, Contact, Services, Pricing, Auth, Dashboard pages
-- Downloads as ZIP · `npm run dev` works immediately
-- Pure templates — no AI writes the code
-No AI writes a single line. Pure template engineering. Same reusable-utility thinking from 2013 jQuery — now generating entire Next.js projects.
+No AI writes the code. It's pure template engineering.
 ---
-## Grid AI Assistant — Voice + Chat
-The Grid AI Assistant can run embedded inside YuktaiGrid or as a standalone component.
-Voice input uses the browser Web Speech API. AI responses can be spoken with SpeechSynthesis. Intent parsing runs locally for the supported Grid operations.
-Supports:
-- Search
-- Sort
-- Count
-- Highest / maximum
-- Lowest / minimum
+## Gemini Nano setup (desktop Chrome, one time)
-- Average
+Needed only for Gemini Nano features on desktop Chrome. Mobile and other browsers use Transformers.js automatically.
-- Total
+1. Open `chrome://flags` and enable: Prompt API for Gemini Nano, Summarization API, Writer API, Rewriter API, Translation API.
+2. Click **Relaunch**.
+3. Open `chrome://components`, find **Optimization Guide On Device Model**, and click **Check for update**.
+4. Refresh your page. AI features unlock automatically.
-- Row lookup
-- English and Telugu AI UI
-- English voice input by default
-- Telugu voice input with inputLanguage="te-IN"
-Example:
-```tsx
-<YuktaiGridAI
-data={data}
-columns={columns}
-onSearch={handleSearch}
-onSort={handleSort}
-language="te-IN"
-inputLanguage="en-US"
-embedded
-/>
-```
+**Gemini Nano features:** plain-English rewriting, 3-sentence page summary, AI-generated ARIA labels, page translation in 18 languages.
-Voice recognition depends on browser Web Speech API support.
+> Chrome 147 moved the APIs from `window.ai` to standalone globals such as `window.LanguageModel`. yuktai supports both.
 ---
-## Icon library
+## Icons
-7 custom SVG icons. Zero external dependency. All seven remain part of the public package API.
+Seven custom SVG icons with no external dependency.
 ```tsx
 import {
-  SearchIcon,
-  SortUpIcon,
-  SortDownIcon,
-  ChevronLeftIcon,
-  ChevronRightIcon,
-  CheckIcon,
-  CloseIcon,
+  SearchIcon,
+  SortUpIcon,
+  SortDownIcon,
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  CheckIcon,
+  CloseIcon,
 } from "@yuktishaalaa/yuktai";
-<SearchIcon        size={20} />
-<SortUpIcon        size={20} color="#0D9488" />
-<CheckIcon         size={20} color="#10b981" label="Task complete" />
-<CloseIcon         size={20} color="#dc2626" />
-<ChevronLeftIcon   size={24} label="Previous" />
-<ChevronRightIcon  size={24} label="Next" />
-```
-Props: `size` (default 20), `color` (default `currentColor`), `strokeWidth` (default 2.5), `label` (adds ARIA — decorative if omitted).
----
-## Gemini Nano (Chrome 147+)
-- Plain-English mode — rewrites complex text
-- Summarise page — 3-sentence summary
-- Smart ARIA labels — AI generates labels
-- Translate page — 18 languages
-- Chrome 147+ standalone globals (`window.LanguageModel`)
-- Fallback to old `window.ai` namespace
-Chrome 147 silently removed `window.ai` and moved everything to standalone globals. Debugged for an evening before finding it in the release notes.
----
-## Technical (17 features)
-Zero API keys · Zero cost · Zero telemetry · Works on all browsers · Works on mobile (Android + iOS) · Works offline after first load · PWA compatible · Next.js 16 compatible · React 19 compatible · TypeScript throughout · SSR safe (no window errors) · Escape closes all panels · Each panel closes others · `data-yuktai-panel` — never reads own UI · Three stacked FAB buttons · Mobile full-screen panels · Tablet responsive · `showRag`, `showAgent`, `position` props.
----
-## Configuration
-```ts
-import { wcagPlugin, A11yConfig } from "@yuktishaalaa/yuktai";
-const config: A11yConfig = {
-  enabled:             true,   // required
-  highContrast:        false,
-  darkMode:            false,
-  reduceMotion:        false,
-  largeTargets:        false,
-  speechEnabled:       false,
-  colorBlindMode:      "none", // none | deuteranopia | protanopia | tritanopia | achromatopsia
-  autoFix:             true,
-  showPreferencePanel: true,
-  showSkipLinks:       true,
-  showAuditBadge:      false,  // dev only (localhost)
-  fontSizeMultiplier:  1,
-  timeoutWarning:      0,      // seconds (0 = off)
-};
-await wcagPlugin.execute(config);
+<SearchIcon size={20} />
+<CheckIcon size={20} color="#10b981" label="Task complete" />
 ```
----
-## WCAG coverage
-| Standard | Criteria covered |
-|---|---|
-| WCAG 2.0 | 19 criteria |
-| WCAG 2.1 | 7 criteria |
-| WCAG 2.2 | 3 criteria (focus appearance, target size, timeout) |
-| Beyond WCAG | SpeechSynthesis, visual alerts, keyboard cheatsheet, audit score, colour-blind modes, dyslexia font |
+Props: `size` (default 20), `color` (default `currentColor`), `strokeWidth` (default 2.5), `label` (adds ARIA; decorative if omitted).
 ---
 ## Design principles
-- **Zero id attributes** — no injected node ever gets an `id`. Tracked via module-level JavaScript references. Never collides with host app ids.
-- **Zero API keys** — runs entirely in the browser. No external calls, no telemetry, no cost.
-- **Zero framework lock-in** — `core/renderer.ts` has no framework imports. Works in Node.js, browsers, and test environments.
-- **Honest limits** — client-side grid pagination works for a few thousand rows. Beyond that, use server-side pagination (pattern shown above).
+- **Zero API keys, zero cost, zero telemetry.** Everything runs in the browser.
+- **Zero injected ids.** Injected nodes are tracked by JavaScript references, so they never collide with your app's ids.
+- **Zero framework lock-in.** `core/renderer.ts` has no framework imports.
+- **Never reads its own UI.** Panels are marked with `data-yuktai-panel`.
+- **SSR safe.** No `window` errors on the server.
+- **Honest limits.** Client-side pagination is for a few thousand rows; use server-side beyond that.
 ---
 ## Compatibility
-### Next.js versions
-| Version | Supported |
+| | Supported |
 |---|---|
-| Next.js 16 | ✅ |
-| Next.js 15 | ✅ |
-| Next.js 14 | ✅ |
-| Next.js 13 | ✅ |
-### React versions
-| Version | Supported | Install flag |
-|---|---|---|
-| React 19 | ✅ | `--legacy-peer-deps` |
-| React 18 | ✅ | none |
-| React 17 | ✅ | none |
-### Browsers
-Chrome 90+ · Firefox 90+ · Safari 15+ · Edge 90+ · Samsung Internet 14+
+| Next.js | 13, 14, 15, 16 |
+| React | 17, 18, 19 (19 needs `--legacy-peer-deps`) |
+| Node.js | 18+ |
+| Browsers | Chrome 90+, Firefox 90+, Safari 15+, Edge 90+, Samsung Internet 14+ |
 ---
 ## Roadmap
-Shipped: v4.6.4 — YuktaiGrid Agentic AI + WebMCP integration, embedded Grid AI Assistant, English/Telugu Grid UI, functional page-size switching, and Grid icon polish.
+- **Shipped (v4.6.4):** YuktaiGrid Agentic AI + WebMCP, embedded Grid AI Assistant, English/Telugu UI, page-size switching, icon polish
+- **Next:** more Grid Agent tools and WebMCP capabilities, multilingual RAG (Telugu, Hindi, Tamil, Bengali)
+- **Later:** RTL support, richer browser-native AI, multimodal grid experiences
+---
-Next: expand Grid Agent tools and WebMCP capabilities.
+## Contributing
-Long term: richer browser-native AI and multimodal Grid experiences.
+Issues and pull requests are welcome at [github.com/sandeepmiriyala03/yuktai](https://github.com/sandeepmiriyala03/yuktai). For security issues, see [SECURITY.md](./SECURITY.md).
 ---
 ## Links
-- npm — [@yuktishaalaa/yuktai](https://www.npmjs.com/package/@yuktishaalaa/yuktai)
-- GitHub — [sandeepmiriyala03/yuktai](https://github.com/sandeepmiriyala03/yuktai)
-- Live demo — [aksharatantra.vercel.app](https://aksharatantra.vercel.app)
+- npm: [@yuktishaalaa/yuktai](https://www.npmjs.com/package/@yuktishaalaa/yuktai)
+- GitHub: [sandeepmiriyala03/yuktai](https://github.com/sandeepmiriyala03/yuktai)
+- Demo: [aksharatantra.miriyala.in/staffdirectory](https://aksharatantra.miriyala.in/staffdirectory)
+- Showcase: [ratnalabala.vercel.app](https://ratnalabala.vercel.app/poems?view=grid)
 ---
 ## License
-ISC © Sandeep Miriyala — [Yuktishaalaa AI Lab](https://github.com/sandeepmiriyala03)
+ISC © Sandeep Miriyala, [Yuktishaalaa AI Lab](https://github.com/sandeepmiriyala03)
-Built in free time. With help from Claude, GPT, and Gemini for learning — but every line written, every bug fixed, every decision made by me.
+Built in free time, with help from Claude, GPT, and Gemini for learning. Every line written, every bug fixed, and every decision made by me.
-Free forever. Open source.
+**Free forever. Open source. Built for every user.** 🏺