docs: function XPathOptimizer(newEngine) {
  // private
      var engine = newEngine;
      var namespaceResolver;
      var mirror = new MirroredDocument(namespaceResolver);
      var finderBuilder = new FinderBuilder();
  
      // keys are full document HTML strings, and values are mappings from
      // XPath's to objects which the following fields:
      //
      //   - finder       the equivalent finder function for the XPath, for
      //                  single node selection
      //   - nodeCount    the node count for the XPath with respect to the given
      //                  document content
      //   - node         the actual, potentially invalidated, node
      //   - sourceIndex  the value of the sourceIndex attribute of the node at
      //                  time of addition to the cache; this can be used to
      //                  determine if the node has since changed positions
      //
      var knownOptimizations = new XPathOptimizationCache(100);
  
      /**
       * Returns whether this optimizer is capable of optimizing XPath's for the
       * given node.
       */
      function isOptimizable(node) {
          return (node.nodeType == 1);
      }
  
      /**
       * Returns whether the given XPath evaluates to the given node in the
       * test document.
       */
      function isXPathValid(xpath, node) {
          var contextNode = mirror.getReflection();
          return (engine.setDocument(mirror.getReflection())
              .selectSingleNode(xpath, contextNode, namespaceResolver) === node);
      }
  
  // public
      this.setDocument = function(newDocument) {
          mirror.setOriginal(newDocument);
          return this;
      }
  
      /**
       * Sets the document object that will be used for test XPath evaluation and
       * traversal related to construction of the optimized expression. This
       * document will be modified freely by the optimize() operation.
       */
      this.setTestDocument = function(newTestDocument) {
          mirror.setReflection(newTestDocument);
          return this;
      };
  
      this.setNamespaceResolver = function(newNamespaceResolver) {
          namespaceResolver = newNamespaceResolver;
          mirror.setNamespaceResolver(newNamespaceResolver);
          return this;
      };
  
      /**
       * Returns an optimal XPath whose first result is the same as the first
       * result of the given XPath, when evaluated on the currently set document.
       * If optimization fails, returns the original XPath.
       */
      this.getOptimizedFinder = function(xpath, contextNode) {
          var originalHtml = mirror.getOriginal().documentElement.innerHTML;
          var optimization = knownOptimizations.get(originalHtml, xpath);
  
          if (optimization) {
              var finder =  optimization.finder;
  
              if (finder) {
                  // the optimized finder for this document content was found in
                  // the cache!
                  safe_log('info', 'Found cached optimized finder for ' + xpath);
                  return finder;
              }
          }
  
          mirror.reflect();
  
          if (contextNode) {
              contextNode = mirror.getReflectedNode(contextNode);
          }
  
          var firstResult = engine.setDocument(mirror.getReflection())
              .selectSingleNode(xpath, contextNode, namespaceResolver);
  
          if (! firstResult) {
              // either the element doesn't exist, or there was a failure to
              // reflect the document accurately
              return null;
          }
  
          if (isOptimizable(firstResult)) {
              var finder = finderBuilder.setDocument(mirror.getReflection())
                  .build(firstResult);
  
              if (finder) {
                  safe_log('info', 'Found optimized finder: ' + finder);
  
                  if (! optimization) {
                      optimization = knownOptimizations
                          .getOrCreate(originalHtml, xpath);
                  }
  
                  optimization.finder = finder;
  
                  return finder;
              }
          }
  
          return null;
      };
  
      this.countNodes = function(xpath, contextNode) {
          var originalHtml = mirror.getOriginal().documentElement.innerHTML;
          var optimization = knownOptimizations.get(originalHtml, xpath);
  
          if (optimization) {
              var nodeCount = optimization.nodeCount;
  
              if (nodeCount != null) {
                  // the node count for the XPath for this document content was
                  // found in the cache!
                  safe_log('info', 'Found cached node count for ' + xpath);
                  return nodeCount;
              }
          }
  
          mirror.reflect();
  
          if (contextNode) {
              contextNode = mirror.getReflectedNode(contextNode);
          }
  
          // count the nodes using the test document, and circumvent
          // window RPC altogether
          var nodeCount = engine.setDocument(mirror.getReflection())
              .countNodes(xpath, contextNode, namespaceResolver);
  
          if (! optimization) {
              optimization = knownOptimizations.getOrCreate(originalHtml, xpath);
          }
  
          optimization.nodeCount = nodeCount;
  
          return nodeCount;
      };
  
      this.getKnownOptimizations = function() {
          return knownOptimizations;
      };
  }