json-diffsync 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Himanshu Singh
+
+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

@@ -0,0 +1,419 @@
+# json-diffsync
+
+Differential synchronization primitives for JSON autosave.
+
+`json-diffsync` helps keep multiple open copies of the same JSON document in sync without letting one stale tab or device overwrite newer work from another. It is designed for autosave flows in editors, form builders, dashboard builders, app-state editors, and JSON-based rich-text frameworks.
+
+It is intentionally not a CRDT and not Operational Transformation. It follows the classic differential synchronization model: every client keeps a local value and a shadow, the server keeps a canonical value and one shadow per client session, and sync requests exchange patches computed between the shadow and current JSON.
+
+## Core Idea
+
+```txt
+Any JSON works.
+Keyed arrays get item-level patches.
+Unkeyed arrays still sync, but as lossy atomic replacements.
+```
+
+Objects are diffed by property path. Arrays of objects are treated as keyed when each item has a stable `key` or `id` field by default. You can configure other identity fields such as `uuid`, `nodeId`, or `blockId`.
+
+## Client Features
+
+- Create an autosave client with `createAutosaveClient`.
+- Track `value`, `shadow`, `clientVersion`, and `serverVersion`.
+- Generate patches from local JSON changes.
+- Send patches through any transport with a `sync(message)` function.
+- Use the built-in `createFetchTransport` for HTTP sync.
+- Persist local client state with `createLocalStoragePersister`.
+- Recover from server shadow mismatch without blindly discarding unsynced local edits.
+- Configure identity fields with `keyFields`.
+- Use `sync({ confirmDestructive: true })` for explicit destructive saves.
+
+## React Client Features
+
+- Use `useDifferentialAutosave` for React apps.
+- Autosync on an interval with `intervalMs`.
+- Persist hook state under a configurable `storageKey`.
+- Expose `value`, `setValue`, `sync`, `status`, and `error`.
+- Works with any JSON-producing editor or UI state, including Lexical-style JSON.
+
+## Server Features
+
+- Create an in-memory reference server with `createMemoryAutosaveServer`.
+- Store canonical JSON document state.
+- Maintain one server-side shadow per client/session.
+- Validate client versions and shadow hashes.
+- Apply client patches and return missing server patches.
+- Configure keyed array identity with `keyFields`.
+- Configure destructive patch sensitivity with `destructiveDeleteRatio`.
+- Keep or disable revision history with `keepRevisions`.
+- Expose a Node HTTP handler with `createNodeSyncHandler`.
+
+The in-memory server is a reference implementation. Production apps will usually wrap the same sync logic with durable storage.
+
+## Shared Patch Features
+
+- Diff arbitrary JSON with `createJsonPatch`.
+- Apply patches with `applyJsonPatch`.
+- Hash JSON deterministically with `hashJson`.
+- Diff keyed arrays as item-level operations: `insertItem`, `removeItem`, `reorderItems`.
+- Diff objects as path-level operations: `set`, `replace`, `delete`.
+- Mark unkeyed array replacements with `patch.lossy === true`.
+
+## Install
+
+```sh
+npm install json-diffsync
+```
+
+## Quick Start
+
+Create a server-side sync store:
+
+```js
+import http from "node:http";
+import {
+  createMemoryAutosaveServer,
+  createNodeSyncHandler
+} from "json-diffsync/server";
+
+const sync = createMemoryAutosaveServer({
+  keyFields: ["key", "id"]
+});
+
+sync.createDocument({
+  documentId: "doc-1",
+  value: {
+    title: "Draft",
+    blocks: []
+  }
+});
+
+const handleSync = createNodeSyncHandler(sync);
+
+http.createServer((request, response) => {
+  if (request.url === "/sync") return handleSync(request, response);
+  response.writeHead(404).end();
+}).listen(3000);
+```
+
+Create a client:
+
+```js
+import { createAutosaveClient } from "json-diffsync";
+import { createFetchTransport } from "json-diffsync/server";
+
+const client = createAutosaveClient({
+  documentId: "doc-1",
+  sessionId: "laptop",
+  initialValue: {
+    title: "Draft",
+    blocks: []
+  },
+  transport: createFetchTransport("/sync")
+});
+
+client.setValue({
+  title: "Draft",
+  blocks: [
+    { id: "intro", text: "Hello from the laptop" }
+  ]
+});
+
+await client.sync();
+```
+
+## React Usage
+
+```jsx
+import { useDifferentialAutosave } from "json-diffsync/react";
+import { createFetchTransport } from "json-diffsync/server";
+
+const transport = createFetchTransport("/sync");
+
+export function JsonEditor({ documentId, sessionId }) {
+  const autosave = useDifferentialAutosave({
+    documentId,
+    sessionId,
+    initialValue: {
+      title: "Untitled",
+      blocks: []
+    },
+    transport,
+    keyFields: ["id"],
+    intervalMs: 1500
+  });
+
+  return (
+    <button onClick={() => autosave.sync()}>
+      Save now
+    </button>
+  );
+}
+```
+
+For Lexical or other editor frameworks, call `autosave.setValue(...)` with the serialized JSON state when the editor updates, then apply `autosave.value` back to the editor when remote patches arrive.
+
+## Fidelity Model
+
+### Objects
+
+Plain objects are diffed by property path:
+
+```json
+{ "title": "Draft" }
+```
+
+If `title` changes, the patch contains a path-level operation.
+
+### Keyed Arrays
+
+Keyed arrays are diffed by item identity:
+
+```json
+{
+  "blocks": [
+    { "id": "intro", "text": "One" },
+    { "id": "body", "text": "Two" }
+  ]
+}
+```
+
+If one client edits `intro` while another inserts a new block, the server can apply both without replacing the whole `blocks` array.
+
+### Unkeyed Arrays
+
+Unkeyed arrays still work:
+
+```json
+{ "tags": ["draft", "review"] }
+```
+
+But they are treated as atomic replacements and marked lossy:
+
+```js
+patch.lossy === true
+patch.ops[0].lossyReason === "unkeyed_array_replace"
+```
+
+This means the library can sync the value, but concurrent edits to the same unkeyed array can overwrite each other. If a collection matters, give each item a stable key.
+
+## Custom Identity Fields
+
+Use `keyFields` on both client and server:
+
+```js
+const sync = createMemoryAutosaveServer({
+  keyFields: ["uuid", "nodeId", "blockId"]
+});
+
+const client = createAutosaveClient({
+  documentId,
+  sessionId,
+  initialValue,
+  transport,
+  keyFields: ["uuid", "nodeId", "blockId"]
+});
+```
+
+## Network Shape
+
+Client sends:
+
+```json
+{
+  "documentId": "doc-1",
+  "sessionId": "laptop",
+  "clientVersion": 2,
+  "serverVersion": 3,
+  "shadowHash": "a1b2c3d4",
+  "patch": {
+    "kind": "json-keyed",
+    "baseHash": "a1b2c3d4",
+    "lossy": false,
+    "ops": [
+      {
+        "op": "set",
+        "path": ["blocks", { "$key": "intro" }, "text"],
+        "value": "Hello from the laptop"
+      }
+    ]
+  }
+}
+```
+
+Server responds with what the client is missing:
+
+```json
+{
+  "ok": true,
+  "clientVersion": 3,
+  "serverVersion": 4,
+  "patch": {
+    "kind": "json-keyed",
+    "lossy": false,
+    "ops": []
+  }
+}
+```
+
+## Autosave Flow
+
+Each client maintains:
+
+```txt
+client.value       current JSON state
+client.shadow      server state this client last synced against
+clientVersion      monotonic version for this client shadow
+serverVersion      last server version this client received
+```
+
+The server maintains:
+
+```txt
+document.value                  canonical JSON
+document.sessions[laptop].value server-side shadow for laptop
+document.sessions[ipad].value   server-side shadow for iPad
+```
+
+When a stale laptop autosaves, it does not say “replace the server with my full JSON.” It sends only the diff between `client.shadow` and `client.value`. If the laptop made no local edits, that patch is empty. The server then diffs the laptop shadow against canonical state and sends back changes made elsewhere.
+
+## Guardrails
+
+Differential sync prevents stale full-document overwrites, but it cannot know whether a valid delete-most diff came from a real user action or a broken client. The reference server includes:
+
+- Shadow hash validation.
+- Client version validation.
+- Destructive patch confirmation.
+- Revision history.
+
+By default, a patch that shrinks the JSON payload by at least 80%, or removes at least 80% of a keyed child array, is rejected unless `sync({ confirmDestructive: true })` is used.
+
+## API
+
+### Client And Shared Core
+
+```js
+import {
+  createAutosaveClient,
+  createLocalStoragePersister,
+  createJsonPatch,
+  applyJsonPatch,
+  cloneJson,
+  stableStringify,
+  hashJson
+} from "json-diffsync";
+```
+
+Client helpers:
+
+- `createAutosaveClient(options)`
+- `createLocalStoragePersister(key, storage?)`
+
+Patch helpers:
+
+- `createJsonPatch(before, after, options?)`
+- `applyJsonPatch(value, patch, options?)`
+- `hashJson(value)`
+- `stableStringify(value)`
+- `cloneJson(value)`
+
+### React Client
+
+```js
+import { useDifferentialAutosave } from "json-diffsync/react";
+```
+
+React hook:
+
+- `useDifferentialAutosave(options)`
+
+### Server
+
+```js
+import {
+  createMemoryAutosaveServer,
+  createNodeSyncHandler,
+  createFetchTransport
+} from "json-diffsync/server";
+```
+
+Server helpers:
+
+- `createMemoryAutosaveServer(options?)`
+- `createNodeSyncHandler(server)`
+- `createFetchTransport(url, fetchImpl?)`
+
+## Source Layout
+
+```txt
+src/index.js             public client/core entrypoint
+src/client.js            autosave client state machine
+src/persistence.js       localStorage-style persister
+src/core/json.js         clone, stable stringify, hash helpers
+src/core/patch.js        JSON diff and patch implementation
+src/react.js             React autosave hook
+src/server.js            public server entrypoint
+src/server/memory.js     in-memory reference sync server
+src/server/transport.js  fetch transport and Node HTTP handler
+```
+
+## Testing
+
+Run the protocol and HTTP E2E tests:
+
+```sh
+npm test
+```
+
+The suite covers:
+
+- stale laptop/iPad autosave recovery
+- keyed item-level patches
+- unkeyed lossy patches
+- custom key fields
+- destructive delete rejection
+- large nested JSON documents
+- HTTP sync over a real local server
+- expected failure paths, including malformed patches, unknown sessions, version/hash mismatches, transport errors, and invalid HTTP methods
+
+Run browser E2E with React + Lexical:
+
+```sh
+npm run test:e2e:browser
+```
+
+That test starts a Node sync API, starts a Vite React app, opens two isolated Chromium contexts as `laptop` and `ipad`, types into both editors, syncs over HTTP, and asserts both browser pages plus the server JSON converge.
+
+## Benchmark
+
+Run:
+
+```sh
+npm run bench
+```
+
+The benchmark generates deterministic nested JSON documents, mutates deep keyed nodes, inserts keyed blocks, reorders sections, and measures patch creation, patch application, and full in-memory client/server sync.
+
+Current MVP behavior: patch size scales well, but full sync time still grows with total JSON size because the implementation hashes, stringifies, and clones whole values in a few places. Optimization targets are documented by the benchmark.
+
+## Status
+
+`json-diffsync` is early-stage software. The core model is working and tested, but the API may change before `1.0.0`.
+
+Good current use cases:
+
+- JSON autosave
+- same-user multi-tab/device editing
+- keyed editor/app state
+- prototype collaboration flows
+
+Use extra care for:
+
+- high-frequency multi-user editing
+- very large JSON values
+- concurrent edits to the same scalar field
+- unkeyed arrays where concurrent edits matter
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "json-diffsync",
+  "version": "0.0.1",
+  "description": "Differential synchronization primitives for JSON autosave, React clients, and Node servers.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Himanshu Singh",
+  "homepage": "https://github.com/the5ereneRebe1/json-diffsync#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/the5ereneRebe1/json-diffsync.git"
+  },
+  "bugs": {
+    "url": "https://github.com/the5ereneRebe1/json-diffsync/issues"
+  },
+  "sideEffects": false,
+  "types": "./src/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./react": {
+      "types": "./src/react.d.ts",
+      "import": "./src/react.js"
+    },
+    "./server": {
+      "types": "./src/server.d.ts",
+      "import": "./src/server.js"
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "bench": "node scripts/bench.js",
+    "test:e2e:browser": "playwright test test/browser-e2e.spec.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "json",
+    "diff",
+    "differential-sync",
+    "autosave",
+    "differential-synchronization",
+    "react",
+    "collaboration",
+    "sync"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@lexical/react": "^0.45.0",
+    "@playwright/test": "^1.60.0",
+    "@vitejs/plugin-react": "^6.0.2",
+    "lexical": "^0.45.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "vite": "^8.0.16"
+  }
+}

