Specify scroll restoration in more detail

Closes whatwg#7517.

Author: domenic

source

@@ -93037,10 +93037,8 @@ location.href = '#foo';</code></pre>
   <ol>
    <li>
     <p>If <var>entry</var>'s <span data-x="she-scroll-restoration-mode">scroll restoration
-    mode</span> is "<code data-x="dom-ScrollRestoration-auto">auto</code>", then the user agent may
-    use <var>entry</var>'s <span data-x="she-scroll-position">scroll position data</span> to restore
-    the scroll positions of <var>entry</var>'s <span data-x="she-document">document</span>'s
-    <span>restorable scrollable regions</span>.</p>
+    mode</span> is "<code data-x="dom-ScrollRestoration-auto">auto</code>", then <span>restore
+    scroll position data</span> given <var>entry</var>.</p>
 
     <p class="note">The user agent not restoring scroll positions does not imply that scroll
     positions will be left at any particular value (e.g., (0,0)). The actual scroll position depends
@@ -93071,14 +93069,45 @@ location.href = '#foo';</code></pre>
 
   <hr>
 
-  <p>The <dfn>restorable scrollable regions</dfn> of a <code>Document</code> <var>document</var> are
-  <var>document</var>'s <span>viewport</span>, and all of <var>document</var>'s scrollable regions
-  excepting any <span data-x="navigable container">navigable containers</span>.</p>
+  <p>Each <code>Document</code> has a boolean <dfn>has been scrolled by the user</dfn>, initially
+  false. If the user scrolls the document, the user agent must set that document's <span>has been
+  scrolled by the user</span> to true.</p>
+
+  <p>The <dfn>restorable scrollable regions</dfn> of a <code>Document</code> <var>document</var>
+  are <var>document</var>'s <span>viewport</span>, and all of <var>document</var>'s scrollable
+  regions excepting any <span data-x="navigable container">navigable containers</span>.</p>
 
   <p class="note"><span>Child navigable</span> scroll restoration is handled as part of state
   restoration for the <span>session history entry</span> for those <span
   data-x="navigable">navigables</span>' <code>Document</code>s.</p>
 
+  <p>To <dfn>restore scroll position data</dfn> given a <span>session history entry</span>
+  <var>entry</var>:</p>
+
+  <ol>
+   <li><p>Let <var>document</var> be <var>entry</var>'s <span
+   data-x="she-document">document</span>.</p></li>
+
+   <li><p>If <var>document</var>'s <span>has been scrolled by the user</span> is true, then the
+   user agent should return.</p></li>
+
+   <li>
+    <p>The user agent should attempt to use <var>entry</var>'s <span
+    data-x="she-scroll-position">scroll position data</span> to restore the scroll positions of
+    <var>entry</var>'s <span data-x="she-document">document</span>'s <span>restorable scrollable
+    regions</span>. The user agent may continue to attempt to do so periodically, until
+    <var>document</var>'s <span>has been scrolled by the user</span> becomes true.</p>
+
+    <p class="note">This is formulated as an <em>attempt</em>, which is potentially repeated until
+    success or until the user scrolls, due to the fact that relevant content indicated by the <span
+    data-x="she-scroll-position">scroll position data</span> might take some time to load from the
+    network.</p>
+
+    <p class="note">Scroll restoration might be affected by scroll anchoring. <ref
+    spec=CSSSCROLLANCHORING></p>
+   </li>
+  </ol>
+
 
   <h3 split-filename="document-lifecycle">Document lifecycle</h3>
 
@@ -93961,6 +93990,8 @@ new PaymentRequest(&hellip;); // Allowed to use
    <span data-x="map get the keys">getting the keys</span> for the
    <span>map of active timers</span>.</p></li>
 
+   <li><p>Set <var>oldDocument</var>'s <span>has been scrolled by the user</span> to false.</p></li>
+
    <li><p>Run any <span>unloading document cleanup steps</span> for <var>oldDocument</var> that are
    defined by this specification and <span>other applicable specifications</span>.</p></li>
 
@@ -130908,15 +130939,15 @@ INSERT INTERFACES HERE
    <dt id="refsCSSSIZING">[CSSSIZING]</dt>
    <dd><cite><a href="https://drafts.csswg.org/css-sizing/">CSS Intrinsic &amp; Extrinsic Sizing Module</a></cite>, T. Atkins, E. Etemad. W3C.</dd>
 
-   <dt id="refsCSSTRANSITIONS">[CSSTRANSITIONS]</dt>
-   <dd>(Non-normative) <cite><a href="https://drafts.csswg.org/css-transitions/">CSS Transitions</a></cite>, D. Jackson, D. Hyatt, C. Marrin, L. Baron. W3C.</dd>
-
-   <dt id="refsCSSUI">[CSSUI]</dt>
-   <dd><cite><a href="https://drafts.csswg.org/css-ui/">CSS3 Basic User Interface Module</a></cite>, T. &Ccedil;elik. W3C.</dd>
+   <dt id="refsCSSSCROLLANCHORING">[CSSSCROLLANCHORING]</dt>
+   <dd>(Non-normative) <cite><a href="https://drafts.csswg.org/css-scroll-anchoring/">CSS Scroll Anchoring</a></cite>, T. Atkins-Bittner. W3C.</dd>
 
    <dt id="refsCSSSYNTAX">[CSSSYNTAX]</dt>
    <dd><cite><a href="https://drafts.csswg.org/css-syntax/">CSS Syntax</a></cite>, T. Atkins, S. Sapin. W3C.</dd>
 
+   <dt id="refsCSSTRANSITIONS">[CSSTRANSITIONS]</dt>
+   <dd>(Non-normative) <cite><a href="https://drafts.csswg.org/css-transitions/">CSS Transitions</a></cite>, L. Baron, D. Jackson, B. Birtles. W3C.</dd>
+
    <dt id="refsCSSTABLE">[CSSTABLE]</dt>
    <dd><cite><a href="https://drafts.csswg.org/css-tables/">CSS Table</a></cite>, F. Remy, G. Whitworth. W3C.</dd>
 
@@ -130926,6 +130957,9 @@ INSERT INTERFACES HERE
    <dt id="refsCSSVALUES">[CSSVALUES]</dt>
    <dd><cite><a href="https://drafts.csswg.org/css-values/">CSS3 Values and Units</a></cite>, H. Lie, T. Atkins, E. Etemad. W3C.</dd>
 
+   <dt id="refsCSSUI">[CSSUI]</dt>
+   <dd><cite><a href="https://drafts.csswg.org/css-ui/">CSS3 Basic User Interface Module</a></cite>, F. Rivoal. W3C.</dd>
+
    <dt id="refsCSSWM">[CSSWM]</dt>
    <dd><cite><a href="https://drafts.csswg.org/css-writing-modes/">CSS Writing Modes</a></cite>, E. Etemad, K. Ishii. W3C.</dd>