@graphrefly/graphrefly 0.27.0 → 0.28.0

package/dist/extra/sources.d.cts

@@ -1,4 +1,4 @@
-import { a as NodeOptions, N as Node } from '../node-BmerH3kS.cjs';
+import { N as NodeOptions, a as Node } from '../node-Cc1TniY8.cjs';
 
 /**
  * Core reactive sources, sinks, and utilities (roadmap §2.3).
@@ -401,6 +401,10 @@ declare function firstValueFrom<T>(source: Node<T>): Promise<T>;
  * @category extra
  */
 declare function firstWhere<T>(source: Node<T>, predicate: (value: T) => boolean): Promise<T>;
+declare function awaitSettled<T>(source: Node<T>, opts?: {
+    predicate?: (value: T) => boolean;
+    timeoutMs?: number;
+}): Promise<NonNullable<T>>;
 /**
  * RxJS-named alias for {@link replay} — multicast with a replay buffer of size `bufferSize`.
  *
@@ -462,4 +466,4 @@ type ReactiveCounterBundle = {
  */
 declare function reactiveCounter(cap: number): ReactiveCounterBundle;
 
-export { type AsyncSourceOpts, type EventTargetLike, type FromCronOptions, type NodeInput, type ReactiveCounterBundle, cached, empty, escapeRegexChar, firstValueFrom, firstWhere, forEach, fromAny, fromAsyncIter, fromCron, fromEvent, fromIter, fromPromise, fromRaf, fromTimer, globToRegExp, keepalive, matchesAnyPattern, never, of, reactiveCounter, replay, share, shareReplay, throwError, toArray };
+export { type AsyncSourceOpts, type EventTargetLike, type FromCronOptions, type NodeInput, type ReactiveCounterBundle, awaitSettled, cached, empty, escapeRegexChar, firstValueFrom, firstWhere, forEach, fromAny, fromAsyncIter, fromCron, fromEvent, fromIter, fromPromise, fromRaf, fromTimer, globToRegExp, keepalive, matchesAnyPattern, never, of, reactiveCounter, replay, share, shareReplay, throwError, toArray };

package/dist/extra/sources.d.ts

@@ -1,4 +1,4 @@
-import { a as NodeOptions, N as Node } from '../node-BmerH3kS.js';
+import { N as NodeOptions, a as Node } from '../node-Cc1TniY8.js';
 
 /**
  * Core reactive sources, sinks, and utilities (roadmap §2.3).
@@ -401,6 +401,10 @@ declare function firstValueFrom<T>(source: Node<T>): Promise<T>;
  * @category extra
  */
 declare function firstWhere<T>(source: Node<T>, predicate: (value: T) => boolean): Promise<T>;
+declare function awaitSettled<T>(source: Node<T>, opts?: {
+    predicate?: (value: T) => boolean;
+    timeoutMs?: number;
+}): Promise<NonNullable<T>>;
 /**
  * RxJS-named alias for {@link replay} — multicast with a replay buffer of size `bufferSize`.
  *
@@ -462,4 +466,4 @@ type ReactiveCounterBundle = {
  */
 declare function reactiveCounter(cap: number): ReactiveCounterBundle;
 
-export { type AsyncSourceOpts, type EventTargetLike, type FromCronOptions, type NodeInput, type ReactiveCounterBundle, cached, empty, escapeRegexChar, firstValueFrom, firstWhere, forEach, fromAny, fromAsyncIter, fromCron, fromEvent, fromIter, fromPromise, fromRaf, fromTimer, globToRegExp, keepalive, matchesAnyPattern, never, of, reactiveCounter, replay, share, shareReplay, throwError, toArray };
+export { type AsyncSourceOpts, type EventTargetLike, type FromCronOptions, type NodeInput, type ReactiveCounterBundle, awaitSettled, cached, empty, escapeRegexChar, firstValueFrom, firstWhere, forEach, fromAny, fromAsyncIter, fromCron, fromEvent, fromIter, fromPromise, fromRaf, fromTimer, globToRegExp, keepalive, matchesAnyPattern, never, of, reactiveCounter, replay, share, shareReplay, throwError, toArray };

package/dist/extra/sources.js

@@ -1,57 +1 @@
-import {
-  cached,
-  empty,
-  escapeRegexChar,
-  firstValueFrom,
-  firstWhere,
-  forEach,
-  fromAny,
-  fromAsyncIter,
-  fromCron,
-  fromEvent,
-  fromIter,
-  fromPromise,
-  fromRaf,
-  fromTimer,
-  globToRegExp,
-  keepalive,
-  matchesAnyPattern,
-  never,
-  of,
-  reactiveCounter,
-  replay,
-  share,
-  shareReplay,
-  throwError,
-  toArray
-} from "../chunk-BVZYTZ5H.js";
-import "../chunk-PHOUUNK7.js";
-import "../chunk-SX52TAR4.js";
-export {
-  cached,
-  empty,
-  escapeRegexChar,
-  firstValueFrom,
-  firstWhere,
-  forEach,
-  fromAny,
-  fromAsyncIter,
-  fromCron,
-  fromEvent,
-  fromIter,
-  fromPromise,
-  fromRaf,
-  fromTimer,
-  globToRegExp,
-  keepalive,
-  matchesAnyPattern,
-  never,
-  of,
-  reactiveCounter,
-  replay,
-  share,
-  shareReplay,
-  throwError,
-  toArray
-};
-//# sourceMappingURL=sources.js.map
+import{A as y,B as z,c as a,d as b,e as c,f as d,g as e,h as f,i as g,j as h,k as i,l as j,m as k,n as l,o as m,p as n,q as o,r as p,s as q,t as r,u as s,v as t,w as u,x as v,y as w,z as x}from"../chunk-2PMCKKRK.js";import"../chunk-ZB5EHBIO.js";import"../chunk-CK2E7BTU.js";import"../chunk-QYADASLV.js";export{w as awaitSettled,t as cached,m as empty,a as escapeRegexChar,u as firstValueFrom,v as firstWhere,p as forEach,k as fromAny,j as fromAsyncIter,f as fromCron,g as fromEvent,h as fromIter,i as fromPromise,e as fromRaf,d as fromTimer,b as globToRegExp,y as keepalive,c as matchesAnyPattern,n as never,l as of,z as reactiveCounter,s as replay,r as share,x as shareReplay,o as throwError,q as toArray};

package/dist/extra/storage-browser.cjs