package/src/client.js

@@ -0,0 +1,102 @@
+import { DEFAULT_KEY_FIELDS, cloneJson, hashJson } from "./core/json.js";
+import { applyJsonPatch, createJsonPatch } from "./core/patch.js";
+
+export function createAutosaveClient(options) {
+  const {
+    documentId,
+    sessionId,
+    initialValue = null,
+    clientVersion = 0,
+    serverVersion = 0,
+    transport,
+    persister,
+    keyFields = DEFAULT_KEY_FIELDS
+  } = options;
+
+  const saved = persister?.load();
+  const state = {
+    documentId,
+    sessionId,
+    value: saved?.value ?? cloneJson(initialValue),
+    shadow: saved?.shadow ?? cloneJson(initialValue),
+    clientVersion: saved?.clientVersion ?? clientVersion,
+    serverVersion: saved?.serverVersion ?? serverVersion,
+    syncing: false,
+    lastError: null
+  };
+
+  function persist() {
+    persister?.save({
+      value: state.value,
+      shadow: state.shadow,
+      clientVersion: state.clientVersion,
+      serverVersion: state.serverVersion
+    });
+  }
+
+  persist();
+
+  return {
+    get state() {
+      return {
+        ...state,
+        value: cloneJson(state.value),
+        shadow: cloneJson(state.shadow)
+      };
+    },
+    getValue() {
+      return cloneJson(state.value);
+    },
+    setValue(nextValue) {
+      state.value = cloneJson(nextValue);
+      persist();
+    },
+    async sync(meta = {}) {
+      if (state.syncing) return { skipped: true };
+      state.syncing = true;
+      state.lastError = null;
+
+      const patch = createJsonPatch(state.shadow, state.value, { keyFields });
+      try {
+        const response = await transport.sync({
+          documentId,
+          sessionId,
+          clientVersion: state.clientVersion,
+          serverVersion: state.serverVersion,
+          shadowHash: hashJson(state.shadow),
+          patch,
+          meta
+        });
+
+        if (!response.ok) {
+          if (response.reason === "shadow_mismatch" && response.value !== undefined) {
+            const hasLocalChanges = hashJson(state.value) !== hashJson(state.shadow);
+            if (!hasLocalChanges) state.value = cloneJson(response.value);
+            state.shadow = cloneJson(response.value);
+            state.clientVersion = response.clientVersion ?? state.clientVersion;
+            state.serverVersion = response.serverVersion ?? state.serverVersion;
+            persist();
+          }
+          throw new Error(response.reason ?? "Sync failed.");
+        }
+
+        state.shadow = applyJsonPatch(state.shadow, patch, { strict: true, keyFields });
+        state.clientVersion = response.clientVersion;
+
+        if (response.patch) {
+          state.value = applyJsonPatch(state.value, response.patch, { keyFields });
+          state.shadow = applyJsonPatch(state.shadow, response.patch, { strict: true, keyFields });
+        }
+
+        state.serverVersion = response.serverVersion;
+        persist();
+        return { ok: true, changed: patch.ops.length > 0 };
+      } catch (error) {
+        state.lastError = error;
+        throw error;
+      } finally {
+        state.syncing = false;
+      }
+    }
+  };
+}

