marathi-transliterate 0.0.0-stage → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ketan Katore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+# marathi-transliterate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Zero-dependency, offline-first Plain JavaScript phonetic transliteration library for Marathi (Devanagari script).**
+> Converts colloquial English typing to authentic Marathi (e.g., `sakhar` → `साखर`, `kanda` → `कांदा`, `batata` → `बटाटा`) with single-step backspace undo and interactive input attachment.
+
+[![npm version](https://img.shields.io/npm/v/marathi-transliterate.svg)](https://www.npmjs.com/package/marathi-transliterate)
+[![license](https://img.shields.io/npm/l/marathi-transliterate.svg)](https://github.com/Ketan-K/marathi-transliterate/blob/main/LICENSE)
+
+---
+
+## Why marathi-transliterate?
+
+Most existing Sanskrit/IAST transliteration libraries convert `sakhar` to **सखर** or `batata` to **बतत** because they require scholarly transliteration (`saakhar`, `bataataa`).
+
+In everyday reality, people in Maharashtra type phonetically:
+- `sakhar` → **साखर**
+- `kanda` → **कांदा**
+- `batata` → **बटाटा**
+- `mith` → **मीठ**
+- `tel` → **तेल**
+- `gahu` → **गहू**
+- `tandul` → **तांदूळ**
+- `pohe` → **पोहे**
+- `rava` → **रवा**
+- `besan` → **बेसन**
+- `toor dal` → **तूर डाळ**
+- `chaha` → **चहा**
+- `dnyaneshwar` → **ज्ञानेश्वर**
+- `patil` → **पाटील**
+
+`marathi-transliterate` is built specifically for modern Marathi phonetic typing:
+- **Zero dependencies**: Pure JavaScript, ~15 KB.
+- **Offline first**: Works 100% offline without requiring internet or API calls.
+- **Framework agnostic**: Works in Plain HTML/JS, Node.js, React, Vue, Svelte, Angular, Electron.
+- **Interactive DOM integration**: Attach directly to any `<input>` or `<textarea>` with Space-to-convert, Backspace-to-undo, and `Ctrl+M` toggle.
+
+---
+
+## Installation
+
+```bash
+npm install marathi-transliterate
+```
+
+---
+
+## Quick Start
+
+### 1. Plain JavaScript / Node.js
+
+```javascript
+import { transliterate, transliterateWord } from 'marathi-transliterate';
+
+// Single word transliteration
+transliterateWord('sakhar');  // → 'साखर'
+transliterateWord('kanda');   // → 'कांदा'
+transliterateWord('batata');  // → 'बटाटा'
+transliterateWord('namaskar'); // → 'नमस्कार'
+
+// Full sentence transliteration (numbers and symbols preserved)
+transliterate('sakhar 1 kilo ani kanda 2 kg');
+// → 'साखर 1 किलो आणि कांदा 2 कि.ग्रॅ.'
+```
+
+---
+
+### 2. Attach to any HTML `<input>` or `<textarea>`
+
+Easily enable Marathi phonetic typing on any input element:
+
+```html
+<input type="text" id="product-name" placeholder="उदा. sakhar टाइप करा..." />
+
+<script type="module">
+  import { attachDevanagari } from 'marathi-transliterate';
+
+  const inputEl = document.getElementById('product-name');
+
+  // Attach Devanagari typing
+  const handler = attachDevanagari(inputEl, {
+    defaultEnabled: true,
+    enableShortcut: true, // Ctrl+M or Cmd+M toggles Marathi/English
+    onToggle: (enabled) => console.log('Marathi typing:', enabled)
+  });
+
+  // To clean up listeners when unmounting:
+  // handler.detach();
+</script>
+```
+
+#### Interactive Smart Suggesting:
+As you type (e.g. `sakhar`), a floating suggestion popup appears with ranked candidates:
+- **`Space` or `Enter`**: Automatically selects the top recommended candidate (`साखर`).
+- **`1`, `2`, `3`, `4`, `5`**: Press any digit key to select that candidate immediately.
+- **`Arrow Down / Up`**: Navigate through candidate suggestions.
+- **`Esc`**: Dismisses the suggestion popup without converting.
+- **`Backspace`**: Undoes the transliteration back to English.
+- **`Ctrl+M` (or `Cmd+M`)**: Toggles Marathi and English typing mode on the fly.
+
+---
+
+### 3. Usage in React
+
+Use a standard React `ref` or `useEffect`:
+
+```jsx
+import React, { useRef, useEffect, useState } from 'react';
+import { attachDevanagari } from 'marathi-transliterate';
+
+export function MarathiInput() {
+  const inputRef = useRef(null);
+  const [isMarathi, setIsMarathi] = useState(true);
+
+  useEffect(() => {
+    if (!inputRef.current) return;
+
+    const handler = attachDevanagari(inputRef.current, {
+      defaultEnabled: true,
+      onToggle: (enabled) => setIsMarathi(enabled)
+    });
+
+    return () => handler.detach();
+  }, []);
+
+  return (
+    <div style={{ position: 'relative' }}>
+      <input ref={inputRef} placeholder="वस्तूचे नाव टाइप करा..." />
+      <span style={{ fontSize: '12px', color: isMarathi ? 'green' : 'gray' }}>
+        {isMarathi ? 'मराठी (Ctrl+M)' : 'English (Ctrl+M)'}
+      </span>
+    </div>
+  );
+}
+```
+
+---
+
+## API Reference
+
+### `transliterateWord(word: string): string`
+Converts a single English word into Marathi Devanagari script.
+
+### `transliterate(text: string): string`
+Converts full text, sentences, or paragraphs into Marathi while preserving numbers, whitespace, and punctuation.
+
+### `getSuggestions(word: string): string[]`
+Returns candidate phonetic variations for a given word.
+
+### `attachDevanagari(element, options): Handler`
+Attaches keyboard listeners to an `<input>` or `<textarea>` element.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `defaultEnabled` | `boolean` | `true` | Whether Marathi typing starts enabled |
+| `enableShortcut` | `boolean` | `true` | Enables `Ctrl+M` / `Cmd+M` toggle |
+| `triggerKeys` | `string[]` | `[' ', 'Enter', ',', '.']` | Keys that trigger transliteration |
+| `onToggle` | `Function` | `undefined` | Callback `(isEnabled) => void` |
+| `onTransliterate` | `Function` | `undefined` | Callback `({ original, transliterated }) => void` |
+
+**Returns:**
+```typescript
+{
+  detach: () => void;
+  setEnabled: (val: boolean) => void;
+  isEnabled: () => boolean;
+  toggle: () => boolean;
+}
+```
+
+---
+
+## License
+
+MIT © Ketan Katore

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "marathi-transliterate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.1",
+  "description": "Zero-dependency, offline-first Marathi / Devanagari phonetic transliteration library. Converts English typing to Marathi (e.g. sakhar -> साखर) seamlessly in plain JS, Node.js, and frontend frameworks.",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./dom": "./src/dom.js",
+    "./dictionary": "./src/dictionary.js"
+  },
+  "scripts": {
+    "test": "node tests/transliterate.test.js"
+  },
+  "keywords": [
+    "marathi",
+    "transliterate",
+    "transliteration",
+    "devanagari",
+    "indic",
+    "marathi-typing",
+    "input-tools",
+    "ime",
+    "offline"
+  ],
+  "author": "Ketan Katore",
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ketan-K/marathi-transliterate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ketan-K/marathi-transliterate/issues"
+  },
+  "homepage": "https://github.com/Ketan-K/marathi-transliterate#readme"
+}

package/src/cache.js

@@ -0,0 +1,87 @@
+/**
+ * Cache and asynchronous online enrichment for Marathi transliteration.
+ */
+
+const MEMORY_CACHE = new Map();
+const LOCAL_STORAGE_KEY = 'marathi_transliterate_cache_v1';
+
+// Load initial persistent cache if available
+function initStorage() {
+  if (typeof window !== 'undefined' && window.localStorage) {
+    try {
+      const stored = localStorage.getItem(LOCAL_STORAGE_KEY);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        for (const [k, v] of Object.entries(parsed)) {
+          MEMORY_CACHE.set(k.toLowerCase(), v);
+        }
+      }
+    } catch {
+      // Ignore storage errors
+    }
+  }
+}
+
+initStorage();
+
+export function getCachedWord(word) {
+  if (!word) return null;
+  return MEMORY_CACHE.get(word.toLowerCase().trim()) || null;
+}
+
+export function setCachedWord(word, transliteratedList) {
+  if (!word || !transliteratedList) return;
+  const key = word.toLowerCase().trim();
+  const list = Array.isArray(transliteratedList) ? transliteratedList : [transliteratedList];
+  MEMORY_CACHE.set(key, list);
+
+  if (typeof window !== 'undefined' && window.localStorage) {
+    try {
+      const obj = {};
+      MEMORY_CACHE.forEach((v, k) => {
+        obj[k] = v;
+      });
+      localStorage.setItem(LOCAL_STORAGE_KEY, JSON.stringify(obj));
+    } catch {
+      // Ignore quota/storage errors
+    }
+  }
+}
+
+/**
+ * Optionally fetch online candidates from Google Input Tools API (mr-t-i0-und)
+ * and cache the results for offline use.
+ * @param {string} word
+ * @param {number} numOptions
+ * @returns {Promise<string[]>}
+ */
+export async function fetchOnlineMarathi(word, numOptions = 5) {
+  if (!word || !word.trim()) return [];
+  const clean = word.toLowerCase().trim();
+
+  // If already in cache
+  const cached = getCachedWord(clean);
+  if (cached && cached.length > 0) {
+    return cached;
+  }
+
+  // If in browser/electron/node with fetch
+  if (typeof fetch !== 'undefined') {
+    try {
+      const url = `https://inputtools.google.com/request?text=${encodeURIComponent(clean)}&itc=mr-t-i0-und&num=${numOptions}`;
+      const res = await fetch(url);
+      if (res.ok) {
+        const data = await res.json();
+        if (data && data[0] === 'SUCCESS' && data[1] && data[1][0] && data[1][0][1]) {
+          const suggestions = data[1][0][1];
+          setCachedWord(clean, suggestions);
+          return suggestions;
+        }
+      }
+    } catch {
+      // Network failure / offline: fail gracefully
+    }
+  }
+
+  return [];
+}

