closure 1.4.3 → 1.5.0

data/closure-templates/soyutils_usegoog.js

@@ -30,9 +30,10 @@
  * 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
  */
 
 goog.provide('soy');
@@ -41,8 +42,10 @@ goog.provide('soy.esc');
 goog.provide('soydata');
 goog.provide('soydata.SanitizedHtml');
 goog.provide('soydata.SanitizedHtmlAttribute');
+goog.provide('soydata.SanitizedJs');
 goog.provide('soydata.SanitizedJsStrChars');
 goog.provide('soydata.SanitizedUri');
+goog.provide('soydata.VERY_UNSAFE');
 
 goog.require('goog.asserts');
 goog.require('goog.dom.DomHelper');
@@ -50,6 +53,7 @@ goog.require('goog.format');
 goog.require('goog.i18n.BidiFormatter');
 goog.require('goog.i18n.bidi');
 goog.require('goog.soy');
+goog.require('goog.soy.data.SanitizedContentKind');
 goog.require('goog.string');
 goog.require('goog.string.StringBuffer');
 
@@ -60,7 +64,7 @@ goog.require('goog.string.StringBuffer');
 
 /**
  * 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,
@@ -77,131 +81,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;
+};
 
-  /** A properly encoded portion of a URI. */
-  URI: 2,
 
-  /** An attribute name and value such as {@code dir="ltr"}. */
-  HTML_ATTRIBUTE: 3
+/**
+ * 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;
 };
 
 
 /**
- * A string-like object that carries a content-type.
- * @param {string} content
+ * 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
- * @private
+ * @extends {goog.soy.data.SanitizedContent}
  */
