braid-text 0.2.48 → 0.2.50

package/README.md

@@ -37,7 +37,7 @@ Or try opening the URL in [Braid-Chrome](https://github.com/braid-org/braid-chro
 
 Check out the `server-demo.js` file to see examples for how to add simple access control, where a user need only enter a password into a cookie in the javascript console like: `document.cookie = 'password'`; and a `/pages` endpoint to show all the edited pages.
 
-## General Use on Server
+## General Use as Server
 
 Install it in your project:
 ```shell
@@ -94,112 +94,138 @@ http_server.on("request", (req, res) => {
     - `patches`: <small style="color:lightgrey">[optional]</small> Array of patches, each of the form `{unit: 'text', range: '[1:3]', content: 'hi'}`, which would replace the second and third unicode code-points in the text with `hi`.  See Braid [Range-Patches](https://github.com/braid-org/braid-spec/blob/master/draft-toomim-httpbis-range-patch-01.txt).
     - `peer`: <small style="color:lightgrey">[optional]</small> Identifies this peer. This mutation will not be echoed back to `get` subscriptions that use this same `peer` header.
 
-## General Use on Client
+## General Use as Client
+
+Here's a basic running example to start:
 
 ```html
+<!-- 1. Your textarea -->
+<textarea id="my_textarea"></textarea>
+
+<!-- 2. Include the libraries -->
+<script src="https://unpkg.com/braid-http@~1.3/braid-http-client.js"></script>
 <script src="https://unpkg.com/braid-text/simpleton-client.js"></script>
-<script>
 
-  // connect to the server
-  let simpleton = simpleton_client('https://example.org/some-resource', {
-    apply_remote_update: ({ state, patches }) => {
-
-      // Apply the incoming state or patches to local text here.
-      //
-      // Example data:
-      //   state: "Hello World"                               // The new text
-      //   patches: [{ range: [5, 5], content: " World" }]    // Patches that create the new text
-      //
-      // Then return the new state of textarea as a string:
-      return new_state
-    },
-    generate_local_diff_update: (prev_state) => {
-
-      // Compute diff between prev_state ^ and the current textarea string, such as:
-      //
-      //   var patches = [{
-      //     range: [5, 5],      // The range from position 5 to position 5
-      //     content: " World"   // is replaced with the string " World"
-      //   }]
-      //
-      // ...to insert something after a prev_state of "Hello".
-
-      // Then return the new state (as a string) and the diff (as `patches`)
-      return {new_state, patches}
-    },
+<!-- 3. Wire it up -->
+<script>
+  // Connect to server
+  var simpleton = simpleton_client('https://braid.org/simpleton_example', {
+    on_state: state => my_textarea.value = state,  // incoming changes
+    get_state: () => my_textarea.value             // outgoing changes
   })
-    
-  ...
-    
-  // When changes occur in client's textarea, let simpleton know,
-  // so that it can call generate_local_diff_update() to ask for them.
-  simpleton.changed()
 
+  // Tell simpleton when user types
+  my_textarea.oninput = () => simpleton.changed()
 </script>
 ```
 
-See [editor.html](https://raw.githubusercontent.com/braid-org/braid-text/master/editor.html) for a simple working example.
+You should see something if you run this (though the server in this example will likely ignore your changes). 
 
-## Client API
+### How It Works
+
+The client uses a **decoupled update mechanism** for efficiency:
+
+1. When users type, you call `simpleton.changed()` to notify the client that something changed
+2. The client decides *when* to actually fetch and send updates based on network conditions
+3. When ready, it calls your `get_state` function to get the current text
+
+This design prevents network congestion and handles disconnections gracefully. For example, if you edit offline for hours, the client will send just one efficient diff when reconnecting, rather than thousands of individual keystrokes.
+
+### Advanced Integration
+
+For better performance and control, you can work with patches instead of full text:
+
+#### Receiving Patches
+
+Instead of receiving complete text updates, you can process individual changes:
 
 ```javascript
-simpleton = simpleton_client(url, options)
+var simpleton = simpleton_client(url, {
+  on_patches: (patches) => {
+    // Apply each patch to your editor..
+  },
+  get_state: () => editor.getValue()
+})
 ```
 
-- `url`: The URL of the resource to synchronize with.
-- `options`: An object containing the following properties:
+This is more efficient for large documents and helps preserve cursor position.
 
-  ### Incoming Updates
+#### Custom Patch Generation
 
-  - `on_patches`: <small style="color:lightgrey">[optional]</small> A function called when patches are received from the server:
+You can provide your own diff algorithm or use patches from your editor's API:
 
-    ```javascript
-    (patches) => {...}
-    ```
+```javascript
+var simpleton = simpleton_client(url, {
+  on_state: state => editor.setValue(state),
+  get_state: () => editor.getValue(),
+  get_patches: (prev_state) => {
+    // Use your own diff algorithm or editor's change tracking
+    return compute_patches(prev_state, editor.getValue())
+  }
+})
+```
 
-    - `patches`: An array of patch objects, each representing a string-replace operation. Each patch object has:
-      - `range`: An array of two numbers, `[start, end]`, specifying the start and end positions of the characters to be deleted.
-      - `content`: The text to be inserted in place of the deleted characters.
+See [editor.html](https://github.com/braid-org/braid-text/blob/master/editor.html) for a complete example with CodeMirror integration.
 
-    Note that patches will always be in order, but the range positions of each patch reference the original string, i.e., the second patch's range values do not take into account the application of the first patch.
+## Client API
+
+### Constructor
+
+```javascript
+simpleton = simpleton_client(url, options)
+```
 
-  - `on_state`: <small style="color:lightgrey">[optional]</small> A function called when a complete state update is received from the server:
+Creates a new Simpleton client that synchronizes with a Braid-Text server.
 
-    ```javascript
-    (state) => {...}
-    ```
+**Parameters:**
+- `url`: The URL of the resource to synchronize with
+- `options`: Configuration object with the following properties:
 
-    - `state`: The new complete value of the text.
+#### Required Options
 
-  ### Local State Management
+- `get_state`: **[required]** Function that returns the current text state
+  ```javascript
+  () => current_text_string
+  ```
 
-  - `get_state`: **[required]** A function that returns the current state of the text:
+#### Incoming Updates (choose one)
 
-    ```javascript
-    () => current_state
-    ```
+- `on_state`: <small style="color:lightgrey">[optional]</small> Callback for receiving complete state updates
+  ```javascript
+  (state) => { /* update your UI with new text */ }
+  ```
 
-  - `get_patches`: <small style="color:lightgrey">[optional]</small> A function that generates patches representing changes between a previous state and the current state:
+- `on_patches`: <small style="color:lightgrey">[optional]</small> Callback for receiving incremental changes
+  ```javascript
+  (patches) => { /* apply patches to your editor */ }
+  ```
+  Each patch has:
+  - `range`: `[start, end]` - positions to delete (in original text coordinates)
+  - `content`: Text to insert at that position
+  
+  **Note:** All patches reference positions in the original text before any patches are applied.
 
-    ```javascript
-    (prev_state) => patches
-    ```
+#### Outgoing Updates
 
-    Returns an array of patch objects representing the changes. The default implementation finds a common prefix and suffix for a simple diff, but you can provide a more sophisticated implementation or track patches directly from your editor.
+- `get_patches`: <small style="color:lightgrey">[optional]</small> Custom function to generate patches
+  ```javascript
+  (previous_state) => array_of_patches
+  ```
+  If not provided, uses a simple prefix/suffix diff algorithm.
 
-  ### Other Options
+#### Additional Options
 
-  - `content_type`: <small style="color:lightgrey">[optional]</small> If set, this value will be sent in the `Accept` and `Content-Type` headers to the server.
+- `content_type`: <small style="color:lightgrey">[optional]</small> MIME type for `Accept` and `Content-Type` headers
 
 ### Methods
 
-- `simpleton.changed()`: Call this function to report local updates whenever they occur, e.g., in the `oninput` event handler of a textarea being synchronized. The system will call `get_patches` when it needs to send updates to the server.
+- `simpleton.changed()`: Notify the client that local changes have occurred. Call this in your editor's change event handler. The client will call `get_patches` and `get_state` when it's ready to send updates.
 
 ### Deprecated Options
 
 The following options are deprecated and should be replaced with the new API:
 
-- ~~`apply_remote_update`~~ → Use `on_patches` and `on_state` instead
+- ~~`apply_remote_update`~~ → Use `on_patches` or `on_state` instead
 - ~~`generate_local_diff_update`~~ → Use `get_patches` and `get_state` instead
 
 ## Testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braid-text",
-  "version": "0.2.48",
+  "version": "0.2.50",
   "description": "Library for collaborative text over http using braid.",
   "author": "Braid Working Group",
   "repository": "braid-org/braid-text",