docs: add llms tips

Author: zxch3n

pages/docs/tutorial/tips.md

@@ -256,3 +256,12 @@ This approach allows you to:
 The mapping is stored within the document, so it automatically synchronizes across all peers and persists with the document's state.
 
 </details>
+
+---
+
+##### You can use https://loro.dev/llms-full.txt to prompt your AI
+
+When working with AI assistants or language models on Loro-related tasks, you can use these URLs to provide comprehensive context about Loro's capabilities and API:
+
+- `https://loro.dev/llms-full.txt` - All the documentation in one file
+- `https://loro.dev/llms.txt` - An overview of Loro website

public/llms-full.txt

@@ -1988,6 +1988,195 @@ doc.import(docB.export({ mode: "update" }));
     - You can use `doc.getMap("user." + userId)` instead of `doc.getMap("user").getOrCreateContainer(userId, new LoroMap())` to avoid this problem.
 </details>
 
+---
+
+##### Use redaction to safely share document history
+
+There are times when users might accidentally paste sensitive information (like API keys, passwords, or personal data) into a collaborative document. When this happens, you need a way to remove just that sensitive content from the document history without compromising the rest of the document's integrity.
+
+<details>
+<summary>How to safely redact sensitive content</summary>
+
+Loro provides a `redactJsonUpdates` function that allows you to selectively redact operations within specific version ranges.
+
+For example, if a user accidentally pastes a password or API key into a document:
+
+```typescript
+const doc = new LoroDoc();
+doc.setPeerId("1");
+
+// Create some content to be redacted
+const text = doc.getText("text");
+text.insert(0, "Sensitive information");
+doc.commit();
+
+const map = doc.getMap("map");
+map.set("password", "secret123");
+map.set("public", "public information");
+doc.commit();
+
+// Export JSON updates
+const jsonUpdates = doc.exportJsonUpdates();
+
+// Define version range to redact (redact the text content)
+const versionRange = {
+  "1": [0, 21]  // Redact the "Sensitive information"
+};
+
+// Apply redaction
+const redactedJson = redactJsonUpdates(jsonUpdates, versionRange);
+
+// Create a new document with redacted content
+const redactedDoc = new LoroDoc();
+redactedDoc.importJsonUpdates(redactedJson);
+
+// The text content is now redacted with replacement characters
+console.log(redactedDoc.getText("text").toString()); 
+// Outputs: "���������������������"
+
+// You can also redact specific map entries
+const versionRange2 = {
+  "1": [21, 22]  // Redact the "secret123" password
+};
+
+const redactedJson2 = redactJsonUpdates(jsonUpdates, versionRange2);
+const redactedDoc2 = new LoroDoc();
+redactedDoc2.importJsonUpdates(redactedJson2);
+
+console.log(redactedDoc2.getMap("map").get("password")); // null
+console.log(redactedDoc2.getMap("map").get("public"));   // "public information"
+```
+
+This approach is safer than manually editing document content because:
+
+1. It maintains document structure and CRDT consistency
+2. It keeps key metadata like operation IDs and dependencies intact
+3. It allows concurrent editing to continue working after redaction
+4. It selectively redacts only specific operations, not the entire document
+
+The redaction process follows these rules:
+- Preserves delete, tree move, and list move operations
+- Replaces text insertion content with Unicode replacement characters '�' 
+- Substitutes list and map insert values with null
+- Maintains structure of child containers
+- Replaces text mark values with null
+- Preserves map keys and text annotation keys
+
+**Important**: Your application needs to ensure that all peers receive the redacted version, otherwise the original document with sensitive information will still exist on other peers.
+
+</details>
+
+---
+
+##### Use shallow snapshots to completely remove old history
+
+When you need to completely remove ALL history older than a certain version point, shallow snapshots provide the solution.
+
+<details>
+<summary>How to remove old history with shallow snapshots</summary>
+
+Shallow snapshots create a new document that preserves the current state but completely eliminates all history before a specified point, similar to Git's shallow clone functionality.
+
+```typescript
+const doc = new LoroDoc();
+doc.setPeerId("1");
+
+// Old history - will be completely removed
+const text = doc.getText("text");
+text.insert(0, "This document has a long history with many edits");
+doc.commit();
+text.insert(0, "Including some potentially sensitive information. ");
+doc.commit();
+
+// More recent history - will be preserved
+text.delete(11, 55); // Remove the middle part
+text.insert(11, "with sanitized history");
+doc.commit();
+
+// Create a sanitized version that removes ALL history before current point
+const sanitizedSnapshot = doc.export({ 
+  mode: "shallow-snapshot", 
+  frontiers: doc.oplogFrontiers() 
+});
+
+// Create a new document from the sanitized snapshot
+const sanitizedDoc = new LoroDoc();
+sanitizedDoc.import(sanitizedSnapshot);
+
+// The document has the final state
+console.log(sanitizedDoc.getText("text").toString());
+// Outputs: "Including with sanitized history"
+
+// But ALL history before the snapshot point is completely removed
+console.log(sanitizedDoc.isShallow()); // true
+console.log(sanitizedDoc.shallowSinceFrontiers()); // Shows the starting point
+```
+
+This approach is useful for:
+
+1. Completely removing all old history that might contain various sensitive information
+2. Significantly reducing document size by eliminating unnecessary history
+3. Creating clean document instances after certain milestones
+4. Ensuring old operations cannot be recovered or examined
+
+Compared to redaction:
+- Shallow snapshots completely remove all operations before a version point
+- Redaction selectively replaces just specific content with placeholders
+
+**Important**: While both methods maintain future synchronization consistency, your application must distribute the sanitized document to all peers. Otherwise, the original document with sensitive information will still exist on other clients.
+
+**When to use each approach**:
+- Use **redaction** when you need to sanitize specific operations (like an accidental password paste) while preserving older history
+- Use **shallow snapshots** when you want to completely eliminate all history before a certain point
+
+</details>
+
+---
+
+##### You can store mappings between LoroDoc's peerIds and user IDs in the document itself
+
+Use `doc.subscribeFirstCommitFromPeer(listener)` to associate peer information with user identities when a peer first interacts with the document.
+
+<details>
+<summary>How to track peer-to-user mappings</summary>
+
+This functionality is essential for building user-centric features in collaborative applications. You often need bidirectional mapping between user IDs and peer IDs:
+
+- **Finding all edits by a user**: When you need to retrieve all document edits made by a specific user ID, you must first find all peer IDs associated with that user
+- **Showing edit attribution**: When displaying which user edited a piece of text, you need to map from the peer ID (stored in the operation) back to the user ID for display
+
+This hook provides an ideal point to associate peer information (such as author identity) with the document. The listener is triggered on the first commit from each peer, allowing you to store user metadata within the document itself.
+
+```typescript
+const doc = new LoroDoc();
+doc.setPeerId(0);
+doc.subscribeFirstCommitFromPeer((e) => {
+  doc.getMap("users").set(e.peer, "user-" + e.peer);
+});
+doc.getList("list").insert(0, 100);
+doc.commit();
+expect(doc.getMap("users").get("0")).toBe("user-0");
+```
+
+This approach allows you to:
+
+1. Automatically track which peers have contributed to the document
+2. Store user metadata (names, emails, etc.) alongside the document
+3. Build features like author attribution, presence indicators, or edit history
+
+The mapping is stored within the document, so it automatically synchronizes across all peers and persists with the document's state.
+
+</details>
+
+---
+
+##### You can use https://loro.dev/llms-full.txt to prompt your AI
+
+When working with AI assistants or language models on Loro-related tasks, you can use these URLs to provide comprehensive context about Loro's capabilities and API:
+
+- `https://loro.dev/llms-full.txt` - All the documentation in one file
+- `https://loro.dev/llms.txt` - An overview of Loro website
+
 
 # FILE: pages/docs/tutorial/map.md
 