package/src/dictionary.js

@@ -0,0 +1,384 @@
+/**
+ * Curated high-accuracy Marathi vocabulary for everyday usage,
+ * Kirana/grocery items, customer names, units, and shop terms.
+ */
+export const MARATHI_DICTIONARY = {
+  // --- Grocery & Kirana Staples ---
+  'sakhar': 'साखर',
+  'saakhar': 'साखर',
+  'sugar': 'साखर',
+  'kanda': 'कांदा',
+  'kaanda': 'कांदा',
+  'onion': 'कांदा',
+  'batata': 'बटाटा',
+  'batate': 'बटाटे',
+  'potato': 'बटाटा',
+  'mith': 'मीठ',
+  'meeth': 'मीठ',
+  'namak': 'मीठ',
+  'salt': 'मीठ',
+  'tel': 'तेल',
+  'godetel': 'गोडेतेल',
+  'gahu': 'गहू',
+  'gehu': 'गहू',
+  'wheat': 'गहू',
+  'tandul': 'तांदूळ',
+  'taandul': 'तांदूळ',
+  'bhat': 'भात',
+  'rice': 'तांदूळ',
+  'kolam': 'कोलम',
+  'basmati': 'बासमती',
+  'jowar': 'ज्वारी',
+  'jwari': 'ज्वारी',
+  'bajra': 'बाजरी',
+  'bajri': 'बाजरी',
+  'nachani': 'नाचणी',
+  'ragi': 'नाचणी',
+  'makka': 'मक्का',
+  'pohe': 'पोहे',
+  'poha': 'पोहे',
+  'rava': 'रवा',
+  'suji': 'सुजी',
+  'sooji': 'सुजी',
+  'maida': 'मैदा',
+  'besan': 'बेसन',
+  'pith': 'पीठ',
+  'atta': 'आटा',
+  'chakki': 'चक्की',
+  'chaha': 'चहा',
+  'chai': 'चहा',
+  'tea': 'चहा',
+  'coffee': 'कॉफी',
+  'toor': 'तूर',
+  'tur': 'तूर',
+  'toordal': 'तूर डाळ',
+  'moong': 'मूग',
+  'mung': 'मूग',
+  'udid': 'उडीद',
+  'urad': 'उडीद',
+  'chana': 'चना',
+  'harbhara': 'हरभरा',
+  'masoor': 'मसूर',
+  'masur': 'मसूर',
+  'matki': 'मटकी',
+  'watana': 'वाटाणा',
+  'vatana': 'वाटाणा',
+  'chole': 'छोले',
+  'rajma': 'राजमा',
+  'chavli': 'चवळी',
+  'kulith': 'कुळीथ',
+  'shengdane': 'शेंगदाणे',
+  'dane': 'दाणे',
+  'sheng': 'शेंगदाणे',
+  'khobare': 'खोबरे',
+  'khobra': 'खोबरे',
+  'coconut': 'खोबरे',
+  'toop': 'तूप',
+  'tup': 'तूप',
+  'ghee': 'तूप',
+  'gul': 'गूळ',
+  'gud': 'गूळ',
+  'jaggery': 'गूळ',
+  'kakvi': 'काकवी',
+  'honey': 'मध',
+  'madh': 'मध',
+
+  // --- Spices & Masala ---
+  'masala': 'मसाला',
+  'mirchi': 'मिरची',
+  'mirch': 'मिरची',
+  'halad': 'हळद',
+  'haldi': 'हळद',
+  'lasun': 'लसूण',
+  'lahsun': 'लसूण',
+  'garlic': 'लसूण',
+  'aale': 'आले',
+  'adrak': 'आले',
+  'ginger': 'आले',
+  'kothimbir': 'कोथिंबीर',
+  'dhana': 'धना',
+  'dhane': 'धने',
+  'dhania': 'धने',
+  'jira': 'जिरे',
+  'jeera': 'जिरे',
+  'jire': 'जिरे',
+  'mohari': 'मोहरी',
+  'rai': 'राई',
+  'mustard': 'मोहरी',
+  'hing': 'हिंग',
+  'dalchini': 'दालचिनी',
+  'lavang': 'लवंग',
+  'miri': 'मिरी',
+  'tamalpatra': 'तमालपत्र',
+  'tejpatta': 'तेजपत्ता',
+  'jayfal': 'जायफळ',
+  'elaichi': 'वेलची',
+  'velchi': 'वेलची',
+  'kesar': 'केसर',
+  'til': 'तीळ',
+  'khaskhas': 'खसखस',
+  'methi': 'मेथी',
+  'badishep': 'बडीशेप',
+  'saunf': 'बडीशेप',
+  'chinch': 'चिंच',
+  'kokam': 'कोकम',
+  'amchur': 'आमचूर',
+
+  // --- Dry Fruits ---
+  'kaju': 'काजू',
+  'cashew': 'काजू',
+  'badam': 'बदाम',
+  'almond': 'बदाम',
+  'pista': 'पिस्ता',
+  'manuka': 'मनुका',
+  'kismis': 'किसमिस',
+  'kharik': 'खारीक',
+  'khajur': 'खजूर',
+  'akhrot': 'अक्रोड',
+  'makhana': 'मखाना',
+  'charoli': 'चारोळी',
+  'anjeer': 'अंजीर',
+
+  // --- Dairy & Cold Storage ---
+  'dudh': 'दूध',
+  'milk': 'दूध',
+  'dahi': 'दही',
+  'curd': 'दही',
+  'taak': 'ताक',
+  'paneer': 'पनीर',
+  'loni': 'लोणी',
+  'maska': 'मस्का',
+  'butter': 'बटर',
+  'cheese': 'चीज',
+  'shrikhand': 'श्रीखंड',
+  'amrakhand': 'आम्रखंड',
+
+  // --- Bakery, Snacks & Packaged Foods ---
+  'biscuit': 'बिस्कीट',
+  'biscuits': 'बिस्कीट',
+  'parle': 'पारले',
+  'toast': 'टोस्ट',
+  'khari': 'खारी',
+  'shev': 'शेव',
+  'bhujia': 'भुजिया',
+  'farsan': 'फरसाण',
+  'chivda': 'चिवडा',
+  'papad': 'पापड',
+  'lonche': 'लोणचे',
+  'achar': 'लोणचे',
+  'ketchup': 'केचप',
+  'sauce': 'सॉस',
+  'maggi': 'मॅगी',
+  'noodles': 'नुडल्स',
+  'sevai': 'शेवया',
+  'pasta': 'पास्ता',
+  'kurdaya': 'कुरडया',
+  'kurdai': 'कुरडई',
+  'wafers': 'वेफर्स',
+  'chips': 'चिप्स',
+
+  // --- Pooja & Religious ---
+  'agarbatti': 'अगरबत्ती',
+  'incense': 'अगरबत्ती',
+  'dhoop': 'धूप',
+  'kapoor': 'कापूर',
+  'karpur': 'कापूर',
+  'supari': 'सुपारी',
+  'gulal': 'गुलाल',
+  'kumkum': 'कुंकू',
+  'shendur': 'शेंदूर',
+  'bukka': 'बुक्का',
+  'abir': 'अबीर',
+  'ashtagandha': 'अष्टगंध',
+  'gandh': 'गंध',
+  'attar': 'अत्तर',
+  'janve': 'जानवे',
+  'phulvat': 'फुलवात',
+  'samai': 'समई',
+
+  // --- Cleaning & Household ---
+  'saban': 'साबण',
+  'soap': 'साबण',
+  'shampoo': 'शॅम्पू',
+  'detergent': 'डिटर्जंट',
+  'colgate': 'कोलगेट',
+  'toothpaste': 'टूथपेस्ट',
+  'surf': 'सर्फ',
+  'rin': 'रिन',
+  'vim': 'विम',
+  'wheel': 'व्हील',
+  'ariel': 'एरियल',
+  'tide': 'टाइड',
+  'harpic': 'हार्पिक',
+  'lizol': 'लायझॉल',
+  'phenyl': 'फिनाईल',
+  'jhadu': 'झाडू',
+  'brush': 'ब्रश',
+
+  // --- Units of Measure ---
+  'kilo': 'किलो',
+  'kg': 'कि.ग्रॅ.',
+  'gram': 'ग्रॅम',
+  'gm': 'ग्रॅम',
+  'liter': 'लिटर',
+  'litre': 'लिटर',
+  'ltr': 'लिटर',
+  'mili': 'मिली',
+  'ml': 'मिली',
+  'packet': 'पॅकेट',
+  'pkt': 'पॅकेट',
+  'nag': 'नग',
+  'piece': 'नग',
+  'dozen': 'डझन',
+  'box': 'बॉक्स',
+  'poti': 'पोती',
+  'bori': 'बोरी',
+  'bag': 'बॅग',
+
+  // --- Customer Names & Surnames ---
+  'ketan': 'केतन',
+  'rahul': 'राहुल',
+  'amit': 'अमित',
+  'sachin': 'सचिन',
+  'suresh': 'सुरेश',
+  'ramesh': 'रमेश',
+  'mahesh': 'महेश',
+  'ganesh': 'गणेश',
+  'santosh': 'संतोष',
+  'vijay': 'विजय',
+  'ajay': 'अजय',
+  'sandeep': 'संदीप',
+  'pradip': 'प्रदीप',
+  'pravin': 'प्रवीण',
+  'nitin': 'नितीन',
+  'anil': 'अनिल',
+  'sunil': 'सुनील',
+  'vikas': 'विकास',
+  'vishal': 'विशाल',
+  'amol': 'अमोल',
+  'swapnil': 'स्वप्निल',
+  'rohit': 'रोहित',
+  'akshay': 'अक्षय',
+  'chetan': 'चेतन',
+  'deepak': 'दीपक',
+  'sagar': 'सागर',
+  'datta': 'दत्त',
+  'dnyaneshwar': 'ज्ञानेश्वर',
+  'shivaji': 'शिवाजी',
+  'sambhaji': 'संभाजी',
+  'tukaram': 'तुकाराम',
+  'eknath': 'एकनाथ',
+  'namdev': 'नामदेव',
+  'ram': 'राम',
+  'krishna': 'कृष्ण',
+  'laxman': 'लक्ष्मण',
+  'bharat': 'भरत',
+  'shankar': 'शंकर',
+  'mahadev': 'महादेव',
+  'hanumant': 'हनुमंत',
+  'maruti': 'मारुती',
+  'priya': 'प्रिया',
+  'pooja': 'पूजा',
+  'sneha': 'स्नेहा',
+  'neha': 'नेहा',
+  'anita': 'अनिता',
+  'sunita': 'सुनिता',
+  'rekha': 'रेखा',
+  'kavita': 'कविता',
+  'savita': 'सविता',
+  'sangita': 'संगीता',
+  'manisha': 'मनीषा',
+  'swati': 'स्वाती',
+  'shital': 'शीतल',
+  'jyoti': 'ज्योती',
+
+  // Surnames
+  'patil': 'पाटील',
+  'deshmukh': 'देशमुख',
+  'pawar': 'पवार',
+  'jadhav': 'जाधव',
+  'shinde': 'शिंदे',
+  'kadam': 'कदम',
+  'chavan': 'चव्हाण',
+  'chavhan': 'चव्हाण',
+  'more': 'मोरे',
+  'gaikwad': 'गायकवाड',
+  'kale': 'काळे',
+  'bhosale': 'भोसले',
+  'jagtap': 'जगतप',
+  'sawant': 'सावंत',
+  'sharma': 'शर्मा',
+  'varma': 'वर्मा',
+  'gupta': 'गुप्ता',
+  'jain': 'जैन',
+  'koli': 'कोळी',
+  'mali': 'माळी',
+  'wagh': 'वाघ',
+  'gore': 'गोरे',
+  'kharat': 'खरात',
+  'gharge': 'घारगे',
+  'joshi': 'जोशी',
+  'kulkarni': 'कुलकर्णी',
+  'salunkhe': 'साळुंखे',
+  'raut': 'राऊत',
+  'thorat': 'थोरात',
+
+  // --- Common Shop, Business & Billing Phrases ---
+  'namaskar': 'नमस्कार',
+  'namaste': 'नमस्ते',
+  'swagat': 'स्वागत',
+  'dhanyavad': 'धन्यवाद',
+  'abhar': 'आभार',
+  'shree': 'श्री',
+  'shri': 'श्री',
+  'om': 'ॐ',
+  'jai': 'जय',
+  'gurudev': 'गुरुदेव',
+  'kirana': 'किराणा',
+  'dukan': 'दुकान',
+  'store': 'स्टोअर',
+  'market': 'मार्केट',
+  'supermarket': 'सुपर मार्केट',
+  'general': 'जनरल',
+  'billing': 'बिलिंग',
+  'bill': 'बिल',
+  'grahak': 'ग्राहक',
+  'customer': 'ग्राहक',
+  'rokh': 'रोख',
+  'cash': 'रोख',
+  'udhari': 'उधारी',
+  'jama': 'जमा',
+  'baki': 'बाकी',
+  'sut': 'सूट',
+  'discount': 'सूट',
+  'ekun': 'एकूण',
+  'total': 'एकूण',
+  'payment': 'पेमेंट',
+  'online': 'ऑनलाइन',
+  'upi': 'युपीआय',
+
+  // --- Common Connecting Words & Pronouns ---
+  'ani': 'आणि',
+  'aani': 'आणि',
+  'and': 'आणि',
+  'pan': 'पण',
+  'madhe': 'मध्ये',
+  'var': 'वर',
+  'khali': 'खाली',
+  'dya': 'द्या',
+  'ghya': 'घ्या',
+  'pahije': 'पाहिजे',
+  'ahe': 'आहे',
+  'nahi': 'नाही',
+  'kiti': 'किती',
+  'kay': 'काय',
+  'kuthe': 'कुठे',
+  'kasa': 'कसा',
+  'kashi': 'कशी',
+  'kashe': 'कसे',
+  'he': 'हे',
+  'te': 'ते',
+  'ha': 'हा',
+  'hi': 'ही'
+};
+

