Introduce webNavigation.onTabReplaced event that is fired when a tab from instant or prerender repl…

chrome/common/extensions/docs/extensions/webNavigation.html

Index: chrome/common/extensions/docs/extensions/webNavigation.html
diff --git a/chrome/common/extensions/docs/extensions/webNavigation.html b/chrome/common/extensions/docs/extensions/webNavigation.html
index d14f32d270b0a8f9a7af80bf1c8d9f9fa9a0dbc6..cfd19a232a692635ec86cc5d4041e672ba4bef87 100644
--- a/chrome/common/extensions/docs/extensions/webNavigation.html
+++ b/chrome/common/extensions/docs/extensions/webNavigation.html
@@ -209,11 +209,15 @@
               <ol>
               </ol>
             </li><li>
-              <a href="#H2-4">A note about timestamps</a>
+              <a href="#H2-4">A note about tab IDs</a>
               <ol>
               </ol>
             </li><li>
-              <a href="#H2-5">Transition types and qualifiers</a>
+              <a href="#H2-5">A note about timestamps</a>
+              <ol>
+              </ol>
+            </li><li>
+              <a href="#H2-6">Transition types and qualifiers</a>
               <ol>
               </ol>
             </li>
@@ -247,6 +251,8 @@
                 <a href="#event-onErrorOccurred">onErrorOccurred</a>
               </li><li>
                 <a href="#event-onReferenceFragmentUpdated">onReferenceFragmentUpdated</a>
+              </li><li>
+                <a href="#event-onTabReplaced">onTabReplaced</a>
               </li>
             </ol>
           </li>
@@ -310,6 +316,12 @@ If the reference fragment of a frame is changed, a
 time after <code>onDOMContentLoaded</code>, even after
 <code>onCompleted</code>.
 </p>
+<p>
+If a navigation was triggered via <a href="https://support.google.com/chrome/bin/answer.py?answer=177873">Chrome
+Instant</a> or <a href="https://support.google.com/chrome/bin/answer.py?answer=1385029">Instant
+Pages</a>, a completely loaded page is swapped into the current tab. In that
+case, an <code>onTabReplaced</code> event is fired.
+</p>
 <a name="H2-3"></a><h2>Relation to webRequest events</h2>
 <p>
 There is no defined ordering between events of the <a href="webRequest.html">webRequest API</a> and the events of the
@@ -322,7 +334,16 @@ In general, the webNavigation events are closely related to the navigation
 state that is displayed in the UI, while the webRequest events correspond to
 the state of the network stack which is generally opaque to the user.
 </p>
-<a name="H2-4"></a><h2>A note about timestamps</h2>
+<a name="H2-4"></a><h2>A note about tab IDs</h2>
+<p>
+Not all navigating tabs correspond to actual tabs in Chrome's UI, e.g., a tab
+that is being pre-rendered. Such tabs are not accessible via the
+<a href="tabs.html">tabs API</a> nor can you request information about them via
+<code>webNavigation.getFrame</code> or <code>webNavigation.getAllFrames</code>.
+Once such a tab is swapped in, an <code>onTabReplaced</code> event is fired and
+they become accessible via these APIs.
+</p>
+<a name="H2-5"></a><h2>A note about timestamps</h2>
 <p>
 It's important to note that some technical oddities in the OS's handling
 of distinct Chrome processes can cause the clock to be skewed between the
@@ -333,7 +354,7 @@ offset between them, but comparing them to the current time inside the
 extension (via <code>(new Date()).getTime()</code>, for instance) might give
 unexpected results.
 </p>
-<a name="H2-5"></a><h2>Transition types and qualifiers</h2>
+<a name="H2-6"></a><h2>Transition types and qualifiers</h2>
 <p>
 The webNavigation API's <code>onCommitted</code> event has a
 <code>transitionType</code> and a <code>transitionQualifiers</code> property.