@@ -0,0 +1 @@
+"use strict";var K=Object.defineProperty;var Se=Object.getOwnPropertyDescriptor;var De=Object.getOwnPropertyNames;var Oe=Object.prototype.hasOwnProperty;var Re=(t,e)=>{for(var n in e)K(t,n,{get:e[n],enumerable:!0})},Ce=(t,e,n,s)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of De(e))!Oe.call(t,r)&&r!==n&&K(t,r,{get:()=>e[r],enumerable:!(s=Se(e,r))||s.enumerable});return t};var Ie=t=>Ce(K({},"__esModule",{value:!0}),t);var Ze={};Re(Ze,{fromIDBRequest:()=>Ye,fromIDBTransaction:()=>Ke,indexedDbStorage:()=>Xe});module.exports=Ie(Ze);var G=Symbol.for("graphrefly/START"),_=Symbol.for("graphrefly/DATA"),A=Symbol.for("graphrefly/DIRTY"),E=Symbol.for("graphrefly/RESOLVED"),M=Symbol.for("graphrefly/INVALIDATE"),S=Symbol.for("graphrefly/PAUSE"),H=Symbol.for("graphrefly/RESUME"),N=Symbol.for("graphrefly/TEARDOWN"),v=Symbol.for("graphrefly/COMPLETE"),h=Symbol.for("graphrefly/ERROR"),D=Object.freeze([A]),J=Object.freeze([E]),Fe=Object.freeze([M]),X=Object.freeze([G]),Ge=Object.freeze([v]),He=Object.freeze([N]),Z=Object.freeze([D]),le=Object.freeze([J]),ce=Object.freeze([Fe]),ue=Object.freeze([Ge]),Q=Object.freeze([He]);var Le={name:"json",version:1,contentType:"application/json",encode(t){let e=JSON.stringify(t);return new TextEncoder().encode(e)},decode(t,e){let n=new TextDecoder().decode(t);return JSON.parse(n)}};function fe(t){t.registerCodec(Le)}var Ve={type:"system",id:""};function B(t){if(t==null)return Ve;let{type:e,id:n,...s}=t;return{type:e??"system",id:n??"",...s}}var ee=0,Pe=!1,he=[],pe=[],ge=[],Be=[];function _e(){return ee>0||Pe}function ye(){return ee>0}function me(t){ee>0?Be.push(t):t()}function U(t,e,n){if(e.length===0)return;if(e.length===1){let l=n(e[0][0]);if(l<3||!_e()){t(e);return}(l>=5?ge:l===4?pe:he).push(()=>t(e));return}let s=e.length,r=s,o=s,i=s,a=0;for(;a<s&&n(e[a][0])<3;)a++;for(r=a;a<s&&n(e[a][0])===3;)a++;for(o=a;a<s&&n(e[a][0])===4;)a++;i=a;let d=_e();if(r>0){let l=e.slice(0,r);t(l)}if(o>r){let l=e.slice(r,o);d?he.push(()=>t(l)):t(l)}if(i>o){let l=e.slice(o,i);d?pe.push(()=>t(l)):t(l)}if(s>i){let l=e.slice(i,s);d?ge.push(()=>t(l)):t(l)}}function be(){return Date.now()*1e6}var W=class{_messageTypes=new Map;_codecs=new Map;_onMessage;_onSubscribe;_defaultVersioning;_defaultHashFn;_inspectorEnabled=!(typeof process<"u"&&process.env?.NODE_ENV==="production");_globalInspector;_frozen=!1;tierOf;constructor(e){this._onMessage=e.onMessage,this._onSubscribe=e.onSubscribe,this._defaultVersioning=e.defaultVersioning,this._defaultHashFn=e.defaultHashFn,this.tierOf=n=>{let s=this._messageTypes.get(n);return s!=null?s.tier:1}}get onMessage(){return this._frozen=!0,this._onMessage}get onSubscribe(){return this._frozen=!0,this._onSubscribe}set onMessage(e){this._assertUnfrozen(),this._onMessage=e}set onSubscribe(e){this._assertUnfrozen(),this._onSubscribe=e}get defaultVersioning(){return this._defaultVersioning}set defaultVersioning(e){this._assertUnfrozen(),this._defaultVersioning=e}get defaultHashFn(){return this._defaultHashFn}set defaultHashFn(e){this._assertUnfrozen(),this._defaultHashFn=e}get inspectorEnabled(){return this._inspectorEnabled}set inspectorEnabled(e){this._inspectorEnabled=e}get globalInspector(){return this._globalInspector}set globalInspector(e){this._globalInspector=e}registerMessageType(e,n){return this._assertUnfrozen(),this._messageTypes.set(e,{tier:n.tier,wireCrossing:n.wireCrossing??n.tier>=3,metaPassthrough:n.metaPassthrough??!0}),this}messageTier(e){let n=this._messageTypes.get(e);return n!=null?n.tier:1}isWireCrossing(e){let n=this._messageTypes.get(e);return n!=null?n.wireCrossing:!0}isLocalOnly(e){return!this.isWireCrossing(e)}isMetaPassthrough(e){let n=this._messageTypes.get(e);return n!=null?n.metaPassthrough:!0}isKnownMessageType(e){return this._messageTypes.has(e)}registerCodec(e){return this._assertUnfrozen(),this._codecs.set(e.name,e),this}lookupCodec(e){return this._codecs.get(e)}_isFrozen(){return this._frozen}_assertUnfrozen(){if(this._frozen)throw new Error("GraphReFlyConfig is frozen: a node has already captured this config. Register custom types and set hooks before creating any node.")}};function ve(t){t.registerMessageType(G,{tier:0,wireCrossing:!1}),t.registerMessageType(A,{tier:1,wireCrossing:!1}),t.registerMessageType(M,{tier:1,wireCrossing:!1,metaPassthrough:!1}),t.registerMessageType(S,{tier:2,wireCrossing:!1}),t.registerMessageType(H,{tier:2,wireCrossing:!1}),t.registerMessageType(_,{tier:3,wireCrossing:!0}),t.registerMessageType(E,{tier:3,wireCrossing:!0}),t.registerMessageType(v,{tier:4,wireCrossing:!0,metaPassthrough:!1}),t.registerMessageType(h,{tier:4,wireCrossing:!0,metaPassthrough:!1}),t.registerMessageType(N,{tier:5,wireCrossing:!0,metaPassthrough:!1})}var O=class extends Error{actor;action;nodeName;constructor(e,n){super(n??`GuardDenied: action "${String(e.action)}" denied for actor type "${String(e.actor.type)}"`),this.name="GuardDenied",this.actor=e.actor,this.action=e.action,this.nodeName=e.nodeName}get node(){return this.nodeName}};function ne(t){if(t===void 0)return null;if(typeof t=="number"){if(!Number.isFinite(t))throw new TypeError(`Cannot hash non-finite number: ${t}`);if(Number.isInteger(t)&&!Number.isSafeInteger(t))throw new TypeError(`Cannot hash integer outside safe range (|n| > 2^53-1): ${t}. Cross-language cid parity is not guaranteed for unsafe integers.`);return t}if(typeof t=="string"||typeof t=="boolean"||t===null)return t;if(Array.isArray(t))return t.map(ne);if(typeof t=="object"&&t!==null){let e={};for(let n of Object.keys(t).sort())e[n]=ne(t[n]);return e}return null}var Ue=new Uint32Array([1116352408,1899447441,3049323471,3921009573,961987163,1508970993,2453635748,2870763221,3624381080,310598401,607225278,1426881987,1925078388,2162078206,2614888103,3248222580,3835390401,4022224774,264347078,604807628,770255983,1249150122,1555081692,1996064986,2554220882,2821834349,2952996808,3210313671,3336571891,3584528711,113926993,338241895,666307205,773529912,1294757372,1396182291,1695183700,1986661051,2177026350,2456956037,2730485921,2820302411,3259730800,3345764771,3516065817,3600352804,4094571909,275423344,430227734,506948616,659060556,883997877,958139571,1322822218,1537002063,1747873779,1955562222,2024104815,2227730452,2361852424,2428436474,2756734187,3204031479,3329325298]),We=new TextEncoder;function je(t){let e=We.encode(t),n=e.length,s=n*8,r=n+9+63&-64,o=new Uint8Array(r);o.set(e),o[n]=128;let i=new DataView(o.buffer);i.setUint32(r-4,s>>>0,!1),i.setUint32(r-8,Math.floor(s/4294967296)>>>0,!1);let a=1779033703,d=3144134277,l=1013904242,c=2773480762,u=1359893119,f=2600822924,g=528734635,y=1541459225,k=new Uint32Array(64),b=(x,m)=>x>>>m|x<<32-m;for(let x=0;x<r;x+=64){for(let p=0;p<16;p++)k[p]=i.getUint32(x+p*4,!1);for(let p=16;p<64;p++){let I=k[p-15],F=k[p-2],P=b(I,7)^b(I,18)^I>>>3,Y=b(F,17)^b(F,19)^F>>>10;k[p]=k[p-16]+P+k[p-7]+Y>>>0}let m=a,R=d,C=l,$=c,T=u,L=f,V=g,q=y;for(let p=0;p<64;p++){let I=b(T,6)^b(T,11)^b(T,25),F=T&L^~T&V,P=q+I+F+Ue[p]+k[p]>>>0,Y=b(m,2)^b(m,13)^b(m,22),Ee=m&R^m&C^R&C,Me=Y+Ee>>>0;q=V,V=L,L=T,T=$+P>>>0,$=C,C=R,R=m,m=P+Me>>>0}a=a+m>>>0,d=d+R>>>0,l=l+C>>>0,c=c+$>>>0,u=u+T>>>0,f=f+L>>>0,g=g+V>>>0,y=y+q>>>0}let w=x=>x.toString(16).padStart(8,"0");return w(a)+w(d)+w(l)+w(c)+w(u)+w(f)+w(g)+w(y)}function te(t){let e=ne(t??null),n=JSON.stringify(e);return je(n).slice(0,16)}function ze(){let t=globalThis.crypto;if(t?.randomUUID)return t.randomUUID();let e=()=>Math.floor(Math.random()*4294967296).toString(16).padStart(8,"0"),n=e()+e()+e()+e();return`${n.slice(0,8)}-${n.slice(8,12)}-4${n.slice(13,16)}-${(parseInt(n.slice(16,17),16)&3|8).toString(16)}${n.slice(17,20)}-${n.slice(20,32)}`}function se(t,e,n){let s=n?.id??ze();if(t===0)return{id:s,version:0};let o=(n?.hash??te)(e);return{id:s,version:0,cid:o,prev:null}}function we(t,e,n){t.version+=1,"cid"in t&&(t.prev=t.cid,t.cid=n(e))}var xe=()=>{},Te=100;function Ne(t){return{node:t,unsub:null,prevData:void 0,dirty:!1,involvedThisWave:!1,dataBatch:[],terminal:void 0}}function re(t){t.prevData=void 0,t.dirty=!1,t.involvedThisWave=!1,t.dataBatch.length=0,t.terminal=void 0}function j(t){return t.length===0?t:typeof t[0]=="symbol"?[t]:t}var $e=(t,e,n,s)=>{n.direction==="down-in"&&t._onDepMessage(n.depIndex,e)},qe=(t,e,n,s)=>{let r=t;if(r._status==="completed"||r._status==="errored")return;let o=r._cached,i=o===void 0?[X]:[X,[_,o]];r._status==="dirty"&&i.push(D),U(e,i,r._config.tierOf)},ie=new W({onMessage:$e,onSubscribe:qe});ve(ie);fe(ie);var z=class t{_optsName;_describeKind;meta;_hasMeta;_config;_deps;_sinks=null;_sinkCount=0;_cached;_status;_cleanup;_store={};_waveHasNewData=!1;_hasNewTerminal=!1;_hasCalledFnOnce=!1;_paused=!1;_pendingWave=!1;_isExecutingFn=!1;_pendingRerun=!1;_rerunDepth=0;_dirtyDepCount=0;_batchPendingMessages=null;_pauseLocks=null;_pauseBuffer=null;_fn;_equals;_resubscribable;_resetOnTeardown;_autoComplete;_autoError;_pausable;_guard;_extraGuards;_hashFn;_versioning;_versioningLevel;_lastMutation;_inspectorHooks;_actions;constructor(e,n,s){this._config=s.config??ie,this._config.onMessage,this._optsName=s.name,this._describeKind=s.describeKind,this._equals=s.equals??Object.is,this._resubscribable=s.resubscribable??!1,this._resetOnTeardown=s.resetOnTeardown??!1,this._autoComplete=s.completeWhenDepsComplete??!0,this._autoError=s.errorWhenDepsError??!0,this._pausable=s.pausable??!0,this._guard=s.guard,this._fn=n,this._cached=s.initial!==void 0?s.initial:void 0,this._status=e.length===0&&n==null&&this._cached!==void 0?"settled":"sentinel",this._hashFn=s.versioningHash??this._config.defaultHashFn??te;let r=s.versioning??this._config.defaultVersioning;this._versioningLevel=r,this._versioning=r!=null?se(r,this._cached===void 0?void 0:this._cached,{id:s.versioningId,hash:this._hashFn}):void 0,this._deps=e.map(Ne);let o={};for(let[a,d]of Object.entries(s.meta??{})){let l={initial:d,name:`${s.name??"node"}:meta:${a}`,describeKind:"state",config:this._config};s.guard!=null&&(l.guard=s.guard),o[a]=new t([],void 0,l)}Object.freeze(o),this.meta=o,this._hasMeta=Object.keys(o).length>0;let i=this;this._actions={emit(a){i._emit([[_,a]])},down(a){i._emit(j(a))},up(a){i._emitUp(j(a))}},this.down=this.down.bind(this),this.up=this.up.bind(this)}get _isTerminal(){return this._status==="completed"||this._status==="errored"}get name(){return this._optsName}get status(){return this._status}get cache(){return this._cached===void 0?void 0:this._cached}get lastMutation(){return this._lastMutation}get v(){return this._versioning}hasGuard(){return this._guard!=null}_applyVersioning(e,n){if(this._isExecutingFn)throw new Error(`Node "${this.name}": _applyVersioning cannot run mid-fn \u2014 call it outside of \`_execFn\` (typically at graph setup time before the first subscribe).`);let s=this._versioningLevel;if(s!=null&&e<=s)return;let r=n?.hash??this._hashFn;r!==this._hashFn&&(this._hashFn=r);let o=this._cached===void 0?void 0:this._cached,i=this._versioning,a=i?.id??n?.id,d=i?.version??0,l=se(e,o,{id:a,hash:r});l.version=d,this._versioning=l,this._versioningLevel=e}_setInspectorHook(e){return e==null?()=>{}:(this._inspectorHooks==null&&(this._inspectorHooks=new Set),this._inspectorHooks.add(e),()=>{this._inspectorHooks?.delete(e),this._inspectorHooks?.size===0&&(this._inspectorHooks=void 0)})}_pushGuard(e){return this._extraGuards==null&&(this._extraGuards=new Set),this._extraGuards.add(e),()=>{this._extraGuards?.delete(e),this._extraGuards?.size===0&&(this._extraGuards=void 0)}}allowsObserve(e){if(this._guard==null&&this._extraGuards==null)return!0;let n=B(e);if(this._guard!=null&&!this._guard(n,"observe"))return!1;if(this._extraGuards!=null){for(let s of this._extraGuards)if(!s(n,"observe"))return!1}return!0}_checkGuard(e){if(e?.internal)return;let n=this._guard!=null||this._extraGuards!=null,s=e?.actor!=null;if(!n&&!s)return;let r=B(e?.actor),o=e?.delivery==="signal"?"signal":"write";if(this._guard!=null&&!this._guard(r,o))throw new O({actor:r,action:o,nodeName:this.name});if(this._extraGuards!=null){for(let i of this._extraGuards)if(!i(r,o))throw new O({actor:r,action:o,nodeName:this.name})}this._lastMutation={actor:r,timestamp_ns:be()}}down(e,n){let s=j(e);s.length!==0&&(this._checkGuard(n),this._emit(s))}emit(e,n){this._checkGuard(n),this._emit([[_,e]])}up(e,n){if(this._deps.length===0)return;let s=j(e);if(s.length===0)return;this._checkGuard(n);let r=n??{internal:!0};this._validateUpTiers(s);for(let o of this._deps)o.node.up?.(s,r)}_emitUp(e){if(this._deps.length!==0&&e.length!==0){this._validateUpTiers(e);for(let n of this._deps)n.node.up?.(e,{internal:!0})}}_validateUpTiers(e){let n=this._config.tierOf;for(let s of e){let r=n(s[0]);if(r===3||r===4)throw new Error(`Node "${this.name}": tier-${r} messages cannot flow up \u2014 DATA/RESOLVED/COMPLETE/ERROR are downstream-only. Use \`down(...)\` for value delivery; \`up(...)\` is for control signals (DIRTY, INVALIDATE, PAUSE, RESUME, TEARDOWN).`)}}subscribe(e,n){if(n!=null&&this._guard!=null){let d=B(n);if(!this._guard(d,"observe"))throw new O({actor:d,action:"observe",nodeName:this.name})}let r=this._isTerminal&&this._resubscribable;if(r){this._cached=void 0,this._status="sentinel",this._store={},this._hasCalledFnOnce=!1,this._waveHasNewData=!1,this._hasNewTerminal=!1,this._paused=!1,this._pendingWave=!1,this._pendingRerun=!1,this._isExecutingFn=!1,this._rerunDepth=0,this._dirtyDepCount=0,this._pauseLocks=null,this._pauseBuffer=null;for(let d of this._deps)re(d)}this._sinkCount+=1;let o;try{o=this._config.onSubscribe(this,e,{sinkCount:this._sinkCount,afterTerminalReset:r},this._actions)}catch(d){throw this._sinkCount-=1,d}this._sinks==null?this._sinks=e:typeof this._sinks=="function"?this._sinks=new Set([this._sinks,e]):this._sinks.add(e);let i=this._isTerminal;if(this._sinkCount===1&&!i)try{this._activate()}catch(d){if(this._sinkCount-=1,this._removeSink(e),this._sinkCount===0&&(this._status="sentinel"),typeof o=="function")try{o()}catch{}throw d}this._status==="sentinel"&&this._cached===void 0&&(this._status="pending");let a=!1;return()=>{a||(a=!0,this._sinkCount-=1,this._removeSink(e),typeof o=="function"&&o(),this._sinks==null&&this._deactivate())}}_removeSink(e){if(this._sinks===e)this._sinks=null;else if(this._sinks!=null&&typeof this._sinks!="function")if(this._sinks.delete(e),this._sinks.size===1){let[n]=this._sinks;this._sinks=n}else this._sinks.size===0&&(this._sinks=null)}_activate(){if(this._deps.length===0){this._fn&&this._execFn();return}this._dirtyDepCount=0;let e=this._deps.length,n=0;try{for(let s=0;s<e;s++){let r=s,o=this._deps[s];o.unsub=xe,o.unsub=o.node.subscribe(i=>{if(o.unsub===null)return;let a=this._config.tierOf,d=!1;for(let l of i)a(l[0])>=3&&(d=!0),this._config.onMessage(this,l,{direction:"down-in",depIndex:r},this._actions);d&&this._maybeRunFnOnSettlement()}),n++}}catch(s){this._deps[n].unsub=null;for(let r=0;r<n;r++){let o=this._deps[r];if(o.unsub!=null){let i=o.unsub;o.unsub=null;try{i()}catch{}re(o)}}throw this._dirtyDepCount=0,s}}_addDep(e){for(let r=0;r<this._deps.length;r++)if(this._deps[r].node===e)return r;let n=this._deps.length,s=Ne(e);if(this._deps.push(s),this._sinks==null)return n;s.dirty=!0,this._dirtyDepCount++,this._status!=="dirty"&&this._emit(Z),s.unsub=xe;try{s.unsub=e.subscribe(r=>{if(s.unsub===null)return;let o=this._config.tierOf,i=!1;for(let a of r)o(a[0])>=3&&(i=!0),this._config.onMessage(this,a,{direction:"down-in",depIndex:n},this._actions);i&&this._maybeRunFnOnSettlement()})}catch(r){throw s.unsub=null,this._deps.pop(),this._dirtyDepCount--,r}return n}_deactivate(e=!1){let n=this._cleanup;if(this._cleanup=void 0,typeof n=="function")try{n()}catch(s){this._emit([[h,this._wrapFnError("cleanup threw",s)]])}else if(n!=null&&typeof n=="object"){let s=n.deactivate;if(typeof s=="function")try{s()}catch(r){this._emit([[h,this._wrapFnError("cleanup.deactivate threw",r)]])}}for(let s of this._deps){if(s.unsub!=null){let r=s.unsub;s.unsub=null;try{r()}catch{}}re(s)}this._waveHasNewData=!1,this._hasNewTerminal=!1,this._hasCalledFnOnce=!1,this._paused=!1,this._pendingWave=!1,this._pendingRerun=!1,this._rerunDepth=0,this._store={},this._dirtyDepCount=0,this._pauseLocks=null,this._pauseBuffer=null,this._fn!=null&&(this._cached=void 0),e||(this._fn!=null||this._deps.length>0)&&(!this._isTerminal||this._resubscribable)&&(this._status="sentinel")}_onDepMessage(e,n){let s=this._deps[e],r=n[0];if(this._inspectorHooks!=null){let o={kind:"dep_message",depIndex:e,message:n};for(let i of this._inspectorHooks)i(o)}if(r!==G){if(r===A){this._depDirtied(s);return}if(r===M){this._depInvalidated(s),this._emit(ce);return}if(r===S||r===H){this._emit([n]);return}if(r===N){this._emit(Q);return}if(r===_)this._depSettledAsData(s,n[1]);else if(r===E)this._depSettledAsResolved(s);else if(r===v)this._depSettledAsTerminal(s,!0);else if(r===h)this._depSettledAsTerminal(s,n[1]);else{this._emit([n]);return}if(!this._fn){(r===_||r===E)&&this._emit([n]),(r===v||r===h)&&this._maybeAutoTerminalAfterWave();return}}}_depDirtied(e){e.dirty||(e.dirty=!0,e.involvedThisWave=!0,this._dirtyDepCount++,this._status!=="dirty"&&this._emit(Z))}_depSettledAsData(e,n){e.dirty&&(e.dirty=!1,this._dirtyDepCount--),e.involvedThisWave=!0,e.dataBatch.push(n),this._waveHasNewData=!0}_depSettledAsResolved(e){e.dirty&&(e.dirty=!1,this._dirtyDepCount--)}_depSettledAsTerminal(e,n){e.dirty&&(e.dirty=!1,this._dirtyDepCount--),e.terminal=n,e.involvedThisWave=!0,this._hasNewTerminal=!0}_depInvalidated(e){e.prevData=void 0,e.terminal=void 0,e.dataBatch.length=0,e.dirty?e.involvedThisWave=!1:(e.dirty=!0,e.involvedThisWave=!0,this._dirtyDepCount++)}_maybeRunFnOnSettlement(){if(!(this._isTerminal&&!this._resubscribable)&&!(this._dirtyDepCount>0)){if(this._paused){this._pendingWave=!0;return}if(!this._waveHasNewData&&!this._hasNewTerminal&&this._hasCalledFnOnce){this._clearWaveFlags(),this._emit(le),this._maybeAutoTerminalAfterWave();return}this._fn&&this._execFn(),this._maybeAutoTerminalAfterWave()}}_maybeAutoTerminalAfterWave(){if(this._deps.length===0||this._isTerminal)return;let e=this._deps.find(n=>n.terminal!==void 0&&n.terminal!==!0);if(e!=null){this._autoError&&this._emit([[h,e.terminal]]);return}this._autoComplete&&this._deps.every(n=>n.terminal!==void 0)&&this._emit(ue)}_execFn(){if(!this._fn||this._isTerminal&&!this._resubscribable)return;if(this._isExecutingFn){this._pendingRerun=!0;return}let e=this._cleanup;if(typeof e=="function"){this._cleanup=void 0;try{e()}catch(i){this._emit([[h,this._wrapFnError("cleanup threw",i)]]);return}}else if(e!=null&&typeof e=="object"){let i=e.beforeRun;if(typeof i=="function"){e.beforeRun=void 0;try{i()}catch(a){this._emit([[h,this._wrapFnError("cleanup.beforeRun threw",a)]]);return}}}let n=this._deps.map(i=>i.involvedThisWave?i.dataBatch.length>0?[...i.dataBatch]:[]:void 0),s=this._deps.map(i=>i.prevData);for(let i=0;i<this._deps.length;i++){let a=n[i];a!=null&&a.length>0&&(this._deps[i].prevData=a[a.length-1])}let r=this._deps.map(i=>i.terminal),o={prevData:s,terminalDeps:r,store:this._store};if(this._hasCalledFnOnce=!0,this._clearWaveFlags(),this._inspectorHooks!=null){let i={kind:"run",batchData:n,prevData:s};for(let a of this._inspectorHooks)a(i)}this._isExecutingFn=!0;try{let i=this._fn(n,this._actions,o);if(typeof i=="function")this._cleanup=i;else if(i!=null&&typeof i=="object"){let a=i;(typeof a.beforeRun=="function"||typeof a.deactivate=="function"||typeof a.invalidate=="function")&&(this._cleanup=i)}}catch(i){this._emit([[h,this._wrapFnError("fn threw",i)]])}finally{this._isExecutingFn=!1,this._pendingRerun?(this._pendingRerun=!1,this._rerunDepth+=1,this._rerunDepth>Te?(this._rerunDepth=0,this._emit([[h,new Error(`Node "${this.name}": _pendingRerun depth exceeded ${Te} \u2014 likely a reactive cycle`)]])):this._maybeRunFnOnSettlement()):this._rerunDepth=0,this._clearWaveFlags()}}_clearWaveFlags(){this._waveHasNewData=!1,this._hasNewTerminal=!1;for(let e of this._deps)e.involvedThisWave=!1,e.dataBatch.length=0}_wrapFnError(e,n){let s=n instanceof Error?n.message:String(n);return new Error(`Node "${this.name}": ${e}: ${s}`,{cause:n})}_frameBatch(e){let n=this._config.tierOf;if(e.length===1)return n(e[0][0])===3&&this._status!=="dirty"?[D,e[0]]:e;let s=!0,r=!1,o=!1,i=-1;for(let d of e){let l=n(d[0]);l<i&&(s=!1),l===3&&(r=!0),d[0]===A&&(o=!0),i=l}let a=e;if(!s){let d=e.map((l,c)=>({m:l,i:c,tier:n(l[0])}));d.sort((l,c)=>l.tier-c.tier||l.i-c.i),a=d.map(l=>l.m)}if(r&&!o&&this._status!=="dirty"){let d=0;for(;d<a.length&&n(a[d][0])===0;)d++;return d===0?[D,...a]:[...a.slice(0,d),D,...a.slice(d)]}return a}_emit(e){if(e.length===0)return;let n=e;if(this._isTerminal&&!this._resubscribable){let a=e.filter(d=>d[0]===N||d[0]===M);if(a.length===0)return;n=a}n=this._frameBatch(n);let r=null;for(let a=0;a<n.length;a++){let d=n[a],l=d[0];if(l!==S&&l!==H){r?.push(d);continue}if(d.length<2)throw new Error(`Node "${this.name}": [[${l===S?"PAUSE":"RESUME"}]] must carry a lockId payload \u2014 bare PAUSE/RESUME is a protocol violation (C0 rule). Use \`[[PAUSE, lockId]]\` / \`[[RESUME, lockId]]\`.`);let c=!0;if(this._pausable!==!1){let u=d[1];if(l===S)this._pauseLocks==null&&(this._pauseLocks=new Set),this._pauseLocks.add(u),this._paused=!0,this._pausable==="resumeAll"&&this._pauseBuffer==null&&(this._pauseBuffer=[]);else if(this._pauseLocks==null||!this._pauseLocks.has(u))c=!1;else if(this._pauseLocks.delete(u),this._pauseLocks.size===0){if(this._paused=!1,this._pauseBuffer!=null&&this._pauseBuffer.length>0){let f=this._pauseBuffer;this._pauseBuffer=[],this._emit(f)}this._pendingWave&&(this._pendingWave=!1,this._maybeRunFnOnSettlement())}}c?r?.push(d):r==null&&(r=n.slice(0,a))}if(r!=null){if(r.length===0)return;n=r}if(this._hasMeta&&n.some(a=>a[0]===N))for(let a of Object.keys(this.meta))try{this.meta[a]._emit(Q)}catch{}let{finalMessages:o,equalsError:i}=this._updateState(n);if(o.length>0&&this._config.inspectorEnabled){let a=this._config.globalInspector;if(a!=null)try{a({kind:"emit",node:this,messages:o})}catch{}}if(o.length>0)if(this._paused&&this._pausable==="resumeAll"&&this._pauseBuffer!=null){let a=this._config.tierOf,d=[];for(let l of o){let c=a(l[0]);c<3||c===5?d.push(l):this._pauseBuffer.push(l)}d.length>0&&this._dispatchOrAccumulate(d)}else this._dispatchOrAccumulate(o);i!=null&&this._emit([[h,i]])}_updateState(e){let n=this._config.tierOf,s,r,o=-1,i=0;for(let c of e)n(c[0])===3&&i++;let a=i<=1,d=-1;if(this._versioning!=null&&i>1){for(let c=e.length-1;c>=0;c--)if(e[c][0]===_){d=c;break}}for(let c=0;c<e.length;c++){let u=e[c],f=u[0];if(f===_){if(u.length>=2){let g=!1;if(a&&this._cached!==void 0)try{g=this._equals(this._cached,u[1])}catch(y){r=this._wrapFnError("equals threw",y),o=c;break}if(g){s==null&&(s=e.slice(0,c)),s.push(J),this._status="resolved";continue}this._cached=u[1],this._versioning!=null&&(d<0||c===d)&&we(this._versioning,u[1],this._hashFn)}this._status="settled",s?.push(u)}else if(s?.push(u),f===A)this._status="dirty";else if(f===E)this._status="resolved";else if(f===v)this._status="completed";else if(f===h)this._status="errored";else if(f===M){this._cached=void 0,this._status="dirty";let g=this._cleanup;if(typeof g=="function"){this._cleanup=void 0;try{g()}catch{}}else if(g!=null&&typeof g=="object"){let y=g.invalidate;if(typeof y=="function")try{y()}catch{}}}else f===N&&(this._resetOnTeardown&&(this._cached=void 0),this._deactivate(!0),this._status="sentinel")}let l=o>=0?s??e.slice(0,o):s??e;return r!=null?{finalMessages:l,equalsError:r}:{finalMessages:l}}_deliverToSinks=e=>{if(this._sinks==null)return;if(typeof this._sinks=="function"){this._sinks(e);return}let n=[...this._sinks];for(let s of n)s(e)};_dispatchOrAccumulate(e){if(ye()){this._batchPendingMessages===null&&(this._batchPendingMessages=[],me(()=>this._flushBatchPending()));for(let n of e)this._batchPendingMessages.push(n);return}U(this._deliverToSinks,e,this._config.tierOf)}_flushBatchPending(){let e=this._batchPendingMessages;if(e===null||(this._batchPendingMessages=null,e.length===0))return;let n=this._frameBatch(e);U(this._deliverToSinks,n,this._config.tierOf)}},ke=t=>Array.isArray(t),oe=t=>typeof t=="object"&&t!=null&&!Array.isArray(t);function Ae(t,e,n){let s=ke(t)?t:[],r=typeof t=="function"?t:typeof e=="function"?e:void 0,o={};return ke(t)?o=(oe(e)?e:n)??{}:oe(t)?o=t:o=(oe(e)?e:n)??{},new z(s,r,o)}function ae(t,e){return Ae((s,r,o)=>t(r,o)??void 0,{describeKind:"producer",...e})}function Ye(t){return ae(e=>{let n=!1,s=()=>{t.onsuccess=null,t.onerror=null};return t.onsuccess=()=>{n||(n=!0,s(),e.down([[_,t.result],[v]]))},t.onerror=()=>{n||(n=!0,s(),e.down([[h,t.error??new Error("IndexedDB request failed")]]))},()=>{n=!0,s()}})}function Ke(t){return ae(e=>{let n=!1,s=()=>{t.oncomplete=null,t.onerror=null,t.onabort=null};return t.oncomplete=()=>{n||(n=!0,s(),e.down([[_,void 0],[v]]))},t.onerror=()=>{n||(n=!0,s(),e.down([[h,t.error??new Error("IndexedDB transaction failed")]]))},t.onabort=()=>{n||(n=!0,s(),e.down([[h,t.error??new Error("IndexedDB transaction aborted")]]))},()=>{n=!0,s()}})}function Je(t,e,n){return new Promise((s,r)=>{if(typeof indexedDB>"u"){r(new TypeError("indexedDB is not available in this environment"));return}let o=indexedDB.open(t,n);o.onupgradeneeded=()=>{let i=o.result;i.objectStoreNames.contains(e)||i.createObjectStore(e)},o.onsuccess=()=>s(o.result),o.onerror=()=>r(o.error??new Error("IndexedDB open failed"))})}function de(t,e,n,s,r){return Je(t,e,n).then(o=>new Promise((i,a)=>{let d=o.transaction(e,s),l=d.objectStore(e),c=r(l),u,f=!1,g=!1,y=()=>{!f||!g||(o.close(),i(u))};c.onsuccess=()=>{u=c.result,f=!0,y()},c.onerror=()=>{o.close(),a(c.error??new Error("IndexedDB request failed"))},d.oncomplete=()=>{if(g=!0,!f){o.close(),a(new Error("IndexedDB transaction completed without request result"));return}y()},d.onerror=()=>{o.close(),a(d.error??new Error("IndexedDB transaction failed"))},d.onabort=()=>{o.close(),a(d.error??new Error("IndexedDB transaction aborted"))}}))}function Xe(t){let{dbName:e,storeName:n}=t,s=t.version??1,r=t.key??"graphrefly_checkpoint";return{async save(o,i){await de(e,n,s,"readwrite",a=>a.put(i,r))},async load(o){let i=await de(e,n,s,"readonly",a=>a.get(r));return i==null||typeof i!="object"||Array.isArray(i)?null:i},async clear(o){await de(e,n,s,"readwrite",i=>i.delete(r))}}}0&&(module.exports={fromIDBRequest,fromIDBTransaction,indexedDbStorage});