package/src/core/json.js

@@ -0,0 +1,35 @@
+export const DEFAULT_KEY_FIELDS = ["key", "id"];
+
+export function cloneJson(value) {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function stableStringify(value) {
+  return JSON.stringify(sortJson(value));
+}
+
+export function hashJson(value) {
+  const text = stableStringify(value);
+  let hash = 2166136261;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+export function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function sortJson(value) {
+  if (Array.isArray(value)) return value.map(sortJson);
+  if (!isPlainObject(value)) return value;
+  return Object.keys(value)
+    .sort()
+    .reduce((sorted, key) => {
+      sorted[key] = sortJson(value[key]);
+      return sorted;
+    }, {});
+}

package/src/core/patch.js

@@ -0,0 +1,242 @@
+import {
+  DEFAULT_KEY_FIELDS,
+  cloneJson,
+  hashJson,
+  isPlainObject,
+  stableStringify
+} from "./json.js";
+
+const KEY_SEGMENT = "$key";
+
+export function createJsonPatch(before, after, options = {}) {
+  const ops = [];
+  diffJson(before, after, [], ops, options);
+  return {
+    kind: "json-keyed",
+    baseHash: hashJson(before),
+    beforeBytes: stableStringify(before).length,
+    afterBytes: stableStringify(after).length,
+    lossy: ops.some((op) => op.lossy === true),
+    ops
+  };
+}
+
+export function applyJsonPatch(value, patch, options = {}) {
+  if (!patch || patch.kind !== "json-keyed") {
+    throw new Error("Unsupported patch format.");
+  }
+
+  let next = cloneJson(value);
+  for (const op of patch.ops) {
+    next = applyJsonOp(next, op, options);
+  }
+  return next;
+}
+
+function diffJson(before, after, path, ops, options) {
+  if (jsonEqual(before, after)) return;
+
+  if (isKeyedArray(before, options) && isKeyedArray(after, options)) {
+    diffKeyedArray(before, after, path, ops, options);
+    return;
+  }
+
+  if (isPlainObject(before) && isPlainObject(after)) {
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const key of [...keys].sort()) {
+      if (!(key in after)) {
+        ops.push({ op: "delete", path: [...path, key], oldValue: cloneJson(before[key]) });
+      } else if (!(key in before)) {
+        ops.push({ op: "set", path: [...path, key], value: cloneJson(after[key]) });
+      } else {
+        diffJson(before[key], after[key], [...path, key], ops, options);
+      }
+    }
+    return;
+  }
+
+  ops.push({
+    op: "replace",
+    path,
+    oldValue: cloneJson(before),
+    value: cloneJson(after),
+    lossy: Array.isArray(before) || Array.isArray(after),
+    lossyReason: Array.isArray(before) || Array.isArray(after) ? "unkeyed_array_replace" : undefined
+  });
+}
+
+function diffKeyedArray(before, after, path, ops, options) {
+  const beforeByKey = mapByKey(before, options);
+  const afterByKey = mapByKey(after, options);
+
+  for (const [key, item] of beforeByKey) {
+    if (!afterByKey.has(key)) {
+      ops.push({
+        op: "removeItem",
+        path,
+        key,
+        oldValue: cloneJson(item),
+        beforeLength: before.length,
+        afterLength: after.length
+      });
+    }
+  }
+
+  for (let index = 0; index < after.length; index += 1) {
+    const item = after[index];
+    const key = getItemKey(item, options);
+    if (!beforeByKey.has(key)) {
+      ops.push({ op: "insertItem", path, key, index, value: cloneJson(item) });
+    } else {
+      diffJson(beforeByKey.get(key), item, [...path, { [KEY_SEGMENT]: key }], ops, options);
+    }
+  }
+
+  const beforeKeys = before.map((item) => getItemKey(item, options));
+  const afterKeys = after.map((item) => getItemKey(item, options));
+  if (!arrayEqual(beforeKeys, afterKeys)) {
+    ops.push({ op: "reorderItems", path, beforeKeys, keys: afterKeys });
+  }
+}
+
+function applyJsonOp(root, op, options) {
+  if (op.path.length === 0) {
+    if (op.op === "replace" || op.op === "set") return cloneJson(op.value);
+    if (op.op === "delete") return undefined;
+  }
+
+  const parentPath = op.op === "insertItem" || op.op === "removeItem" || op.op === "reorderItems"
+    ? op.path
+    : op.path.slice(0, -1);
+  const parent = resolvePath(root, parentPath, options);
+
+  switch (op.op) {
+    case "set":
+    case "replace": {
+      const key = op.path.at(-1);
+      if (options.strict && "oldValue" in op && !jsonEqual(getChild(parent, key, options), op.oldValue)) {
+        throw new Error("Patch oldValue does not match target.");
+      }
+      setChild(parent, key, cloneJson(op.value), options);
+      return root;
+    }
+    case "delete": {
+      const key = op.path.at(-1);
+      if (options.strict && "oldValue" in op && !jsonEqual(getChild(parent, key, options), op.oldValue)) {
+        throw new Error("Patch oldValue does not match target.");
+      }
+      deleteChild(parent, key);
+      return root;
+    }
+    case "insertItem": {
+      if (!Array.isArray(parent)) throw new Error("insertItem target is not an array.");
+      const existing = findIndexByKey(parent, op.key, options);
+      if (existing >= 0) parent.splice(existing, 1);
+      parent.splice(Math.min(op.index, parent.length), 0, cloneJson(op.value));
+      return root;
+    }
+    case "removeItem": {
+      if (!Array.isArray(parent)) throw new Error("removeItem target is not an array.");
+      const index = findIndexByKey(parent, op.key, options);
+      if (index < 0) {
+        if (options.strict) throw new Error("removeItem target key does not exist.");
+        return root;
+      }
+      if (options.strict && op.oldValue && !jsonEqual(parent[index], op.oldValue)) {
+        throw new Error("Patch oldValue does not match target.");
+      }
+      parent.splice(index, 1);
+      return root;
+    }
+    case "reorderItems": {
+      if (!Array.isArray(parent)) throw new Error("reorderItems target is not an array.");
+      const byKey = mapByKey(parent, options);
+      const ordered = [];
+      for (const key of op.keys) {
+        if (byKey.has(key)) ordered.push(byKey.get(key));
+      }
+      for (const item of parent) {
+        const key = getItemKey(item, options);
+        if (!op.keys.includes(key)) ordered.push(item);
+      }
+      parent.splice(0, parent.length, ...ordered);
+      return root;
+    }
+    default:
+      throw new Error(`Unsupported op: ${op.op}`);
+  }
+}
+
+function resolvePath(root, path, options) {
+  let current = root;
+  for (const segment of path) {
+    current = getChild(current, segment, options);
+    if (current === undefined) throw new Error("Patch path could not be resolved.");
+  }
+  return current;
+}
+
+function getChild(parent, segment, options) {
+  if (isKeySegment(segment)) {
+    if (!Array.isArray(parent)) throw new Error("Key segment parent is not an array.");
+    return parent.find((item) => getItemKey(item, options) === segment[KEY_SEGMENT]);
+  }
+  return parent?.[segment];
+}
+
+function setChild(parent, segment, value, options) {
+  if (isKeySegment(segment)) {
+    if (!Array.isArray(parent)) throw new Error("Key segment parent is not an array.");
+    const index = findIndexByKey(parent, segment[KEY_SEGMENT], options);
+    if (index < 0) parent.push(value);
+    else parent[index] = value;
+    return;
+  }
+  parent[segment] = value;
+}
+
+function deleteChild(parent, segment) {
+  if (Array.isArray(parent) && typeof segment === "number") {
+    parent.splice(segment, 1);
+    return;
+  }
+  delete parent[segment];
+}
+
+function isKeyedArray(value, options) {
+  return (
+    Array.isArray(value) &&
+    value.every((item) => getItemKey(item, options) !== null)
+  );
+}
+
+function mapByKey(array, options) {
+  return new Map(array.map((item) => [getItemKey(item, options), item]));
+}
+
+function getItemKey(item, options) {
+  if (!item || typeof item !== "object" || Array.isArray(item)) return null;
+  if (typeof options.getKey === "function") return options.getKey(item);
+  for (const field of options.keyFields ?? DEFAULT_KEY_FIELDS) {
+    if (typeof item[field] === "string" || typeof item[field] === "number") {
+      return String(item[field]);
+    }
+  }
+  return null;
+}
+
+function findIndexByKey(array, key, options) {
+  return array.findIndex((item) => getItemKey(item, options) === key);
+}
+
+function isKeySegment(segment) {
+  return isPlainObject(segment) && typeof segment[KEY_SEGMENT] === "string";
+}
+
+function jsonEqual(left, right) {
+  return stableStringify(left) === stableStringify(right);
+}
+
+function arrayEqual(left, right) {
+  return left.length === right.length && left.every((item, index) => item === right[index]);
+}

package/src/index.d.ts

@@ -0,0 +1,35 @@
+export type JsonPathSegment = string | number | { $key: string };
+
+export interface JsonPatch {
+  kind: "json-keyed";
+  baseHash: string;
+  beforeBytes: number;
+  afterBytes: number;
+  lossy: boolean;
+  ops: Array<Record<string, unknown>>;
+}
+
+export interface SyncTransport {
+  sync(message: unknown): Promise<any>;
+}
+
+export function cloneJson<T>(value: T): T;
+export function stableStringify(value: unknown): string;
+export function hashJson(value: unknown): string;
+export function createJsonPatch(before: unknown, after: unknown, options?: { keyFields?: string[] }): JsonPatch;
+export function applyJsonPatch<T>(value: T, patch: JsonPatch, options?: { strict?: boolean; keyFields?: string[] }): T;
+export function createLocalStoragePersister(key: string, storage?: Storage): {
+  load(): any;
+  save(state: unknown): void;
+  clear(): void;
+};
+export function createAutosaveClient(options: {
+  documentId: string;
+  sessionId: string;
+  initialValue?: unknown;
+  clientVersion?: number;
+  serverVersion?: number;
+  keyFields?: string[];
+  transport: SyncTransport;
+  persister?: { load(): any; save(state: unknown): void };
+}): any;

package/src/index.js

@@ -0,0 +1,4 @@
+export { createAutosaveClient } from "./client.js";
+export { applyJsonPatch, createJsonPatch } from "./core/patch.js";
+export { cloneJson, hashJson, stableStringify } from "./core/json.js";
+export { createLocalStoragePersister } from "./persistence.js";

package/src/persistence.js

@@ -0,0 +1,14 @@
+export function createLocalStoragePersister(key, storage = globalThis.localStorage) {
+  return {
+    load() {
+      const raw = storage?.getItem(key);
+      return raw ? JSON.parse(raw) : null;
+    },
+    save(state) {
+      storage?.setItem(key, JSON.stringify(state));
+    },
+    clear() {
+      storage?.removeItem(key);
+    }
+  };
+}

package/src/react.d.ts

@@ -0,0 +1,16 @@
+export function useDifferentialAutosave(options: {
+  documentId: string;
+  sessionId: string;
+  initialValue?: unknown;
+  transport: { sync(message: unknown): Promise<any> };
+  intervalMs?: number;
+  keyFields?: string[];
+  storageKey?: string;
+}): {
+  value: any;
+  setValue(nextValue: unknown): void;
+  sync(meta?: Record<string, unknown>): Promise<any>;
+  status: "idle" | "syncing" | "error";
+  error: unknown;
+  client: any;
+};

package/src/react.js

@@ -0,0 +1,72 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createAutosaveClient, createLocalStoragePersister } from "./index.js";
+
+export function useDifferentialAutosave(options) {
+  const {
+    documentId,
+    sessionId,
+    initialValue = null,
+    transport,
+    intervalMs = 2000,
+    keyFields,
+    storageKey = `driftsync:${documentId}:${sessionId}`
+  } = options;
+
+  const [, forceRender] = useState(0);
+  const clientRef = useRef(null);
+
+  if (!clientRef.current) {
+    clientRef.current = createAutosaveClient({
+      documentId,
+      sessionId,
+      initialValue,
+      transport,
+      keyFields,
+      persister: createLocalStoragePersister(storageKey)
+    });
+  }
+
+  const client = clientRef.current;
+
+  const sync = useCallback(
+    async (meta) => {
+      const result = await client.sync(meta);
+      forceRender((value) => value + 1);
+      return result;
+    },
+    [client]
+  );
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      sync().catch(() => forceRender((value) => value + 1));
+    }, intervalMs);
+
+    const flush = () => {
+      sync().catch(() => {});
+    };
+
+    globalThis.addEventListener?.("visibilitychange", flush);
+    globalThis.addEventListener?.("beforeunload", flush);
+
+    return () => {
+      clearInterval(timer);
+      globalThis.removeEventListener?.("visibilitychange", flush);
+      globalThis.removeEventListener?.("beforeunload", flush);
+    };
+  }, [intervalMs, sync]);
+
+  const snapshot = client.state;
+
+  return useMemo(() => ({
+    value: snapshot.value,
+    setValue(nextValue) {
+      client.setValue(nextValue);
+      forceRender((value) => value + 1);
+    },
+    sync,
+    status: snapshot.syncing ? "syncing" : snapshot.lastError ? "error" : "idle",
+    error: snapshot.lastError,
+    client
+  }), [client, sync, snapshot]);
+}