package/src/dom.js

@@ -0,0 +1,274 @@
+import { transliterateWord, getSuggestions } from './index.js';
+
+export function attachDevanagari(target, options = {}) {
+  const el = typeof target === 'string' ? document.querySelector(target) : target;
+  if (!el) {
+    console.warn('[marathi-transliterate] attachDevanagari: element not found', target);
+    return { detach: () => {}, setEnabled: () => {}, isEnabled: () => false, toggle: () => false };
+  }
+
+  const {
+    defaultEnabled = true,
+    showSuggestions = true,
+    enableShortcut = true,
+    maxSuggestions = 5,
+    onToggle,
+    onTransliterate
+  } = options;
+
+  let enabled = defaultEnabled;
+  let lastConversion = null;
+  let activeWord = '';
+  let activeWordStart = -1;
+  let candidates = [];
+  let selectedIndex = 0;
+  let popupEl = null;
+
+  function createPopup() {
+    if (typeof document === 'undefined') return;
+    popupEl = document.createElement('div');
+    popupEl.className = 'devanagari-suggestion-popup';
+    Object.assign(popupEl.style, {
+      position: 'fixed',
+      zIndex: '999999',
+      display: 'none',
+      flexDirection: 'column',
+      background: 'rgba(23, 23, 23, 0.95)',
+      color: '#f8fafc',
+      backdropFilter: 'blur(12px)',
+      WebkitBackdropFilter: 'blur(12px)',
+      border: '1px solid rgba(255, 255, 255, 0.15)',
+      borderRadius: '8px',
+      padding: '4px',
+      boxShadow: '0 12px 30px -4px rgba(0, 0, 0, 0.5), 0 6px 12px -4px rgba(0, 0, 0, 0.3)',
+      fontFamily: 'system-ui, -apple-system, sans-serif',
+      fontSize: '13px',
+      minWidth: '160px',
+      maxWidth: '300px',
+      userSelect: 'none',
+      pointerEvents: 'auto'
+    });
+    document.body.appendChild(popupEl);
+  }
+
+  if (showSuggestions) createPopup();
+
+  function positionPopup() {
+    if (!popupEl || !el) return;
+    const rect = el.getBoundingClientRect();
+    const popupHeight = popupEl.offsetHeight || 120;
+    const spaceBelow = window.innerHeight - rect.bottom;
+    let top = rect.bottom + 4;
+    if (spaceBelow < popupHeight && rect.top > popupHeight) {
+      top = rect.top - popupHeight - 4;
+    }
+    popupEl.style.top = Math.max(8, top) + 'px';
+    popupEl.style.left = Math.max(8, Math.min(rect.left, window.innerWidth - 320)) + 'px';
+  }
+
+  function hidePopup() {
+    if (!popupEl) return;
+    popupEl.style.display = 'none';
+    candidates = [];
+    selectedIndex = 0;
+    activeWord = '';
+    activeWordStart = -1;
+  }
+
+  function renderPopup() {
+    if (!popupEl || candidates.length === 0) {
+      hidePopup();
+      return;
+    }
+    popupEl.innerHTML = '';
+    candidates.forEach((cand, idx) => {
+      const item = document.createElement('div');
+      item.className = 'devanagari-suggestion-item';
+      const isSelected = idx === selectedIndex;
+      Object.assign(item.style, {
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        padding: '6px 10px',
+        borderRadius: '5px',
+        cursor: 'pointer',
+        background: isSelected ? 'rgba(59, 130, 246, 0.95)' : 'transparent',
+        color: isSelected ? '#ffffff' : '#f1f5f9',
+        fontWeight: isSelected ? '700' : '500',
+        transition: 'background 0.1s ease'
+      });
+      const label = document.createElement('span');
+      label.textContent = cand;
+      label.style.overflow = 'hidden';
+      label.style.textOverflow = 'ellipsis';
+      label.style.whiteSpace = 'nowrap';
+      const keyBadge = document.createElement('span');
+      keyBadge.textContent = String(idx + 1);
+      Object.assign(keyBadge.style, {
+        fontSize: '10px',
+        fontWeight: '700',
+        opacity: isSelected ? '1' : '0.6',
+        marginLeft: '8px',
+        background: isSelected ? 'rgba(255, 255, 255, 0.3)' : 'rgba(255, 255, 255, 0.12)',
+        padding: '1px 5px',
+        borderRadius: '3px'
+      });
+      item.appendChild(label);
+      item.appendChild(keyBadge);
+      item.addEventListener('mousedown', (e) => {
+        e.preventDefault();
+        selectCandidate(idx, ' ');
+      });
+      popupEl.appendChild(item);
+    });
+    popupEl.style.display = 'flex';
+    positionPopup();
+  }
+
+  function setNativeValue(input, newValue) {
+    const isInput = input instanceof HTMLInputElement;
+    const proto = isInput ? HTMLInputElement.prototype : HTMLTextAreaElement.prototype;
+    const desc = Object.getOwnPropertyDescriptor(proto, 'value');
+    if (desc && desc.set) {
+      desc.set.call(input, newValue);
+    } else {
+      input.value = newValue;
+    }
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    input.dispatchEvent(new Event('change', { bubbles: true }));
+  }
+
+  function selectCandidate(index, delimiter = ' ') {
+    if (index < 0 || index >= candidates.length) return;
+    const chosen = candidates[index];
+    const currentValue = el.value;
+    const before = currentValue.slice(0, activeWordStart);
+    const after = currentValue.slice(el.selectionStart);
+    const newValue = before + chosen + delimiter + after;
+    setNativeValue(el, newValue);
+    const newCursor = activeWordStart + chosen.length + delimiter.length;
+    setTimeout(() => { el.setSelectionRange(newCursor, newCursor); }, 0);
+    lastConversion = {
+      original: activeWord,
+      converted: chosen,
+      startPos: activeWordStart,
+      endPos: activeWordStart + chosen.length
+    };
+    if (onTransliterate) {
+      onTransliterate({ original: activeWord, transliterated: chosen });
+    }
+    hidePopup();
+  }
+
+  function setEnabled(val) {
+    enabled = Boolean(val);
+    if (!enabled) hidePopup();
+    if (onToggle) onToggle(enabled);
+  }
+
+  function isEnabled() { return enabled; }
+
+  function toggle() { setEnabled(!enabled); return enabled; }
+
+  function handleInput() {
+    if (!enabled || !showSuggestions) return;
+    const cursorPos = el.selectionStart;
+    const textBeforeCursor = el.value.slice(0, cursorPos);
+    const match = textBeforeCursor.match(/([a-zA-Z]+)$/);
+    if (match) {
+      activeWord = match[1];
+      activeWordStart = cursorPos - activeWord.length;
+      candidates = getSuggestions(activeWord, { maxSuggestions, includeOriginal: true });
+      selectedIndex = 0;
+      renderPopup();
+    } else {
+      hidePopup();
+    }
+  }
+
+  function handleKeyDown(e) {
+    const isCmdOrCtrl = e.metaKey || e.ctrlKey;
+    if (enableShortcut && isCmdOrCtrl && e.key.toLowerCase() === 'm') {
+      e.preventDefault();
+      toggle();
+      return;
+    }
+    if (!enabled) return;
+
+    if (popupEl && popupEl.style.display !== 'none' && candidates.length > 0) {
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        selectedIndex = (selectedIndex + 1) % candidates.length;
+        renderPopup();
+        return;
+      }
+      if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        selectedIndex = (selectedIndex - 1 + candidates.length) % candidates.length;
+        renderPopup();
+        return;
+      }
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        hidePopup();
+        return;
+      }
+      if (e.key === 'Tab' || e.key === 'Enter') {
+        e.preventDefault();
+        selectCandidate(selectedIndex, e.key === 'Enter' ? '' : ' ');
+        return;
+      }
+      if (e.key === ' ') {
+        e.preventDefault();
+        selectCandidate(selectedIndex, ' ');
+        return;
+      }
+      const num = parseInt(e.key, 10);
+      if (!isNaN(num) && num >= 1 && num <= candidates.length) {
+        e.preventDefault();
+        selectCandidate(num - 1, ' ');
+        return;
+      }
+    }
+
+    const cursorPos = el.selectionStart;
+    if (e.key === 'Backspace' && lastConversion) {
+      if (cursorPos === lastConversion.endPos || cursorPos === lastConversion.endPos + 1) {
+        e.preventDefault();
+        const currentValue = el.value;
+        const before = currentValue.slice(0, lastConversion.startPos);
+        const after = currentValue.slice(cursorPos);
+        const restored = before + lastConversion.original + after;
+        setNativeValue(el, restored);
+        const newCursor = lastConversion.startPos + lastConversion.original.length;
+        setTimeout(() => { el.setSelectionRange(newCursor, newCursor); }, 0);
+        lastConversion = null;
+        hidePopup();
+        return;
+      }
+    }
+    if (e.key !== 'Backspace') {
+      lastConversion = null;
+    }
+  }
+
+  function handleBlur() {
+    setTimeout(() => { hidePopup(); }, 200);
+  }
+
+  el.addEventListener('keydown', handleKeyDown);
+  el.addEventListener('input', handleInput);
+  el.addEventListener('blur', handleBlur);
+
+  function detach() {
+    el.removeEventListener('keydown', handleKeyDown);
+    el.removeEventListener('input', handleInput);
+    el.removeEventListener('blur', handleBlur);
+    if (popupEl && popupEl.parentNode) {
+      popupEl.parentNode.removeChild(popupEl);
+    }
+    popupEl = null;
+  }
+
+  return { detach, setEnabled, isEnabled, toggle };
+}