package/dist/extra/storage-browser.d.cts

@@ -0,0 +1,71 @@
+import { a as Node } from '../node-Cc1TniY8.cjs';
+import { StorageTier } from './storage-core.cjs';
+
+/**
+ * Browser-only storage backend + IndexedDB reactive sources.
+ *
+ * `indexedDbStorage` provides async {@link StorageTier} semantics backed by
+ * IndexedDB; `fromIDBRequest` / `fromIDBTransaction` wrap raw IDB primitives
+ * as reactive sources. Imports require the DOM lib — not safe to pull into
+ * Node-only bundles without `lib: ["dom"]` in the consumer's tsconfig.
+ *
+ * The legacy `extra/storage.ts` barrel re-exports this module for back-compat;
+ * browser-first consumers should import from here directly.
+ *
+ * @module
+ */
+
+type IndexedDbStorageSpec = {
+    dbName: string;
+    storeName: string;
+    /** Object-store key under which snapshots are written. @default `"graphrefly_checkpoint"`. */
+    key?: string;
+    version?: number;
+};
+/**
+ * Wraps an `IDBRequest` as a one-shot reactive source.
+ *
+ * @param req - Request whose callbacks are converted to protocol messages.
+ * @returns `Node<T>` that emits `DATA` once on success then `COMPLETE`;
+ *   emits `ERROR` on failure.
+ *
+ * @category extra
+ */
+declare function fromIDBRequest<T>(req: IDBRequest<T>): Node<T>;
+/**
+ * Wraps an `IDBTransaction` terminal lifecycle as a one-shot reactive source.
+ *
+ * @param tx - Transaction to observe.
+ * @returns `Node<void>` that emits `DATA` (`undefined`) then `COMPLETE` on
+ *   success; emits `ERROR` on `error`/`abort`.
+ *
+ * @category extra
+ */
+declare function fromIDBTransaction(tx: IDBTransaction): Node<void>;
+/**
+ * IndexedDB-backed async storage tier (browser runtime).
+ *
+ * All three methods return `Promise`s — pairs naturally with a warm/cold
+ * cadence where async writes are debounced per tier via
+ * `Graph.attachStorage`. Writes use `readwrite` transactions; reads use
+ * `readonly`. Missing records resolve to `null`.
+ *
+ * @param spec - Database name, store name, optional `key` (default
+ *   `"graphrefly_checkpoint"`) and schema `version` (default `1`).
+ * @returns Async {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { indexedDbStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * graph.attachStorage([
+ *   memoryStorage(),
+ *   indexedDbStorage({ dbName: "myApp", storeName: "checkpoints" }),
+ * ]);
+ * ```
+ *
+ * @category extra
+ */
+declare function indexedDbStorage(spec: IndexedDbStorageSpec): StorageTier;
+
+export { type IndexedDbStorageSpec, fromIDBRequest, fromIDBTransaction, indexedDbStorage };

