@xnetjs/runtime 0.4.0 → 0.5.1

package/dist/index.d.ts

@@ -164,6 +164,19 @@ interface SyncManagerConfig {
     onDocEvict?: (nodeId: string, doc: Y.Doc) => void;
     /** Optional room for node-change relay (enables NodeStore sync via hub) */
     nodeSyncRoom?: string;
+    /**
+     * Production Yjs history capture (exploration 0329): wired to
+     * `DocumentHistoryEngine` (duck-typed to avoid a hard coupling). Steady
+     * debounce persists go through the engine's own min-interval throttle
+     * (`captureSnapshot`); session boundaries (evict/flush/destroy) force a
+     * capture so a doc never leaves memory without a restorable snapshot.
+     */
+    documentHistory?: DocumentHistoryCapture;
+}
+/** Duck-typed slice of DocumentHistoryEngine used for capture wiring. */
+interface DocumentHistoryCapture {
+    captureSnapshot(nodeId: string, doc: Y.Doc): Promise<unknown>;
+    forceCapture(nodeId: string, doc: Y.Doc): Promise<unknown>;
 }
 type SyncReconciliationOptions = {
     /** Optional node subset. Defaults to all joined rooms. */
@@ -716,6 +729,14 @@ interface NodePoolConfig {
     onDocUpdate?: (nodeId: string, doc: Y.Doc) => void;
     /** Optional callback before a doc is evicted */
     onDocEvict?: (nodeId: string, doc: Y.Doc) => void;
+    /**
+     * Fired after a doc's state was successfully persisted to `yjs_state`
+     * (exploration 0329: the production Yjs history capture hook). `context`
+     * distinguishes the steady-state debounce from session boundaries
+     * (evict/flush/destroy) so capture policies can throttle the former and
+     * force the latter. Must never throw — persist correctness wins.
+     */
+    onDocPersist?: (nodeId: string, doc: Y.Doc, context: 'debounce' | 'evict' | 'flush' | 'destroy') => void;
     /**
      * Predicate marking a node's Y.Doc as **ephemeral** — never persisted to
      * `yjs_state` and never cold-loaded from it. Workspace presence is the
@@ -997,6 +1018,13 @@ declare class NodeStoreSyncProvider {
     private store;
     private room;
     private subscribeOnly;
+    /**
+     * Outbound exclusion (exploration 0329): return false to keep a change
+     * out of this room entirely (live subscribe AND cursor backfill both
+     * funnel through `enqueueChange`). Used to keep device-local draft
+     * clones out of the personal node-sync room.
+     */
+    private shouldPublish?;
     /** Confirmed, persisted high-water mark (advanced from the hub's response). */
     private lastSyncedLamport;
     /** Optimistic in-memory cursor: lamport of the last change actually sent. */
@@ -1026,7 +1054,14 @@ declare class NodeStoreSyncProvider {
      * sync-response high-water mark, and author lamports across members are not
      * mutually ordered.
      */
-    constructor(store: NodeStore, room: string, subscribeOnly?: boolean);
+    constructor(store: NodeStore, room: string, subscribeOnly?: boolean, 
+    /**
+     * Outbound exclusion (exploration 0329): return false to keep a change
+     * out of this room entirely (live subscribe AND cursor backfill both
+     * funnel through `enqueueChange`). Used to keep device-local draft
+     * clones out of the personal node-sync room.
+     */
+    shouldPublish?: ((change: NodeChange) => boolean) | undefined);
     /**
      * Mark the first remote apply once. Platform-agnostic and defensive: a
      * missing `performance` global, or a throw, is a no-op — instrumentation

package/dist/index.js

@@ -2,7 +2,11 @@
 import { getSigningPublicKeyFromPrivate, sign, verify } from "@xnetjs/crypto";
 import { MemoryNodeStorageAdapter, NodeStore } from "@xnetjs/data";
 import { createMainThreadBridgeSync } from "@xnetjs/data-bridge";
-import { UndoManager } from "@xnetjs/history";
+import {
+  DocumentHistoryEngine,
+  UndoManager,
+  rehydrateDraftPrivacy
+} from "@xnetjs/history";
 import { PluginRegistry } from "@xnetjs/plugins";
 
 // src/sync/sync-manager.ts
@@ -750,6 +754,13 @@ function createNodePool(config) {
   const isEphemeral = config.isEphemeral ?? defaultIsEphemeral;
   const largeDocWarnBytes = config.largeDocWarnBytes ?? DEFAULT_LARGE_DOC_WARN_BYTES;
   let firstAcquireMarked = false;
+  function notifyPersist(nodeId, doc, context) {
+    try {
+      config.onDocPersist?.(nodeId, doc, context);
+    } catch (err) {
+      console.warn(`[NodePool] onDocPersist hook failed for ${nodeId}:`, err);
+    }
+  }
   function markFirstAcquire() {
     if (firstAcquireMarked) return;
     firstAcquireMarked = true;
@@ -795,6 +806,7 @@ function createNodePool(config) {
           const content = Y.encodeStateAsUpdate(entry.doc);
           await config.storage.setDocumentContent(nodeId, content);
           entry.dirty = false;
+          notifyPersist(nodeId, entry.doc, "debounce");
         }
       }, persistDelay)
     );
@@ -822,6 +834,7 @@ function createNodePool(config) {
               );
             }
             await config.storage.setDocumentContent(id, content);
+            notifyPersist(id, entry.doc, "evict");
           }
         } catch (err) {
           console.error(`[NodePool] Failed to persist document ${id} during eviction:`, err);
@@ -898,6 +911,7 @@ function createNodePool(config) {
           promises.push(
             config.storage.setDocumentContent(id, content).then(() => {
               entry.dirty = false;
+              notifyPersist(id, entry.doc, "flush");
             })
           );
         }
@@ -944,10 +958,11 @@ var NodeStoreSyncProvider = class {
    * sync-response high-water mark, and author lamports across members are not
    * mutually ordered.
    */
-  constructor(store, room, subscribeOnly = false) {
+  constructor(store, room, subscribeOnly = false, shouldPublish) {
     this.store = store;
     this.room = room;
     this.subscribeOnly = subscribeOnly;
+    this.shouldPublish = shouldPublish;
   }
   /** Confirmed, persisted high-water mark (advanced from the hub's response). */
   lastSyncedLamport = 0;
@@ -1311,6 +1326,7 @@ var NodeStoreSyncProvider = class {
   /** Queue a change for throttled broadcast (deduped by hash). */
   enqueueChange(change) {
     if (this.outboundHalted) return;
+    if (this.shouldPublish && !this.shouldPublish(change)) return;
     if (change.lamport <= this.pushedThrough) return;
     if (this.queuedHashes.has(change.hash)) return;
     this.queuedHashes.add(change.hash);
@@ -1701,7 +1717,7 @@ function hasEnvelope(data) {
 function extractBlobCids(doc) {
   const cids = [];
   const seen = /* @__PURE__ */ new Set();
-  for (const name of ["default", "prosemirror", ""]) {
+  for (const name of ["content-v4", "content", "default", "prosemirror", ""]) {
     let fragment;
     try {
       fragment = doc.getXmlFragment(name);
@@ -1775,7 +1791,14 @@ function createSyncManager(config) {
     onDocEvict: (nodeId, doc) => {
       broadcastDocs.delete(nodeId);
       config.onDocEvict?.(nodeId, doc);
-    }
+    },
+    onDocPersist: config.documentHistory ? (nodeId, doc, context) => {
+      const history = config.documentHistory;
+      const capture = context === "debounce" ? history.captureSnapshot(nodeId, doc) : history.forceCapture(nodeId, doc);
+      void capture.catch(
+        (err) => console.warn(`[SyncManager] Yjs snapshot capture failed for ${nodeId}:`, err)
+      );
+    } : void 0
   });
   const registry = createRegistry({
     storage: createRegistryStorageAdapter(config.storage),
@@ -1841,7 +1864,14 @@ function createSyncManager(config) {
     storage: config.storage
   });
   let offlineQueueReady = Promise.resolve();
-  const nodeSyncProvider = config.nodeSyncRoom ? new NodeStoreSyncProvider(config.nodeStore, config.nodeSyncRoom) : null;
+  const nodeSyncProvider = config.nodeSyncRoom ? new NodeStoreSyncProvider(
+    config.nodeStore,
+    config.nodeSyncRoom,
+    false,
+    // Draft privacy (0329): device-local draft nodes/clones never publish
+    // to the personal node-sync room.
+    (change) => !config.nodeStore.isDraftPrivate(change.payload.nodeId)
+  ) : null;
   const shareRoomProviders = /* @__PURE__ */ new Map();
   let blobSync = null;
   if (config.blobStore) {
@@ -2530,6 +2560,15 @@ function buildNodeStore(options, storage) {
     telemetry: options.telemetry
   });
 }
+function buildDocumentHistory(storage) {
+  const snapshotStorage = storage;
+  if (typeof snapshotStorage.saveYjsSnapshot !== "function" || typeof snapshotStorage.getYjsSnapshots !== "function" || typeof snapshotStorage.deleteYjsSnapshots !== "function") {
+    return void 0;
+  }
+  return new DocumentHistoryEngine(snapshotStorage, {
+    pins: storage.pins
+  });
+}
 function buildSyncManager(store, storage, options) {
   const sync = options.sync;
   if (!sync) return null;
@@ -2537,6 +2576,7 @@ function buildSyncManager(store, storage, options) {
   return createSyncManager({
     nodeStore: store,
     storage,
+    documentHistory: buildDocumentHistory(storage),
     signalingUrl,
     authorDID: options.authorDID,
     signingKey: options.signingKey,
@@ -2558,6 +2598,14 @@ function startSyncManager(syncManager, bridge, sync, telemetry) {
   if (sync.autoStart === false) return;
   syncManager.start().catch((err) => reportCrash(telemetry, err, "runtime.syncManager.start"));
 }
+async function startSyncManagerWithDraftPrivacy(store, syncManager, bridge, sync, telemetry) {
+  try {
+    await rehydrateDraftPrivacy(store);
+  } catch (err) {
+    reportCrash(telemetry, err, "runtime.drafts.rehydratePrivacy");
+  }
+  startSyncManager(syncManager, bridge, sync, telemetry);
+}
 function buildPlugins(store, options) {
   const plugins = options.plugins;
   if (!plugins) return null;
@@ -2601,7 +2649,9 @@ async function createXNetClient(options) {
   const bridgeCreatedInternally = !dataBridge;
   const bridge = dataBridge ?? createMainThreadBridgeSync(store, bridgeOptions);
   const syncManager = buildSyncManager(store, storage, options);
-  if (syncManager && sync) startSyncManager(syncManager, bridge, sync, telemetry);
+  if (syncManager && sync) {
+    void startSyncManagerWithDraftPrivacy(store, syncManager, bridge, sync, telemetry);
+  }
   const pluginRegistry = buildPlugins(store, options);
   const undoManager = buildUndo(store, options);
   const publicKey = getSigningPublicKeyFromPrivate(signingKey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xnetjs/runtime",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Framework-agnostic xNet runtime: createXNetClient() and sync orchestration, usable from any framework, a CLI, a worker, or a Node service",
   "license": "MIT",
   "repository": {
@@ -28,15 +28,15 @@
   "dependencies": {
     "y-protocols": "^1.0.6",
     "yjs": "^13.6.24",
-    "@xnetjs/core": "1.0.0",
-    "@xnetjs/crypto": "1.0.0",
-    "@xnetjs/data": "1.0.0",
-    "@xnetjs/data-bridge": "1.0.0",
-    "@xnetjs/history": "1.0.0",
-    "@xnetjs/identity": "1.0.0",
-    "@xnetjs/plugins": "1.0.0",
-    "@xnetjs/storage": "1.0.0",
-    "@xnetjs/sync": "1.0.0"
+    "@xnetjs/core": "2.1.0",
+    "@xnetjs/crypto": "2.1.0",
+    "@xnetjs/data": "2.1.0",
+    "@xnetjs/data-bridge": "2.1.0",
+    "@xnetjs/history": "2.1.0",
+    "@xnetjs/identity": "2.1.0",
+    "@xnetjs/plugins": "2.1.0",
+    "@xnetjs/storage": "2.1.0",
+    "@xnetjs/sync": "2.1.0"
   },
   "devDependencies": {
     "jsdom": "^26.0.0",