package/src/server/memory.js

@@ -0,0 +1,168 @@
+import { applyJsonPatch, createJsonPatch } from "../core/patch.js";
+import { cloneJson, hashJson, stableStringify } from "../core/json.js";
+
+export function createMemoryAutosaveServer(options = {}) {
+  const documents = new Map();
+  const destructiveDeleteRatio = options.destructiveDeleteRatio ?? 0.8;
+  const keepRevisions = options.keepRevisions ?? true;
+  const keyFields = options.keyFields ?? ["key", "id"];
+
+  function getDocument(documentId) {
+    const document = documents.get(documentId);
+    if (!document) throw new Error(`Unknown document: ${documentId}`);
+    return document;
+  }
+
+  return {
+    createDocument({ documentId = cryptoRandomId(), value = null } = {}) {
+      const document = {
+        documentId,
+        value: cloneJson(value),
+        version: 0,
+        sessions: new Map(),
+        revisions: []
+      };
+      documents.set(documentId, document);
+      return { documentId, value: cloneJson(value), version: 0 };
+    },
+    openDocument({ documentId, sessionId }) {
+      const document = getDocument(documentId);
+      document.sessions.set(sessionId, {
+        value: cloneJson(document.value),
+        clientVersion: 0,
+        serverVersion: document.version
+      });
+      return {
+        ok: true,
+        documentId,
+        sessionId,
+        value: cloneJson(document.value),
+        clientVersion: 0,
+        serverVersion: document.version
+      };
+    },
+    inspectDocument(documentId) {
+      const document = getDocument(documentId);
+      return {
+        documentId,
+        value: cloneJson(document.value),
+        version: document.version,
+        sessions: [...document.sessions.entries()].map(([sessionId, shadow]) => ({
+          sessionId,
+          value: cloneJson(shadow.value),
+          clientVersion: shadow.clientVersion,
+          serverVersion: shadow.serverVersion
+        })),
+        revisions: cloneJson(document.revisions)
+      };
+    },
+    sync(message) {
+      const document = getDocument(message.documentId);
+      const shadow = document.sessions.get(message.sessionId);
+      if (!shadow) {
+        return { ok: false, reason: "unknown_session" };
+      }
+
+      if (message.clientVersion !== shadow.clientVersion) {
+        return {
+          ok: false,
+          reason: "client_version_mismatch",
+          clientVersion: shadow.clientVersion,
+          serverVersion: shadow.serverVersion
+        };
+      }
+
+      if (message.shadowHash !== hashJson(shadow.value) || message.patch.baseHash !== hashJson(shadow.value)) {
+        return {
+          ok: false,
+          reason: "shadow_mismatch",
+          value: cloneJson(document.value),
+          clientVersion: shadow.clientVersion,
+          serverVersion: document.version
+        };
+      }
+
+      if (isDestructivePatch(message.patch, destructiveDeleteRatio) && !message.meta?.confirmDestructive) {
+        return {
+          ok: false,
+          reason: "destructive_patch_requires_confirmation",
+          clientVersion: shadow.clientVersion,
+          serverVersion: shadow.serverVersion
+        };
+      }
+
+      let nextShadow;
+      let nextValue;
+      try {
+        nextShadow = applyJsonPatch(shadow.value, message.patch, { strict: true, keyFields });
+        nextValue = applyJsonPatch(document.value, message.patch, { keyFields });
+      } catch (error) {
+        return {
+          ok: false,
+          reason: "patch_apply_failed",
+          detail: error.message,
+          clientVersion: shadow.clientVersion,
+          serverVersion: shadow.serverVersion
+        };
+      }
+
+      const changedServer = stableStringify(nextValue) !== stableStringify(document.value);
+      if (keepRevisions && changedServer) {
+        document.revisions.push({
+          version: document.version,
+          sessionId: message.sessionId,
+          before: cloneJson(document.value),
+          after: cloneJson(nextValue),
+          patch: cloneJson(message.patch),
+          at: new Date().toISOString()
+        });
+      }
+
+      document.value = nextValue;
+      if (changedServer) document.version += 1;
+      shadow.value = nextShadow;
+      shadow.clientVersion += 1;
+
+      const serverPatch = createJsonPatch(shadow.value, document.value, { keyFields });
+      shadow.value = applyJsonPatch(shadow.value, serverPatch, { strict: true, keyFields });
+      shadow.serverVersion = document.version;
+
+      return {
+        ok: true,
+        clientVersion: shadow.clientVersion,
+        serverVersion: shadow.serverVersion,
+        patch: serverPatch
+      };
+    },
+    documents
+  };
+}
+
+function isDestructivePatch(patch, ratio) {
+  if (patch.beforeBytes === 0) return false;
+  const removedMostBytes = patch.afterBytes / patch.beforeBytes <= 1 - ratio;
+  const removedMostKeyedItems = patch.ops.some((op) => (
+    op.op === "removeItem" &&
+    op.beforeLength > 0 &&
+    op.afterLength / op.beforeLength <= 1 - ratio
+  ));
+  const reorderedToEmpty = patch.ops.some((op) => (
+    op.op === "reorderItems" &&
+    Array.isArray(op.beforeKeys) &&
+    op.beforeKeys.length > 0 &&
+    Array.isArray(op.keys) &&
+    op.keys.length === 0
+  ));
+
+  if (!removedMostBytes && !removedMostKeyedItems && !reorderedToEmpty) return false;
+  return patch.ops.some((op) => (
+    op.op === "delete" ||
+    op.op === "removeItem" ||
+    (op.op === "replace" && stableStringify(op.value).length < stableStringify(op.oldValue).length)
+  ));
+}
+
+function cryptoRandomId() {
+  if (globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID();
+  return `doc_${Math.random().toString(36).slice(2)}`;
+}

package/src/server/transport.js

@@ -0,0 +1,34 @@
+export function createFetchTransport(url, fetchImpl = globalThis.fetch) {
+  return {
+    async sync(message) {
+      const response = await fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(message)
+      });
+      if (!response.ok) {
+        const body = await response.json().catch(() => ({}));
+        return body.ok === false ? body : { ok: false, reason: `http_${response.status}` };
+      }
+      return response.json();
+    }
+  };
+}
+
+export function createNodeSyncHandler(server) {
+  return async function handleSync(request, response) {
+    if (request.method !== "POST") {
+      response.writeHead(405, { "content-type": "application/json" });
+      response.end(JSON.stringify({ ok: false, reason: "method_not_allowed" }));
+      return;
+    }
+
+    const chunks = [];
+    for await (const chunk of request) chunks.push(chunk);
+    const message = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    const result = server.sync(message);
+
+    response.writeHead(result.ok ? 200 : 409, { "content-type": "application/json" });
+    response.end(JSON.stringify(result));
+  };
+}

package/src/server.d.ts

@@ -0,0 +1,9 @@
+export function createMemoryAutosaveServer(options?: {
+  destructiveDeleteRatio?: number;
+  keepRevisions?: boolean;
+  keyFields?: string[];
+}): any;
+export function createFetchTransport(url: string, fetchImpl?: typeof fetch): {
+  sync(message: unknown): Promise<any>;
+};
+export function createNodeSyncHandler(server: any): (request: any, response: any) => Promise<void>;

package/src/server.js

@@ -0,0 +1,2 @@
+export { createMemoryAutosaveServer } from "./server/memory.js";
+export { createFetchTransport, createNodeSyncHandler } from "./server/transport.js";