closure 1.4.3 → 1.5.0

data/closure-templates/soyutils.js

@@ -30,27 +30,41 @@
  * by Soy-generated JS code. Please do not use these functions directly from
  * your hand-writen code. Their names all start with '$$'.
  *
+ * @author Garrett Boyer
  * @author Mike Samuel
  * @author Kai Huang
- * @author Aharon Lenin
+ * @author Aharon Lanin
  */
 
 
 // COPIED FROM nogoog_shim.js
 
 // Create closure namespaces.
-var goog;
-if (typeof goog == "undefined") {
-  goog = {};
-}
+var goog = goog || {};
+
+
+goog.DEBUG = false;
+
 
 goog.inherits = function(childCtor, parentCtor) {
   /** @constructor */
-  function tempCtor() {}
+  function tempCtor() {};
   tempCtor.prototype = parentCtor.prototype;
   childCtor.superClass_ = parentCtor.prototype;
   childCtor.prototype = new tempCtor();
   childCtor.prototype.constructor = childCtor;
+
+  /**
+   * Calls superclass constructor/method.
+   * @param {!Object} me Should always be "this".
+   * @param {string} methodName
+   * @param {...*} var_args
+   * @return {?} The return value of the superclass method/constructor.
+   */
+  childCtor.base = function(me, methodName, var_args) {
+    var args = Array.prototype.slice.call(arguments, 2);
+    return parentCtor.prototype[methodName].apply(me, args);
+  };
 };
 
 
@@ -64,45 +78,76 @@ if (!goog.userAgent) {
     }
     var isOpera = userAgent.indexOf('Opera') == 0;
     return {
+      jscript: {
+        /**
+         * @type {boolean}
+         */
+        HAS_JSCRIPT: 'ScriptEngine' in this
+      },
       /**
        * @type {boolean}
        */
-      HAS_JSCRIPT: typeof 'ScriptEngine' in this,
-      /**
-       * @type {boolean}
-       */
-      IS_OPERA: isOpera,
+      OPERA: isOpera,
       /**
        * @type {boolean}
        */
-      IS_IE: !isOpera && userAgent.indexOf('MSIE') != -1,
+      IE: !isOpera && userAgent.indexOf('MSIE') != -1,
       /**
        * @type {boolean}
        */
-      IS_WEBKIT: !isOpera && userAgent.indexOf('WebKit') != -1
+      WEBKIT: !isOpera && userAgent.indexOf('WebKit') != -1
     };
   })();
 }
 
 if (!goog.asserts) {
   goog.asserts = {
-    fail: function () {}
+    /**
+     * @param {*} condition Condition to check.
+     */
+    assert: function (condition) {
+      if (!condition) {
+        throw Error('Assertion error');
+      }
+    },
+    /**
+     * @param {...*} var_args
+     */
+    fail: function (var_args) {}
   };
 }
 
 
 // Stub out the document wrapper used by renderAs*.
 if (!goog.dom) {
-  goog.dom = {
-    DomHelper: function (d) {
-      d = d || document;
-      return {
-        createElement: function (name) { return d.createElement(name); },
-        createDocumentFragment: function () {
-          return d.createDocumentFragment();
-        }
-      };
-    }
+  goog.dom = {};
+  /**
+   * @param {Document=} d
+   * @constructor
+   */
+  goog.dom.DomHelper = function(d) {
+    this.document_ = d || document;
+  };
+  /**
+   * @return {!Document}
+   */
+  goog.dom.DomHelper.prototype.getDocument = function() {
+    return this.document_;
+  };
+  /**
+   * Creates a new element.
+   * @param {string} name Tag name.
+   * @return {!Element}
+   */
+  goog.dom.DomHelper.prototype.createElement = function(name) {
+    return this.document_.createElement(name);
+  };
+  /**
+   * Creates a new document fragment.
+   * @return {!DocumentFragment}
+   */
+  goog.dom.DomHelper.prototype.createDocumentFragment = function() {
+    return this.document_.createDocumentFragment();
   };
 }
 
@@ -195,66 +240,177 @@ if (!goog.format) {
     },
     /**
      * String inserted as a word break by insertWordBreaks(). Safari requires
-     * <wbr></wbr>, Opera needs the 'shy' entity, though this will give a
-     * visible hyphen at breaks. Other browsers just use <wbr>.
+     * <wbr></wbr>, Opera needs the &shy; entity, though this will give a
+     * visible hyphen at breaks. IE8+ use a zero width space. Other browsers
+     * just use <wbr>.
      * @type {string}
      * @private
      */
-    WORD_BREAK: goog.userAgent.IS_WEBKIT
-        ? '<wbr></wbr>' : goog.userAgent.IS_OPERA ? '&shy;' : '<wbr>'
+    WORD_BREAK:
+        goog.userAgent.WEBKIT ? '<wbr></wbr>' :
+        goog.userAgent.OPERA ? '&shy;' :
+        goog.userAgent.IE ? '&#8203;' :
+        '<wbr>'
   };
 }
 
 
 if (!goog.i18n) {
   goog.i18n = {
-    /**
-     * Utility class for formatting text for display in a potentially
-     * opposite-directionality context without garbling. Provides the following
-     * functionality:
-     *
-     * @param {goog.i18n.bidi.Dir|number|boolean} contextDir The context
-     *     directionality as a number
-     *     (positive = LRT, negative = RTL, 0 = unknown).
-     * @constructor
-     */
-    BidiFormatter: function (dir) {
-      this.dir_ = dir;
-    },
-    bidi: {
-      /**
-       * Check the directionality of a piece of text, return true if the piece
-       * of text should be laid out in RTL direction.
-       * @param {string} text The piece of text that need to be detected.
-       * @param {boolean=} opt_isHtml Whether {@code text} is HTML/HTML-escaped.
-       *     Default: false.
-       * @return {boolean}
-       * @private
-       */
-      detectRtlDirectionality: function(text, opt_isHtml) {
-        text = soyshim.$$bidiStripHtmlIfNecessary_(text, opt_isHtml);
-        return soyshim.$$bidiRtlWordRatio_(text)
-            > soyshim.$$bidiRtlDetectionThreshold_;
-      }
-    }
+    bidi: {}
   };
 }
 
 
 /**
- * Returns "dir=ltr" or "dir=rtl", depending on {@code text}'s estimated
- * directionality, if it is not the same as the context directionality.
- * Otherwise, returns the empty string.
+ * Constant that defines whether or not the current locale is an RTL locale.
  *
- * @param {string} text Text whose directionality is to be estimated.
- * @param {boolean=} opt_isHtml Whether {@code text} is HTML / HTML-escaped.
+ * @type {boolean}
+ */
+goog.i18n.bidi.IS_RTL = false;
+
+
+/**
+ * Directionality enum.
+ * @enum {number}
+ */
+goog.i18n.bidi.Dir = {
+  /**
+   * Left-to-right.
+   */
+  LTR: 1,
+
+  /**
+   * Right-to-left.
+   */
+  RTL: -1,
+
+  /**
+   * Neither left-to-right nor right-to-left.
+   */
+  NEUTRAL: 0,
+
+  /**
+   * A historical misnomer for NEUTRAL.
+   * @deprecated For "neutral", use NEUTRAL; for "unknown", use null.
+   */
+  UNKNOWN: 0
+};
+
+
+/**
+ * Convert a directionality given in various formats to a goog.i18n.bidi.Dir
+ * constant. Useful for interaction with different standards of directionality
+ * representation.
+ *
+ * @param {goog.i18n.bidi.Dir|number|boolean|null} givenDir Directionality given
+ *     in one of the following formats:
+ *     1. A goog.i18n.bidi.Dir constant.
+ *     2. A number (positive = LTR, negative = RTL, 0 = neutral).
+ *     3. A boolean (true = RTL, false = LTR).
+ *     4. A null for unknown directionality.
+ * @param {boolean=} opt_noNeutral Whether a givenDir of zero or
+ *     goog.i18n.bidi.Dir.NEUTRAL should be treated as null, i.e. unknown, in
+ *     order to preserve legacy behavior.
+ * @return {?goog.i18n.bidi.Dir} A goog.i18n.bidi.Dir constant matching the
+ *     given directionality. If given null, returns null (i.e. unknown).
+ */
+goog.i18n.bidi.toDir = function(givenDir, opt_noNeutral) {
+  if (typeof givenDir == 'number') {
+    // This includes the non-null goog.i18n.bidi.Dir case.
+    return givenDir > 0 ? goog.i18n.bidi.Dir.LTR :
+        givenDir < 0 ? goog.i18n.bidi.Dir.RTL :
+        opt_noNeutral ? null : goog.i18n.bidi.Dir.NEUTRAL;
+  } else if (givenDir == null) {
+    return null;
+  } else {
+    // Must be typeof givenDir == 'boolean'.
+    return givenDir ? goog.i18n.bidi.Dir.RTL : goog.i18n.bidi.Dir.LTR;
+  }
+};
+
+
+/**
+ * Estimates the directionality of a string based on relative word counts.
+ * If the number of RTL words is above a certain percentage of the total number
+ * of strongly directional words, returns RTL.
+ * Otherwise, if any words are strongly or weakly LTR, returns LTR.
+ * Otherwise, returns NEUTRAL.
+ * Numbers are counted as weakly LTR.
+ * @param {string} str The string to be checked.
+ * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
  *     Default: false.
- * @return {string} "dir=rtl" for RTL text in non-RTL context; "dir=ltr" for LTR
- *     text in non-LTR context; else, the empty string.
+ * @return {goog.i18n.bidi.Dir} Estimated overall directionality of {@code str}.
  */