package/dist/extra/storage-browser.d.ts

@@ -0,0 +1,71 @@
+import { a as Node } from '../node-Cc1TniY8.js';
+import { StorageTier } from './storage-core.js';
+
+/**
+ * Browser-only storage backend + IndexedDB reactive sources.
+ *
+ * `indexedDbStorage` provides async {@link StorageTier} semantics backed by
+ * IndexedDB; `fromIDBRequest` / `fromIDBTransaction` wrap raw IDB primitives
+ * as reactive sources. Imports require the DOM lib — not safe to pull into
+ * Node-only bundles without `lib: ["dom"]` in the consumer's tsconfig.
+ *
+ * The legacy `extra/storage.ts` barrel re-exports this module for back-compat;
+ * browser-first consumers should import from here directly.
+ *
+ * @module
+ */
+
+type IndexedDbStorageSpec = {
+    dbName: string;
+    storeName: string;
+    /** Object-store key under which snapshots are written. @default `"graphrefly_checkpoint"`. */
+    key?: string;
+    version?: number;
+};
+/**
+ * Wraps an `IDBRequest` as a one-shot reactive source.
+ *
+ * @param req - Request whose callbacks are converted to protocol messages.
+ * @returns `Node<T>` that emits `DATA` once on success then `COMPLETE`;
+ *   emits `ERROR` on failure.
+ *
+ * @category extra
+ */
+declare function fromIDBRequest<T>(req: IDBRequest<T>): Node<T>;
+/**
+ * Wraps an `IDBTransaction` terminal lifecycle as a one-shot reactive source.
+ *
+ * @param tx - Transaction to observe.
+ * @returns `Node<void>` that emits `DATA` (`undefined`) then `COMPLETE` on
+ *   success; emits `ERROR` on `error`/`abort`.
+ *
+ * @category extra
+ */
+declare function fromIDBTransaction(tx: IDBTransaction): Node<void>;
+/**
+ * IndexedDB-backed async storage tier (browser runtime).
+ *
+ * All three methods return `Promise`s — pairs naturally with a warm/cold
+ * cadence where async writes are debounced per tier via
+ * `Graph.attachStorage`. Writes use `readwrite` transactions; reads use
+ * `readonly`. Missing records resolve to `null`.
+ *
+ * @param spec - Database name, store name, optional `key` (default
+ *   `"graphrefly_checkpoint"`) and schema `version` (default `1`).
+ * @returns Async {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { indexedDbStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * graph.attachStorage([
+ *   memoryStorage(),
+ *   indexedDbStorage({ dbName: "myApp", storeName: "checkpoints" }),
+ * ]);
+ * ```
+ *
+ * @category extra
+ */
+declare function indexedDbStorage(spec: IndexedDbStorageSpec): StorageTier;
+
+export { type IndexedDbStorageSpec, fromIDBRequest, fromIDBTransaction, indexedDbStorage };