@@ -1995,6 +2016,127 @@ The following transition qualifiers exist:
                 </dl>
               </div> <!-- /description -->
                <!-- /description -->
+            </div><div class="apiItem">
+              <a name="event-onTabReplaced"></a>
+              <h4>onTabReplaced</h4>
+              <div class="summary">
+                <!-- Note: intentionally longer 80 columns -->
+                <span class="subdued">chrome.webNavigation.</span><span>onTabReplaced</span><span class="subdued">.addListener</span>(function(<span>object details</span>) <span class="subdued">{...}</span><span></span>);
+              </div>
+              <div class="description">
+                <p>Fired when the contents of the tab is replaced by a different (usually previously pre-rendered) tab.</p>
+                <!-- LISTENER PARAMETERS -->
+                <div>
+                  <h4>Listener parameters</h4>
+                  <dl>
+                    <div>
+                      <div>
+          <dt>
+            <var>details</var>
+              <em>
+                <!-- TYPE -->
+                <div style="display:inline">
+                  (
+                    <span id="typeTemplate">
+                      <span>
+                        <span>object</span>
+                      </span>
+                    </span>
+                  )
+                </div>
+              </em>
+          </dt>
+          <dd class="todo">
+            Undocumented.
+          </dd>
+          <!-- OBJECT PROPERTIES -->
+          <dd>
+            <dl>
+              <div>
+                <div>
+          <dt>
+            <var>replacedTabId</var>
+              <em>
+                <!-- TYPE -->
+                <div style="display:inline">
+                  (
+                    <span id="typeTemplate">
+                      <span>
+                        <span>integer</span>
+                      </span>
+                    </span>
+                  )
+                </div>
+              </em>
+          </dt>
+          <dd>The ID of the tab that was replaced.</dd>
+          <!-- OBJECT PROPERTIES -->
+          <!-- OBJECT METHODS -->
+          <!-- OBJECT EVENT FIELDS -->
+          <!-- FUNCTION PARAMETERS -->
+        </div>
+              </div><div>
+                <div>
+          <dt>
+            <var>tabId</var>
+              <em>
+                <!-- TYPE -->
+                <div style="display:inline">
+                  (
+                    <span id="typeTemplate">
+                      <span>
+                        <span>integer</span>
+                      </span>
+                    </span>
+                  )
+                </div>
+              </em>
+          </dt>
+          <dd>The ID of the tab that replaced the old tab.</dd>
+          <!-- OBJECT PROPERTIES -->
+          <!-- OBJECT METHODS -->
+          <!-- OBJECT EVENT FIELDS -->
+          <!-- FUNCTION PARAMETERS -->
+        </div>
+              </div><div>
+                <div>
+          <dt>
+            <var>timeStamp</var>
+              <em>
+                <!-- TYPE -->
+                <div style="display:inline">
+                  (
+                    <span id="typeTemplate">
+                      <span>
+                        <span>number</span>
+                      </span>
+                    </span>
+                  )
+                </div>
+              </em>
+          </dt>
+          <dd>The time when the replacement happened, in milliseconds since the epoch.</dd>
+          <!-- OBJECT PROPERTIES -->
+          <!-- OBJECT METHODS -->
+          <!-- OBJECT EVENT FIELDS -->
+          <!-- FUNCTION PARAMETERS -->
+        </div>
+              </div>
+            </dl>
+          </dd>
+          <!-- OBJECT METHODS -->
+          <!-- OBJECT EVENT FIELDS -->
+          <!-- FUNCTION PARAMETERS -->
+        </div>
+                    </div>
+                  </dl>
+                </div>
+                <!-- EXTRA PARAMETERS -->
+                <!-- LISTENER RETURN VALUE -->
+                <dl>
+                </dl>
+              </div> <!-- /description -->
+               <!-- /description -->
             </div> <!-- /apiItem -->
           </div> <!-- /apiGroup -->
           <!-- TYPES -->