@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/hi-IN/real-time-collaboration.md

@@ -0,0 +1,676 @@
+---
+title: "वास्तविक समय सहयोग"
+description: "बहु-उपयोगकर्ता सहयोगात्मक संपादन जहां AI एजेंट प्रथम श्रेणी का सहकर्मी है: CRDT विलय, लाइव उपस्थिति, SSE फास्ट-पाथ, और ग्रैन्युलर सर्वर-साइड मर्ज - किसी भी SQL डेटाबेस और किसी भी होस्ट पर।"
+---
+
+# वास्तविक समय सहयोग
+
+एक दस्तावेज़ खोलने और एक साथी के कर्सर को एक पैराग्राफ तक स्क्रॉल करते हुए देखने की कल्पना करें,
+फिर पाठ स्वयं को पुनः लिखता है - शल्य चिकित्सा द्वारा, अपना स्थान खोए बिना। वह
+सहकर्मी टीम का साथी हो सकता है। यह एजेंट हो सकता है. फ्रेमवर्क से
+परिप्रेक्ष्य में वे समान हैं: दोनों Yjs ऑपरेशन उत्पन्न करते हैं जो विलीन हो जाते हैं
+साझा दस्तावेज़ में संघर्ष-मुक्त। यह
+एजेंट-मूल सहयोग मॉडल।
+
+## दृष्टिकोण {#vision}
+
+एजेंट के साथ संपादन करना Google डॉक्स या फिग्मा में काम करने जैसा लगता है
+एक सहकर्मी जो त्वरित और अथक दोनों है:
+
+यदि आपको एजेंट या किसी अन्य उपयोगकर्ता द्वारा SQL को लिखने पर ताज़ा करने के लिए UI की आवश्यकता है, तो आपको इसकी कोई आवश्यकता नहीं है - [`useDbSync`](/docs/client) का उपयोग करें। यह पृष्ठ एकल समृद्ध-पाठ दस्तावेज़ (साझा कर्सर, संघर्ष-मुक्त विलय) के चरित्र-स्तरीय सह-संपादन के लिए है। दोनों एक ही `/_agent-native/poll` चैनल पर चलते हैं।
+
+यह तीन युद्ध-परीक्षित प्रौद्योगिकियों पर बनाया गया है: **Yjs** (संघर्ष-मुक्त विलय के लिए CRDT), **टिपटैप** (रिच टेक्स्ट एडिटर), और **पोलिंग-आधारित सिंक** (सर्वर रहित और एज सहित सभी तैनाती वातावरण में काम करता है)।
+
+- **CRDT विलय** — मनुष्यों और एजेंटों के समवर्ती संपादन बिना विलय
+  संघर्ष। आप एक पैराग्राफ टाइप करें; एजेंट दूसरे को फिर से लिखता है; दोनों
+  साफ-सुथरा उतरें।
+- **उपस्थिति** - एक `PresenceBar` दिखाता है कि दस्तावेज़ में अभी कौन है,
+  जब एजेंट सक्रिय रूप से संपादन कर रहा हो तो एजेंट उपस्थिति संकेतक भी शामिल है।
+- **एक सहकर्मी संपादक के रूप में एजेंट** — एजेंट संपादन उसी Yjs के माध्यम से प्रवाहित होता है
+  मानव संपादन के रूप में बुनियादी ढाँचा। वे कर्सर को बाधित किए बिना, लाइव दिखाई देते हैं
+  पद, चयन, या पूर्ववत स्टैक।
+- **हर जगह काम करता है** - कोई भी SQL डेटाबेस Drizzle समर्थन करता है (SQLite, Postgres)।
+  कोई भी होस्टिंग लक्ष्य Nitro सर्वर रहित और एज सहित समर्थन करता है।
+
+## आर्किटेक्चर {#architecture}
+
+सहयोग प्रणाली में पांच इंटरलॉकिंग परतें हैं।
+
+```an-diagram title="Five interlocking layers" summary="From the in-memory CRDT down to the transport that carries updates between peers — each layer has one job."
+{
+  "html": "<div class=\"diagram-stack\"><div class=\"diagram-card layer\"><span class=\"diagram-pill accent\">1 &middot; Yjs Y.Doc</span><small class=\"diagram-muted\">CRDT &mdash; conflict-free merge, no coordinator</small></div><div class=\"diagram-card layer\"><span class=\"diagram-pill\">2 &middot; SQL canonical content</span><small class=\"diagram-muted\">_collab_docs &mdash; durable source of truth, versioned</small></div><div class=\"diagram-card layer\"><span class=\"diagram-pill\">3 &middot; updatedAt-gated reconcile</span><small class=\"diagram-muted\">agent edits propagate via the SQL bump</small></div><div class=\"diagram-card layer\"><span class=\"diagram-pill\">4 &middot; Lead-client election</span><small class=\"diagram-muted\">exactly one tab applies the snapshot</small></div><div class=\"diagram-card layer\"><span class=\"diagram-pill ok\">5 &middot; SSE fast-path + polling</span><small class=\"diagram-muted\">~tens of ms, degrades to 2s poll anywhere</small></div></div>",
+  "css": ".diagram-stack{display:flex;flex-direction:column;gap:8px}.diagram-stack .layer{display:flex;flex-direction:column;gap:4px;padding:12px 14px}"
+}
+```
+
+### 1. Yjs Y.Doc (CRDT परत)
+
+प्रत्येक सहयोगी दस्तावेज़ एक `Y.Doc` है जिसमें साझा प्रकार होते हैं - आमतौर पर एक
+रिच टेक्स्ट के लिए `Y.XmlFragment` (प्रोसेमिरर नोड ट्री जिसे टिपटैप पढ़ता है) या
+संरचित JSON डेटा के लिए `Y.Map` / `Y.Array`। Yjs समवर्ती अद्यतनों को मर्ज करता है
+बिना किसी केंद्रीय समन्वयक के; कोई भी दो ग्राहक जो अपनी राज्य पहुंच का आदान-प्रदान करते हैं
+ऑर्डर की परवाह किए बिना वही परिणाम।
+
+### 2. SQL विहित सामग्री (सच्चाई का टिकाऊ स्रोत)
+
+Yjs स्थिति `_collab_docs` तालिका में बेस64-एन्कोडेड बाइनरी के रूप में बनी रहती है।
+तालिका फ़्रेमवर्क-प्रबंधित और प्रदाता-अज्ञेयवादी है (SQLite और Postgres उपयोग
+समान स्कीमा)। प्रत्येक पंक्ति में एक आशावादी-समवर्ती संस्करण कॉलम होता है
+समवर्ती लेखन दौड़ को रोकने के लिए। टॉम्बस्टोन संघनन अवसरवादी ढंग से चलता है
+जब संग्रहीत ब्लॉब ताज़ा एन्कोडेड स्थिति 4× से अधिक हो जाता है - कोई पृष्ठभूमि कार्य नहीं
+आवश्यक.
+
+### 3. `updatedAt`-गेटेड सुलह (एजेंट-संपादन प्रचार)
+
+एजेंट actions प्रक्रिया के दौरान Yjs में प्रवेश नहीं करता है। इसके बजाय, क्रिया
+विहित SQL सामग्री स्तंभ और उभार `updatedAt`। परिवर्तन-सिंक प्रणाली
+बम्प का पता लगाता है, खुला संपादक रिकॉर्ड और लीड क्लाइंट को पुनः प्राप्त करता है
+नई सामग्री को `setContent` के माध्यम से साझा Y.Doc में लागू करता है। एक `updatedAt`
+गेट यह सुनिश्चित करता है कि केवल वास्तविक रूप से नई सामग्री ही अपनाई जाए - सर्वेक्षण की धीमी प्रतिक्रियाएं
+संपादन को पूर्ववत नहीं किया जा सकता।
+
+### 4. लीड-क्लाइंट चुनाव (डुप्लिकेशन)
+
+जब कई टैब खुले होते हैं, तो उनमें से एक आधिकारिक SQL स्नैपशॉट लागू होता है
+साझा Y.Doc में। लीड सबसे कम Yjs `clientID`
+वर्तमान में दृश्यमान साथियों के बीच। एजेंट की जागरूकता प्रविष्टि का उपयोग करता है
+`AGENT_CLIENT_ID` (अधिकतम पूर्णांक) इसलिए यह कभी भी अग्रणी नहीं हो सकता। एक क्लाइंट संपादन
+अकेला हमेशा अग्रणी होता है। चुनाव बिना किसी समन्वय के नियतिवादी है
+राउंड-ट्रिप (`@agent-native/core/client` से `isReconcileLeadClient`)।
+
+### 5. SSE फास्ट-पाथ + पोलिंग फ़ॉलबैक (परिवहन)
+
+कोलैब अपडेट इवेंट दो रास्तों से होकर गुजरते हैं:
+
+- **SSE फास्ट-पाथ** - ग्राहक `/_agent-native/poll-events` की सदस्यता लेता है
+  (वही `EventSource` जो `useDbSync` द्वारा उपयोग किया जाता है)। कोलैब अपडेट इवेंट आ गए
+  पुश-शैली, आमतौर पर दसियों मिलीसेकंड में। जबकि SSE स्वस्थ है
+  पोल लूप धीमी गति से शिथिल हो जाता है (डिफ़ॉल्ट रूप से ~12 सेकंड)।
+- **पोलिंग फ़ॉलबैक** — `/_agent-native/poll?since=N` पर हर 2 सेकंड में पोल होता है
+  जब SSE अनुपलब्ध हो। यह किसी भी परिनियोजन पर सहयोग कार्य करता है
+  लक्ष्य - सर्वर रहित फ़ंक्शंस सहित जहां लगातार कनेक्शन हैं
+  असंभव और अलग-अलग आह्वान अलग-अलग अनुरोधों को संभाल सकते हैं।
+
+स्थानीय Yjs अपडेट को `Y.mergeUpdates` (~80 एमएस) के साथ खारिज और संयोजित किया जाता है
+सर्वर पर भेजे जाने से पहले, कीस्ट्रोक-स्तरीय नेटवर्क ट्रैफ़िक को कम करना।
+बैच को तुरंत `visibilitychange` या `pagehide` पर फ्लश किया जाता है। ए
+राज्य-वेक्टर अंतर (`GET /:docId/state?stateVector=…`) केवल
+पुनः कनेक्ट, रिंग-बफर ओवरफ़्लो, या हर 15वें मतदान चक्र - हर पर नहीं
+चक्र.
+
+नेटवर्क त्रुटियाँ घबराहट के साथ घातीय बैकऑफ़ का उपयोग करती हैं, जिसकी सीमा ~15 सेकंड है।
+
+```an-diagram title="Two edit paths, one merge" summary="Human keystrokes flow Y.Doc → server → SSE. Agent edits go through SQL: the action bumps updatedAt, the lead client reconciles, then the change re-enters Yjs."
+{
+  "html": "<div class=\"diagram-collab\"><div class=\"lane\"><span class=\"diagram-pill\">Human edit</span><div class=\"diagram-node\">Y.Doc update<br><small class=\"diagram-muted\">debounce ~80ms</small></div><span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</span><div class=\"diagram-box\" data-rough>POST /update<br><small class=\"diagram-muted\">apply + persist</small></div><span class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</span><div class=\"diagram-box diagram-accent\">SSE push<br><small class=\"diagram-muted\">to all peers</small></div></div><div class=\"lane\"><span class=\"diagram-pill warn\">Agent edit</span><div class=\"diagram-node\">Action writes SQL<br><small class=\"diagram-muted\">bumps updatedAt</small></div><span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</span><div class=\"diagram-box\" data-rough>Lead client<br><small class=\"diagram-muted\">setContent into Y.Doc</small></div><span class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</span><div class=\"diagram-box diagram-accent\">POST /update<br><small class=\"diagram-muted\">re-enters Yjs &middot; SSE push</small></div></div></div>",
+  "css": ".diagram-collab{display:flex;flex-direction:column;gap:14px}.diagram-collab .lane{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.diagram-collab .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## त्वरित प्रारंभ {#quickstart}
+
+### 1. पैकेज स्थापित करें
+
+```bash
+pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap @tiptap/core
+```
+
+### 2. Vite optimDeps
+
+Vite को डेव के दौरान असंगत तरीकों से टिपटैप को फिर से बंडल करने से रोकता है:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [reactRouter()],
+  optimizeDeps: {
+    include: [
+      "yjs",
+      "y-protocols/awareness",
+      "@tiptap/core",
+      "@tiptap/extension-collaboration",
+      "@tiptap/extension-collaboration-caret",
+      "@tiptap/y-tiptap",
+    ],
+  },
+});
+```
+
+### 3. कोलाब सर्वर प्लगइन जोड़ें
+
+हमेशा `resourceType` को पंजीकृत साझा करने योग्य संसाधन के नाम पर सेट करें
+`registerShareableResource` के माध्यम से। इसके बिना, कोलाब पुश इवेंट वितरित किए जाते हैं
+दस्तावेज़-स्तरीय दायरे के बिना सभी प्रमाणित उपयोगकर्ताओं और सर्वर के लिए
+एक बार की चेतावनी लॉग करता है।
+
+```ts
+// server/plugins/collab.ts
+import { createCollabPlugin } from "@agent-native/core/server";
+
+export default createCollabPlugin({
+  table: "documents",
+  contentColumn: "content",
+  idColumn: "id",
+  resourceType: "document", // required for access-scoped event delivery
+});
+```
+
+### 4. क्लाइंट हुक का उपयोग करें
+
+```ts
+import {
+  useCollaborativeDoc,
+  emailToColor,
+  emailToName,
+} from "@agent-native/core/client";
+
+const TAB_ID = generateTabId(); // or Math.random().toString(36)
+
+const { ydoc, awareness, isLoading, activeUsers, agentActive, agentPresent } =
+  useCollaborativeDoc({
+    docId: documentId,
+    requestSource: TAB_ID,
+    user: {
+      name: emailToName(session.email),
+      email: session.email,
+      color: emailToColor(session.email),
+    },
+  });
+```
+
+### 5. टिपटैप एक्सटेंशन जोड़ें
+
+```ts
+import Collaboration from "@tiptap/extension-collaboration";
+import CollaborationCaret from "@tiptap/extension-collaboration-caret";
+
+const editor = useEditor({
+  extensions: [
+    StarterKit.configure({ history: false }), // Yjs owns undo
+    Collaboration.configure({ document: ydoc }),
+    CollaborationCaret.configure({
+      provider: { awareness },
+      user: { name, color },
+    }),
+  ],
+  // Do NOT pass content here — Yjs owns the content
+});
+```
+
+### 6. पहले लोड पर बीज (यदि सामग्री मौजूद है)
+
+सहयोग एक्सटेंशन `content` प्रोप से ऑटो-सीड नहीं होता है। यदि
+Y.Doc खाली है और दस्तावेज़ में मौजूदा सामग्री है, इसे सीड करें:
+
+```ts
+useEffect(() => {
+  if (!ydoc || !editor || !isLoaded) return;
+  const fragment = ydoc.getXmlFragment("default");
+  if (fragment.length === 0 && initialContent) {
+    editor.commands.setContent(initialContent);
+  }
+}, [ydoc, editor, isLoaded]);
+```
+
+उपयोगकर्ता की पहचान सत्र ईमेल से ली गई है। फ़्रेमवर्क लगातार कर्सर रंग उत्पन्न करने और ईमेल पते से नाम प्रदर्शित करने के लिए `emailToColor()` और `emailToName()` सहायक प्रदान करता है।
+
+## टिप्पणियाँ {#comments}
+
+टेम्प्लेट दस्तावेज़ों पर थ्रेडेड चर्चाओं के साथ एक टिप्पणी प्रणाली जोड़ सकते हैं। सामग्री टेम्पलेट की टिप्पणी प्रणाली में पूर्ण कार्यान्वयन शामिल है:
+
+- `document_comments` SQL तालिका (थ्रेड्स, उत्तर, हल की गई स्थिति)
+- `/api/comments/:id` पर अद्यतन/हटाने के लिए सामग्री टेम्पलेट का REST मार्ग; बनाएं और सूचीबद्ध करें `add-comment` / `list-comments` actions के माध्यम से चलाएं। कस्टम टेम्प्लेट कोर `POST /_agent-native/collab/:docId/search-replace` रूट के विरुद्ध अपने स्वयं के समकक्ष समापन बिंदु लागू करते हैं।
+- थ्रेडेड व्यू और उत्तर UI के साथ टिप्पणियाँ साइडबार
+- धागे को हल/अनसुलझा करें
+- **एआई को भेजें** बटन - टिप्पणी थ्रेड संदर्भ को `sendToAgentChat()` के माध्यम से एजेंट चैट पर भेजता है
+- एजेंट actions: `list-comments`, `add-comment`
+- Notion टिप्पणी सिंक: द्विदिशात्मक पुल/पुश के लिए `sync-notion-comments` क्रिया
+
+## सहयोग मार्ग {#collab-routes}
+
+सभी कोलाब रूट कोलाब प्लगइन द्वारा `/_agent-native/collab/` के तहत ऑटो-माउंटेड हैं:
+
+| मार्ग                         | उद्देश्य                                            |
+| ----------------------------- | --------------------------------------------------- |
+| `GET /:docId/state`           | पूर्ण Y.Doc स्थिति प्राप्त करें (बेस64)             |
+| `POST /:docId/update`         | क्लाइंट Yjs अपडेट लागू करें                         |
+| `POST /:docId/text`           | पूर्ण पाठ प्रतिस्थापन लागू करें (अंतर-आधारित)       |
+| `POST /:docId/search-replace` | Y.XmlFragment में सर्जिकल खोज/प्रतिस्थापन           |
+| `POST /:docId/awareness`      | कर्सर/उपस्थिति स्थिति को सिंक करें                  |
+| `GET /:docId/users`           | किसी दस्तावेज़ पर सक्रिय उपयोगकर्ताओं की सूची बनाएं |
+
+## एजेंट कार्रवाई संपादित करें {#edit-document}
+
+सामग्री टेम्पलेट की `edit-document` क्रिया एजेंटों द्वारा सहयोगात्मक मोड में दस्तावेज़ों में परिवर्तन करने का प्राथमिक तरीका है:
+
+```bash
+# Single edit
+pnpm action edit-document --id doc123 --find "old text" --replace "new text"
+
+# Batch edits
+pnpm action edit-document --id doc123 --edits '[{"find":"old","replace":"new"}]'
+
+# Delete text
+pnpm action edit-document --id doc123 --find "delete me" --replace ""
+```
+
+---
+
+## उपस्थिति किट {#presence-kit}
+
+उपस्थिति किट मौजूदा जागरूकता परत के शीर्ष पर लाइवब्लॉक/फिग्मा-ग्रेड लाइव-कर्सर और चयन प्राइमेटिव प्रदान करती है।
+
+केंद्रित ब्राउज़र उपपथ से क्लाइंट-साइड उपस्थिति और संपादक UI आयात करें:
+
+```ts
+import {
+  PresenceBar,
+  LiveCursorOverlay,
+  RemoteSelectionRings,
+  useCollaborativeDoc,
+  usePresence,
+} from "@agent-native/core/client/collab";
+```
+
+सर्वर-साइड एजेंट उपस्थिति सहायक निम्न-स्तरीय सहयोग पैकेज में रहते हैं:
+
+```ts
+import {
+  agentEnterDocument,
+  agentLeaveDocument,
+  agentUpdateSelection,
+} from "@agent-native/core/collab";
+```
+
+### सार्वजनिक API {#presence-public-api}
+
+| API                                                 | उद्देश्य                                                                                                                                               |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `useCollaborativeDoc(options)`                      | स्थिर `Y.Doc` और जागरूकता उदाहरण बनाता है, राज्य-वेक्टर सिंक, SSE फास्ट-पाथ, पोलिंग फ़ॉलबैक, सक्रिय उपयोगकर्ता और एजेंट उपस्थिति फ़्लैग को संभालता है। |
+| `usePresence(awareness, localClientId)`             | दूरस्थ प्रतिभागियों को प्राप्त करता है और कर्सर, चयन, व्यूपोर्ट, या टूल मोड जैसे मनमाने स्थानीय जागरूकता क्षेत्रों को प्रकाशित करता है।                |
+| `<PresenceBar>`                                     | वैकल्पिक अवतार-क्लिक फॉलो मोड वायरिंग के साथ सक्रिय सहयोगियों और एआई एजेंट को प्रस्तुत करता है।                                                        |
+| `<LiveCursorOverlay>`                               | सामान्यीकृत 0-1 निर्देशांक से एक स्थित कंटेनर पर दूरस्थ कर्सर लेबल प्रस्तुत करता है।                                                                   |
+| `<RemoteSelectionRings>`                            | आपके ऐप द्वारा हल किए गए चयनित DOM तत्वों के चारों ओर रंगीन छल्ले और लेबल प्रस्तुत करता है।                                                            |
+| `useFollowUser(options)`                            | जब अनुसरण किया गया प्रतिभागी व्यूपोर्ट परिवर्तन प्रकाशित करता है तो कॉलबैक शुरू हो जाता है।                                                            |
+| `toNormalized()` / `fromNormalized()`               | पॉइंटर निर्देशांक को सामान्यीकृत कंटेनर निर्देशांक से/में कनवर्ट करें।                                                                                 |
+| `dedupeCollabUsersByEmail()`                        | प्रति खुले टैब में एक उपयोगकर्ता को एक बार दिखाए बिना कस्टम अवतार स्टैक बनाएं।                                                                         |
+| `useCollaborativeMap()` / `useCollaborativeArray()` | Y.Map/Y.Array संरचित सहयोग के लिए क्लाइंट हुक। जब तक कोई टेम्प्लेट सटीक उत्पाद पैटर्न साबित न कर दे, तब तक निचले स्तर का ही व्यवहार करें।              |
+
+`UseCollaborativeDocOptions`:
+
+| विकल्प                | विवरण                                                                                     |
+| --------------------- | ----------------------------------------------------------------------------------------- |
+| `docId`               | हुक को अक्षम करने के लिए दस्तावेज़ आईडी, या `null`।                                       |
+| `pollInterval`        | पोल अंतराल जब SSE अनुपलब्ध है। डिफ़ॉल्ट: `2000`.                                          |
+| `pollIntervalWithSse` | धीमा मतदान अंतराल जबकि SSE स्वस्थ है। डिफ़ॉल्ट: `12000`.                                  |
+| `pauseWhenHidden`     | छिपे रहने पर दूरस्थ अद्यतन/उपस्थिति मतदान को रोकें। डिफ़ॉल्ट: `true`.                     |
+| `baseUrl`             | कोलैब एंडपॉइंट उपसर्ग. डिफ़ॉल्ट: `/_agent-native/collab`.                                 |
+| `requestSource`       | स्थिर टैब/स्रोत आईडी का उपयोग स्वयं-उत्पन्न ताज़ा शोर को अनदेखा करने के लिए किया जाता है। |
+| `user`                | `{ name, email, color }` कर्सर और उपस्थिति UI में दिखाया गया है।                          |
+
+`UseCollaborativeDocResult`:
+
+| फ़ील्ड         | विवरण                                                                     |
+| -------------- | ------------------------------------------------------------------------- |
+| `ydoc`         | वर्तमान `docId` के लिए स्थिर `Y.Doc`।                                     |
+| `awareness`    | Yjs जागरूकता उदाहरण का उपयोग कर्सर, चयन और फ़ॉलो मोड द्वारा किया जाता है। |
+| `isLoading`    | प्रारंभिक सर्वर स्थिति अभी भी लोड हो रही है।                              |
+| `isSynced`     | हुक ने सर्वर स्थिति को पकड़ लिया है।                                      |
+| `activeUsers`  | जागरूकता से मानव सहयोगी।                                                  |
+| `agentActive`  | एजेंट अभी सक्रिय रूप से संपादन कर रहा है।                                 |
+| `agentPresent` | एजेंट के पास इस दस्तावेज़ के लिए एक जागरूकता प्रविष्टि है।                |
+
+### तेज़ जागरूकता {#fast-awareness}
+
+जागरूकता स्थिति में परिवर्तन अब 2 सेकंड मतदान चक्र के बजाय ~150ms पर प्रसारित होता है:
+
+- **क्लाइंट → सर्वर**: `setPresence()` या `awareness.setLocalStateField()` पर कोई भी कॉल 150ms के भीतर एक थ्रॉटल POST को `/_agent-native/collab/:docId/awareness` पर ट्रिगर करता है, जिससे एक अनुरोध में तेजी से बदलाव होते हैं।
+- **सर्वर → क्लाइंट**: `postAwareness` हैंडलर भंडारण के बाद एक `AWARENESS_CHANGE_EVENT` उत्सर्जित करता है। `/_agent-native/poll-events` SSE स्ट्रीम इन घटनाओं को पुश-शैली में कनेक्टेड साथियों तक अग्रेषित करती है। केवल-मतदान परिनियोजन काम करना जारी रखता है - कर्सर त्रुटियों के बिना मतदान ताल में गिरावट करते हैं।
+
+### `usePresence(awareness, localClientId)` {#use-presence}
+
+दूरस्थ प्रतिभागियों की एक प्रतिक्रियाशील सूची और स्थानीय उपस्थिति पेलोड के लिए एक सेटर लौटाता है:
+
+```ts
+import { usePresence } from "@agent-native/core/client";
+
+const { others, setPresence } = usePresence(awareness, ydoc?.clientID);
+
+// Publish cursor position (normalized 0–1)
+setPresence({ cursor: { x: 0.4, y: 0.7 }, selection: "#hero" });
+
+// others: OtherPresence[]
+// {
+//   clientId: number
+//   user: { name, email, color }
+//   presence: { cursor?, selection?, viewport?, ... }
+//   isAgent: boolean   ← true for AGENT_CLIENT_ID
+// }
+```
+
+एजेंट (AGENT_CLIENT_ID) `isAgent: true` के साथ प्रथम श्रेणी प्रतिभागी के रूप में प्रकट होता है। जब `agentUpdateSelection()` को सर्वर-साइड कहा जाता है, तो इसका चयन मेटाडेटा किसी अन्य भागीदार की तरह `usePresence` के माध्यम से प्रवाहित होता है।
+
+### `LiveCursorOverlay` {#live-cursor-overlay}
+
+दूरस्थ कर्सर को एक कंटेनर तत्व पर बिल्कुल स्थित लेबल के रूप में प्रस्तुत करता है:
+
+```tsx
+import { LiveCursorOverlay } from "@agent-native/core/client";
+
+// cursor positions stored as { x, y } normalized 0–1 under presence.cursor
+<div ref={containerRef} style={{ position: "relative" }}>
+  {content}
+  <LiveCursorOverlay
+    others={others} // from usePresence
+    containerRef={containerRef}
+    cursorKey="cursor" // key in presence payload (default: "cursor")
+  />
+</div>;
+```
+
+एजेंट का कर्सर एक चमकदार आइकन के साथ स्पष्ट रूप से प्रस्तुत होता है। 120ms पर सुचारू CSS ट्रांज़िशन के साथ 10 सेकंड की निष्क्रियता के बाद कर्सर फीके पड़ जाते हैं।
+
+### `RemoteSelectionRings` {#remote-selection-rings}
+
+दूरस्थ रूप से चयनित तत्वों पर रंगीन आउटलाइन रिंग + नाम टैग प्रस्तुत करता है:
+
+```tsx
+import { RemoteSelectionRings } from "@agent-native/core/client";
+
+<div ref={containerRef} style={{ position: "relative" }}>
+  {content}
+  <RemoteSelectionRings
+    others={others}
+    selectionKey="selection" // key in presence payload (default: "selection")
+    resolveRect={(descriptor) =>
+      document.querySelector(descriptor)?.getBoundingClientRect() ?? null
+    }
+    containerRef={containerRef}
+  />
+</div>;
+```
+
+### `useFollowUser` {#follow-user}
+
+जब भी निम्नलिखित प्रतिभागी का व्यूपोर्ट बदलता है तो कॉलबैक शुरू करें:
+
+```ts
+import { useFollowUser } from "@agent-native/core/client";
+
+const { isFollowing, stopFollowing } = useFollowUser({
+  others,
+  followingId, // null to stop following
+  viewportKey: "viewport",
+  onViewport: (vp) => {
+    if (vp.fileId) setActiveFileId(vp.fileId);
+    if (vp.zoom) setZoom(vp.zoom);
+  },
+});
+```
+
+प्रतिभागी अपना व्यूपोर्ट `setPresence({ viewport: { fileId, zoom } })` के साथ प्रकाशित करते हैं।
+
+### `PresenceBar` फॉलो-मोड प्रॉप्स {#presence-bar-follow}
+
+`PresenceBar` घटक अब वैकल्पिक फॉलो-मोड प्रॉप्स स्वीकार करता है:
+
+```tsx
+<PresenceBar
+  activeUsers={activeUsers}
+  agentActive={agentActive}
+  onAvatarClick={(user) => {
+    // user is null for the agent avatar
+    const email = user?.email ?? "agent@system";
+    setFollowing((prev) => (prev === email ? null : email));
+  }}
+  followingEmail={followingEmail} // highlighted avatar + "Following X" chip
+/>
+```
+
+### सामान्यीकृत समन्वय सहायक {#norm-coords}
+
+```ts
+import { toNormalized, fromNormalized } from "@agent-native/core/client";
+
+// In a pointer event handler:
+const norm = toNormalized(
+  e.clientX,
+  e.clientY,
+  container.getBoundingClientRect(),
+);
+setPresence({ cursor: norm });
+
+// In a cursor renderer:
+const px = fromNormalized(norm, container.getBoundingClientRect());
+```
+
+### एजेंट कर्सर प्लंबिंग {#agent-cursor}
+
+सर्वर-साइड actions यह प्रकाशित करने के लिए `agentUpdateSelection()` पर कॉल करें कि एजेंट कहां काम कर रहा है। डिज़ाइन टेम्पलेट के `edit-design` और `generate-design` actions इसे स्वचालित रूप से कॉल करते हैं। अन्य टेम्पलेट भी ऐसा ही कर सकते हैं:
+
+```ts
+import {
+  agentEnterDocument,
+  agentLeaveDocument,
+  agentUpdateSelection,
+} from "@agent-native/core/collab";
+
+agentEnterDocument(docId);
+agentUpdateSelection(docId, {
+  selection: "#target-element",
+  editingFile: "index.html",
+});
+try {
+  // ... perform edits ...
+} finally {
+  agentLeaveDocument(docId);
+}
+```
+
+चयन मेटाडेटा `usePresence` के माध्यम से कनेक्टेड क्लाइंट पर `other.presence.selection` के रूप में प्रवाहित होता है।
+
+---
+
+## रूट टेबल {#routes}
+
+सभी रूट कोलाब द्वारा `/_agent-native/collab/` के तहत ऑटो-माउंटेड हैं
+प्लगइन:
+
+| मार्ग                         | उद्देश्य                                                                |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| `GET /:docId/state`           | पूर्ण Y.Doc स्थिति (बेस64)। अंतर के लिए `?stateVector=` स्वीकार करता है |
+| `POST /:docId/update`         | क्लाइंट Yjs अद्यतन (बेस64) लागू करें। डिफ़ॉल्ट रूप से अधिकतम 2 एमबी     |
+| `POST /:docId/text`           | पूर्ण पाठ प्रतिस्थापन लागू करें (अंतर-आधारित)                           |
+| `POST /:docId/search-replace` | Y.XmlFragment में सर्जिकल खोज/प्रतिस्थापन                               |
+| `POST /:docId/json`           | Y.Map/Y.Array पर पूर्ण JSON अंतर लागू करें                              |
+| `GET /:docId/json`            | वर्तमान JSON स्थिति पढ़ें                                               |
+| `POST /:docId/patch`          | सर्जिकल JSON पैच ऑप्स लागू करें (अपसर्ट/निकालें/पुनः व्यवस्थित करें)    |
+| `POST /:docId/awareness`      | कर्सर/उपस्थिति स्थिति को सिंक करें                                      |
+| `GET /:docId/users`           | किसी दस्तावेज़ पर सक्रिय उपयोगकर्ताओं की सूची बनाएं                     |
+
+## परिवहन और प्रदर्शन {#transport}
+
+| संपत्ति                      | मान                                                                       |
+| ---------------------------- | ------------------------------------------------------------------------- |
+| अपडेट डिबाउंस                | ~80 एमएस (`Y.mergeUpdates` के माध्यम से तीव्र कीस्ट्रोक्स को जोड़ता है)   |
+| मतदान अंतराल (कोई SSE नहीं)  | 2 सेकंड (`pollInterval` के माध्यम से कॉन्फ़िगर करने योग्य)                |
+| मतदान अंतराल (SSE स्वस्थ)    | ~12 सेकंड (`pollIntervalWithSse` के माध्यम से कॉन्फ़िगर करने योग्य)       |
+| राज्य-वेक्टर लाने की आवृत्ति | पुनः कनेक्ट होने पर, रिंग-बफ़र गैप, या हर 15वें मतदान चक्र पर             |
+| त्रुटि पर पीछे हटना          | घबराहट के साथ घातीय, कैप ~15 एस                                           |
+| अधिकतम पेलोड (लिखता है)      | 2 एमबी डिफ़ॉल्ट, `maxPayloadBytes` के माध्यम से कॉन्फ़िगर करने योग्य      |
+| संघनन सीमा                   | संग्रहीत ब्लॉब > 4× ताजा एन्कोडिंग टॉम्बस्टोन कॉम्पैक्ट को ट्रिगर करता है |
+| प्रति-लिखित डीबी पढ़ता है    | 1 (CAS संस्करण केवल `persistMergedState` के अंदर पढ़ा जाता है)            |
+
+## सुरक्षा {#security}
+
+### हमेशा `resourceType` सेट करें
+
+```ts
+createCollabPlugin({
+  resourceType: "document", // the name passed to registerShareableResource
+});
+```
+
+`resourceType` के बिना प्लगइन एक चेतावनी लॉग करता है और कोलाब पुश प्रसारित करता है
+दस्तावेज़-स्तर के बिना परिनियोजन पर सभी प्रमाणित उपयोगकर्ताओं के लिए ईवेंट
+स्कोपिंग। गैर-मालिक राज्य-वेक्टर कैच-अप (सुरक्षित लेकिन उच्चतर
+विलंबता) चाहे `resourceType` सेट हो।
+
+### पहुंच जांच
+
+सभी सहयोग मार्गों को प्रमाणीकरण की आवश्यकता होती है। जब `resourceType` सेट हो, तो पढ़ें
+के उपयोग से कम से कम दर्शक पहुंच की आवश्यकता होती है और लेखन के लिए संपादक पहुंच की आवश्यकता होती है।
+साझाकरण प्रणाली के समान `resolveAccess` / `assertAccess` सहायक। ए 404
+(403 नहीं) लौटाया जाता है।
+
+### पेलोड सीमा
+
+मार्ग लिखें (`update`, `text`, `json`, `patch`, `search-replace`) अस्वीकार करें
+HTTP 413 के साथ कॉन्फ़िगर की गई सीमा से अधिक पेलोड। डिफ़ॉल्ट 2 एमबी है।
+प्रति-प्लगइन ओवरराइड करें:
+
+```ts
+createCollabPlugin({
+  resourceType: "document",
+  maxPayloadBytes: 512 * 1024, // 512 KB
+});
+```
+
+### जागरूकता का दायरा
+
+जागरूकता मार्ग (`POST /awareness`, `GET /users`) उसी के द्वारा निर्धारित हैं
+पढते ही पहुंच की जांच करें - जिस उपयोगकर्ता के पास दर्शक पहुंच का अभाव है वह यह नहीं जान सकता कि और कौन है
+एक दस्तावेज़ संपादित कर रहा है।
+
+## पैटर्न {#patterns}
+
+### संरचित डेटा के लिए ग्रैन्युलर सर्वर-साइड मर्ज
+
+संरचित दस्तावेज़ों (स्लाइड डेक, फॉर्म बिल्डर्स, डिज़ाइन फ़ाइलें) के लिए Yjs
+जब दो एजेंट या उपयोगकर्ता इसे दोबारा लिखते हैं तो बॉडी कोलाब मॉडल में टकराव हो सकता है
+शीर्ष-स्तरीय रिकॉर्ड एक साथ। सुरक्षित पैटर्न **दानेदार सर्वर-साइड
+मर्ज**: एक ऐसी कार्रवाई को परिभाषित करें जो लक्षित संचालन के एक सेट को स्वीकार करती है और
+उन्हें परमाणु रूप से लागू करता है, इसलिए विभिन्न वस्तुओं पर समवर्ती संपादन दोनों जीवित रहते हैं।
+
+**स्लाइड्स (`patch-deck`)** - पूरे डेक को बदलने के बजाय प्रत्येक पर JSON
+परिवर्तन, क्रिया प्रति-स्लाइड संचालन स्वीकार करती है:
+
+```ts
+// Conceptual patch-deck action shape
+type PatchDeckOp =
+  | { type: "patch"; slideId: string; fields: Partial<SlideFields> }
+  | { type: "add"; position: number; slide: SlideData }
+  | { type: "delete"; slideId: string }
+  | { type: "reorder"; slideId: string; newIndex: number };
+```
+
+दो उपयोगकर्ता अलग-अलग स्लाइड संपादित कर रहे हैं, दोनों सफल होते हैं;
+डेक स्तर.
+
+**फॉर्म (`patch-form-fields`)** - अपसर्ट/रिमूव/रीऑर्डर के साथ फील्ड-स्तरीय मर्ज
+ऑप्स ताकि अलग-अलग फॉर्म फ़ील्ड में समवर्ती संपादन दोनों बने रहें।
+
+इस पैटर्न का उपयोग तब करें जब:
+
+- दस्तावेज़ संरचित है (कंटेनर के अंदर आइटम)।
+- समवर्ती संपादन विभिन्न आइटमों को लक्षित करते हैं।
+- बॉडी कोलैब (Yjs `Y.XmlFragment`) अत्यधिक या अनुपयुक्त है।
+
+बॉडी कोलैब (Y.XmlFragment + टिपटैप) का उपयोग करें जब:
+
+- दस्तावेज़ फ्री-फॉर्म रिच टेक्स्ट है जहां किसी भी क्षेत्र को संपादित किया जा सकता है।
+- कर्सर-स्तरीय CRDT मर्ज मायने रखता है।
+
+### सहयोगात्मक पूर्ववत स्कोपिंग (Y.UndoManager)
+
+डिज़ाइन टेम्प्लेट स्थानीय स्तर पर पूर्ववत/पुनः करने के लिए `Y.UndoManager` का उपयोग करता है
+उपयोगकर्ता के स्वयं के संपादन। दूरस्थ सहकर्मी संपादन और एजेंट संपादन कभी भी a
+उपयोगकर्ता का Cmd+Z.
+
+```ts
+import * as Y from "yjs";
+
+const LOCAL_EDIT_ORIGIN = "local";
+
+const undoManager = new Y.UndoManager(ydoc.getText("content"), {
+  trackedOrigins: new Set([LOCAL_EDIT_ORIGIN]),
+  captureTimeout: 800, // coalesce rapid slider drags into one undo step
+});
+
+// Wrap local edits with the tracked origin
+ydoc.transact(() => {
+  // apply local style change
+}, LOCAL_EDIT_ORIGIN);
+
+// Undo/redo — only reverses LOCAL_EDIT_ORIGIN transactions
+undoManager.undo(); // Cmd+Z
+undoManager.redo(); // Shift+Cmd+Z
+```
+
+मुख्य गुण:
+
+- `trackedOrigins` एक `Set` होना चाहिए। केवल मिलान मूल वाले ट्रांसactions
+  पूर्ववत स्टैक में कैप्चर किए गए हैं।
+- दूरस्थ अपडेट (मूल `"remote"`) और एजेंट अपडेट (मूल `"agent"`) हैं
+  कभी कैप्चर नहीं किया गया।
+- सक्रिय दस्तावेज़ में परिवर्तन होने पर प्रबंधक को पुनः बनाएँ और उसका निपटान करें; बासी
+  प्रबंधक ऐसे संदर्भ रखते हैं जो असीमित रूप से बढ़ सकते हैं।
+
+## ज्ञात सीमाएं {#limitations}
+
+```an-callout
+{
+  "tone": "risk",
+  "body": "**Same-region simultaneous rewrite is last-write-wins.** If the agent rewrites a passage while a human has unsaved edits in the *exact same region*, the lead-client snapshot can clobber the in-flight human edit. Edits in different regions always merge cleanly via the CRDT. For structured documents, use granular server-side merge to sidestep this entirely."
+}
+```
+
+- **एक ही क्षेत्र का एक साथ पुनर्लेखन LWW है** - यदि एजेंट फिर से लिखता है
+  मार्ग और एक मानव के संपादन ठीक उसी क्षेत्र में हैं,
+  लीड-क्लाइंट स्नैपशॉट मानव के उड़ान में परिवर्तनों को अधिलेखित कर सकता है। में संपादन
+  विभिन्न क्षेत्र CRDT के माध्यम से सही ढंग से विलय होते हैं। ग्रैन्युलर सर्वर-साइड मर्ज
+  (ऊपर देखें) संरचित दस्तावेज़ों के लिए इसे टालता है।
+- **सर्वर रहित पर इन-प्रोसेस राइट लॉक** — `_writeLocks` मैप है
+  प्रक्रिया-स्थानीय। समवर्ती अनुरोध अलग-अलग सर्वर रहित पर आ रहे हैं
+  आह्वान SQL CAS परत (आशावादी संगामिति) पर क्रमबद्ध होते हैं
+  इन-मेमोरी लॉक की तुलना में। यह सुरक्षित है लेकिन इसका मतलब है
+  सर्वर रहित को अधिक CAS पुनः प्रयास देखने को मिल सकते हैं।
+- **जागरूकता प्रति-प्रक्रिया है** - स्मृति में जागरूकता का भण्डार है
+  प्रक्रिया-स्थानीय। सर्वर रहित/बहु-प्रक्रिया परिनियोजन में आंशिक जागरूकता देखी जाती है
+  प्रति मंगलाचरण बताएं। ग्राहकों को अभी भी प्रत्येक
+  मतदान चक्र, इसलिए उपस्थिति संकेतक एक मतदान अंतराल के भीतर अद्यतन होते हैं।
+
+## उपस्थिति {#presence}
+
+`useCollaborativeDoc` हुक रिटर्न:
+
+- `activeUsers` - सभी साथियों के लिए `CollabUser` (नाम, ईमेल, रंग) की सरणी
+  वर्तमान में दस्तावेज़ में (जागरूकता से प्राप्त)।
+- `agentActive` - एजेंट द्वारा संपादन करने के बाद संक्षेप में `true` (ए के लिए उपयोग करें
+  क्षणिक दृश्य संकेतक).
+- `agentPresent` - `true` जबकि एजेंट के पास सक्रिय जागरूकता प्रविष्टि है
+  (टिकाऊ उपस्थिति दिल की धड़कन).
+
+से `emailToColor(email)` और `emailToName(email)` का उपयोग करें
+`@agent-native/core/client` सुसंगत कर्सर रंग और डिस्प्ले उत्पन्न करने के लिए
+ईमेल पते से नाम।
+
+`activeUsers` के साथ प्रस्तुत एक `PresenceBar` जीवित मानव और एजेंट को दर्शाता है
+सहयोगी। प्रति-स्लाइड उपस्थिति (कौन से उपयोगकर्ता किसी दी गई स्लाइड को देख रहे हैं)
+समान जागरूकता स्थिति के शीर्ष पर परतें।
+
+## संबंधित दस्तावेज़ {#related}
+
+- [Real-Time Sync](/docs/client#usedbsync) - `useDbSync` + `useChangeVersion`
+  प्रणाली जो `updatedAt` बम्प ड्राइविंग एडिटर समाधान प्रदान करती है।
+- [Security](/docs/security) — `registerShareableResource`, `resolveAccess`,
+  और `resourceType` द्वारा संदर्भित एक्सेस मॉडल के लिए `assertAccess`।
+- [Sharing](/docs/sharing) - दस्तावेज़ कैसे साझा किए जाते हैं और पहुंच कैसे प्रदान की जाती है।
+- [Template: Content](/docs/template-content) — का संदर्भ कार्यान्वयन
+  सहयोगात्मक रिच-टेक्स्ट संपादन।
+- [Template: Slides](/docs/template-slides) — के लिए बारीक `patch-deck` क्रिया
+  संरचित समवर्ती संपादन।
+- [Template: Forms](/docs/template-forms) — फ़ील्ड-स्तरीय `patch-form-fields`
+  सर्वर-साइड मर्ज।
+- [Template: Design](/docs/template-design) — `Y.UndoManager` पूर्ववत करें/फिर से करें स्कोप
+  स्थानीय उपयोगकर्ता संपादनों के लिए।