package/dist/extra/storage-browser.js

@@ -0,0 +1 @@
+import{a,b,c}from"../chunk-DQA3UIQ2.js";import"../chunk-ZB5EHBIO.js";import"../chunk-CK2E7BTU.js";import"../chunk-QYADASLV.js";export{a as fromIDBRequest,b as fromIDBTransaction,c as indexedDbStorage};

package/dist/extra/storage-core.cjs

@@ -0,0 +1 @@
+"use strict";var s=Object.defineProperty;var u=Object.getOwnPropertyDescriptor;var a=Object.getOwnPropertyNames;var d=Object.prototype.hasOwnProperty;var c=(n,r)=>{for(var e in r)s(n,e,{get:r[e],enumerable:!0})},g=(n,r,e,o)=>{if(r&&typeof r=="object"||typeof r=="function")for(let t of a(r))!d.call(n,t)&&t!==e&&s(n,t,{get:()=>r[t],enumerable:!(o=u(r,t))||o.enumerable});return n};var f=n=>g(s({},"__esModule",{value:!0}),n);var S={};c(S,{dictStorage:()=>l,memoryStorage:()=>y,sortJsonValue:()=>i,stableJsonString:()=>k});module.exports=f(S);function i(n){if(n===null||typeof n!="object")return n;if(Array.isArray(n))return n.map(i);let r=n,e=Object.keys(r).sort(),o={};for(let t of e)o[t]=i(r[t]);return o}function k(n){return JSON.stringify(i(n),void 0,0)}function y(){let n=new Map;return{save(r,e){n.set(r,JSON.parse(JSON.stringify(e)))},load(r){let e=n.get(r);return e===void 0?null:JSON.parse(JSON.stringify(e))},clear(r){n.delete(r)},list(){return[...n.keys()].sort()}}}function l(n){return{save(r,e){n[r]=JSON.parse(JSON.stringify(e))},load(r){let e=n[r];return e===void 0?null:JSON.parse(JSON.stringify(e))},clear(r){delete n[r]},list(){return Object.keys(n).sort()}}}0&&(module.exports={dictStorage,memoryStorage,sortJsonValue,stableJsonString});