package/src/index.js

@@ -0,0 +1,125 @@
+/**
+ * marathi-transliterate
+ * Zero-dependency, offline-first Plain JavaScript phonetic transliteration library
+ * for Marathi (Devanagari) script with live smart suggestions.
+ */
+
+import { MARATHI_DICTIONARY } from './dictionary.js';
+import { phoneticTransliterateWord } from './phonetics.js';
+import { getCachedWord, setCachedWord, fetchOnlineMarathi } from './cache.js';
+import { attachDevanagari } from './dom.js';
+
+export { MARATHI_DICTIONARY, fetchOnlineMarathi, attachDevanagari };
+
+/**
+ * Transliterates a single English word into Marathi (Devanagari).
+ * @param {string} word - Romanized word e.g. sakhar, kanda, atata * @returns {string} - Marathi Devanagari script e.g. साखर, कांदा, बटाटा */
+export function transliterateWord(word) {
+  if (!word) return '';
+  const clean = word.toLowerCase().trim();
+
+  // 1. Check curated high-accuracy dictionary first
+  if (MARATHI_DICTIONARY[clean]) {
+    return MARATHI_DICTIONARY[clean];
+  }
+
+  // 2. Check local/memory cache
+  const cached = getCachedWord(clean);
+  if (cached && cached.length > 0) {
+    return cached[0];
+  }
+
+  // 3. Algorithmic rule-based phonetic engine
+  const phonetic = phoneticTransliterateWord(word);
+
+  // Background fetch to enrich cache if online (non-blocking)
+  if (typeof fetch !== 'undefined') {
+    fetchOnlineMarathi(clean).catch(() => {});
+  }
+
+  return phonetic;
+}
+
+/**
+ * Transliterates a full sentence, paragraph or mixed text into Marathi.
+ * Preserves numbers, punctuation, spaces, and formatting.
+ * @param {string} text - Input text
+ * @returns {string} - Transliterated text
+ */
+export function transliterate(text) {
+  if (!text) return '';
+
+  return text.replace(/[a-zA-Z]+/g, match => {
+    return transliterateWord(match);
+  });
+}
+
+/**
+ * Alias for transliterate (drop-in compatibility)
+ */
+export const toDevanagari = transliterate;
+
+/**
+ * Returns ranked candidate spelling suggestions for a word.
+ * @param {string} word
+ * @param {Object} [options]
+ * @param {number} [options.maxSuggestions=5]
+ * @param {boolean} [options.includeOriginal=true]
+ * @returns {string[]}
+ */
+export function getSuggestions(word, options = {}) {
+  if (!word || !word.trim()) return [];
+  const clean = word.toLowerCase().trim();
+  const max = options.maxSuggestions || 5;
+  const includeOriginal = options.includeOriginal !== false;
+  const suggestions = [];
+
+  const add = (candidate) => {
+    if (candidate && !suggestions.includes(candidate)) {
+      suggestions.push(candidate);
+    }
+  };
+
+  // 1. Exact match from curated dictionary
+  if (MARATHI_DICTIONARY[clean]) {
+    add(MARATHI_DICTIONARY[clean]);
+  }
+
+  // 2. Check local/memory cache
+  const cached = getCachedWord(clean);
+  if (cached) {
+    for (const c of cached) add(c);
+  }
+
+  // 3. Phonetic algorithm conversion
+  const phonetic = phoneticTransliterateWord(word);
+  if (phonetic) add(phonetic);
+
+  // 4. Prefix matches from dictionary (if clean.length >= 3)
+  if (clean.length >= 3 && suggestions.length < max) {
+    for (const [key, val] of Object.entries(MARATHI_DICTIONARY)) {
+      if (key.startsWith(clean) && key !== clean) {
+        add(val);
+        if (suggestions.length >= max) break;
+      }
+    }
+  }
+
+  // 5. Add raw English word at the end so user can easily keep original
+  if (includeOriginal && !suggestions.includes(word)) {
+    suggestions.push(word);
+  }
+
+  return suggestions.slice(0, max);
+}
+
+// Default export
+export default {
+  transliterate,
+  transliterateWord,
+  toDevanagari,
+  getSuggestions,
+  attachDevanagari,
+  MARATHI_DICTIONARY,
+  fetchOnlineMarathi
+};