-soydata.SanitizedContent = function(content) {
-  /**
-   * The textual content.
-   * @type {string}
-   */
-  this.content = content;
+soydata.SanitizedHtml = function() {
+  goog.soy.data.SanitizedContent.call(this);  // Throws an exception.
 };
-
-/** @type {soydata.SanitizedContentKind} */
-soydata.SanitizedContent.prototype.contentKind;
+goog.inherits(soydata.SanitizedHtml, goog.soy.data.SanitizedContent);
 
 /** @override */
-soydata.SanitizedContent.prototype.toString = function() {
-  return this.content;
+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.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
- *     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.
+ * 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 {soydata.SanitizedContent}
+ * @extends {goog.soy.data.SanitizedContent}
  */
-soydata.SanitizedHtml = function(content) {
-  soydata.SanitizedContent.call(this, content);
+soydata.SanitizedJs = function() {
+  goog.soy.data.SanitizedContent.call(this);  // Throws an exception.
 };
-goog.inherits(soydata.SanitizedHtml, soydata.SanitizedContent);
+goog.inherits(soydata.SanitizedJs, goog.soy.data.SanitizedContent);
 
 /** @override */
-soydata.SanitizedHtml.prototype.contentKind = soydata.SanitizedContentKind.HTML;
+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}.
- * @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.
+ *
+ * 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 {soydata.SanitizedContent}
+ * @extends {goog.soy.data.SanitizedContent}
  */
-soydata.SanitizedJsStrChars = function(content) {
-  soydata.SanitizedContent.call(this, content);
+soydata.SanitizedJsStrChars = function() {
+  goog.soy.data.SanitizedContent.call(this);  // Throws an exception.
 };
-goog.inherits(soydata.SanitizedJsStrChars, soydata.SanitizedContent);
+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}.
- * @param {string} content A chunk of URI that the caller knows is safe to
- *     emit in a template.
+ *
+ * The content is a URI chunk that the caller knows is safe to emit in a
+ * template. The content direction is LTR.
+ *
  * @constructor
- * @extends {soydata.SanitizedContent}
+ * @extends {goog.soy.data.SanitizedContent}
  */
-soydata.SanitizedUri = function(content) {
-  soydata.SanitizedContent.call(this, content);
+soydata.SanitizedUri = function() {
+  goog.soy.data.SanitizedContent.call(this);  // Throws an exception.
 };
-goog.inherits(soydata.SanitizedUri, soydata.SanitizedContent);
+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.HTML_ATTRIBUTE}.
- * @param {string} content An attribute name and value, such as
- *     {@code 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 {soydata.SanitizedContent}
+ * @extends {goog.soy.data.SanitizedContent}
  */
-soydata.SanitizedHtmlAttribute = function(content) {
-  soydata.SanitizedContent.call(this, content);
+soydata.SanitizedHtmlAttribute = function() {
+  goog.soy.data.SanitizedContent.call(this);  // Throws an exception.
 };
-goog.inherits(soydata.SanitizedHtmlAttribute, soydata.SanitizedContent);
+goog.inherits(soydata.SanitizedHtmlAttribute, goog.soy.data.SanitizedContent);
 
 /** @override */
 soydata.SanitizedHtmlAttribute.prototype.contentKind =
-    soydata.SanitizedContentKind.HTML_ATTRIBUTE;
+    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: ''
+};
+
+
+/**
+ * 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;
+};
+
+
+/**
+ * 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.$$makeSanitizedContentFactoryWithDefaultDirOnly_ = 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} 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) {
+    var result = new InstantiableCtor();
+    result.content = String(content);
+    return result;
+  }
+  return sanitizedContentFactory;
+};
+
+
+// -----------------------------------------------------------------------------
+// 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);
+};
+
+
+/**
+ * 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.
+ * @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.VERY_UNSAFE.ordainSanitizedHtml =
+    soydata.$$makeSanitizedContentFactory_(soydata.SanitizedHtml);
+
+
+/**
+ * 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.VERY_UNSAFE.ordainSanitizedJs =
+    soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_(
+        soydata.SanitizedJs);
+
+
+// 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);
+
+
+/**
+ * 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.
+ * @return {!soydata.SanitizedUri} Sanitized content wrapper that indicates to
+ *     Soy not to escape or filter when printed in URI context.
+ */
+soydata.VERY_UNSAFE.ordainSanitizedUri =
+    soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_(
+        soydata.SanitizedUri);
+
+
+/**
+ * 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"}.
+ * @return {!soydata.SanitizedHtmlAttribute} Sanitized content wrapper that
+ *     indicates to Soy not to escape when printed as an HTML attribute.
+ */
+soydata.VERY_UNSAFE.ordainSanitizedHtmlAttribute =
+    soydata.$$makeSanitizedContentFactoryWithDefaultDirOnly_(
+        soydata.SanitizedHtmlAttribute);
+
+
+/**
+ * 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);
 
 
 // -----------------------------------------------------------------------------
@@ -217,9 +531,11 @@ soydata.SanitizedHtmlAttribute.prototype.contentKind =
  * NOTE: New code should consider using goog.soy.renderElement instead.
  *
  * @param {Element} element The element whose content we are rendering.
- * @param {Function} template The Soy template defining the element's content.
- * @param {Object=} opt_templateData The data for the template.
+ * @param {null|function(ARG_TYPES, null=, Object.<string, *>=):*} template
+ *     The Soy template defining the element's content.
+ * @param {ARG_TYPES} opt_templateData The data for the template.
  * @param {Object=} opt_injectedData The injected data for the template.
+ * @template ARG_TYPES
  */
 soy.renderElement = goog.soy.renderElement;
 
@@ -234,12 +550,14 @@ soy.renderElement = goog.soy.renderElement;
  * NOTE: New code should consider using goog.soy.renderAsFragment
  * instead (note that the arguments are different).
  *
- * @param {Function} template The Soy template defining the element's content.
- * @param {Object=} opt_templateData The data for the template.
+ * @param {null|function(ARG_TYPES, null=, Object.<string, *>=):*} template
+ *     The Soy template defining the element's content.
+ * @param {ARG_TYPES} 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.
  * @return {!Node} The resulting node or document fragment.
+ * @template ARG_TYPES
  */
 soy.renderAsFragment = function(
     template, opt_templateData, opt_document, opt_injectedData) {
@@ -257,13 +575,15 @@ soy.renderAsFragment = function(
  * NOTE: New code should consider using goog.soy.renderAsElement
  * instead (note that the arguments are different).
  *
- * @param {Function} template The Soy template defining the element's content.
- * @param {Object=} opt_templateData The data for the template.
+ * @param {null|function(ARG_TYPES, null=, Object.<string, *>=):*} template
+ *     The Soy template defining the element's content.
+ * @param {ARG_TYPES} 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.
  * @return {!Element} Rendered template contents, wrapped in a parent DIV
  *     element if necessary.
+ * @template ARG_TYPES
  */
 soy.renderAsElement = function(
     template, opt_templateData, opt_document, opt_injectedData) {
@@ -278,39 +598,61 @@ 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;
 };
 
 
 /**
  * Gets the keys in a map as an array. There are no guarantees on the order.
  * @param {Object} map The map to get the keys of.
- * @return {Array.<string>} The array of keys in the given map.
+ * @return {!Array.<string>} The array of keys in the given map.
  */
 soy.$$getMapKeys = function(map) {
   var mapKeys = [];
@@ -339,13 +681,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
@@ -353,7 +695,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
  */
@@ -361,17 +703,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.
@@ -380,8 +726,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.
   }
@@ -390,16 +736,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} delTemplateVariant The delegate template variant (can be
+ *     empty string).
+ * @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").');
+  }
 };
 
 
@@ -418,26 +786,222 @@ 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.
+   * 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.
+   * 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));
 };
 
 