package/dist/extra/storage-core.d.cts

@@ -0,0 +1,98 @@
+/**
+ * Storage tier primitive — browser-safe core (types + in-memory backends).
+ *
+ * Split out of `extra/storage.ts` so browser bundles can import the
+ * {@link StorageTier} contract, {@link memoryStorage}, {@link dictStorage}
+ * and shared JSON helpers without pulling `node:fs` / `node:sqlite` /
+ * `node:crypto`. Node-only backends (`fileStorage`, `sqliteStorage`) live in
+ * {@link ./storage-node}; browser-only ones (`indexedDbStorage`,
+ * `fromIDBRequest`, `fromIDBTransaction`) live in {@link ./storage-browser}.
+ * The legacy `extra/storage.ts` module re-exports all three for back-compat.
+ *
+ * @module
+ */
+/**
+ * Single persistence primitive — supports sync and async backends alike via
+ * `void | Promise<void>` returns. `debounceMs` / `compactEvery` / `filter`
+ * are per-tier cadence controls honored by `Graph.attachStorage`;
+ * `cascadingCache` ignores them (it has its own eviction policy).
+ */
+interface StorageTier {
+    /** Read a value. Returns `null` (or resolves to `null`) on miss. */
+    load(key: string): unknown | Promise<unknown>;
+    /** Write a record. Sync tiers return `void`; async tiers return `Promise<void>`. */
+    save(key: string, data: unknown): void | Promise<void>;
+    /** Delete a value. Optional — tiers without `clear` are append/overwrite-only. */
+    clear?(key: string): void | Promise<void>;
+    /**
+     * Enumerate known keys. Optional — tiers that only address a single record
+     * (e.g. `indexedDbStorage`) or that can't cheaply enumerate (e.g. a remote
+     * write-only sink) may omit it. Callers that require enumeration (the
+     * surface `snapshot.list()` helper, MCP `graphrefly_snapshot_list`, CLI
+     * `graphrefly snapshot list`) should check before calling.
+     */
+    list?(): readonly string[] | Promise<readonly string[]>;
+    /**
+     * Debounce saves on this tier (ms). Hot tier: `0` (sync-through).
+     * Warm: `1000`. Cold: `60000`. Each tier holds its own last-save baseline,
+     * so cold flushes aren't penalized by hot flushes.
+     */
+    debounceMs?: number;
+    /**
+     * Every Nth record is a full snapshot; others are diffs against this
+     * tier's own baseline. Default `10`. Set `1` for always-full;
+     * `Number.POSITIVE_INFINITY` is unsafe — WAL replay needs periodic anchors.
+     */
+    compactEvery?: number;
+    /** Pre-save filter — return `false` to skip this record on this tier. */
+    filter?: (key: string, record: unknown) => boolean;
+}
+/** Handle returned by `Graph.attachStorage` — dispose to stop observing. */
+interface StorageHandle {
+    dispose(): void;
+}
+/** Recursively sort object keys so `JSON.stringify` output is order-independent. */
+declare function sortJsonValue(value: unknown): unknown;
+/**
+ * Stable JSON encoding (no trailing newline). Tiers that want POSIX newline
+ * convention (e.g. `fileStorage`) append their own; in-database tiers
+ * (`sqliteStorage`) keep the payload byte-identical for cross-tier hash/CID
+ * comparison.
+ */
+declare function stableJsonString(data: unknown): string;
+/**
+ * In-memory storage tier (process-local; useful for tests and hot tier).
+ *
+ * @returns Sync {@link StorageTier} with JSON-cloned isolation.
+ *
+ * @example
+ * ```ts
+ * import { memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const hot = memoryStorage();
+ * graph.attachStorage([hot]);
+ * ```
+ *
+ * @category extra
+ */
+declare function memoryStorage(): StorageTier;
+/**
+ * Dict-backed storage tier — stores JSON-cloned values under caller keys in
+ * a caller-owned plain object. Useful for embedding in a parent state shape.
+ *
+ * @param storage - Caller-owned object used as the backing store.
+ * @returns Sync {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { dictStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const state: Record<string, unknown> = {};
+ * graph.attachStorage([dictStorage(state)]);
+ * ```
+ *
+ * @category extra
+ */
+declare function dictStorage(storage: Record<string, unknown>): StorageTier;
+
+export { type StorageHandle, type StorageTier, dictStorage, memoryStorage, sortJsonValue, stableJsonString };