@@ -2602,6 +2791,107 @@ of operations will converge to the same document state, obviating concerns about
 the order, duplication, or timing of operation delivery.
 
 
+# FILE: pages/docs/tutorial/ephemeral.md
+
+---
+keywords: "ephemeral, awareness, presence, collaborative"
+description: "How to use Loro's ephemeral store feature to implement user awareness and online status management in real-time collaboration."
+---
+
+# Ephemeral Store
+
+In real-time collaborative scenarios, Presence information is just as important as maintaining document consistency across peers through CRDTs. This includes information such as the current collaborator's username, mouse pointer position, or selected objects. We need a mechanism that doesn't persist in the CRDT Document but remains ephemeral, allowing collaborators to perceive each other's presence for better coordination and to avoid conflicts when multiple users edit the same object. This is why we've introduced the Ephemeral Store.
+
+![](/images/ephemeral.png)
+
+Since Ephemeral information is primarily used for real-time collaboration, we've chosen a simple yet effective approach. The Ephemeral Store is a timestamp-based, last-write-wins key-value store. Each entry maintains its own timestamp of the last update, enabling the system to send only the updated entry content rather than the complete current state.
+
+
+## Example
+
+```ts
+import {
+    EphemeralStore,
+    EphemeralListener,
+    EphemeralStoreEvent,
+} from "loro-crdt";
+
+const store = new EphemeralStore();
+// Set ephemeral data
+store.set("loro-prosemirror", {
+    anchor: ...,
+    focus: ...,
+    user: "Alice"
+});
+store.set("online-users", ["Alice", "Bob"]);
+
+expect(storeB.get("online-users")).toEqual(["Alice", "Bob"]);
+// Encode only the data for `loro-prosemirror`
+const encoded = store.encode("loro-prosemirror")
+
+store.subscribe((e: EphemeralStoreEvent) => {
+    // Listen to changes from `local`, `remote`, or `timeout` events
+});
+```
+
+## API
+
+- `constructor(timeout)`:
+  Creates a new EphemeralStore instance with an optional timeout parameter (default: 30000ms). The timeout determines how long ephemeral data remains valid before being automatically removed.
+
+- `set(key, value)`:
+  Sets a value for the specified key in the ephemeral store. If the key already exists, its value will be updated.
+
+- `get(key)`:
+  Retrieves the current value for the specified key, or returns `undefined` if the key doesn't exist.
+
+- `delete(key)`:
+  Removes the specified key and its associated value from the ephemeral store.
+
+- `getAllStates()`:
+  Returns all current key-value pairs in the ephemeral store.
+
+- `keys()`:
+  Returns an array of all keys currently in the ephemeral store.
+
+- `encode(key)`:
+  Encodes the value associated with the specified key into a binary format that can be transmitted to other peers.
+
+- `encodeAll()`:
+  Encodes all key-value pairs in the ephemeral store into a binary format.
+
+- `apply(bytes)`:
+  Applies encoded ephemeral data received from other peers to the local ephemeral store.
+
+- `subscribe((event: EphemeralStoreEvent)=>void)`:
+  Registers a listener function that will be called whenever the ephemeral store is updated, either from local changes, remote changes, or timeout events.
+  ```ts
+  interface EphemeralStoreEvent {
+    // The source of the event: local changes, imported from remote, or timeout expiration
+    by: "local" | "import" | "timeout";
+    // Array of keys that were newly added
+    added: string[];
+    // Array of keys that had their values updated
+    updated: string[];
+    // Array of keys that were removed
+    removed: string[];
+  }
+  ```
+
+- `subscribeLocalUpdates((bytes: Uint8Array) => void)`:
+  Registers a listener that will be called only for local updates to the ephemeral store.
+  ```ts
+    // you need maintain the Subscription to avoid gc
+    const _sub1 = ephemeral1.subscribeLocalUpdates((update) => {
+        ephemeral2.apply(update);
+    });
+
+    const _sub2 = ephemeral2.subscribeLocalUpdates((update) => {
+        ephemeral1.apply(update);
+    });
+  ```
+
+
 # FILE: pages/docs/tutorial/sync.md
 
 ## Sync