-goog.i18n.BidiFormatter.prototype.dirAttr = function (text, opt_isHtml) {
-  var dir = soy.$$bidiTextDir(text, opt_isHtml);
-  return dir && dir != this.dir_ ? dir < 0 ? 'dir=rtl' : 'dir=ltr' : '';
+goog.i18n.bidi.estimateDirection = function(str, opt_isHtml) {
+  var rtlCount = 0;
+  var totalCount = 0;
+  var hasWeaklyLtr = false;
+  var tokens = soyshim.$$bidiStripHtmlIfNecessary_(str, opt_isHtml).
+      split(soyshim.$$bidiWordSeparatorRe_);
+  for (var i = 0; i < tokens.length; i++) {
+    var token = tokens[i];
+    if (soyshim.$$bidiRtlDirCheckRe_.test(token)) {
+      rtlCount++;
+      totalCount++;
+    } else if (soyshim.$$bidiIsRequiredLtrRe_.test(token)) {
+      hasWeaklyLtr = true;
+    } else if (soyshim.$$bidiLtrCharRe_.test(token)) {
+      totalCount++;
+    } else if (soyshim.$$bidiHasNumeralsRe_.test(token)) {
+      hasWeaklyLtr = true;
+    }
+  }
+
+  return totalCount == 0 ?
+      (hasWeaklyLtr ? goog.i18n.bidi.Dir.LTR : goog.i18n.bidi.Dir.NEUTRAL) :
+      (rtlCount / totalCount > soyshim.$$bidiRtlDetectionThreshold_ ?
+          goog.i18n.bidi.Dir.RTL : goog.i18n.bidi.Dir.LTR);
+};
+
+
+/**
+ * Utility class for formatting text for display in a potentially
+ * opposite-directionality context without garbling. Provides the following
+ * functionality:
+ *
+ * @param {goog.i18n.bidi.Dir|number|boolean|null} dir The context
+ *     directionality, in one of the following formats:
+ *     1. A goog.i18n.bidi.Dir constant. NEUTRAL is treated the same as null,
+ *        i.e. unknown, for backward compatibility with legacy calls.
+ *     2. A number (positive = LTR, negative = RTL, 0 = unknown).
+ *     3. A boolean (true = RTL, false = LTR).
+ *     4. A null for unknown directionality.
+ * @constructor
+ */
+goog.i18n.BidiFormatter = function(dir) {
+  /**
+   * The overall directionality of the context in which the formatter is being
+   * used.
+   * @type {?goog.i18n.bidi.Dir}
+   * @private
+   */
+  this.dir_ = goog.i18n.bidi.toDir(dir, true /* opt_noNeutral */);
+};
+
+/**
+ * @return {?goog.i18n.bidi.Dir} The context directionality.
+ */
+goog.i18n.BidiFormatter.prototype.getContextDir = function() {
+  return this.dir_;
+};
+
+/**
+ * Returns 'dir="ltr"' or 'dir="rtl"', depending on the given directionality, if
+ * it is not the same as the context directionality. Otherwise, returns the
+ * empty string.
+ *
+ * @param {goog.i18n.bidi.Dir} dir A directionality.
+ * @return {string} 'dir="rtl"' for RTL text in non-RTL context; 'dir="ltr"' for
+ *     LTR text in non-LTR context; else, the empty string.
+ */
+goog.i18n.BidiFormatter.prototype.knownDirAttr = function(dir) {
+  return !dir || dir == this.dir_ ? '' : dir < 0 ? 'dir="rtl"' : 'dir="ltr"';
 };
 
 /**
@@ -269,7 +425,7 @@ goog.i18n.BidiFormatter.prototype.endEdge = function () {
 /**
  * Returns the Unicode BiDi mark matching the context directionality (LRM for
  * LTR context directionality, RLM for RTL context directionality), or the
- * empty string for neutral / unknown context directionality.
+ * empty string for unknown context directionality.
  *
  * @return {string} LRM for LTR context directionality and RLM for RTL context
  *     directionality.
@@ -282,37 +438,55 @@ goog.i18n.BidiFormatter.prototype.mark = function () {
 };
 
 /**
- * Returns a Unicode BiDi mark matching the context directionality (LRM or RLM)
+ * Returns a Unicode bidi mark matching the context directionality (LRM or RLM)
  * if the directionality or the exit directionality of {@code text} are opposite
  * to the context directionality. Otherwise returns the empty string.
- *
- * @param {string} text The input text.
- * @param {boolean=} opt_isHtml Whether {@code text} is HTML / HTML-escaped.
+ * If opt_isHtml, makes sure to ignore the LTR nature of the mark-up and escapes
+ * in text, making the logic suitable for HTML and HTML-escaped text.
+ * @param {?goog.i18n.bidi.Dir} textDir {@code text}'s overall directionality,
+ *     or null if unknown and needs to be estimated.
+ * @param {string} text The text whose directionality is to be estimated.
+ * @param {boolean=} opt_isHtml Whether text is HTML/HTML-escaped.
  *     Default: false.
- * @return {string} A Unicode bidi mark matching the global directionality or
- *     the empty string.
- */
-goog.i18n.BidiFormatter.prototype.markAfter = function (text, opt_isHtml) {
-  var dir = soy.$$bidiTextDir(text, opt_isHtml);
-  return soyshim.$$bidiMarkAfterKnownDir_(this.dir_, dir, text, opt_isHtml);
+ * @return {string} A Unicode bidi mark matching the context directionality, or
+ *     the empty string when either the context directionality is unknown or
+ *     neither the text's overall nor its exit directionality is opposite to it.
+ */
+goog.i18n.BidiFormatter.prototype.markAfterKnownDir = function (
+    textDir, text, opt_isHtml) {
+  if (textDir == null) {
+    textDir = goog.i18n.bidi.estimateDirection(text, opt_isHtml);
+  }
+  return (
+      this.dir_ > 0 && (textDir < 0 ||
+          soyshim.$$bidiIsRtlExitText_(text, opt_isHtml)) ? '\u200E' : // LRM
+      this.dir_ < 0 && (textDir > 0 ||
+          soyshim.$$bidiIsLtrExitText_(text, opt_isHtml)) ? '\u200F' : // RLM
+      '');
 };
 
 /**
- * Formats a string of unknown directionality for use in HTML output of the
- * context directionality, so an opposite-directionality string is neither
- * garbled nor garbles what follows it.
+ * Formats an HTML string for use in HTML output of the context directionality,
+ * so an opposite-directionality string is neither garbled nor garbles what
+ * follows it.
  *
- * @param {string} str The input text.
- * @return {string} Input text after applying the above processing.
- */
-goog.i18n.BidiFormatter.prototype.spanWrap = function(str) {
-  str = String(str);
-  var textDir = soy.$$bidiTextDir(str, true);
-  var reset = soyshim.$$bidiMarkAfterKnownDir_(this.dir_, textDir, str, true);
+ * @param {?goog.i18n.bidi.Dir} textDir {@code str}'s overall directionality, or
+ *     null if unknown and needs to be estimated.
+ * @param {string} str The input text (HTML or HTML-escaped).
+ * @param {boolean=} placeholder This argument exists for consistency with the
+ *     Closure Library. Specifying it has no effect.
+ * @return {string} The input text after applying the above processing.
+ */
+goog.i18n.BidiFormatter.prototype.spanWrapWithKnownDir = function(
+    textDir, str, placeholder) {
+  if (textDir == null) {
+    textDir = goog.i18n.bidi.estimateDirection(str, true);
+  }
+  var reset = this.markAfterKnownDir(textDir, str, true);
   if (textDir > 0 && this.dir_ <= 0) {
-    str = '<span dir=ltr>' + str + '</span>';
+    str = '<span dir="ltr">' + str + '</span>';
   } else if (textDir < 0 && this.dir_ >= 0) {
-    str = '<span dir=rtl>' + str + '</span>';
+    str = '<span dir="rtl">' + str + '</span>';
   }
   return str + reset;
 };
@@ -327,20 +501,26 @@ goog.i18n.BidiFormatter.prototype.startEdge = function () {
 };
 
 /**
- * Formats a string of unknown directionality for use in plain-text output of
- * the context directionality, so an opposite-directionality string is neither
- * garbled nor garbles what follows it.
- * As opposed to {@link #spanWrap}, this makes use of unicode BiDi formatting
- * characters. In HTML, its *only* valid use is inside of elements that do not
- * allow mark-up, e.g. an 'option' tag.
+ * Formats an HTML-escaped string for use in HTML output of the context
+ * directionality, so an opposite-directionality string is neither garbled nor
+ * garbles what follows it.
+ * As opposed to {@link #spanWrapWithKnownDir}, this makes use of unicode bidi
+ * formatting characters. In HTML, it should only be used inside attribute
+ * values and elements that do not allow markup, e.g. an 'option' tag.
  *
- * @param {string} str The input text.
- * @return {string} Input text after applying the above processing.
+ * @param {?goog.i18n.bidi.Dir} textDir {@code str}'s overall directionality, or
+ *     null if unknown and needs to be estimated.
+ * @param {string} str The input text (HTML-escaped).
+ * @param {boolean=} opt_isHtml Whether {@code str} is HTML / HTML-escaped.
+ *     Default: false.
+ * @return {string} The input text after applying the above processing.
  */
-goog.i18n.BidiFormatter.prototype.unicodeWrap = function(str) {
-  str = String(str);
-  var textDir = soy.$$bidiTextDir(str, true);
-  var reset = soyshim.$$bidiMarkAfterKnownDir_(this.dir_, textDir, str, true);
+goog.i18n.BidiFormatter.prototype.unicodeWrapWithKnownDir = function(
+    textDir, str, opt_isHtml) {
+  if (textDir == null) {
+    textDir = goog.i18n.bidi.estimateDirection(str, opt_isHtml);
+  }
+  var reset = this.markAfterKnownDir(textDir, str, opt_isHtml);
   if (textDir > 0 && this.dir_ <= 0) {
     str = '\u202A' + str + '\u202C';
   } else if (textDir < 0 && this.dir_ >= 0) {
@@ -350,55 +530,58 @@ goog.i18n.BidiFormatter.prototype.unicodeWrap = function(str) {
 };
 
 
-goog.string = {
-  /**
-   * Utility class to facilitate much faster string concatenation in IE,
-   * using Array.join() rather than the '+' operator.  For other browsers
-   * we simply use the '+' operator.
-   *
-   * @param {Object|number|string|boolean=} opt_a1 Optional first initial item
-   *     to append.
-   * @param {...Object|number|string|boolean} var_args Other initial items to
-   *     append, e.g., new goog.string.StringBuffer('foo', 'bar').
-   * @constructor
-   */
-  StringBuffer: function(opt_a1, var_args) {
-
+if (!goog.string) {
+  goog.string = {
     /**
-     * Internal buffer for the string to be concatenated.
-     * @type {string|Array}
-     * @private
+     * Converts \r\n, \r, and \n to <br>s
+     * @param {*} str The string in which to convert newlines.
+     * @param {boolean=} opt_xml Whether to use XML compatible tags.
+     * @return {string} A copy of {@code str} with converted newlines.
      */
-    this.buffer_ = goog.userAgent.HAS_JSCRIPT ? [] : '';
+    newLineToBr: function(str, opt_xml) {
 
-    if (opt_a1 != null) {
-      this.append.apply(this, arguments);
-    }
-  },
-  /**
-   * Converts \r\n, \r, and \n to <br>s
-   * @param {*} str The string in which to convert newlines.
-   * @return {string} A copy of {@code str} with converted newlines.
-   */
-  newlineToBr: function(str) {
+      str = String(str);
 
-    str = String(str);
+      // This quick test helps in the case when there are no chars to replace,
+      // in the worst case this makes barely a difference to the time taken.
+      if (!goog.string.NEWLINE_TO_BR_RE_.test(str)) {
+        return str;
+      }
 
-    // This quick test helps in the case when there are no chars to replace,
-    // in the worst case this makes barely a difference to the time taken.
-    if (!goog.string.NEWLINE_TO_BR_RE_.test(str)) {
-      return str;
-    }
+      return str.replace(/(\r\n|\r|\n)/g, opt_xml ? '<br />' : '<br>');
+    },
+    urlEncode: encodeURIComponent,
+    /**
+     * Regular expression used within newlineToBr().
+     * @type {RegExp}
+     * @private
+     */
+    NEWLINE_TO_BR_RE_: /[\r\n]/
+  };
+}
 
-    return str.replace(/(\r\n|\r|\n)/g, '<br>');
-  },
-  urlEncode: encodeURIComponent,
+/**
+ * Utility class to facilitate much faster string concatenation in IE,
+ * using Array.join() rather than the '+' operator. For other browsers
+ * we simply use the '+' operator.
+ *
+ * @param {Object|number|string|boolean=} opt_a1 Optional first initial item
+ *     to append.
+ * @param {...Object|number|string|boolean} var_args Other initial items to
+ *     append, e.g., new goog.string.StringBuffer('foo', 'bar').
+ * @constructor
+ */
+goog.string.StringBuffer = function(opt_a1, var_args) {
   /**
-   * Regular expression used within newlineToBr().
-   * @type {RegExp}
+   * Internal buffer for the string to be concatenated.
+   * @type {string|Array}
    * @private
    */
-  NEWLINE_TO_BR_RE: /[\r\n]/
+  this.buffer_ = goog.userAgent.jscript.HAS_JSCRIPT ? [] : '';
+
+  if (opt_a1 != null) {
+    this.append.apply(this, arguments);
+  }
 };
 
 
@@ -423,13 +606,13 @@ goog.string.StringBuffer.prototype.bufferLength_ = 0;
  */
 goog.string.StringBuffer.prototype.append = function(a1, opt_a2, var_args) {
 
-  if (goog.userAgent.HAS_JSCRIPT) {
+  if (goog.userAgent.jscript.HAS_JSCRIPT) {
     if (opt_a2 == null) {  // no second argument (note: undefined == null)
-      // Array assignment is 2x faster than Array push.  Also, use a1
+      // Array assignment is 2x faster than Array push. Also, use a1
       // directly to avoid arguments instantiation, another 2x improvement.
       this.buffer_[this.bufferLength_++] = a1;
     } else {
-      var arr = /**@type {Array.<number|string|boolean>}*/this.buffer_;
+      var arr = /**@type {Array.<number|string|boolean>}*/(this.buffer_);
       arr.push.apply(arr, arguments);
       this.bufferLength_ = this.buffer_.length;
     }
@@ -454,7 +637,7 @@ goog.string.StringBuffer.prototype.append = function(a1, opt_a2, var_args) {
  */
 goog.string.StringBuffer.prototype.clear = function() {
 
-  if (goog.userAgent.HAS_JSCRIPT) {
+  if (goog.userAgent.jscript.HAS_JSCRIPT) {
      this.buffer_.length = 0;  // reuse array to avoid creating new object
      this.bufferLength_ = 0;
 
@@ -471,7 +654,7 @@ goog.string.StringBuffer.prototype.clear = function() {
  */
 goog.string.StringBuffer.prototype.toString = function() {
 
-  if (goog.userAgent.HAS_JSCRIPT) {
+  if (goog.userAgent.jscript.HAS_JSCRIPT) {
     var str = this.buffer_.join('');
     // Given a string with the entire contents, simplify the StringBuilder by
     // setting its contents to only be this string, rather than many fragments.
@@ -495,15 +678,16 @@ if (!goog.soy) goog.soy = {
    * innerHTML in your hand-written code, so that it will be easier
    * to audit the code for cross-site scripting vulnerabilities.
    *
-   * @param {Element} element The element whose content we are rendering.
    * @param {Function} template The Soy template defining element's content.
    * @param {Object=} opt_templateData The data for the template.
    * @param {Object=} opt_injectedData The injected data for the template.
+   * @param {(goog.dom.DomHelper|Document)=} opt_dom The context in which DOM
+   *     nodes will be created.
    */
   renderAsElement: function(
-    template, opt_templateData, opt_injectedData, opt_document) {
+    template, opt_templateData, opt_injectedData, opt_dom) {
     return /** @type {!Element} */ (soyshim.$$renderWithWrapper_(
-        template, opt_templateData, opt_document, true /* asElement */,
+        template, opt_templateData, opt_dom, true /* asElement */,
         opt_injectedData));
   },
   /**
@@ -515,15 +699,15 @@ if (!goog.soy) goog.soy = {
    *
    * @param {Function} template The Soy template defining element's content.
    * @param {Object=} opt_templateData The data for the template.
-   * @param {Document=} opt_document The document used to create DOM nodes.
-   *     If not specified, global document object is used.
    * @param {Object=} opt_injectedData The injected data for the template.
+   * @param {(goog.dom.DomHelper|Document)=} opt_dom The context in which DOM
+   *     nodes will be created.
    * @return {!Node} The resulting node or document fragment.
    */
   renderAsFragment: function(
-    template, opt_templateData, opt_injectedData, opt_document) {
+    template, opt_templateData, opt_injectedData, opt_dom) {
     return soyshim.$$renderWithWrapper_(
-        template, opt_templateData, opt_document, false /* asElement */,
+        template, opt_templateData, opt_dom, false /* asElement */,
         opt_injectedData);
   },
   /**
@@ -542,13 +726,129 @@ if (!goog.soy) goog.soy = {
   renderElement: function(
       element, template, opt_templateData, opt_injectedData) {
     element.innerHTML = template(opt_templateData, null, opt_injectedData);
-  }
+  },
+  data: {}
+};
+
+
+/**
+ * A type of textual content.
+ *
+ * This is an enum of type Object so that these values are unforgeable.
+ *
+ * @enum {!Object}
+ */
+goog.soy.data.SanitizedContentKind = {
+
+  /**
+   * A snippet of HTML that does not start or end inside a tag, comment, entity,
+   * or DOCTYPE; and that does not contain any executable code
+   * (JS, {@code <object>}s, etc.) from a different trust domain.
+   */
+  HTML: goog.DEBUG ? {sanitizedContentKindHtml: true} : {},
+
+  /**
+   * Executable Javascript code or expression, safe for insertion in a
+   * script-tag or event handler context, known to be free of any
+   * attacker-controlled scripts. This can either be side-effect-free
+   * Javascript (such as JSON) or Javascript that's entirely under Google's
+   * control.
+   */
+  JS: goog.DEBUG ? {sanitizedContentJsChars: true} : {},
+
+  /**
+   * A sequence of code units that can appear between quotes (either kind) in a
+   * JS program without causing a parse error, and without causing any side
+   * effects.
+   * <p>
+   * The content should not contain unescaped quotes, newlines, or anything else
+   * that would cause parsing to fail or to cause a JS parser to finish the
+   * string its parsing inside the content.
+   * <p>
+   * The content must also not end inside an escape sequence ; no partial octal
+   * escape sequences or odd number of '{@code \}'s at the end.
+   */
+  JS_STR_CHARS: goog.DEBUG ? {sanitizedContentJsStrChars: true} : {},
+
+  /** A properly encoded portion of a URI. */
+  URI: goog.DEBUG ? {sanitizedContentUri: true} : {},
+
+  /**
+   * Repeated attribute names and values. For example,
+   * {@code dir="ltr" foo="bar" onclick="trustedFunction()" checked}.
+   */
+  ATTRIBUTES: goog.DEBUG ? {sanitizedContentHtmlAttribute: true} : {},
+
+  // TODO: Consider separating rules, declarations, and values into
+  // separate types, but for simplicity, we'll treat explicitly blessed
+  // SanitizedContent as allowed in all of these contexts.
+  /**
+   * A CSS3 declaration, property, value or group of semicolon separated
+   * declarations.
+   */
+  CSS: goog.DEBUG ? {sanitizedContentCss: true} : {},
+
+  /**
+   * Unsanitized plain-text content.
+   *
+   * This is effectively the "null" entry of this enum, and is sometimes used
+   * to explicitly mark content that should never be used unescaped. Since any
+   * string is safe to use as text, being of ContentKind.TEXT makes no
+   * guarantees about its safety in any other context such as HTML.
+   */
+  TEXT: goog.DEBUG ? {sanitizedContentKindText: true} : {}
+};
+
+
+
+/**
+ * A string-like object that carries a content-type and a content direction.
+ *
+ * IMPORTANT! Do not create these directly, nor instantiate the subclasses.
+ * Instead, use a trusted, centrally reviewed library as endorsed by your team
+ * to generate these objects. Otherwise, you risk accidentally creating
+ * SanitizedContent that is attacker-controlled and gets evaluated unescaped in
+ * templates.
+ *
+ * @constructor
+ */
+goog.soy.data.SanitizedContent = function() {
+  throw Error('Do not instantiate directly');
+};
+
+
+/**
+ * The context in which this content is safe from XSS attacks.
+ * @type {goog.soy.data.SanitizedContentKind}
+ */
+goog.soy.data.SanitizedContent.prototype.contentKind;
+
+
+/**
+ * The content's direction; null if unknown and thus to be estimated when
+ * necessary.
+ * @type {?goog.i18n.bidi.Dir}
+ */
+goog.soy.data.SanitizedContent.prototype.contentDir = null;
+
+
+/**
+ * The already-safe content.
+ * @type {string}
+ */
+goog.soy.data.SanitizedContent.prototype.content;
+
+
+/** @override */
+goog.soy.data.SanitizedContent.prototype.toString = function() {
+  return this.content;
 };
 
 
 var soy = { esc: {} };
 var soydata = {};
-var soyshim = {};
+soydata.VERY_UNSAFE = {};
+var soyshim = { $$DEFAULT_TEMPLATE_DATA_: {} };
 /**
  * Helper function to render a Soy template into a single node or a document
  * fragment. If the rendered HTML string represents a single node, then that
@@ -557,8 +857,8 @@ var soyshim = {};
  *
  * @param {Function} template The Soy template defining the element's content.
  * @param {Object=} opt_templateData The data for the template.
- * @param {Document=} opt_document The document used to create DOM nodes. If
- *     not specified, global document object is used.
+ * @param {(goog.dom.DomHelper|Document)=} opt_dom The context in which DOM
+ *     nodes will be created.
  * @param {boolean=} opt_asElement Whether to wrap the fragment in an
  *     element if the template does not render a single element. If true,
  *     result is always an Element.
@@ -567,10 +867,10 @@ var soyshim = {};
  * @private
  */
 soyshim.$$renderWithWrapper_ = function(
-    template, opt_templateData, opt_document, opt_asElement, opt_injectedData) {
+    template, opt_templateData, opt_dom, opt_asElement, opt_injectedData) {
 
-  var doc = opt_document || document;
-  var wrapper = doc.createElement('div');
+  var dom = opt_dom || document;
+  var wrapper = dom.createElement('div');
   wrapper.innerHTML = template(
     opt_templateData || soyshim.$$DEFAULT_TEMPLATE_DATA_, undefined,
     opt_injectedData);
@@ -589,7 +889,7 @@ soyshim.$$renderWithWrapper_ = function(
   }
 
   // Otherwise, create and return a fragment.
-  var fragment = doc.createDocumentFragment();
+  var fragment = dom.createDocumentFragment();
   while (wrapper.firstChild) {
     fragment.appendChild(wrapper.firstChild);
   }
@@ -597,38 +897,11 @@ soyshim.$$renderWithWrapper_ = function(
 };
 
 
-/**
- * Returns a Unicode BiDi mark matching bidiGlobalDir (LRM or RLM) if the
- * directionality or the exit directionality of text are opposite to
- * bidiGlobalDir. Otherwise returns the empty string.
- * If opt_isHtml, makes sure to ignore the LTR nature of the mark-up and escapes
- * in text, making the logic suitable for HTML and HTML-escaped text.
- * @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
- *     if rtl, 0 if unknown.
- * @param {number} dir text's directionality: 1 if ltr, -1 if rtl, 0 if unknown.
- * @param {string} text The text whose directionality is to be estimated.
- * @param {boolean=} opt_isHtml Whether text is HTML/HTML-escaped.
- *     Default: false.
- * @return {string} A Unicode bidi mark matching bidiGlobalDir, or
- *     the empty string when text's overall and exit directionalities both match
- *     bidiGlobalDir, or bidiGlobalDir is 0 (unknown).
- * @private
- */
-soyshim.$$bidiMarkAfterKnownDir_ = function(
-    bidiGlobalDir, dir, text, opt_isHtml) {
-  return (
-      bidiGlobalDir > 0 && (dir < 0 ||
-          soyshim.$$bidiIsRtlExitText_(text, opt_isHtml)) ? '\u200E' : // LRM
-      bidiGlobalDir < 0 && (dir > 0 ||
-          soyshim.$$bidiIsLtrExitText_(text, opt_isHtml)) ? '\u200F' : // RLM
-      '');
-};
-
-
 /**
  * Strips str of any HTML mark-up and escapes. Imprecise in several ways, but
  * precision is not very important, since the result is only meant to be used
  * for directionality detection.
+ * Based on goog.i18n.bidi.stripHtmlIfNeeded_().
  * @param {string} str The string to be stripped.
  * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
  *     Default: false.
@@ -636,7 +909,7 @@ soyshim.$$bidiMarkAfterKnownDir_ = function(
  * @private
  */
 soyshim.$$bidiStripHtmlIfNecessary_ = function(str, opt_isHtml) {
-  return opt_isHtml ? str.replace(soyshim.$$BIDI_HTML_SKIP_RE_, ' ') : str;
+  return opt_isHtml ? str.replace(soyshim.$$BIDI_HTML_SKIP_RE_, '') : str;
 };
 
 
@@ -644,6 +917,7 @@ soyshim.$$bidiStripHtmlIfNecessary_ = function(str, opt_isHtml) {
  * Simplified regular expression for am HTML tag (opening or closing) or an HTML
  * escape - the things we want to skip over in order to ignore their ltr
  * characters.
+ * Copied from goog.i18n.bidi.htmlSkipReg_.
  * @type {RegExp}
  * @private
  */
@@ -654,38 +928,30 @@ soyshim.$$BIDI_HTML_SKIP_RE_ = /<[^>]*>|&[^;]+;/g;
  * A practical pattern to identify strong LTR character. This pattern is not
  * theoretically correct according to unicode standard. It is simplified for
  * performance and small code size.
+ * Copied from goog.i18n.bidi.ltrChars_.
  * @type {string}
  * @private
  */
 soyshim.$$bidiLtrChars_ =
     'A-Za-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02B8\u0300-\u0590\u0800-\u1FFF' +
-    '\u2C00-\uFB1C\uFDFE-\uFE6F\uFEFD-\uFFFF';
-
-
-/**
- * A practical pattern to identify strong neutral and weak character. This
- * pattern is not theoretically correct according to unicode standard. It is
- * simplified for performance and small code size.
- * @type {string}
- * @private
- */
-soyshim.$$bidiNeutralChars_ =
-    '\u0000-\u0020!-@[-`{-\u00BF\u00D7\u00F7\u02B9-\u02FF\u2000-\u2BFF';
+    '\u200E\u2C00-\uFB1C\uFE00-\uFE6F\uFEFD-\uFFFF';
 
 
 /**
  * A practical pattern to identify strong RTL character. This pattern is not
  * theoretically correct according to unicode standard. It is simplified for
  * performance and small code size.
+ * Copied from goog.i18n.bidi.rtlChars_.
  * @type {string}
  * @private
  */
-soyshim.$$bidiRtlChars_ = '\u0591-\u07FF\uFB1D-\uFDFD\uFE70-\uFEFC';
+soyshim.$$bidiRtlChars_ = '\u0591-\u07FF\u200F\uFB1D-\uFDFF\uFE70-\uFEFC';
 
 
 /**
  * Regular expressions to check if a piece of text is of RTL directionality
  * on first character with strong directionality.
+ * Based on goog.i18n.bidi.rtlDirCheckRe_.
  * @type {RegExp}
  * @private
  */
@@ -694,73 +960,59 @@ soyshim.$$bidiRtlDirCheckRe_ = new RegExp(
 
 
 /**
- * Regular expressions to check if a piece of text is of neutral directionality.
- * Url are considered as neutral.
+ * Regular expression to check for LTR characters.
+ * Based on goog.i18n.bidi.ltrCharReg_.
  * @type {RegExp}
  * @private
  */
-soyshim.$$bidiNeutralDirCheckRe_ = new RegExp(
-    '^[' + soyshim.$$bidiNeutralChars_ + ']*$|^http://');
+soyshim.$$bidiLtrCharRe_ = new RegExp('[' + soyshim.$$bidiLtrChars_ + ']');
 
 
 /**
- * Check the directionality of the a piece of text based on the first character
- * with strong directionality.
- * @param {string} str string being checked.
- * @return {boolean} return true if rtl directionality is being detected.
+ * Regular expression to check if a string looks like something that must
+ * always be LTR even in RTL text, e.g. a URL. When estimating the
+ * directionality of text containing these, we treat these as weakly LTR,
+ * like numbers.
+ * Copied from goog.i18n.bidi.isRequiredLtrRe_.
+ * @type {RegExp}
  * @private
  */
-soyshim.$$bidiIsRtlText_ = function(str) {
-  return soyshim.$$bidiRtlDirCheckRe_.test(str);
-};
+soyshim.$$bidiIsRequiredLtrRe_ = /^http:\/\/.*/;
 
 
 /**
- * Check the directionality of the a piece of text based on the first character
- * with strong directionality.
- * @param {string} str string being checked.
- * @return {boolean} true if all characters have neutral directionality.
+ * Regular expression to check if a string contains any numerals. Used to
+ * differentiate between completely neutral strings and those containing
+ * numbers, which are weakly LTR.
+ * Copied from goog.i18n.bidi.hasNumeralsRe_.
+ * @type {RegExp}
  * @private
  */
-soyshim.$$bidiIsNeutralText_ = function(str) {
-  return soyshim.$$bidiNeutralDirCheckRe_.test(str);
-};
+soyshim.$$bidiHasNumeralsRe_ = /\d/;
 
 
 /**
- * This constant controls threshold of rtl directionality.
- * @type {number}
+ * Regular expression to split a string into "words" for directionality
+ * estimation based on relative word counts.
+ * Copied from goog.i18n.bidi.wordSeparatorRe_.
+ * @type {RegExp}
  * @private
  */
-soyshim.$$bidiRtlDetectionThreshold_ = 0.40;
+soyshim.$$bidiWordSeparatorRe_ = /\s+/;
 
 
 /**
- * Returns the RTL ratio based on word count.
- * @param {string} str the string that need to be checked.
- * @return {number} the ratio of RTL words among all words with directionality.
+ * This constant controls threshold of rtl directionality.
+ * Copied from goog.i18n.bidi.rtlDetectionThreshold_.
+ * @type {number}
  * @private
  */
-soyshim.$$bidiRtlWordRatio_ = function(str) {
-  var rtlCount = 0;
-  var totalCount = 0;
-  var tokens = str.split(' ');
-  for (var i = 0; i < tokens.length; i++) {
-    if (soyshim.$$bidiIsRtlText_(tokens[i])) {
-      rtlCount++;
-      totalCount++;
-    } else if (!soyshim.$$bidiIsNeutralText_(tokens[i])) {
-      totalCount++;
-    }
-  }
-
-  return totalCount == 0 ? 0 : rtlCount / totalCount;
-};
-
+soyshim.$$bidiRtlDetectionThreshold_ = 0.40;
 
 /**
  * Regular expressions to check if the last strongly-directional character in a
  * piece of text is LTR.
+ * Based on goog.i18n.bidi.ltrExitDirCheckRe_.
  * @type {RegExp}
  * @private
  */
@@ -771,6 +1023,7 @@ soyshim.$$bidiLtrExitDirCheckRe_ = new RegExp(
 /**
  * Regular expressions to check if the last strongly-directional character in a
  * piece of text is RTL.
+ * Based on goog.i18n.bidi.rtlExitDirCheckRe_.
  * @type {RegExp}
  * @private
  */
@@ -781,6 +1034,7 @@ soyshim.$$bidiRtlExitDirCheckRe_ = new RegExp(
 /**
  * Check if the exit directionality a piece of text is LTR, i.e. if the last
  * strongly-directional character in the string is LTR.
+ * Based on goog.i18n.bidi.endsWithLtr().
  * @param {string} str string being checked.
  * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
  *     Default: false.
@@ -796,6 +1050,7 @@ soyshim.$$bidiIsLtrExitText_ = function(str, opt_isHtml) {
 /**
  * Check if the exit directionality a piece of text is RTL, i.e. if the last
  * strongly-directional character in the string is RTL.
+ * Based on goog.i18n.bidi.endsWithRtl().
  * @param {string} str string being checked.
  * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
  *     Default: false.
@@ -818,7 +1073,7 @@ soyshim.$$bidiIsRtlExitText_ = function(str, opt_isHtml) {
 
 /**
  * Utility class to facilitate much faster string concatenation in IE,
- * using Array.join() rather than the '+' operator.  For other browsers
+ * using Array.join() rather than the '+' operator. For other browsers
  * we simply use the '+' operator.
  *
  * @param {Object} var_args Initial items to append,
@@ -835,131 +1090,441 @@ soy.StringBuilder = goog.string.StringBuffer;
 
 /**
  * A type of textual content.
- * @enum {number}
+ *
+ * This is an enum of type Object so that these values are unforgeable.
+ *
+ * @enum {!Object}
  */
-soydata.SanitizedContentKind = {
+soydata.SanitizedContentKind = goog.soy.data.SanitizedContentKind;
 
-  /**
-   * A snippet of HTML that does not start or end inside a tag, comment, entity,
-   * or DOCTYPE; and that does not contain any executable code
-   * (JS, {@code <object>}s, etc.) from a different trust domain.
-   */
-  HTML: 0,
 
-  /**
-   * A sequence of code units that can appear between quotes (either kind) in a
-   * JS program without causing a parse error, and without causing any side
-   * effects.
-   * <p>
-   * The content should not contain unescaped quotes, newlines, or anything else
-   * that would cause parsing to fail or to cause a JS parser to finish the
-   * string its parsing inside the content.
-   * <p>
-   * The content must also not end inside an escape sequence ; no partial octal
-   * escape sequences or odd number of '{@code \}'s at the end.
-   */
-  JS_STR_CHARS: 1,
+/**
+ * Checks whether a given value is of a given content kind.
+ *
+ * @param {*} value The value to be examined.
+ * @param {soydata.SanitizedContentKind} contentKind The desired content
+ *     kind.
+ * @return {boolean} Whether the given value is of the given kind.
+ * @private
+ */
+soydata.isContentKind = function(value, contentKind) {
+  // TODO(user): This function should really include the assert on
+  // value.constructor that is currently sprinkled at most of the call sites.
+  // Unfortunately, that would require a (debug-mode-only) switch statement.
+  // TODO(user): Perhaps we should get rid of the contentKind property
+  // altogether and only at the constructor.
+  return value != null && value.contentKind === contentKind;
+};
+
+
+/**
+ * Returns a given value's contentDir property, constrained to a
+ * goog.i18n.bidi.Dir value or null. Returns null if the value is null,
+ * undefined, a primitive or does not have a contentDir property, or the
+ * property's value is not 1 (for LTR), -1 (for RTL), or 0 (for neutral).
+ *
+ * @param {*} value The value whose contentDir property, if any, is to
+ *     be returned.
+ * @return {?goog.i18n.bidi.Dir} The contentDir property.
+ */
+soydata.getContentDir = function(value) {
+  if (value != null) {
+    switch (value.contentDir) {
+      case goog.i18n.bidi.Dir.LTR:
+        return goog.i18n.bidi.Dir.LTR;
+      case goog.i18n.bidi.Dir.RTL:
+        return goog.i18n.bidi.Dir.RTL;
+      case goog.i18n.bidi.Dir.NEUTRAL:
+        return goog.i18n.bidi.Dir.NEUTRAL;
+    }
+  }
+  return null;
+};
+
+
+/**
+ * Content of type {@link soydata.SanitizedContentKind.HTML}.
+ *
+ * The content is a string of HTML that can safely be embedded in a PCDATA
+ * context in your app.  If you would be surprised to find that an HTML
+ * sanitizer produced {@code s} (e.g.  it runs code or fetches bad URLs) and
+ * you wouldn't write a template that produces {@code s} on security or privacy
+ * grounds, then don't pass {@code s} here. The default content direction is
+ * unknown, i.e. to be estimated when necessary.
+ *
+ * @constructor
+ * @extends {goog.soy.data.SanitizedContent}
+ */
+soydata.SanitizedHtml = function() {
+  goog.soy.data.SanitizedContent.call(this);  // Throws an exception.
+};
+goog.inherits(soydata.SanitizedHtml, goog.soy.data.SanitizedContent);
+
+/** @override */
+soydata.SanitizedHtml.prototype.contentKind = soydata.SanitizedContentKind.HTML;
+
+/**
+ * Returns a SanitizedHtml object for a particular value. The content direction
+ * is preserved.
+ *
+ * This HTML-escapes the value unless it is already SanitizedHtml.
+ *
+ * @param {*} value The value to convert. If it is already a SanitizedHtml
+ *     object, it is left alone.
+ * @return {!soydata.SanitizedHtml} A SanitizedHtml object derived from the
+ *     stringified value. It is escaped unless the input is SanitizedHtml.
+ */
+soydata.SanitizedHtml.from = function(value) {
+  // The check is soydata.isContentKind() inlined for performance.
+  if (value != null &&
+      value.contentKind === soydata.SanitizedContentKind.HTML) {
+    goog.asserts.assert(value.constructor === soydata.SanitizedHtml);
+    return /** @type {!soydata.SanitizedHtml} */ (value);
+  }
+  return soydata.VERY_UNSAFE.ordainSanitizedHtml(
+      soy.esc.$$escapeHtmlHelper(String(value)), soydata.getContentDir(value));
+};
+
+
+/**
+ * Content of type {@link soydata.SanitizedContentKind.JS}.
+ *
+ * The content is Javascript source that when evaluated does not execute any
+ * attacker-controlled scripts. The content direction is LTR.
+ *
+ * @constructor
+ * @extends {goog.soy.data.SanitizedContent}
+ */
+soydata.SanitizedJs = function() {
+  goog.soy.data.SanitizedContent.call(this);  // Throws an exception.
+};
+goog.inherits(soydata.SanitizedJs, goog.soy.data.SanitizedContent);
+
+/** @override */
+soydata.SanitizedJs.prototype.contentKind =
+    soydata.SanitizedContentKind.JS;
+
+/** @override */
+soydata.SanitizedJs.prototype.contentDir = goog.i18n.bidi.Dir.LTR;
+
+
+/**
+ * Content of type {@link soydata.SanitizedContentKind.JS_STR_CHARS}.
+ *
+ * The content can be safely inserted as part of a single- or double-quoted
+ * string without terminating the string. The default content direction is
+ * unknown, i.e. to be estimated when necessary.
+ *
+ * @constructor
+ * @extends {goog.soy.data.SanitizedContent}
+ */
+soydata.SanitizedJsStrChars = function() {
+  goog.soy.data.SanitizedContent.call(this);  // Throws an exception.
+};
+goog.inherits(soydata.SanitizedJsStrChars, goog.soy.data.SanitizedContent);
+
+/** @override */
+soydata.SanitizedJsStrChars.prototype.contentKind =
+    soydata.SanitizedContentKind.JS_STR_CHARS;
+
+/**
+ * Content of type {@link soydata.SanitizedContentKind.URI}.
+ *
+ * The content is a URI chunk that the caller knows is safe to emit in a
+ * template. The content direction is LTR.
+ *
+ * @constructor
+ * @extends {goog.soy.data.SanitizedContent}
+ */
+soydata.SanitizedUri = function() {
+  goog.soy.data.SanitizedContent.call(this);  // Throws an exception.
+};
+goog.inherits(soydata.SanitizedUri, goog.soy.data.SanitizedContent);
+
+/** @override */
+soydata.SanitizedUri.prototype.contentKind = soydata.SanitizedContentKind.URI;
+
+/** @override */
+soydata.SanitizedUri.prototype.contentDir = goog.i18n.bidi.Dir.LTR;
+
+
+/**
+ * Content of type {@link soydata.SanitizedContentKind.ATTRIBUTES}.
+ *
+ * The content should be safely embeddable within an open tag, such as a
+ * key="value" pair. The content direction is LTR.
+ *
+ * @constructor
+ * @extends {goog.soy.data.SanitizedContent}
+ */
+soydata.SanitizedHtmlAttribute = function() {
+  goog.soy.data.SanitizedContent.call(this);  // Throws an exception.
+};
+goog.inherits(soydata.SanitizedHtmlAttribute, goog.soy.data.SanitizedContent);
+
+/** @override */
+soydata.SanitizedHtmlAttribute.prototype.contentKind =
+    soydata.SanitizedContentKind.ATTRIBUTES;
+
+/** @override */
+soydata.SanitizedHtmlAttribute.prototype.contentDir = goog.i18n.bidi.Dir.LTR;
+
+
+/**
+ * Content of type {@link soydata.SanitizedContentKind.CSS}.
+ *
+ * The content is non-attacker-exploitable CSS, such as {@code color:#c3d9ff}.
+ * The content direction is LTR.
+ *
+ * @constructor
+ * @extends {goog.soy.data.SanitizedContent}
+ */
+soydata.SanitizedCss = function() {
+  goog.soy.data.SanitizedContent.call(this);  // Throws an exception.
+};
+goog.inherits(soydata.SanitizedCss, goog.soy.data.SanitizedContent);
+
+/** @override */
+soydata.SanitizedCss.prototype.contentKind =
+    soydata.SanitizedContentKind.CSS;
+
+/** @override */
+soydata.SanitizedCss.prototype.contentDir = goog.i18n.bidi.Dir.LTR;
+
+
+/**
+ * Unsanitized plain text string.
+ *
+ * While all strings are effectively safe to use as a plain text, there are no
+ * guarantees about safety in any other context such as HTML. This is
+ * sometimes used to mark that should never be used unescaped.
+ *
+ * @param {*} content Plain text with no guarantees.
+ * @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction; null if
+ *     unknown and thus to be estimated when necessary. Default: null.
+ * @constructor
+ * @extends {goog.soy.data.SanitizedContent}
+ */
+soydata.UnsanitizedText = function(content, opt_contentDir) {
+  /** @override */
+  this.content = String(content);
+  this.contentDir = opt_contentDir != null ? opt_contentDir : null;
+};
+goog.inherits(soydata.UnsanitizedText, goog.soy.data.SanitizedContent);
+
+/** @override */
+soydata.UnsanitizedText.prototype.contentKind =
+    soydata.SanitizedContentKind.TEXT;
+
+
+/**
+ * Empty string, used as a type in Soy templates.
+ * @enum {string}
+ * @private
+ */
+soydata.$$EMPTY_STRING_ = {
+  VALUE: ''
+};
 
-  /** A properly encoded portion of a URI. */
-  URI: 2,
 
-  /** An attribute name and value such as {@code dir="ltr"}. */
-  HTML_ATTRIBUTE: 3
+/**
+ * Creates a factory for SanitizedContent types.
+ *
+ * This is a hack so that the soydata.VERY_UNSAFE.ordainSanitized* can
+ * instantiate Sanitized* classes, without making the Sanitized* constructors
+ * publicly usable. Requiring all construction to use the VERY_UNSAFE names
+ * helps callers and their reviewers easily tell that creating SanitizedContent
+ * is not always safe and calls for careful review.
+ *
+ * @param {function(new: T)} ctor A constructor.
+ * @return {!function(*, ?goog.i18n.bidi.Dir=): T} A factory that takes
+ *     content and an optional content direction and returns a new instance. If
+ *     the content direction is undefined, ctor.prototype.contentDir is used.
+ * @template T
+ * @private
+ */
+soydata.$$makeSanitizedContentFactory_ = function(ctor) {
+  /** @type {function(new: goog.soy.data.SanitizedContent)} */
+  function InstantiableCtor() {}
+  InstantiableCtor.prototype = ctor.prototype;
+  /**
+   * Creates a ctor-type SanitizedContent instance.
+   *
+   * @param {*} content The content to put in the instance.
+   * @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction. If
+   *     undefined, ctor.prototype.contentDir is used.
+   * @return {goog.soy.data.SanitizedContent} The new instance. It is actually
+   *     of type T above (ctor's type, a descendant of SanitizedContent), but
+   *     there is no way to express that here.
+   */
+  function sanitizedContentFactory(content, opt_contentDir) {
+    var result = new InstantiableCtor();
+    result.content = String(content);
+    if (opt_contentDir !== undefined) {
+      result.contentDir = opt_contentDir;
+    }
+    return result;
+  }
+  return sanitizedContentFactory;
 };
 
 
 /**
- * A string-like object that carries a content-type.
- * @param {string} content
- * @constructor
+ * Creates a factory for SanitizedContent types that should always have their
+ * default directionality.
+ *
+ * This is a hack so that the soydata.VERY_UNSAFE.ordainSanitized* can
+ * instantiate Sanitized* classes, without making the Sanitized* constructors
+ * publicly usable. Requiring all construction to use the VERY_UNSAFE names
+ * helps callers and their reviewers easily tell that creating SanitizedContent
+ * is not always safe and calls for careful review.
+ *
+ * @param {function(new: T, string)} ctor A constructor.
+ * @return {!function(*): T} A factory that takes content and returns a new
+ *     instance (with default directionality, i.e. ctor.prototype.contentDir).
+ * @template T
  * @private
  */
-soydata.SanitizedContent = function(content) {
+soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_ = function(ctor) {
+  /** @type {function(new: goog.soy.data.SanitizedContent)} */
+  function InstantiableCtor() {}
+  InstantiableCtor.prototype = ctor.prototype;
   /**
-   * The textual content.
-   * @type {string}
+   * Creates a ctor-type SanitizedContent instance.
+   *
+   * @param {*} content The content to put in the instance.
+   * @return {goog.soy.data.SanitizedContent} The new instance. It is actually
+   *     of type T above (ctor's type, a descendant of SanitizedContent), but
+   *     there is no way to express that here.
    */
-  this.content = content;
+  function sanitizedContentFactory(content) {
+    var result = new InstantiableCtor();
+    result.content = String(content);
+    return result;
+  }
+  return sanitizedContentFactory;
 };
 
-/** @type {soydata.SanitizedContentKind} */
-soydata.SanitizedContent.prototype.contentKind;
 
-/** @override */
-soydata.SanitizedContent.prototype.toString = function() {
-  return this.content;
+// -----------------------------------------------------------------------------
+// Sanitized content ordainers. Please use these with extreme caution (with the
+// exception of markUnsanitizedText). A good recommendation is to limit usage
+// of these to just a handful of files in your source tree where usages can be
+// carefully audited.
+
+
+/**
+ * Protects a string from being used in an noAutoescaped context.
+ *
+ * This is useful for content where there is significant risk of accidental
+ * unescaped usage in a Soy template. A great case is for user-controlled
+ * data that has historically been a source of vulernabilities.
+ *
+ * @param {*} content Text to protect.
+ * @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction; null if
+ *     unknown and thus to be estimated when necessary. Default: null.
+ * @return {!soydata.UnsanitizedText} A wrapper that is rejected by the
+ *     Soy noAutoescape print directive.
+ */
+soydata.markUnsanitizedText = function(content, opt_contentDir) {
+  return new soydata.UnsanitizedText(content, opt_contentDir);
 };
 
 
 /**
- * Content of type {@link soydata.SanitizedContentKind.HTML}.
- * @param {string} content A string of HTML that can safely be embedded in
- *     a PCDATA context in your app.  If you would be surprised to find that an
+ * Takes a leap of faith that the provided content is "safe" HTML.
+ *
+ * @param {*} content A string of HTML that can safely be embedded in
+ *     a PCDATA context in your app. If you would be surprised to find that an
  *     HTML sanitizer produced {@code s} (e.g. it runs code or fetches bad URLs)
  *     and you wouldn't write a template that produces {@code s} on security or
  *     privacy grounds, then don't pass {@code s} here.
- * @constructor
- * @extends {soydata.SanitizedContent}
+ * @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction; null if
+ *     unknown and thus to be estimated when necessary. Default: null.
+ * @return {!soydata.SanitizedHtml} Sanitized content wrapper that
+ *     indicates to Soy not to escape when printed as HTML.
  */
-soydata.SanitizedHtml = function(content) {
-  soydata.SanitizedContent.call(this, content);
-};
-goog.inherits(soydata.SanitizedHtml, soydata.SanitizedContent);
-
-/** @override */
-soydata.SanitizedHtml.prototype.contentKind = soydata.SanitizedContentKind.HTML;
+soydata.VERY_UNSAFE.ordainSanitizedHtml =
+    soydata.$$makeSanitizedContentFactory_(soydata.SanitizedHtml);
 
 
 /**
- * Content of type {@link soydata.SanitizedContentKind.JS_STR_CHARS}.
- * @param {string} content A string of JS that when evaled, produces a
- *     value that does not depend on any sensitive data and has no side effects
- *     <b>OR</b> a string of JS that does not reference any variables or have
- *     any side effects not known statically to the app authors.
- * @constructor
- * @extends {soydata.SanitizedContent}
+ * Takes a leap of faith that the provided content is "safe" (non-attacker-
+ * controlled, XSS-free) Javascript.
+ *
+ * @param {*} content Javascript source that when evaluated does not
+ *     execute any attacker-controlled scripts.
+ * @return {!soydata.SanitizedJs} Sanitized content wrapper that indicates to
+ *     Soy not to escape when printed as Javascript source.
  */
-soydata.SanitizedJsStrChars = function(content) {
-  soydata.SanitizedContent.call(this, content);
-};
-goog.inherits(soydata.SanitizedJsStrChars, soydata.SanitizedContent);
+soydata.VERY_UNSAFE.ordainSanitizedJs =
+    soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_(
+        soydata.SanitizedJs);
 
-/** @override */
-soydata.SanitizedJsStrChars.prototype.contentKind =
-    soydata.SanitizedContentKind.JS_STR_CHARS;
+
+// TODO: This function is probably necessary, either externally or internally
+// as an implementation detail. Generally, plain text will always work here,
+// as there's no harm to unescaping the string and then re-escaping when
+// finally printed.
+/**
+ * Takes a leap of faith that the provided content can be safely embedded in
+ * a Javascript string without re-esacping.
+ *
+ * @param {*} content Content that can be safely inserted as part of a
+ *     single- or double-quoted string without terminating the string.
+ * @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction; null if
+ *     unknown and thus to be estimated when necessary. Default: null.
+ * @return {!soydata.SanitizedJsStrChars} Sanitized content wrapper that
+ *     indicates to Soy not to escape when printed in a JS string.
+ */
+soydata.VERY_UNSAFE.ordainSanitizedJsStrChars =
+    soydata.$$makeSanitizedContentFactory_(soydata.SanitizedJsStrChars);
 
 
 /**
- * Content of type {@link soydata.SanitizedContentKind.URI}.
- * @param {string} content A chunk of URI that the caller knows is safe to
+ * Takes a leap of faith that the provided content is "safe" to use as a URI
+ * in a Soy template.
+ *
+ * This creates a Soy SanitizedContent object which indicates to Soy there is
+ * no need to escape it when printed as a URI (e.g. in an href or src
+ * attribute), such as if it's already been encoded or  if it's a Javascript:
+ * URI.
+ *
+ * @param {*} content A chunk of URI that the caller knows is safe to
  *     emit in a template.
- * @constructor
- * @extends {soydata.SanitizedContent}
+ * @return {!soydata.SanitizedUri} Sanitized content wrapper that indicates to
+ *     Soy not to escape or filter when printed in URI context.
  */
-soydata.SanitizedUri = function(content) {
-  soydata.SanitizedContent.call(this, content);
-};
-goog.inherits(soydata.SanitizedUri, soydata.SanitizedContent);
-
-/** @override */
-soydata.SanitizedUri.prototype.contentKind = soydata.SanitizedContentKind.URI;
+soydata.VERY_UNSAFE.ordainSanitizedUri =
+    soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_(
+        soydata.SanitizedUri);
 
 
 /**
- * Content of type {@link soydata.SanitizedContentKind.HTML_ATTRIBUTE}.
- * @param {string} content An attribute name and value, such as
+ * Takes a leap of faith that the provided content is "safe" to use as an
+ * HTML attribute.
+ *
+ * @param {*} content An attribute name and value, such as
  *     {@code dir="ltr"}.
- * @constructor
- * @extends {soydata.SanitizedContent}
+ * @return {!soydata.SanitizedHtmlAttribute} Sanitized content wrapper that
+ *     indicates to Soy not to escape when printed as an HTML attribute.
  */
-soydata.SanitizedHtmlAttribute = function(content) {
-  soydata.SanitizedContent.call(this, content);
-};
-goog.inherits(soydata.SanitizedHtmlAttribute, soydata.SanitizedContent);
+soydata.VERY_UNSAFE.ordainSanitizedHtmlAttribute =
+    soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_(
+        soydata.SanitizedHtmlAttribute);
 
-/** @override */
-soydata.SanitizedHtmlAttribute.prototype.contentKind =
-    soydata.SanitizedContentKind.HTML_ATTRIBUTE;
+
+/**
+ * Takes a leap of faith that the provided content is "safe" to use as CSS
+ * in a style attribute or block.
+ *
+ * @param {*} content CSS, such as {@code color:#c3d9ff}.
+ * @return {!soydata.SanitizedCss} Sanitized CSS wrapper that indicates to
+ *     Soy there is no need to escape or filter when printed in CSS context.
+ */
+soydata.VERY_UNSAFE.ordainSanitizedCss =
+    soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_(
+        soydata.SanitizedCss);
 
 
 // -----------------------------------------------------------------------------
@@ -1036,32 +1601,54 @@ soy.renderAsElement = function(
 
 
 /**
- * Builds an augmented data object to be passed when a template calls another,
- * and needs to pass both original data and additional params. The returned
- * object will contain both the original data and the additional params. If the
- * same key appears in both, then the value from the additional params will be
- * visible, while the value from the original data will be hidden. The original
- * data object will be used, but not modified.
+ * Whether the locale is right-to-left.
+ *
+ * @type {boolean}
+ */
+soy.$$IS_LOCALE_RTL = goog.i18n.bidi.IS_RTL;
+
+
+/**
+ * Builds an augmented map. The returned map will contain mappings from both
+ * the base map and the additional map. If the same key appears in both, then
+ * the value from the additional map will be visible, while the value from the
+ * base map will be hidden. The base map will be used, but not modified.
  *
- * @param {!Object} origData The original data to pass.
- * @param {Object} additionalParams The additional params to pass.
- * @return {Object} An augmented data object containing both the original data
- *     and the additional params.
+ * @param {!Object} baseMap The original map to augment.
+ * @param {!Object} additionalMap A map containing the additional mappings.
+ * @return {!Object} An augmented map containing both the original and
+ *     additional mappings.
  */
-soy.$$augmentData = function(origData, additionalParams) {
+soy.$$augmentMap = function(baseMap, additionalMap) {
 
-  // Create a new object whose '__proto__' field is set to origData.
+  // Create a new map whose '__proto__' field is set to baseMap.
   /** @constructor */
   function TempCtor() {}
-  TempCtor.prototype = origData;
-  var newData = new TempCtor();
+  TempCtor.prototype = baseMap;
+  var augmentedMap = new TempCtor();
 
-  // Add the additional params to the new object.
-  for (var key in additionalParams) {
-    newData[key] = additionalParams[key];
+  // Add the additional mappings to the new map.
+  for (var key in additionalMap) {
+    augmentedMap[key] = additionalMap[key];
   }
 
-  return newData;
+  return augmentedMap;
+};
+
+
+/**
+ * Checks that the given map key is a string.
+ * @param {*} key Key to check.
+ * @return {string} The given key.
+ */
+soy.$$checkMapKey = function(key) {
+  // TODO: Support map literal with nonstring key.
+  if ((typeof key) != 'string') {
+    throw Error(
+        'Map literal\'s key expression must evaluate to string' +
+        ' (encountered type "' + (typeof key) + '").');
+  }
+  return key;
 };
 
 
@@ -1097,13 +1684,13 @@ soy.$$getMapKeys = function(map) {
  *
  * @consistentIdGenerator
  */
-soy.$$getDelegateId = function(delTemplateName) {
+soy.$$getDelTemplateId = function(delTemplateName) {
   return delTemplateName;
 };
 
 
 /**
- * Map from registered delegate template id/name to the priority of the
+ * Map from registered delegate template key to the priority of the
  * implementation.
  * @type {Object}
  * @private
@@ -1111,7 +1698,7 @@ soy.$$getDelegateId = function(delTemplateName) {
 soy.$$DELEGATE_REGISTRY_PRIORITIES_ = {};
 
 /**
- * Map from registered delegate template id/name to the implementation function.
+ * Map from registered delegate template key to the implementation function.
  * @type {Object}
  * @private
  */
@@ -1119,17 +1706,21 @@ soy.$$DELEGATE_REGISTRY_FUNCTIONS_ = {};
 
 
 /**
- * Registers a delegate implementation. If the same delegate template id/name
- * has been registered previously, then priority values are compared and only
- * the higher priority implementation is stored (if priorities are equal, an
- * error is thrown).
+ * Registers a delegate implementation. If the same delegate template key (id
+ * and variant) has been registered previously, then priority values are
+ * compared and only the higher priority implementation is stored (if
+ * priorities are equal, an error is thrown).
  *
- * @param {string} delTemplateId The delegate template id/name to register.
+ * @param {string} delTemplateId The delegate template id.
+ * @param {string} delTemplateVariant The delegate template variant (can be
+ *     empty string).
  * @param {number} delPriority The implementation's priority value.
  * @param {Function} delFn The implementation function.
  */
-soy.$$registerDelegateFn = function(delTemplateId, delPriority, delFn) {
-  var mapKey = 'key_' + delTemplateId;
+soy.$$registerDelegateFn = function(
+    delTemplateId, delTemplateVariant, delPriority, delFn) {
+
+  var mapKey = 'key_' + delTemplateId + ':' + delTemplateVariant;
   var currPriority = soy.$$DELEGATE_REGISTRY_PRIORITIES_[mapKey];
   if (currPriority === undefined || delPriority > currPriority) {
     // Registering new or higher-priority function: replace registry entry.
@@ -1138,8 +1729,8 @@ soy.$$registerDelegateFn = function(delTemplateId, delPriority, delFn) {
   } else if (delPriority == currPriority) {
     // Registering same-priority function: error.
     throw Error(
-        'Encountered two active delegates with same priority (id/name "' +
-        delTemplateId + '").');
+        'Encountered two active delegates with the same priority ("' +
+            delTemplateId + ':' + delTemplateVariant + '").');
   } else {
     // Registering lower-priority function: do nothing.
   }
@@ -1148,16 +1739,38 @@ soy.$$registerDelegateFn = function(delTemplateId, delPriority, delFn) {
 
 /**
  * Retrieves the (highest-priority) implementation that has been registered for
- * a given delegate template id/name. If no implementation has been registered
- * for the id/name, then returns an implementation that is equivalent to an
- * empty template (i.e. rendered output would be empty string).
+ * a given delegate template key (id and variant). If no implementation has
+ * been registered for the key, then the fallback is the same id with empty
+ * variant. If the fallback is also not registered, and allowsEmptyDefault is
+ * true, then returns an implementation that is equivalent to an empty template
+ * (i.e. rendered output would be empty string).
  *
- * @param {string} delTemplateId The delegate template id/name to get.
+ * @param {string} delTemplateId The delegate template id.
+ * @param {string|number} delTemplateVariant The delegate template variant (can
+ *     be an empty string, or a number when a global is used).
+ * @param {boolean} allowsEmptyDefault Whether to default to the empty template
+ *     function if there's no active implementation.
  * @return {Function} The retrieved implementation function.
  */
-soy.$$getDelegateFn = function(delTemplateId) {
-  var delFn = soy.$$DELEGATE_REGISTRY_FUNCTIONS_['key_' + delTemplateId];
-  return delFn ? delFn : soy.$$EMPTY_TEMPLATE_FN_;
+soy.$$getDelegateFn = function(
+    delTemplateId, delTemplateVariant, allowsEmptyDefault) {
+
+  var delFn = soy.$$DELEGATE_REGISTRY_FUNCTIONS_[
+      'key_' + delTemplateId + ':' + delTemplateVariant];
+  if (! delFn && delTemplateVariant != '') {
+    // Fallback to empty variant.
+    delFn = soy.$$DELEGATE_REGISTRY_FUNCTIONS_['key_' + delTemplateId + ':'];
+  }
+
+  if (delFn) {
+    return delFn;
+  } else if (allowsEmptyDefault) {
+    return soy.$$EMPTY_TEMPLATE_FN_;
+  } else {
+    throw Error(
+        'Found no active impl for delegate call to "' + delTemplateId + ':' +
+            delTemplateVariant + '" (and not allowemptydefault="true").');
+  }
 };
 
 
@@ -1176,26 +1789,220 @@ soy.$$EMPTY_TEMPLATE_FN_ = function(opt_data, opt_sb, opt_ijData) {
 };
 
 
+// -----------------------------------------------------------------------------
+// Internal sanitized content wrappers.
+
+
+/**
+ * Creates a SanitizedContent factory for SanitizedContent types for internal
+ * Soy let and param blocks.
+ *
+ * This is a hack within Soy so that SanitizedContent objects created via let
+ * and param blocks will truth-test as false if they are empty string.
+ * Tricking the Javascript runtime to treat empty SanitizedContent as falsey is
+ * not possible, and changing the Soy compiler to wrap every boolean statement
+ * for just this purpose is impractical.  Instead, we just avoid wrapping empty
+ * string as SanitizedContent, since it's a no-op for empty strings anyways.
+ *
+ * @param {function(new: T)} ctor A constructor.
+ * @return {!function(*, ?goog.i18n.bidi.Dir=): (T|soydata.$$EMPTY_STRING_)}
+ *     A factory that takes content and an optional content direction and
+ *     returns a new instance, or an empty string. If the content direction is
+ *     undefined, ctor.prototype.contentDir is used.
+ * @template T
+ * @private
+ */
+soydata.$$makeSanitizedContentFactoryForInternalBlocks_ = function(ctor) {
+  /** @type {function(new: goog.soy.data.SanitizedContent)} */
+  function InstantiableCtor() {}
+  InstantiableCtor.prototype = ctor.prototype;
+  /**
+   * Creates a ctor-type SanitizedContent instance.
+   *
+   * @param {*} content The content to put in the instance.
+   * @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction. If
+   *     undefined, ctor.prototype.contentDir is used.
+   * @return {goog.soy.data.SanitizedContent|soydata.$$EMPTY_STRING_} The new
+   *     instance, or an empty string. A new instance is actually of type T
+   *     above (ctor's type, a descendant of SanitizedContent), but there's no
+   *     way to express that here.
+   */
+  function sanitizedContentFactory(content, opt_contentDir) {
+    var contentString = String(content);
+    if (!contentString) {
+      return soydata.$$EMPTY_STRING_.VALUE;
+    }
+    var result = new InstantiableCtor();
+    result.content = String(content);
+    if (opt_contentDir !== undefined) {
+      result.contentDir = opt_contentDir;
+    }
+    return result;
+  }
+  return sanitizedContentFactory;
+};
+
+
+/**
+ * Creates a SanitizedContent factory for SanitizedContent types that should
+ * always have their default directionality for internal Soy let and param
+ * blocks.
+ *
+ * This is a hack within Soy so that SanitizedContent objects created via let
+ * and param blocks will truth-test as false if they are empty string.
+ * Tricking the Javascript runtime to treat empty SanitizedContent as falsey is
+ * not possible, and changing the Soy compiler to wrap every boolean statement
+ * for just this purpose is impractical.  Instead, we just avoid wrapping empty
+ * string as SanitizedContent, since it's a no-op for empty strings anyways.
+ *
+ * @param {function(new: T)} ctor A constructor.
+ * @return {!function(*): (T|soydata.$$EMPTY_STRING_)} A
+ *     factory that takes content and returns a
+ *     new instance (with default directionality, i.e.
+ *     ctor.prototype.contentDir), or an empty string.
+ * @template T
+ * @private
+ */
+soydata.$$makeSanitizedContentFactoryWithDefaultDirOnlyForInternalBlocks_ =
+    function(ctor) {
+  /** @type {function(new: goog.soy.data.SanitizedContent)} */
+  function InstantiableCtor() {}
+  InstantiableCtor.prototype = ctor.prototype;
+  /**
+   * Creates a ctor-type SanitizedContent instance.
+   *
+   * @param {*} content The content to put in the instance.
+   * @return {goog.soy.data.SanitizedContent|soydata.$$EMPTY_STRING_} The new
+   *     instance, or an empty string. A new instance is actually of type T
+   *     above (ctor's type, a descendant of SanitizedContent), but there's no
+   *     way to express that here.
+   */
+  function sanitizedContentFactory(content) {
+    var contentString = String(content);
+    if (!contentString) {
+      return soydata.$$EMPTY_STRING_.VALUE;
+    }
+    var result = new InstantiableCtor();
+    result.content = String(content);
+    return result;
+  }
+  return sanitizedContentFactory;
+};
+
+
+/**
+ * Creates kind="text" block contents (internal use only).
+ *
+ * @param {*} content Text.
+ * @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction; null if
+ *     unknown and thus to be estimated when necessary. Default: null.
+ * @return {!soydata.UnsanitizedText|soydata.$$EMPTY_STRING_} Wrapped result.
+ */
+soydata.$$markUnsanitizedTextForInternalBlocks = function(
+    content, opt_contentDir) {
+  var contentString = String(content);
+  if (!contentString) {
+    return soydata.$$EMPTY_STRING_.VALUE;
+  }
+  return new soydata.UnsanitizedText(contentString, opt_contentDir);
+};
+
+
+/**
+ * Creates kind="html" block contents (internal use only).
+ *
+ * @param {*} content Text.
+ * @param {?goog.i18n.bidi.Dir=} opt_contentDir The content direction; null if
+ *     unknown and thus to be estimated when necessary. Default: null.
+ * @return {soydata.SanitizedHtml|soydata.$$EMPTY_STRING_} Wrapped result.
+ */
+soydata.VERY_UNSAFE.$$ordainSanitizedHtmlForInternalBlocks =
+    soydata.$$makeSanitizedContentFactoryForInternalBlocks_(
+        soydata.SanitizedHtml);
+
+
+/**
+ * Creates kind="js" block contents (internal use only).
+ *
+ * @param {*} content Text.
+ * @return {soydata.SanitizedJs|soydata.$$EMPTY_STRING_} Wrapped result.
+ */
+soydata.VERY_UNSAFE.$$ordainSanitizedJsForInternalBlocks =
+    soydata.$$makeSanitizedContentFactoryWithDefaultDirOnlyForInternalBlocks_(
+        soydata.SanitizedJs);
+
+
+/**
+ * Creates kind="uri" block contents (internal use only).
+ *
+ * @param {*} content Text.
+ * @return {soydata.SanitizedUri|soydata.$$EMPTY_STRING_} Wrapped result.
+ */
+soydata.VERY_UNSAFE.$$ordainSanitizedUriForInternalBlocks =
+    soydata.$$makeSanitizedContentFactoryWithDefaultDirOnlyForInternalBlocks_(
+        soydata.SanitizedUri);
+
+
+/**
+ * Creates kind="attributes" block contents (internal use only).
+ *
+ * @param {*} content Text.
+ * @return {soydata.SanitizedHtmlAttribute|soydata.$$EMPTY_STRING_} Wrapped
+ *     result.
+ */
+soydata.VERY_UNSAFE.$$ordainSanitizedAttributesForInternalBlocks =
+    soydata.$$makeSanitizedContentFactoryWithDefaultDirOnlyForInternalBlocks_(
+        soydata.SanitizedHtmlAttribute);
+
+
+/**
+ * Creates kind="css" block contents (internal use only).
+ *
+ * @param {*} content Text.
+ * @return {soydata.SanitizedCss|soydata.$$EMPTY_STRING_} Wrapped result.
+ */
+soydata.VERY_UNSAFE.$$ordainSanitizedCssForInternalBlocks =
+    soydata.$$makeSanitizedContentFactoryWithDefaultDirOnlyForInternalBlocks_(
+        soydata.SanitizedCss);
+
+
 // -----------------------------------------------------------------------------
 // Escape/filter/normalize.
 
 
 /**
- * Escapes HTML special characters in a string.  Escapes double quote '"' in
- * addition to '&', '<', and '>' so that a string can be included in an HTML
- * tag attribute value within double quotes.
- * Will emit known safe HTML as-is.
+ * Returns a SanitizedHtml object for a particular value. The content direction
+ * is preserved.
  *
- * @param {*} value The string-like value to be escaped.  May not be a string,
- *     but the value will be coerced to a string.
- * @return {string} An escaped version of value.
+ * This HTML-escapes the value unless it is already SanitizedHtml. Escapes
+ * double quote '"' in addition to '&', '<', and '>' so that a string can be
+ * included in an HTML tag attribute value within double quotes.
+ *
+ * @param {*} value The value to convert. If it is already a SanitizedHtml
+ *     object, it is left alone.
+ * @return {!soydata.SanitizedHtml} An escaped version of value.
  */
 soy.$$escapeHtml = function(value) {
-  if (typeof value === 'object' && value &&
-      value.contentKind === soydata.SanitizedContentKind.HTML) {
-    return value.content;
+  return soydata.SanitizedHtml.from(value);
+};
+
+
+/**
+ * Strips unsafe tags to convert a string of untrusted HTML into HTML that
+ * is safe to embed. The content direction is preserved.
+ *
+ * @param {*} value The string-like value to be escaped. May not be a string,
+ *     but the value will be coerced to a string.
+ * @return {!soydata.SanitizedHtml} A sanitized and normalized version of value.
+ */
+soy.$$cleanHtml = function(value) {
+  if (soydata.isContentKind(value, soydata.SanitizedContentKind.HTML)) {
+    goog.asserts.assert(value.constructor === soydata.SanitizedHtml);
+    return /** @type {!soydata.SanitizedHtml} */ (value);
   }
-  return soy.esc.$$escapeHtmlHelper(value);
+  return soydata.VERY_UNSAFE.ordainSanitizedHtml(
+      soy.$$stripHtmlTags(value, soy.esc.$$SAFE_TAG_WHITELIST_),
+      soydata.getContentDir(value));
 };
 
 
@@ -1204,7 +2011,7 @@ soy.$$escapeHtml = function(value) {
  * RCDATA.
  * <p>
  * Escapes HTML special characters so that the value will not prematurely end
- * the body of a tag like {@code <textarea>} or {@code <title>}.  RCDATA tags
+ * the body of a tag like {@code <textarea>} or {@code <title>}. RCDATA tags
  * cannot contain other HTML entities, so it is not strictly necessary to escape
  * HTML special characters except when part of that text looks like an HTML
  * entity or like a close tag : {@code </textarea>}.
@@ -1213,13 +2020,13 @@ soy.$$escapeHtml = function(value) {
  * contain an innocuous {@code </textarea>} don't prematurely end an RCDATA
  * element.
  *
- * @param {*} value The string-like value to be escaped.  May not be a string,
+ * @param {*} value The string-like value to be escaped. May not be a string,
  *     but the value will be coerced to a string.
  * @return {string} An escaped version of value.
  */
 soy.$$escapeHtmlRcdata = function(value) {
-  if (typeof value === 'object' && value &&
-      value.contentKind === soydata.SanitizedContentKind.HTML) {
+  if (soydata.isContentKind(value, soydata.SanitizedContentKind.HTML)) {
+    goog.asserts.assert(value.constructor === soydata.SanitizedHtml);
     return soy.esc.$$normalizeHtmlHelper(value.content);
   }
   return soy.esc.$$escapeHtmlHelper(value);
@@ -1227,29 +2034,133 @@ soy.$$escapeHtmlRcdata = function(value) {
 
 
 /**
- * Removes HTML tags from a string of known safe HTML so it can be used as an
- * attribute value.
+ * Matches any/only HTML5 void elements' start tags.
+ * See http://www.w3.org/TR/html-markup/syntax.html#syntax-elements
+ * @type {RegExp}
+ * @private
+ */
+soy.$$HTML5_VOID_ELEMENTS_ = new RegExp(
+    '^<(?:area|base|br|col|command|embed|hr|img|input' +
+    '|keygen|link|meta|param|source|track|wbr)\\b');
+
+
+/**
+ * Removes HTML tags from a string of known safe HTML.
+ * If opt_tagWhitelist is not specified or is empty, then
+ * the result can be used as an attribute value.
  *
- * @param {*} value The HTML to be escaped.  May not be a string, but the
+ * @param {*} value The HTML to be escaped. May not be a string, but the
  *     value will be coerced to a string.
- * @return {string} A representation of value without tags, HTML comments, or
- *     other content.
+ * @param {Object.<string, number>=} opt_tagWhitelist Has an own property whose
+ *     name is a lower-case tag name and whose value is {@code 1} for
+ *     each element that is allowed in the output.
+ * @return {string} A representation of value without disallowed tags,
+ *     HTML comments, or other non-text content.
+ */
+soy.$$stripHtmlTags = function(value, opt_tagWhitelist) {
+  if (!opt_tagWhitelist) {
+    // If we have no white-list, then use a fast track which elides all tags.
+    return String(value).replace(soy.esc.$$HTML_TAG_REGEX_, '')
+        // This is just paranoia since callers should normalize the result
+        // anyway, but if they didn't, it would be necessary to ensure that
+        // after the first replace non-tag uses of < do not recombine into
+        // tags as in "<<foo>script>alert(1337)</<foo>script>".
+        .replace(soy.esc.$$LT_REGEX_, '&lt;');
+  }
+
+  // Escapes '[' so that we can use [123] below to mark places where tags
+  // have been removed.
+  var html = String(value).replace(/\[/g, '&#91;');
+
+  // Consider all uses of '<' and replace whitelisted tags with markers like
+  // [1] which are indices into a list of approved tag names.
+  // Replace all other uses of < and > with entities.
+  var tags = [];
+  html = html.replace(
+    soy.esc.$$HTML_TAG_REGEX_,
+    function(tok, tagName) {
+      if (tagName) {
+        tagName = tagName.toLowerCase();
+        if (opt_tagWhitelist.hasOwnProperty(tagName) &&
+            opt_tagWhitelist[tagName]) {
+          var start = tok.charAt(1) === '/' ? '</' : '<';
+          var index = tags.length;
+          tags[index] = start + tagName + '>';
+          return '[' + index + ']';
+        }
+      }
+      return '';
+    });
+
+  // Escape HTML special characters. Now there are no '<' in html that could
+  // start a tag.
+  html = soy.esc.$$normalizeHtmlHelper(html);
+
+  var finalCloseTags = soy.$$balanceTags_(tags);
+
+  // Now html contains no tags or less-than characters that could become
+  // part of a tag via a replacement operation and tags only contains
+  // approved tags.
+  // Reinsert the white-listed tags.
+  html = html.replace(
+       /\[(\d+)\]/g, function(_, index) { return tags[index]; });
+
+  // Close any still open tags.
+  // This prevents unclosed formatting elements like <ol> and <table> from
+  // breaking the layout of containing HTML.
+  return html + finalCloseTags;
+};
+
+
+/**
+ * Throw out any close tags that don't correspond to start tags.
+ * If {@code <table>} is used for formatting, embedded HTML shouldn't be able
+ * to use a mismatched {@code </table>} to break page layout.
+ *
+ * @param {Array.<string>} tags an array of tags that will be modified in place
+ *    include tags, the empty string, or concatenations of empty tags.
+ * @return {string} zero or more closed tags that close all elements that are
+ *    opened in tags but not closed.
+ * @private
  */
-soy.$$stripHtmlTags = function(value) {
-  return String(value).replace(soy.esc.$$HTML_TAG_REGEX_, '');
+soy.$$balanceTags_ = function(tags) {
+  var open = [];
+  for (var i = 0, n = tags.length; i < n; ++i) {
+    var tag = tags[i];
+    if (tag.charAt(1) === '/') {
+      var openTagIndex = open.length - 1;
+      // NOTE: This is essentially lastIndexOf, but it's not supported in IE.
+      while (openTagIndex >= 0 && open[openTagIndex] != tag) {
+        openTagIndex--;
+      }
+      if (openTagIndex < 0) {
+        tags[i] = '';  // Drop close tag.
+      } else {
+        tags[i] = open.slice(openTagIndex).reverse().join('');
+        open.length = openTagIndex;
+      }
+    } else if (!soy.$$HTML5_VOID_ELEMENTS_.test(tag)) {
+      open.push('</' + tag.substring(1));
+    }
+  }
+  return open.reverse().join('');
 };
 
 
 /**
  * Escapes HTML special characters in an HTML attribute value.
  *
- * @param {*} value The HTML to be escaped.  May not be a string, but the
+ * @param {*} value The HTML to be escaped. May not be a string, but the
  *     value will be coerced to a string.
  * @return {string} An escaped version of value.
  */
 soy.$$escapeHtmlAttribute = function(value) {
-  if (typeof value === 'object' && value &&
-      value.contentKind === soydata.SanitizedContentKind.HTML) {
+  // NOTE: We don't accept ATTRIBUTES here because ATTRIBUTES is actually not
+  // the attribute value context, but instead k/v pairs.
+  if (soydata.isContentKind(value, soydata.SanitizedContentKind.HTML)) {
+    // NOTE: After removing tags, we also escape quotes ("normalize") so that
+    // the HTML can be embedded in attribute context.
+    goog.asserts.assert(value.constructor === soydata.SanitizedHtml);
     return soy.esc.$$normalizeHtmlHelper(soy.$$stripHtmlTags(value.content));
   }
   return soy.esc.$$escapeHtmlHelper(value);
@@ -1260,13 +2171,13 @@ soy.$$escapeHtmlAttribute = function(value) {
  * Escapes HTML special characters in a string including space and other
  * characters that can end an unquoted HTML attribute value.
  *
- * @param {*} value The HTML to be escaped.  May not be a string, but the
+ * @param {*} value The HTML to be escaped. May not be a string, but the
  *     value will be coerced to a string.
  * @return {string} An escaped version of value.
  */
 soy.$$escapeHtmlAttributeNospace = function(value) {
-  if (typeof value === 'object' && value &&
-      value.contentKind === soydata.SanitizedContentKind.HTML) {
+  if (soydata.isContentKind(value, soydata.SanitizedContentKind.HTML)) {
+    goog.asserts.assert(value.constructor === soydata.SanitizedHtml);
     return soy.esc.$$normalizeHtmlNospaceHelper(
         soy.$$stripHtmlTags(value.content));
   }
@@ -1277,29 +2188,46 @@ soy.$$escapeHtmlAttributeNospace = function(value) {
 /**
  * Filters out strings that cannot be a substring of a valid HTML attribute.
  *
- * @param {*} value The value to escape.  May not be a string, but the value
+ * Note the input is expected to be key=value pairs.
+ *
+ * @param {*} value The value to escape. May not be a string, but the value
  *     will be coerced to a string.
  * @return {string} A valid HTML attribute name part or name/value pair.
  *     {@code "zSoyz"} if the input is invalid.
  */
-soy.$$filterHtmlAttribute = function(value) {
-  if (typeof value === 'object' && value &&
-      value.contentKind === soydata.SanitizedContentKind.HTML_ATTRIBUTE) {
-    return value.content.replace(/=([^"']*)$/, '="$1"');
+soy.$$filterHtmlAttributes = function(value) {
+  // NOTE: Explicitly no support for SanitizedContentKind.HTML, since that is
+  // meaningless in this context, which is generally *between* html attributes.
+  if (soydata.isContentKind(value, soydata.SanitizedContentKind.ATTRIBUTES)) {
+    goog.asserts.assert(value.constructor === soydata.SanitizedHtmlAttribute);
+    // Add a space at the end to ensure this won't get merged into following
+    // attributes, unless the interpretation is unambiguous (ending with quotes
+    // or a space).
+    return value.content.replace(/([^"'\s])$/, '$1 ');
   }
-  return soy.esc.$$filterHtmlAttributeHelper(value);
+  // TODO: Dynamically inserting attributes that aren't marked as trusted is
+  // probably unnecessary.  Any filtering done here will either be inadequate
+  // for security or not flexible enough.  Having clients use kind="attributes"
+  // in parameters seems like a wiser idea.
+  return soy.esc.$$filterHtmlAttributesHelper(value);
 };
 
 
 /**
  * Filters out strings that cannot be a substring of a valid HTML element name.
  *
- * @param {*} value The value to escape.  May not be a string, but the value
+ * @param {*} value The value to escape. May not be a string, but the value
  *     will be coerced to a string.
  * @return {string} A valid HTML element name part.
  *     {@code "zSoyz"} if the input is invalid.
  */
 soy.$$filterHtmlElementName = function(value) {
+  // NOTE: We don't accept any SanitizedContent here. HTML indicates valid
+  // PCDATA, not tag names. A sloppy developer shouldn't be able to cause an
+  // exploit:
+  // ... {let userInput}script src=http://evil.com/evil.js{/let} ...
+  // ... {param tagName kind="html"}{$userInput}{/param} ...
+  // ... <{$tagName}>Hello World</{$tagName}>
   return soy.esc.$$filterHtmlElementNameHelper(value);
 };
 
@@ -1308,7 +2236,7 @@ soy.$$filterHtmlElementName = function(value) {
  * Escapes characters in the value to make it valid content for a JS string
  * literal.
  *
- * @param {*} value The value to escape.  May not be a string, but the value
+ * @param {*} value The value to escape. May not be a string, but the value
  *     will be coerced to a string.
  * @return {string} An escaped version of value.
  * @deprecated
@@ -1322,13 +2250,15 @@ soy.$$escapeJs = function(value) {
  * Escapes characters in the value to make it valid content for a JS string
  * literal.
  *
- * @param {*} value The value to escape.  May not be a string, but the value
+ * @param {*} value The value to escape. May not be a string, but the value
  *     will be coerced to a string.
  * @return {string} An escaped version of value.
  */
 soy.$$escapeJsString = function(value) {
-  if (typeof value === 'object' &&
-      value.contentKind === soydata.SanitizedContentKind.JS_STR_CHARS) {
+  if (soydata.isContentKind(value, soydata.SanitizedContentKind.JS_STR_CHARS)) {
+    // TODO: It might still be worthwhile to normalize it to remove
+    // unescaped quotes, null, etc: replace(/(?:^|[^\])['"]/g, '\\$
+    goog.asserts.assert(value.constructor === soydata.SanitizedJsStrChars);
     return value.content;
   }
   return soy.esc.$$escapeJsStringHelper(value);
@@ -1338,7 +2268,7 @@ soy.$$escapeJsString = function(value) {
 /**
  * Encodes a value as a JavaScript literal.
  *
- * @param {*} value The value to escape.  May not be a string, but the value
+ * @param {*} value The value to escape. May not be a string, but the value
  *     will be coerced to a string.
  * @return {string} A JavaScript code representation of the input.
  */
@@ -1353,6 +2283,10 @@ soy.$$escapeJsValue = function(value) {
     // distinct undefined value.
     return ' null ';
   }
+  if (soydata.isContentKind(value, soydata.SanitizedContentKind.JS)) {
+    goog.asserts.assert(value.constructor === soydata.SanitizedJs);
+    return value.content;
+  }
   switch (typeof value) {
     case 'boolean': case 'number':
       return ' ' + value + ' ';
@@ -1366,7 +2300,7 @@ soy.$$escapeJsValue = function(value) {
  * Escapes characters in the string to make it valid content for a JS regular
  * expression literal.
  *
- * @param {*} value The value to escape.  May not be a string, but the value
+ * @param {*} value The value to escape. May not be a string, but the value
  *     will be coerced to a string.
  * @return {string} An escaped version of value.
  */
@@ -1400,13 +2334,13 @@ soy.$$pctEncode_ = function(ch) {
 /**
  * Escapes a string so that it can be safely included in a URI.
  *
- * @param {*} value The value to escape.  May not be a string, but the value
+ * @param {*} value The value to escape. May not be a string, but the value
  *     will be coerced to a string.
  * @return {string} An escaped version of value.
  */
 soy.$$escapeUri = function(value) {
-  if (typeof value === 'object' &&
-      value.contentKind === soydata.SanitizedContentKind.URI) {
+  if (soydata.isContentKind(value, soydata.SanitizedContentKind.URI)) {
+    goog.asserts.assert(value.constructor === soydata.SanitizedUri);
     return soy.$$normalizeUri(value);
   }
   // Apostophes and parentheses are not matched by encodeURIComponent.
@@ -1425,7 +2359,7 @@ soy.$$escapeUri = function(value) {
 /**
  * Removes rough edges from a URI by escaping any raw HTML/JS string delimiters.
  *
- * @param {*} value The value to escape.  May not be a string, but the value
+ * @param {*} value The value to escape. May not be a string, but the value
  *     will be coerced to a string.
  * @return {string} An escaped version of value.
  */
@@ -1438,19 +2372,37 @@ soy.$$normalizeUri = function(value) {
  * Vets a URI's protocol and removes rough edges from a URI by escaping
  * any raw HTML/JS string delimiters.
  *
- * @param {*} value The value to escape.  May not be a string, but the value
+ * @param {*} value The value to escape. May not be a string, but the value
  *     will be coerced to a string.
  * @return {string} An escaped version of value.
  */
 soy.$$filterNormalizeUri = function(value) {
+  if (soydata.isContentKind(value, soydata.SanitizedContentKind.URI)) {
+    goog.asserts.assert(value.constructor === soydata.SanitizedUri);
+    return soy.$$normalizeUri(value);
+  }
   return soy.esc.$$filterNormalizeUriHelper(value);
 };
 
 
+/**
+ * Allows only data-protocol image URI's.
+ *
+ * @param {*} value The value to process. May not be a string, but the value
+ *     will be coerced to a string.
+ * @return {!soydata.SanitizedUri} An escaped version of value.
+ */
+soy.$$filterImageDataUri = function(value) {
+  // NOTE: Even if it's a SanitizedUri, we will still filter it.
+  return soydata.VERY_UNSAFE.ordainSanitizedUri(
+      soy.esc.$$filterImageDataUriHelper(value));
+};
+
+
 /**
  * Escapes a string so it can safely be included inside a quoted CSS string.
  *
- * @param {*} value The value to escape.  May not be a string, but the value
+ * @param {*} value The value to escape. May not be a string, but the value
  *     will be coerced to a string.
  * @return {string} An escaped version of value.
  */
@@ -1462,11 +2414,15 @@ soy.$$escapeCssString = function(value) {
 /**
  * Encodes a value as a CSS identifier part, keyword, or quantity.
  *
- * @param {*} value The value to escape.  May not be a string, but the value
+ * @param {*} value The value to escape. May not be a string, but the value
  *     will be coerced to a string.
  * @return {string} A safe CSS identifier part, keyword, or quanitity.
  */
 soy.$$filterCssValue = function(value) {
+  if (soydata.isContentKind(value, soydata.SanitizedContentKind.CSS)) {
+    goog.asserts.assert(value.constructor === soydata.SanitizedCss);
+    return value.content;
+  }
   // Uses == to intentionally match null and undefined for Java compatibility.
   if (value == null) {
     return '';
@@ -1475,17 +2431,47 @@ soy.$$filterCssValue = function(value) {
 };
 
 
+/**
+ * Sanity-checks noAutoescape input for explicitly tainted content.
+ *
+ * SanitizedContentKind.TEXT is used to explicitly mark input that was never
+ * meant to be used unescaped.
+ *
+ * @param {*} value The value to filter.
+ * @return {*} The value, that we dearly hope will not cause an attack.
+ */
+soy.$$filterNoAutoescape = function(value) {
+  if (soydata.isContentKind(value, soydata.SanitizedContentKind.TEXT)) {
+    // Fail in development mode.
+    goog.asserts.fail(
+        'Tainted SanitizedContentKind.TEXT for |noAutoescape: `%s`',
+        [value.content]);
+    // Return innocuous data in production.
+    return 'zSoyz';
+  }
+
+  return value;
+};
+
+
 // -----------------------------------------------------------------------------
 // Basic directives/functions.
 
 
 /**
  * Converts \r\n, \r, and \n to <br>s
- * @param {*} str The string in which to convert newlines.
- * @return {string} A copy of {@code str} with converted newlines.
- */
-soy.$$changeNewlineToBr = function(str) {
-  return goog.string.newLineToBr(String(str), false);
+ * @param {*} value The string in which to convert newlines.
+ * @return {string|!soydata.SanitizedHtml} A copy of {@code value} with
+ *     converted newlines. If {@code value} is SanitizedHtml, the return value
+ *     is also SanitizedHtml, of the same known directionality.
+ */
+soy.$$changeNewlineToBr = function(value) {
+  var result = goog.string.newLineToBr(String(value), false);
+  if (soydata.isContentKind(value, soydata.SanitizedContentKind.HTML)) {
+    return soydata.VERY_UNSAFE.ordainSanitizedHtml(
+        result, soydata.getContentDir(value));
+  }
+  return result;
 };
 
 
@@ -1495,14 +2481,22 @@ soy.$$changeNewlineToBr = function(str) {
  * HTML tags or entities. Entites count towards the character count; HTML tags
  * do not.
  *
- * @param {*} str The HTML string to insert word breaks into. Can be other
+ * @param {*} value The HTML string to insert word breaks into. Can be other
  *     types, but the value will be coerced to a string.
  * @param {number} maxCharsBetweenWordBreaks Maximum number of non-space
  *     characters to allow before adding a word break.
- * @return {string} The string including word breaks.
- */
-soy.$$insertWordBreaks = function(str, maxCharsBetweenWordBreaks) {
-  return goog.format.insertWordBreaks(String(str), maxCharsBetweenWordBreaks);
+ * @return {string|!soydata.SanitizedHtml} The string including word
+ *     breaks. If {@code value} is SanitizedHtml, the return value
+ *     is also SanitizedHtml, of the same known directionality.
+ */
+soy.$$insertWordBreaks = function(value, maxCharsBetweenWordBreaks) {
+  var result = goog.format.insertWordBreaks(
+      String(value), maxCharsBetweenWordBreaks);
+  if (soydata.isContentKind(value, soydata.SanitizedContentKind.HTML)) {
+    return soydata.VERY_UNSAFE.ordainSanitizedHtml(
+        result, soydata.getContentDir(value));
+  }
+  return result;
 };
 
 
@@ -1604,37 +2598,53 @@ soy.$$getBidiFormatterInstance_ = function(bidiGlobalDir) {
  * Estimate the overall directionality of text. If opt_isHtml, makes sure to
  * ignore the LTR nature of the mark-up and escapes in text, making the logic
  * suitable for HTML and HTML-escaped text.
- * @param {string} text The text whose directionality is to be estimated.
+ * If text has a goog.i18n.bidi.Dir-valued contentDir, this is used instead of
+ * estimating the directionality.
+ *
+ * @param {*} text The content whose directionality is to be estimated.
  * @param {boolean=} opt_isHtml Whether text is HTML/HTML-escaped.
  *     Default: false.
  * @return {number} 1 if text is LTR, -1 if it is RTL, and 0 if it is neutral.
  */
 soy.$$bidiTextDir = function(text, opt_isHtml) {
-  if (!text) {
-    return 0;
+  var contentDir = soydata.getContentDir(text);
+  if (contentDir != null) {
+    return contentDir;
   }
-  return goog.i18n.bidi.detectRtlDirectionality(text, opt_isHtml) ? -1 : 1;
+  var isHtml = opt_isHtml ||
+      soydata.isContentKind(text, soydata.SanitizedContentKind.HTML);
+  return goog.i18n.bidi.estimateDirection(text + '', isHtml);
 };
 
 
 /**
- * Returns "dir=ltr" or "dir=rtl", depending on text's estimated
+ * Returns 'dir="ltr"' or 'dir="rtl"', depending on text's estimated
  * directionality, if it is not the same as bidiGlobalDir.
  * Otherwise, returns the empty string.
  * If opt_isHtml, makes sure to ignore the LTR nature of the mark-up and escapes
  * in text, making the logic suitable for HTML and HTML-escaped text.
+ * If text has a goog.i18n.bidi.Dir-valued contentDir, this is used instead of
+ * estimating the directionality.
+ *
  * @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
  *     if rtl, 0 if unknown.
- * @param {string} text The text whose directionality is to be estimated.
+ * @param {*} text The content whose directionality is to be estimated.
  * @param {boolean=} opt_isHtml Whether text is HTML/HTML-escaped.
  *     Default: false.
- * @return {soydata.SanitizedHtmlAttribute} "dir=rtl" for RTL text in non-RTL
- *     context; "dir=ltr" for LTR text in non-LTR context;
+ * @return {soydata.SanitizedHtmlAttribute} 'dir="rtl"' for RTL text in non-RTL
+ *     context; 'dir="ltr"' for LTR text in non-LTR context;
  *     else, the empty string.
  */
 soy.$$bidiDirAttr = function(bidiGlobalDir, text, opt_isHtml) {
-  return new soydata.SanitizedHtmlAttribute(
-      soy.$$getBidiFormatterInstance_(bidiGlobalDir).dirAttr(text, opt_isHtml));
+  var formatter = soy.$$getBidiFormatterInstance_(bidiGlobalDir);
+  var contentDir = soydata.getContentDir(text);
+  if (contentDir == null) {
+    var isHtml = opt_isHtml ||
+        soydata.isContentKind(text, soydata.SanitizedContentKind.HTML);
+    contentDir = goog.i18n.bidi.estimateDirection(text + '', isHtml);
+  }
+  return soydata.VERY_UNSAFE.ordainSanitizedHtmlAttribute(
+      formatter.knownDirAttr(contentDir));
 };
 
 
@@ -1644,9 +2654,12 @@ soy.$$bidiDirAttr = function(bidiGlobalDir, text, opt_isHtml) {
  * bidiGlobalDir. Otherwise returns the empty string.
  * If opt_isHtml, makes sure to ignore the LTR nature of the mark-up and escapes
  * in text, making the logic suitable for HTML and HTML-escaped text.
+ * If text has a goog.i18n.bidi.Dir-valued contentDir, this is used instead of
+ * estimating the directionality.
+ *
  * @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
  *     if rtl, 0 if unknown.
- * @param {string} text The text whose directionality is to be estimated.
+ * @param {*} text The content whose directionality is to be estimated.
  * @param {boolean=} opt_isHtml Whether text is HTML/HTML-escaped.
  *     Default: false.
  * @return {string} A Unicode bidi mark matching bidiGlobalDir, or the empty
@@ -1655,44 +2668,112 @@ soy.$$bidiDirAttr = function(bidiGlobalDir, text, opt_isHtml) {
  */
 soy.$$bidiMarkAfter = function(bidiGlobalDir, text, opt_isHtml) {
   var formatter = soy.$$getBidiFormatterInstance_(bidiGlobalDir);
-  return formatter.markAfter(text, opt_isHtml);
+  var isHtml = opt_isHtml ||
+      soydata.isContentKind(text, soydata.SanitizedContentKind.HTML);
+  return formatter.markAfterKnownDir(soydata.getContentDir(text), text + '',
+      isHtml);
 };
 
 
 /**
- * Returns str wrapped in a <span dir=ltr|rtl> according to its directionality -
- * but only if that is neither neutral nor the same as the global context.
- * Otherwise, returns str unchanged.
- * Always treats str as HTML/HTML-escaped, i.e. ignores mark-up and escapes when
- * estimating str's directionality.
+ * Returns text wrapped in a <span dir="ltr|rtl"> according to its
+ * directionality - but only if that is neither neutral nor the same as the
+ * global context. Otherwise, returns text unchanged.
+ * Always treats text as HTML/HTML-escaped, i.e. ignores mark-up and escapes
+ * when estimating text's directionality.
+ * If text has a goog.i18n.bidi.Dir-valued contentDir, this is used instead of
+ * estimating the directionality.
+ *
  * @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
  *     if rtl, 0 if unknown.
- * @param {*} str The string to be wrapped. Can be other types, but the value
+ * @param {*} text The string to be wrapped. Can be other types, but the value
  *     will be coerced to a string.
- * @return {string} The wrapped string.
+ * @return {!goog.soy.data.SanitizedContent|string} The wrapped text.
  */
-soy.$$bidiSpanWrap = function(bidiGlobalDir, str) {
+soy.$$bidiSpanWrap = function(bidiGlobalDir, text) {
   var formatter = soy.$$getBidiFormatterInstance_(bidiGlobalDir);
-  return formatter.spanWrap(str + '', true);
+
+  // We always treat the value as HTML, because span-wrapping is only useful
+  // when its output will be treated as HTML (without escaping), and because
+  // |bidiSpanWrap is not itself specified to do HTML escaping in Soy. (Both
+  // explicit and automatic HTML escaping, if any, is done before calling
+  // |bidiSpanWrap because the BidiSpanWrapDirective Java class implements
+  // SanitizedContentOperator, but this does not mean that the input has to be
+  // HTML SanitizedContent. In legacy usage, a string that is not
+  // SanitizedContent is often printed in an autoescape="false" template or by
+  // a print with a |noAutoescape, in which case our input is just SoyData.) If
+  // the output will be treated as HTML, the input had better be safe
+  // HTML/HTML-escaped (even if it isn't HTML SanitizedData), or we have an XSS
+  // opportunity and a much bigger problem than bidi garbling.
+  var wrappedText = formatter.spanWrapWithKnownDir(
+      soydata.getContentDir(text), text + '', true /* opt_isHtml */);
+
+  // Like other directives whose Java class implements SanitizedContentOperator,
+  // |bidiSpanWrap is called after the escaping (if any) has already been done,
+  // and thus there is no need for it to produce actual SanitizedContent.
+  return wrappedText;
 };
 
 
 /**
- * Returns str wrapped in Unicode BiDi formatting characters according to its
+ * Returns text wrapped in Unicode BiDi formatting characters according to its
  * directionality, i.e. either LRE or RLE at the beginning and PDF at the end -
- * but only if str's directionality is neither neutral nor the same as the
- * global context. Otherwise, returns str unchanged.
- * Always treats str as HTML/HTML-escaped, i.e. ignores mark-up and escapes when
- * estimating str's directionality.
+ * but only if text's directionality is neither neutral nor the same as the
+ * global context. Otherwise, returns text unchanged.
+ * Only treats soydata.SanitizedHtml as HTML/HTML-escaped, i.e. ignores mark-up
+ * and escapes when estimating text's directionality.
+ * If text has a goog.i18n.bidi.Dir-valued contentDir, this is used instead of
+ * estimating the directionality.
+ *
  * @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
  *     if rtl, 0 if unknown.
- * @param {*} str The string to be wrapped. Can be other types, but the value
+ * @param {*} text The string to be wrapped. Can be other types, but the value
  *     will be coerced to a string.
- * @return {string} The wrapped string.
+ * @return {!goog.soy.data.SanitizedContent|string} The wrapped string.
  */
-soy.$$bidiUnicodeWrap = function(bidiGlobalDir, str) {
+soy.$$bidiUnicodeWrap = function(bidiGlobalDir, text) {
   var formatter = soy.$$getBidiFormatterInstance_(bidiGlobalDir);
-  return formatter.unicodeWrap(str + '', true);
+
+  // We treat the value as HTML if and only if it says it's HTML, even though in
+  // legacy usage, we sometimes have an HTML string (not SanitizedContent) that
+  // is passed to an autoescape="false" template or a {print $foo|noAutoescape},
+  // with the output going into an HTML context without escaping. We simply have
+  // no way of knowing if this is what is happening when we get
+  // non-SanitizedContent input, and most of the time it isn't.
+  var isHtml = soydata.isContentKind(text, soydata.SanitizedContentKind.HTML);
+  var wrappedText = formatter.unicodeWrapWithKnownDir(
+      soydata.getContentDir(text), text + '', isHtml);
+
+  // Bidi-wrapping a value converts it to the context directionality. Since it
+  // does not cost us anything, we will indicate this known direction in the
+  // output SanitizedContent, even though the intended consumer of that
+  // information - a bidi wrapping directive - has already been run.
+  var wrappedTextDir = formatter.getContextDir();
+
+  // Unicode-wrapping UnsanitizedText gives UnsanitizedText.
+  // Unicode-wrapping safe HTML or JS string data gives valid, safe HTML or JS
+  // string data.
+  // ATTENTION: Do these need to be ...ForInternalBlocks()?
+  if (soydata.isContentKind(text, soydata.SanitizedContentKind.TEXT)) {
+    return new soydata.UnsanitizedText(wrappedText, wrappedTextDir);
+  }
+  if (isHtml) {
+    return soydata.VERY_UNSAFE.ordainSanitizedHtml(wrappedText, wrappedTextDir);
+  }
+  if (soydata.isContentKind(text, soydata.SanitizedContentKind.JS_STR_CHARS)) {
+    return soydata.VERY_UNSAFE.ordainSanitizedJsStrChars(
+        wrappedText, wrappedTextDir);
+  }
+
+  // Unicode-wrapping does not conform to the syntax of the other types of
+  // content. For lack of anything better to do, we we do not declare a content
+  // kind at all by falling through to the non-SanitizedContent case below.
+  // TODO(user): Consider throwing a runtime error on receipt of
+  // SanitizedContent other than TEXT, HTML, or JS_STR_CHARS.
+
+  // The input was not SanitizedContent, so our output isn't SanitizedContent
+  // either.
+  return wrappedText;
 };
 
 
@@ -1702,6 +2783,10 @@ soy.$$bidiUnicodeWrap = function(bidiGlobalDir, str) {
 
 
 
+
+
+
+
 // START GENERATED CODE FOR ESCAPERS.
 
 /**
@@ -1712,7 +2797,7 @@ soy.esc.$$escapeUriHelper = function(v) {
 };
 
 /**
- * Maps charcters to the escaped versions for the named escape directives.
+ * Maps characters to the escaped versions for the named escape directives.
  * @type {Object.<string, string>}
  * @private
  */
@@ -1740,7 +2825,7 @@ soy.esc.$$ESCAPE_MAP_FOR_ESCAPE_HTML__AND__NORMALIZE_HTML__AND__ESCAPE_HTML_NOSP
 };
 
 /**
- * A function that can be used with String.replace..
+ * A function that can be used with String.replace.
  * @param {string} ch A single character matched by a compatible matcher.
  * @return {string} A token in the output language.
  * @private
@@ -1750,7 +2835,7 @@ soy.esc.$$REPLACER_FOR_ESCAPE_HTML__AND__NORMALIZE_HTML__AND__ESCAPE_HTML_NOSPAC
 };
 
 /**
- * Maps charcters to the escaped versions for the named escape directives.
+ * Maps characters to the escaped versions for the named escape directives.
  * @type {Object.<string, string>}
  * @private
  */
@@ -1792,7 +2877,7 @@ soy.esc.$$ESCAPE_MAP_FOR_ESCAPE_JS_STRING__AND__ESCAPE_JS_REGEX_ = {
 };
 
 /**
- * A function that can be used with String.replace..
+ * A function that can be used with String.replace.
  * @param {string} ch A single character matched by a compatible matcher.
  * @return {string} A token in the output language.
  * @private
@@ -1802,7 +2887,7 @@ soy.esc.$$REPLACER_FOR_ESCAPE_JS_STRING__AND__ESCAPE_JS_REGEX_ = function(ch) {
 };
 
 /**
- * Maps charcters to the escaped versions for the named escape directives.
+ * Maps characters to the escaped versions for the named escape directives.
  * @type {Object.<string, string>}
  * @private
  */
@@ -1837,7 +2922,7 @@ soy.esc.$$ESCAPE_MAP_FOR_ESCAPE_CSS_STRING_ = {
 };
 
 /**
- * A function that can be used with String.replace..
+ * A function that can be used with String.replace.
  * @param {string} ch A single character matched by a compatible matcher.
  * @return {string} A token in the output language.
  * @private
@@ -1847,7 +2932,7 @@ soy.esc.$$REPLACER_FOR_ESCAPE_CSS_STRING_ = function(ch) {
 };
 
 /**
- * Maps charcters to the escaped versions for the named escape directives.
+ * Maps characters to the escaped versions for the named escape directives.
  * @type {Object.<string, string>}
  * @private
  */
@@ -1920,7 +3005,7 @@ soy.esc.$$ESCAPE_MAP_FOR_NORMALIZE_URI__AND__FILTER_NORMALIZE_URI_ = {
 };
 
 /**
- * A function that can be used with String.replace..
+ * A function that can be used with String.replace.
  * @param {string} ch A single character matched by a compatible matcher.
  * @return {string} A token in the output language.
  * @private
@@ -2004,7 +3089,14 @@ soy.esc.$$FILTER_FOR_FILTER_NORMALIZE_URI_ = /^(?:(?:https?|mailto):|[^&:\/?#]*(
  * @type RegExp
  * @private
  */
-soy.esc.$$FILTER_FOR_FILTER_HTML_ATTRIBUTE_ = /^(?!style|on|action|archive|background|cite|classid|codebase|data|dsync|href|longdesc|src|usemap)(?:[a-z0-9_$:-]*)$/i;
+soy.esc.$$FILTER_FOR_FILTER_IMAGE_DATA_URI_ = /^data:image\/(?:bmp|gif|jpe?g|png|tiff|webp);base64,[a-z0-9+\/]+=*$/i;
+
+/**
+ * A pattern that vets values produced by the named directives.
+ * @type RegExp
+ * @private
+ */
+soy.esc.$$FILTER_FOR_FILTER_HTML_ATTRIBUTES_ = /^(?!style|on|action|archive|background|cite|classid|codebase|data|dsync|href|longdesc|src|usemap)(?:[a-z0-9_$:-]*)$/i;
 
 /**
  * A pattern that vets values produced by the named directives.
@@ -2130,7 +3222,7 @@ soy.esc.$$normalizeUriHelper = function(value) {
 soy.esc.$$filterNormalizeUriHelper = function(value) {
   var str = String(value);
   if (!soy.esc.$$FILTER_FOR_FILTER_NORMALIZE_URI_.test(str)) {
-    return 'zSoyz';
+    return '#zSoyz';
   }
   return str.replace(
       soy.esc.$$MATCHER_FOR_NORMALIZE_URI__AND__FILTER_NORMALIZE_URI_,
@@ -2138,13 +3230,26 @@ soy.esc.$$filterNormalizeUriHelper = function(value) {
 };
 
 /**
- * A helper for the Soy directive |filterHtmlAttribute
+ * A helper for the Soy directive |filterImageDataUri
+ * @param {*} value Can be of any type but will be coerced to a string.
+ * @return {string} The escaped text.
+ */
+soy.esc.$$filterImageDataUriHelper = function(value) {
+  var str = String(value);
+  if (!soy.esc.$$FILTER_FOR_FILTER_IMAGE_DATA_URI_.test(str)) {
+    return 'data:image/gif;base64,zSoyz';
+  }
+  return str;
+};
+
+/**
+ * A helper for the Soy directive |filterHtmlAttributes
  * @param {*} value Can be of any type but will be coerced to a string.
  * @return {string} The escaped text.
  */
-soy.esc.$$filterHtmlAttributeHelper = function(value) {
+soy.esc.$$filterHtmlAttributesHelper = function(value) {
   var str = String(value);
-  if (!soy.esc.$$FILTER_FOR_FILTER_HTML_ATTRIBUTE_.test(str)) {
+  if (!soy.esc.$$FILTER_FOR_FILTER_HTML_ATTRIBUTES_.test(str)) {
     return 'zSoyz';
   }
   return str;
@@ -2165,10 +3270,29 @@ soy.esc.$$filterHtmlElementNameHelper = function(value) {
 
 /**
  * Matches all tags, HTML comments, and DOCTYPEs in tag soup HTML.
+ * By removing these, and replacing any '<' or '>' characters with
+ * entities we guarantee that the result can be embedded into a
+ * an attribute without introducing a tag boundary.
+ *
+ * @type {RegExp}
+ * @private
+ */
+soy.esc.$$HTML_TAG_REGEX_ = /<(?:!|\/?([a-zA-Z][a-zA-Z0-9:\-]*))(?:[^>'"]|"[^"]*"|'[^']*')*>/g;
+
+/**
+ * Matches all occurrences of '<'.
  *
  * @type {RegExp}
  * @private
  */
-soy.esc.$$HTML_TAG_REGEX_ = /<(?:!|\/?[a-zA-Z])(?:[^>'"]|"[^"]*"|'[^']*')*>/g;
+soy.esc.$$LT_REGEX_ = /</g;
+
+/**
+ * Maps lower-case names of innocuous tags to 1.
+ *
+ * @type {Object.<string,number>}
+ * @private
+ */
+soy.esc.$$SAFE_TAG_WHITELIST_ = {'b': 1, 'br': 1, 'em': 1, 'i': 1, 's': 1, 'sub': 1, 'sup': 1, 'u': 1};
 
 // END GENERATED CODE