diff --git a/packages/xsnap/README.md b/packages/xsnap/README.md
index 08a658bdb88..81810337d43 100644
--- a/packages/xsnap/README.md
+++ b/packages/xsnap/README.md
@@ -43,6 +43,8 @@ The parent and child communicate using "commands".
 - The Node.js parent can implement an asynchronous `handleCommand` function to
   respond to commands from the XS child.
 
+![state diagram](doc/xsnap-states.svg)
+
 # xsrepl
 
 With `xsnap` comes an `xsrepl` command line tool.
diff --git a/packages/xsnap/doc/xsnap-states.dot b/packages/xsnap/doc/xsnap-states.dot
new file mode 100644
index 00000000000..0353bfda7c2
--- /dev/null
+++ b/packages/xsnap/doc/xsnap-states.dot
@@ -0,0 +1,8 @@
+digraph G {
+ idle -> idle [label="snapshot"]
+ idle -> running [label="rx:eval"]
+ idle -> running [label="rx:handleCommand"]
+ running -> sysCalling [label="tx:issueCommand"]
+ sysCalling -> running [label="rx:response"]
+ running -> idle [label="tx:response"]
+}
diff --git a/packages/xsnap/doc/xsnap-states.svg b/packages/xsnap/doc/xsnap-states.svg
new file mode 100644
index 00000000000..71a9dc6ee39
--- /dev/null
+++ b/packages/xsnap/doc/xsnap-states.svg
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><!-- Generated by graphviz version 2.40.1 (20161225.0304)
+ --><!-- Title: G Pages: 1 --><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="252pt" height="222pt" viewBox="0.00 0.00 251.61 221.60">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 217.6)">
+<title>G</title>
+<polygon fill="#ffffff" stroke="transparent" points="-4,4 -4,-217.6 247.6072,-217.6 247.6072,4 -4,4"/>
+<!-- idle -->
+<g id="node1" class="node">
+<title>idle</title>
+<ellipse fill="none" stroke="#000000" cx="63.847" cy="-195.6" rx="27" ry="18"/>
+<text text-anchor="middle" x="63.847" y="-191.4" font-family="Times,serif" font-size="14.00" fill="#000000">idle</text>
+</g>
+<!-- idle&#45;&gt;idle -->
+<g id="edge1" class="edge">
+<title>idle-&gt;idle</title>
+<path fill="none" stroke="#000000" d="M88.3794,-203.7211C99.3548,-204.4945 108.847,-201.7875 108.847,-195.6 108.847,-191.4428 104.562,-188.8567 98.4213,-187.8417"/>
+<polygon fill="#000000" stroke="#000000" points="98.4993,-184.3424 88.3794,-187.4789 98.2465,-191.3378 98.4993,-184.3424"/>
+<text text-anchor="middle" x="133.3442" y="-191.4" font-family="Times,serif" font-size="14.00" fill="#000000">snapshot</text>
+</g>
+<!-- running -->
+<g id="node2" class="node">
+<title>running</title>
+<ellipse fill="none" stroke="#000000" cx="63.847" cy="-106.8" rx="41.1548" ry="18"/>
+<text text-anchor="middle" x="63.847" y="-102.6" font-family="Times,serif" font-size="14.00" fill="#000000">running</text>
+</g>
+<!-- idle&#45;&gt;running -->
+<g id="edge2" class="edge">
+<title>idle-&gt;running</title>
+<path fill="none" stroke="#000000" d="M39.2512,-187.8383C25.98,-182.251 10.7623,-173.251 2.976,-159.6 -5.3284,-145.0406 7.4736,-132.544 23.4447,-123.3684"/>
+<polygon fill="#000000" stroke="#000000" points="25.288,-126.3542 32.5296,-118.6205 22.0458,-120.1503 25.288,-126.3542"/>
+<text text-anchor="middle" x="23.2825" y="-147" font-family="Times,serif" font-size="14.00" fill="#000000">rx:eval</text>
+</g>
+<!-- idle&#45;&gt;running -->
+<g id="edge3" class="edge">
+<title>idle-&gt;running</title>
+<path fill="none" stroke="#000000" d="M63.847,-177.2006C63.847,-165.0949 63.847,-149.0076 63.847,-135.2674"/>
+<polygon fill="#000000" stroke="#000000" points="67.3471,-134.872 63.847,-124.872 60.3471,-134.8721 67.3471,-134.872"/>
+<text text-anchor="middle" x="119.4487" y="-147" font-family="Times,serif" font-size="14.00" fill="#000000">rx:handleCommand</text>
+</g>
+<!-- running&#45;&gt;idle -->
+<g id="edge6" class="edge">
+<title>running-&gt;idle</title>
+<path fill="none" stroke="#000000" d="M103.799,-111.1516C143.8549,-117.2058 196.8042,-130.8505 175.847,-159.6 166.726,-172.1124 129.1205,-182.4317 99.9716,-188.7665"/>
+<polygon fill="#000000" stroke="#000000" points="99.1453,-185.3635 90.0745,-190.8381 100.5795,-192.215 99.1453,-185.3635"/>
+<text text-anchor="middle" x="211.7271" y="-147" font-family="Times,serif" font-size="14.00" fill="#000000">tx:response</text>
+</g>
+<!-- sysCalling -->
+<g id="node3" class="node">
+<title>sysCalling</title>
+<ellipse fill="none" stroke="#000000" cx="63.847" cy="-18" rx="51.6227" ry="18"/>
+<text text-anchor="middle" x="63.847" y="-13.8" font-family="Times,serif" font-size="14.00" fill="#000000">sysCalling</text>
+</g>
+<!-- running&#45;&gt;sysCalling -->
+<g id="edge4" class="edge">
+<title>running-&gt;sysCalling</title>
+<path fill="none" stroke="#000000" d="M31.5205,-95.5555C20.3696,-89.9441 9.0931,-81.9181 2.739,-70.8 -5.0539,-57.1644 5.6727,-45.3526 20.2039,-36.3791"/>
+<polygon fill="#000000" stroke="#000000" points="22.0545,-39.3547 29.0881,-31.4314 18.6486,-33.2391 22.0545,-39.3547"/>
+<text text-anchor="middle" x="53.401" y="-58.2" font-family="Times,serif" font-size="14.00" fill="#000000">tx:issueCommand</text>
+</g>
+<!-- sysCalling&#45;&gt;running -->
+<g id="edge5" class="edge">
+<title>sysCalling-&gt;running</title>
+<path fill="none" stroke="#000000" d="M88.0688,-34.0849C99.6785,-43.9469 109.8825,-57.2481 103.847,-70.8 101.5664,-75.9208 98.1575,-80.6187 94.2746,-84.8108"/>
+<polygon fill="#000000" stroke="#000000" points="91.7612,-82.3708 86.9146,-91.7921 96.5786,-87.4495 91.7612,-82.3708"/>
+<text text-anchor="middle" x="137.1121" y="-58.2" font-family="Times,serif" font-size="14.00" fill="#000000">rx:response</text>
+</g>
+</g>
+</svg>
\ No newline at end of file