@@ -3892,6 +4182,68 @@ const sinceFrontiers = doc.shallowSinceFrontiers();
 
 Note: A shallow document only contains history after a certain version point. Operations before the shallow start point are not included, but the document remains fully functional for collaboration.
 
+### Redacting Sensitive Content
+
+Loro allows you to redact specific segments of document history while preserving the rest. This is particularly useful when:
+
+1. A user accidentally pastes sensitive information (like passwords or API keys) into the document
+2. You need to remove just the sensitive part of the history while keeping older and newer edits intact
+3. You want to share document history with sensitive segments sanitized
+
+Here's how to use the redaction functionality:
+
+```typescript
+const doc = new LoroDoc();
+doc.setPeerId("1");
+
+// Create some content to be redacted
+const text = doc.getText("text");
+text.insert(0, "Sensitive information");
+doc.commit();
+
+const map = doc.getMap("map");
+map.set("password", "secret123");
+map.set("public", "public information");
+doc.commit();
+
+// Export JSON updates
+const jsonUpdates = doc.exportJsonUpdates();
+
+// Define version range to redact (redact the text content)
+const versionRange = {
+  "1": [0, 21]  // Redact the "Sensitive information"
+};
+
+// Apply redaction
+const redactedJson = redactJsonUpdates(jsonUpdates, versionRange);
+
+// Create a new document with redacted content
+const redactedDoc = new LoroDoc();
+redactedDoc.importJsonUpdates(redactedJson);
+
+// The text content is now redacted with replacement characters
+console.log(redactedDoc.getText("text").toString());
+// Outputs: "���������������������"
+
+// Map operations after the redacted range remain intact
+console.log(redactedDoc.getMap("map").get("password")); // "secret123"
+console.log(redactedDoc.getMap("map").get("public"));   // "public information"
+```
+
+Redaction applies these rules to preserve document structure while removing sensitive content:
+- Preserves delete and move operations
+- Replaces text insertion content with Unicode replacement characters '�'
+- Substitutes list and map insert values with null
+- Maintains structure of nested containers
+- Replaces text mark values with null
+- Preserves map keys and text annotation keys
+
+Note that redaction doesn't remove the operations completely - it just replaces the sensitive content with placeholders. If you need to completely remove portions of history, see the section on shallow snapshots in the [Tips](./tips.md) section.
+
+#### Important: Synchronization Considerations
+
+Both redaction and shallow snapshots maintain future synchronization consistency, but your application is responsible for ensuring all peers get the sanitized version. Otherwise, old instances of the document with sensitive information will still exist on other peers.
+
 ## Event Subscription
 
 Subscribe to changes in the document:

public/llms.txt

@@ -19,6 +19,7 @@ Loro provides a robust framework for building collaborative applications with fe
 - [Tree](https://loro.dev/docs/tutorial/tree): Hierarchical data structures with Loro's movable tree CRDT
 - [Time Travel](https://loro.dev/docs/tutorial/time_travel): Implementing version control and history navigation
 - [Sync](https://loro.dev/docs/tutorial/sync): Guide to synchronizing data between instances
+- [Tips](https://loro.dev/docs/tutorial/tips): Tips and tricks for using Loro
 
 ## Advanced Topics