package/dist/extra/storage-core.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Storage tier primitive — browser-safe core (types + in-memory backends).
+ *
+ * Split out of `extra/storage.ts` so browser bundles can import the
+ * {@link StorageTier} contract, {@link memoryStorage}, {@link dictStorage}
+ * and shared JSON helpers without pulling `node:fs` / `node:sqlite` /
+ * `node:crypto`. Node-only backends (`fileStorage`, `sqliteStorage`) live in
+ * {@link ./storage-node}; browser-only ones (`indexedDbStorage`,
+ * `fromIDBRequest`, `fromIDBTransaction`) live in {@link ./storage-browser}.
+ * The legacy `extra/storage.ts` module re-exports all three for back-compat.
+ *
+ * @module
+ */
+/**
+ * Single persistence primitive — supports sync and async backends alike via
+ * `void | Promise<void>` returns. `debounceMs` / `compactEvery` / `filter`
+ * are per-tier cadence controls honored by `Graph.attachStorage`;
+ * `cascadingCache` ignores them (it has its own eviction policy).
+ */
+interface StorageTier {
+    /** Read a value. Returns `null` (or resolves to `null`) on miss. */
+    load(key: string): unknown | Promise<unknown>;
+    /** Write a record. Sync tiers return `void`; async tiers return `Promise<void>`. */
+    save(key: string, data: unknown): void | Promise<void>;
+    /** Delete a value. Optional — tiers without `clear` are append/overwrite-only. */
+    clear?(key: string): void | Promise<void>;
+    /**
+     * Enumerate known keys. Optional — tiers that only address a single record
+     * (e.g. `indexedDbStorage`) or that can't cheaply enumerate (e.g. a remote
+     * write-only sink) may omit it. Callers that require enumeration (the
+     * surface `snapshot.list()` helper, MCP `graphrefly_snapshot_list`, CLI
+     * `graphrefly snapshot list`) should check before calling.
+     */
+    list?(): readonly string[] | Promise<readonly string[]>;
+    /**
+     * Debounce saves on this tier (ms). Hot tier: `0` (sync-through).
+     * Warm: `1000`. Cold: `60000`. Each tier holds its own last-save baseline,
+     * so cold flushes aren't penalized by hot flushes.
+     */
+    debounceMs?: number;
+    /**
+     * Every Nth record is a full snapshot; others are diffs against this
+     * tier's own baseline. Default `10`. Set `1` for always-full;
+     * `Number.POSITIVE_INFINITY` is unsafe — WAL replay needs periodic anchors.
+     */
+    compactEvery?: number;
+    /** Pre-save filter — return `false` to skip this record on this tier. */
+    filter?: (key: string, record: unknown) => boolean;
+}
+/** Handle returned by `Graph.attachStorage` — dispose to stop observing. */
+interface StorageHandle {
+    dispose(): void;
+}
+/** Recursively sort object keys so `JSON.stringify` output is order-independent. */
+declare function sortJsonValue(value: unknown): unknown;
+/**
+ * Stable JSON encoding (no trailing newline). Tiers that want POSIX newline
+ * convention (e.g. `fileStorage`) append their own; in-database tiers
+ * (`sqliteStorage`) keep the payload byte-identical for cross-tier hash/CID
+ * comparison.
+ */
+declare function stableJsonString(data: unknown): string;
+/**
+ * In-memory storage tier (process-local; useful for tests and hot tier).
+ *
+ * @returns Sync {@link StorageTier} with JSON-cloned isolation.
+ *
+ * @example
+ * ```ts
+ * import { memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const hot = memoryStorage();
+ * graph.attachStorage([hot]);
+ * ```
+ *
+ * @category extra
+ */
+declare function memoryStorage(): StorageTier;
+/**
+ * Dict-backed storage tier — stores JSON-cloned values under caller keys in
+ * a caller-owned plain object. Useful for embedding in a parent state shape.
+ *
+ * @param storage - Caller-owned object used as the backing store.
+ * @returns Sync {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { dictStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const state: Record<string, unknown> = {};
+ * graph.attachStorage([dictStorage(state)]);
+ * ```
+ *
+ * @category extra
+ */
+declare function dictStorage(storage: Record<string, unknown>): StorageTier;
+
+export { type StorageHandle, type StorageTier, dictStorage, memoryStorage, sortJsonValue, stableJsonString };

package/dist/extra/storage-core.js

@@ -0,0 +1 @@
+import{a,b,c,d}from"../chunk-I6VIH3VA.js";import"../chunk-QYADASLV.js";export{d as dictStorage,c as memoryStorage,a as sortJsonValue,b as stableJsonString};

package/dist/extra/storage-node.cjs