package/src/phonetics.js

@@ -0,0 +1,182 @@
+/**
+ * Algorithmic phonetic transliteration from Roman (English) script
+ * to Marathi (Devanagari) script.
+ */
+
+const CONSONANTS = [
+  // Multi-character special combinations
+  { en: 'dny', mr: 'ज्ञ' },
+  { en: 'jn', mr: 'ज्ञ' },
+  { en: 'gy', mr: 'ज्ञ' },
+  { en: 'ksh', mr: 'क्ष' },
+  { en: 'shr', mr: 'श्र' },
+  { en: 'chh', mr: 'छ' },
+  { en: 'ch', mr: 'च' },
+  { en: 'kh', mr: 'ख' },
+  { en: 'gh', mr: 'घ' },
+  { en: 'jh', mr: 'झ' },
+  { en: 'zh', mr: 'झ' },
+  { en: 'th', mr: 'थ' },
+  { en: 'dh', mr: 'ध' },
+  { en: 'ph', mr: 'फ' },
+  { en: 'bh', mr: 'भ' },
+  { en: 'shh', mr: 'ष' },
+  { en: 'sh', mr: 'श' },
+  { en: 'ng', mr: 'ङ' },
+
+  // Single consonants
+  { en: 'k', mr: 'क' },
+  { en: 'g', mr: 'ग' },
+  { en: 'j', mr: 'ज' },
+  { en: 't', mr: 'त' },
+  { en: 'd', mr: 'द' },
+  { en: 'n', mr: 'न' },
+  { en: 'p', mr: 'प' },
+  { en: 'f', mr: 'फ' },
+  { en: 'b', mr: 'ब' },
+  { en: 'm', mr: 'म' },
+  { en: 'y', mr: 'य' },
+  { en: 'r', mr: 'र' },
+  { en: 'l', mr: 'ल' },
+  { en: 'L', mr: 'ळ' },
+  { en: 'v', mr: 'व' },
+  { en: 'w', mr: 'व' },
+  { en: 's', mr: 'स' },
+  { en: 'h', mr: 'ह' },
+  { en: 'x', mr: 'क्ष' },
+  { en: 'z', mr: 'झ' },
+  { en: 'T', mr: 'ट' },
+  { en: 'D', mr: 'ड' },
+  { en: 'N', mr: 'ण' }
+];
+
+const INDEPENDENT_VOWELS = [
+  { en: 'aa', mr: 'आ' },
+  { en: 'A', mr: 'आ' },
+  { en: 'a', mr: 'अ' },
+  { en: 'ee', mr: 'ई' },
+  { en: 'ii', mr: 'ई' },
+  { en: 'i', mr: 'इ' },
+  { en: 'oo', mr: 'ऊ' },
+  { en: 'uu', mr: 'ऊ' },
+  { en: 'u', mr: 'उ' },
+  { en: 'ai', mr: 'ऐ' },
+  { en: 'ay', mr: 'ऐ' },
+  { en: 'au', mr: 'औ' },
+  { en: 'ou', mr: 'औ' },
+  { en: 'ow', mr: 'औ' },
+  { en: 'e', mr: 'ए' },
+  { en: 'o', mr: 'ओ' },
+  { en: 'am', mr: 'अं' },
+  { en: 'an', mr: 'अं' },
+  { en: 'ri', mr: 'ऋ' },
+  { en: 'ru', mr: 'ऋ' }
+];
+
+const MATRAS = [
+  { en: 'aa', mr: 'ा' },
+  { en: 'A', mr: 'ा' },
+  { en: 'a', mr: '' }, // Inherent vowel: cancels halant, no visible matra
+  { en: 'ee', mr: 'ी' },
+  { en: 'ii', mr: 'ी' },
+  { en: 'i', mr: 'ि' },
+  { en: 'oo', mr: 'ू' },
+  { en: 'uu', mr: 'ू' },
+  { en: 'u', mr: 'ु' },
+  { en: 'ai', mr: 'ै' },
+  { en: 'ay', mr: 'ै' },
+  { en: 'au', mr: 'ौ' },
+  { en: 'ou', mr: 'ौ' },
+  { en: 'ow', mr: 'ौ' },
+  { en: 'e', mr: 'े' },
+  { en: 'o', mr: 'ो' },
+  { en: 'am', mr: 'ं' },
+  { en: 'an', mr: 'ं' },
+  { en: 'ri', mr: 'ृ' },
+  { en: 'ru', mr: 'ृ' }
+];
+
+/**
+ * Phonetically transliterates a single Roman word to Devanagari.
+ * @param {string} text - Single English word (e.g. "shantanu", "ramesh")
+ * @returns {string} - Devanagari representation
+ */
+export function phoneticTransliterateWord(text) {
+  if (!text) return '';
+  const clean = text.trim();
+  if (!clean) return '';
+
+  let res = '';
+  let i = 0;
+  const n = clean.length;
+
+  while (i < n) {
+    // Non-alphabetical character: preserve as is
+    if (!/[a-zA-Z]/.test(clean[i])) {
+      res += clean[i];
+      i++;
+      continue;
+    }
+
+    // Check independent vowel at the beginning of a word or after non-alpha
+    let matchedVowel = false;
+    if (i === 0 || !/[a-zA-Z]/.test(clean[i - 1])) {
+      for (const v of INDEPENDENT_VOWELS) {
+        if (clean.substring(i, i + v.en.length).toLowerCase() === v.en.toLowerCase()) {
+          res += v.mr;
+          i += v.en.length;
+          matchedVowel = true;
+          break;
+        }
+      }
+      if (matchedVowel) continue;
+    }
+
+    // Match consonant
+    let matchedConsonant = false;
+    for (const c of CONSONANTS) {
+      const sub = clean.substring(i, i + c.en.length);
+      const isCaseSensitive = c.en === 'L' || c.en === 'T' || c.en === 'D' || c.en === 'N';
+      const isMatch = isCaseSensitive ? sub === c.en : sub.toLowerCase() === c.en.toLowerCase();
+
+      if (isMatch) {
+        res += c.mr;
+        i += c.en.length;
+        matchedConsonant = true;
+
+        // Check for attached vowel matra
+        let matchedMatra = false;
+        for (const m of MATRAS) {
+          const nextSub = clean.substring(i, i + m.en.length);
+          const mCaseSensitive = m.en === 'A';
+          const mMatch = mCaseSensitive ? nextSub === m.en : nextSub.toLowerCase() === m.en.toLowerCase();
+
+          if (mMatch) {
+            res += m.mr;
+            i += m.en.length;
+            matchedMatra = true;
+            break;
+          }
+        }
+
+        // If no vowel followed and next character is also a consonant, apply halant (virama ्)
+        // In Marathi/Hindi phonetics, word-final consonants do NOT get halant
+        if (!matchedMatra) {
+          if (i < n && /[a-zA-Z]/.test(clean[i])) {
+            res += '्';
+          }
+        }
+
+        break;
+      }
+    }
+
+    if (!matchedConsonant) {
+      // Fallback
+      res += clean[i];
+      i++;
+    }
+  }
+
+  return res;
+}