@@ -446,7 +1010,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>}.
@@ -455,13 +1019,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);
@@ -469,29 +1033,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);
@@ -502,13 +1170,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));
   }
@@ -519,29 +1187,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);
 };
 
@@ -550,7 +1235,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
@@ -564,13 +1249,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);
@@ -580,7 +1267,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.
  */
@@ -595,6 +1282,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 + ' ';
@@ -608,7 +1299,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.
  */
@@ -642,13 +1333,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.
@@ -667,7 +1358,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.
  */
@@ -680,19 +1371,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.
  */
@@ -704,11 +1413,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 '';
@@ -717,17 +1430,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;
 };
 
 
@@ -737,14 +1480,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;
 };
 
 
@@ -832,7 +1583,7 @@ soy.$$bidiFormatterCache_ = {};
  * Returns cached bidi formatter for bidiGlobalDir, or creates a new one.
  * @param {number} bidiGlobalDir The global directionality context: 1 if ltr, -1
  *     if rtl, 0 if unknown.
- * @return {goog.i18n.BidiFormatter} A formatter for bidiGlobalDir.
+ * @return {!goog.i18n.BidiFormatter} A formatter for bidiGlobalDir.
  * @private
  */
 soy.$$getBidiFormatterInstance_ = function(bidiGlobalDir) {
@@ -846,37 +1597,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));
 };
 
 
@@ -886,9 +1653,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
@@ -897,44 +1667,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;
 };
 
 
@@ -944,6 +1782,10 @@ soy.$$bidiUnicodeWrap = function(bidiGlobalDir, str) {
 
 
 
+
+
+
+
 // START GENERATED CODE FOR ESCAPERS.
 
 /**
@@ -954,7 +1796,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
  */
@@ -982,7 +1824,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
@@ -992,7 +1834,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
  */
@@ -1034,7 +1876,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
@@ -1044,7 +1886,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
  */
@@ -1079,7 +1921,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
@@ -1089,7 +1931,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
  */
@@ -1162,7 +2004,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
@@ -1246,7 +2088,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.
@@ -1374,7 +2223,7 @@ soy.esc.$$filterNormalizeUriHelper = function(value) {
   var str = String(value);
   if (!soy.esc.$$FILTER_FOR_FILTER_NORMALIZE_URI_.test(str)) {
     goog.asserts.fail('Bad value `%s` for |filterNormalizeUri', [str]);
-    return 'zSoyz';
+    return '#zSoyz';
   }
   return str.replace(
       soy.esc.$$MATCHER_FOR_NORMALIZE_URI__AND__FILTER_NORMALIZE_URI_,
@@ -1382,14 +2231,28 @@ 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.$$filterHtmlAttributeHelper = function(value) {
+soy.esc.$$filterImageDataUriHelper = function(value) {
   var str = String(value);
-  if (!soy.esc.$$FILTER_FOR_FILTER_HTML_ATTRIBUTE_.test(str)) {
-    goog.asserts.fail('Bad value `%s` for |filterHtmlAttribute', [str]);
+  if (!soy.esc.$$FILTER_FOR_FILTER_IMAGE_DATA_URI_.test(str)) {
+    goog.asserts.fail('Bad value `%s` for |filterImageDataUri', [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.$$filterHtmlAttributesHelper = function(value) {
+  var str = String(value);
+  if (!soy.esc.$$FILTER_FOR_FILTER_HTML_ATTRIBUTES_.test(str)) {
+    goog.asserts.fail('Bad value `%s` for |filterHtmlAttributes', [str]);
     return 'zSoyz';
   }
   return str;
@@ -1411,10 +2274,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