@@ -0,0 +1,2 @@
+"use strict";var g=Object.defineProperty;var E=Object.getOwnPropertyDescriptor;var w=Object.getOwnPropertyNames;var T=Object.prototype.hasOwnProperty;var N=(n,e)=>{for(var o in e)g(n,o,{get:e[o],enumerable:!0})},O=(n,e,o,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let a of w(e))!T.call(n,a)&&a!==o&&g(n,a,{get:()=>e[a],enumerable:!(r=E(e,a))||r.enumerable});return n};var b=n=>O(g({},"__esModule",{value:!0}),n);var J={};N(J,{fileStorage:()=>v,sqliteStorage:()=>x});module.exports=b(J);var k=require("node:crypto"),c=require("node:fs"),p=require("node:path"),h=require("node:sqlite");function y(n){if(n===null||typeof n!="object")return n;if(Array.isArray(n))return n.map(y);let e=n,o=Object.keys(e).sort(),r={};for(let a of o)r[a]=y(e[a]);return r}function S(n){return JSON.stringify(y(n),void 0,0)}function v(n){let e=new TextEncoder,o=new TextDecoder("utf-8",{fatal:!0}),r=s=>{let t="";for(let i of s){if(i.length===1&&/[a-zA-Z0-9_-]/.test(i)){t+=i;continue}for(let d of e.encode(i))t+=`%${d.toString(16).padStart(2,"0")}`}return(0,p.join)(n,`${t}.json`)},a=s=>{if(!s.endsWith(".json"))return null;let t=s.slice(0,-5),i=[],d=f=>{for(let u=0;u<f.length;u++)i.push(f.charCodeAt(u))},l=0;for(;l<t.length;){let f=t[l];if(f==="%"&&l+2<t.length){let u=t.slice(l+1,l+3);if(/^[0-9a-f]{2}$/i.test(u)){i.push(Number.parseInt(u,16)),l+=3;continue}}d(f),l+=1}try{return o.decode(new Uint8Array(i))}catch{return null}};return{save(s,t){(0,c.mkdirSync)(n,{recursive:!0});let i=r(s),d=`${S(t)}
+`,l=(0,p.basename)(i),f=(0,p.dirname)(i),u=(0,p.join)(f,`.${l}.${(0,k.randomBytes)(8).toString("hex")}.tmp`);try{(0,c.writeFileSync)(u,d,"utf8"),(0,c.renameSync)(u,i)}catch(m){try{(0,c.unlinkSync)(u)}catch{}throw m}},load(s){try{let t=(0,c.readFileSync)(r(s),"utf8").trim();return t?JSON.parse(t):null}catch{return null}},clear(s){try{(0,c.unlinkSync)(r(s))}catch(t){if(t.code!=="ENOENT")throw t}},list(){try{let s=(0,c.readdirSync)(n),t=[];for(let i of s){if(i.startsWith("."))continue;let d=a(i);d!==null&&t.push(d)}return t.sort()}catch(s){if(s.code==="ENOENT")return[];throw s}}}}function x(n){let e=new h.DatabaseSync(n);return e.exec("CREATE TABLE IF NOT EXISTS graphrefly_checkpoint (k TEXT PRIMARY KEY, v TEXT NOT NULL)"),{save(o,r){let a=S(r);e.prepare("INSERT OR REPLACE INTO graphrefly_checkpoint (k, v) VALUES (?, ?)").run(o,a)},load(o){let r=e.prepare("SELECT v FROM graphrefly_checkpoint WHERE k = ?").get(o);return r===void 0||typeof r.v!="string"||r.v.trim()===""?null:JSON.parse(r.v)},clear(o){e.prepare("DELETE FROM graphrefly_checkpoint WHERE k = ?").run(o)},list(){return e.prepare("SELECT k FROM graphrefly_checkpoint ORDER BY k").all().map(r=>r.k)},close(){try{e.close()}catch{}}}}0&&(module.exports={fileStorage,sqliteStorage});

package/dist/extra/storage-node.d.cts

@@ -0,0 +1,60 @@
+import { StorageTier } from './storage-core.cjs';
+
+/**
+ * Node-only storage backends — `fileStorage` (atomic per-key JSON files) and
+ * `sqliteStorage` (Node 22.5+ `node:sqlite`). Imports `node:fs`, `node:path`,
+ * `node:crypto`, `node:sqlite`.
+ *
+ * Browser-safe consumers should import {@link ./storage-core} instead; the
+ * legacy `extra/storage.ts` barrel re-exports this module for back-compat.
+ *
+ * @module
+ */
+
+/**
+ * Atomic JSON file storage tier (one file per key in a directory, temp + rename).
+ *
+ * Keys are sanitized to filesystem-safe names (`[^a-zA-Z0-9_-]` → `%<hex>`).
+ * `load` returns `null` for missing files, empty files, or invalid JSON.
+ *
+ * @param dir - Directory where per-key JSON files are written.
+ * @returns Sync {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { fileStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * graph.attachStorage([memoryStorage(), fileStorage("./checkpoints")]);
+ * ```
+ *
+ * @category extra
+ */
+declare function fileStorage(dir: string): StorageTier;
+/**
+ * SQLite storage tier using Node.js `node:sqlite` ({@link DatabaseSync}).
+ *
+ * Returns a {@link StorageTier} extended with `close()` — the caller owns the
+ * connection and should close it when discarding the tier.
+ *
+ * **Runtime:** Requires Node 22.5+ with `node:sqlite` enabled.
+ *
+ * @param path - SQLite database file path.
+ * @returns Sync {@link StorageTier} with an idempotent `close()` method.
+ *
+ * @example
+ * ```ts
+ * import { sqliteStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const cold = sqliteStorage("./graphs.sqlite");
+ * graph.attachStorage([memoryStorage(), cold]);
+ * // ... later, on shutdown:
+ * cold.close();
+ * ```
+ *
+ * @category extra
+ */
+declare function sqliteStorage(path: string): StorageTier & {
+    close(): void;
+};
+
+export { fileStorage, sqliteStorage };

package/dist/extra/storage-node.d.ts

@@ -0,0 +1,60 @@
+import { StorageTier } from './storage-core.js';
+
+/**
+ * Node-only storage backends — `fileStorage` (atomic per-key JSON files) and
+ * `sqliteStorage` (Node 22.5+ `node:sqlite`). Imports `node:fs`, `node:path`,
+ * `node:crypto`, `node:sqlite`.
+ *
+ * Browser-safe consumers should import {@link ./storage-core} instead; the
+ * legacy `extra/storage.ts` barrel re-exports this module for back-compat.
+ *
+ * @module
+ */
+
+/**
+ * Atomic JSON file storage tier (one file per key in a directory, temp + rename).
+ *
+ * Keys are sanitized to filesystem-safe names (`[^a-zA-Z0-9_-]` → `%<hex>`).
+ * `load` returns `null` for missing files, empty files, or invalid JSON.
+ *
+ * @param dir - Directory where per-key JSON files are written.
+ * @returns Sync {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { fileStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * graph.attachStorage([memoryStorage(), fileStorage("./checkpoints")]);
+ * ```
+ *
+ * @category extra
+ */
+declare function fileStorage(dir: string): StorageTier;
+/**
+ * SQLite storage tier using Node.js `node:sqlite` ({@link DatabaseSync}).
+ *
+ * Returns a {@link StorageTier} extended with `close()` — the caller owns the
+ * connection and should close it when discarding the tier.
+ *
+ * **Runtime:** Requires Node 22.5+ with `node:sqlite` enabled.
+ *
+ * @param path - SQLite database file path.
+ * @returns Sync {@link StorageTier} with an idempotent `close()` method.
+ *
+ * @example
+ * ```ts
+ * import { sqliteStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const cold = sqliteStorage("./graphs.sqlite");
+ * graph.attachStorage([memoryStorage(), cold]);
+ * // ... later, on shutdown:
+ * cold.close();
+ * ```
+ *
+ * @category extra
+ */
+declare function sqliteStorage(path: string): StorageTier & {
+    close(): void;
+};
+
+export { fileStorage, sqliteStorage };

package/dist/extra/storage-node.js

@@ -0,0 +1 @@
+import{a,b}from"../chunk-3JXNEPCD.js";import"../chunk-I6VIH3VA.js";import"../chunk-QYADASLV.js";export{a as fileStorage,b as sqliteStorage};