index.bs

<!-- max-line-length: 100 -->
<pre class=metadata>
Title: Soft Navigations and Interaction Contentful Paint
Status: CG-DRAFT
Shortname: soft-navigations
Group: wicg
Level: none
Editor: Michal Mocny, Google https://google.com, mmocny@chromium.org, w3cid 110398
        Scott Haseley, Google https://google.com, shaseley@google.com, w3cid 122093
Former Editor: Yoav Weiss, Shopify https://shopify.com, yoav@yoav.ws, w3cid 58673
URL: https://wicg.github.io/soft-navigations/
Repository: https://github.com/WICG/soft-navigations
Test Suite: https://github.com/web-platform-tests/wpt/tree/master/soft-navigation-heuristics
Abstract: This document defines a set of APIs that web page authors can use to detect same-document ("soft") navigations and attribute subsequent page modifications and contentful paints back to the user interactions that triggered them.
Boilerplate: omit conformance
Default Highlight: js
Complain About: accidental-2119 yes
Markup Shorthands: markdown on
Indent: 2
</pre>

<pre class=anchors>
urlPrefix: https://html.spec.whatwg.org/multipage/webappapis.html; spec: HTML;
  type: dfn;
    text: execute the script element; url: #execute-the-script-element;
    text: timer initialisation steps; url: #timer-initialisation-steps;
    text: HostMakeJobCallback; url: #hostmakejobcallback;
    text: hostcalljobcallback; url: #hostcalljobcallback;
urlPrefix: https://html.spec.whatwg.org/multipage/browsing-the-web.html; spec: HTML;
  type: dfn;
    text: update document for history step application; url: #update-document-for-history-step-application;
    text: top-level traversable; url: #top-level-traversable;
    text: apply the history step; url: #apply-the-history-step;
    text: append session history traversal steps; url: #tn-append-session-history-traversal-steps;
    text: append session history synchronous navigation steps; url: #tn-append-session-history-sync-nav-steps;
    text: navigate to a fragment; url: #navigate-fragid;
    text: session history entry url; url: #she-url;
urlPrefix: https://html.spec.whatwg.org/multipage/scripting.html; spec: HTML;
  type: dfn; text: prepare the script element; url: #prepare-the-script-element;
urlPrefix: https://html.spec.whatwg.org/multipage/web-messaging.html; spec: HTML;
  type: dfn; text: message port post message steps; url: #message-port-post-message-steps;
urlPrefix: https://html.spec.whatwg.org/multipage/nav-history-apis.html; spec: HTML;
  type: dfn; text: shared history push/replace steps; url: #shared-history-push/replace-steps;
urlPrefix: https://dom.spec.whatwg.org/; spec: DOM;
  type: dfn;
    text: event dispatch; url: #concept-event-dispatch;
    text: node insert; url: #concept-node-insert;
    text: isTrusted; url: #dom-event-istrusted;
    text: event; url: #concept-event;
    text: node; url: #concept-node;
    text: descendent; url: #concept-tree-descendant
urlPrefix: https://www.w3.org/TR/css-view-transitions-1/
  type: dfn; text: startViewTransition(); url: #dom-document-startviewtransition;
urlPrefix: https://w3c.github.io/performance-timeline/; spec: PERFORMANCE-TIMELINE
  type: dfn; text: queue a PerformanceEntry; url: #dfn-queue-a-performanceentry;
urlPrefix: https://w3c.github.io/largest-contentful-paint/; spec: LARGEST-CONTENTFUL-PAINT
  type: dfn;
    text: has dispatched scroll event; url: #has-dispatched-scroll-event;
    text: report largest contentful paint; url: #report-largest-contentful-paint;
    text: largest contentful paint candidate; url: #largest-contentful-paint-candidate;
    text: compute a new largest contentful paint candidate; url: #compute-a-new-largest-contentful-paint-candidate;
    text: create a LargestContentfulPaint entry; url: #create-a-largestcontentfulpaint-entry;
urlPrefix: https://w3c.github.io/long-animation-frames/; spec: LONG-ANIMATION-FRAMES;
  type: interface; text: PerformanceLongAnimationFrameTiming; url: #sec-PerformanceLongAnimationFrameTiming;
  type: dfn; text: long animation frame; url: #dfn-long-animation-frame;
  type: dfn; text: report long animation frames; url: #dfn-report-long-animation-frames;
urlPrefix: https://pr-preview.s3.amazonaws.com/mmocny/event-timing/pull/165.html; spec: EVENT-TIMING;
  type: dfn;
    text: interaction count; url: #window-interaction-count;
    text: initial interactionId value; url: #window-initial-interactionid-value;
    text: interactionId increment; url: #window-interactionid-increment;
    text: get the next interactionId; url: #get-the-next-interactionid;
    text: initialize and record event timing processing start; url: #initialize-and-record-event-timing-processing-start;
    text: record event timing processing end; url: #record-event-timing-processing-end;
    text: associated event; url: #performanceeventtiming-associated-event;
    text: has dispatched input event; url: #has-dispatched-input-event;
    text: interaction; url: #dfn-interaction;
urlPrefix: https://w3c.github.io/paint-timing/
  type: dfn;
    text: previously reported paints; url: #previously-reported-paints;
    text: pending image record; url: #pending-image-record;
    text: pending image record element; url: #pending-image-record-element;
    text: paint timing info; url: #paint-timing-info;
    text: default paint timestamp; url: #default-paint-timestamp;
  type: dfn; for: paint timing info;
    text: rendering update end time; url: #paint-timing-info-rendering-update-end-time;
    text: implementation-defined presentation time; url: #paint-timing-info-implementation-defined-presentation-time;
  type: interface; text: PaintTimingMixin; url: #paint-timing-mixin;
  type: attribute; for: PaintTimingMixin;
    text: paintTime; url: #dom-painttimingmixin-painttime;
    text: presentationTime; url: #dom-painttimingmixin-presentationtime;
</pre>
<pre class=link-defaults>
spec:dom; type:dfn; text:element;
spec:dom; type:dfn; for:/; text:document;
spec:html; type:dfn; for:/; text:global object;
spec:dom; type:dfn; text:event;
spec:dom; type:dfn; for:event; text:type;
spec:hr-time-3; type:dfn; for:/; text:duration;
spec:infra; type:dfn; for:/; text:set
</pre>

<pre class=biblio>
{
  "ASYNC-CONTEXT": {
    "title": "AsyncContext",
    "href": "https://github.com/tc39/proposal-async-context"
  },
  "CONTAINER-TIMING": {
    "title": "Container Timing API",
    "href": "https://github.com/WICG/container-timing"
  }
}
</pre>

Introduction {#sec-intro}
=====================

<div class="non-normative">
<em>This section is non-normative.</em>

Modern web applications often dynamically update content in response to user interactions without
performing a full page navigation. These interaction-initiated effects—such as structural DOM
modifications, contentful paints, and history state changes—have historically been difficult to
measure and attribute to the correct user actions.

Consider a typical Single Page Application pattern: a user clicks a product link, which triggers a
`click` event handler. This handler initiates a network `fetch()` for product details. When the
response arrives, a callback is executed that dynamically injects the new content into the DOM and
uses the History or Navigation API to update the URL. While this appears to the user as a
navigation, existing metrics like Largest Contentful Paint (LCP) ([[LARGEST-CONTENTFUL-PAINT]]) only
measure the initial page load, and Interaction to Next Paint (INP) only measures the immediate
visual feedback of the click itself, leaving the significant subsequent rendering and "soft"
navigation uncaptured.

This specification leverages the [[EVENT-TIMING]] API to define interactions and the
[[ASYNC-CONTEXT]] proposal to track causality across asynchronous task boundaries, mapping modified
DOM nodes to interactions, enabling attribution of contentful paints to interactions that caused
them. It defines how browsers can identify and report these effects, including "Soft Navigations,"
by integrating with [[PAINT-TIMING]] and [[LARGEST-CONTENTFUL-PAINT]] to attribute rendering changes
to the performance timeline.
</div>

Performance Timeline Slicing {#sec-timeline-slicing}
====================================================

<div class="non-normative">
<em>This section is non-normative.</em>

To attribute performance metrics (such as event timings, layout shifts, resource loads, or
long animation frames) to their initiating navigation, the performance timeline is sliced into
segments using a {{PerformanceEntry/navigationId}} attribute on {{PerformanceEntry}}.

Determining the exact slice point for a transition that spans time is complex. To ensure
consistent attribution, this specification adopts a model where the timeline is not sliced
immediately upon every URL modification; instead, the transition is deferred until a
[=soft navigation=] is ready to be emitted to the performance timeline.

For a detailed discussion of the design trade-offs, attribution rules, and edge cases, see
the [[PERFORMANCE-TIMELINE]] issue
[comment](https://github.com/w3c/performance-timeline/issues/182#issuecomment-4460611895).
</div>


Navigation ID {#sec-nav-id}
---------------------------

A <dfn export>navigation id</dfn> is a unique identifier assigned to each navigation (both hard and
soft) within a [=global object=]'s lifetime.

Each {{Window}} has:
 * a <dfn for="Window">current navigation id</dfn>, a [=64-bit unsigned integer=],
   initially set to the {{Window}}'s [=Window/initial navigation id value=].
 * a <dfn for="Window">navigation count</dfn>, a [=64-bit unsigned integer=], initially 0.
 * a <dfn for="Window">initial navigation id value</dfn>, a [=64-bit unsigned integer=],
   initially set to a random integer between 100 and 10000.
 * a <dfn for="Window">navigation id increment</dfn>, a [=64-bit unsigned integer=],
   initially set to a small positive integer chosen by the user agent.

Note: The [=Window/initial navigation id value=] and [=Window/navigation id increment=] are
used to calculate {{PerformanceEntry/navigationId}} values (see
[=increment the current navigation id=]).
This discourages developers from relying on it to count the exact number of navigations or
assuming it starts at zero.
User agents are expected not to use shared global navigation values across different {{Window}}
objects to prevent cross-origin leaks.

<div algorithm="increment the current navigation id">
  To <dfn>increment the current navigation id</dfn> given a {{Window}} |window|:

  1. Set |window|'s [=Window/navigation count=] to |window|'s
     [=Window/navigation count=] plus 1.
  1. Let |newId| be |window|'s [=Window/initial navigation id value=] plus
     (|window|'s [=Window/navigation count=] times
     |window|'s [=Window/navigation id increment=]).
  1. Set |window|'s [=Window/current navigation id=] to |newId|.
</div>


The `PerformanceEntry` extension {#sec-pe-extension}
----------------------------------------------------

<pre class=idl>
[Exposed=(Window,Worker)]
partial interface PerformanceEntry {
    readonly attribute unsigned long long navigationId;
};
</pre>

<div dfn-for="PerformanceEntry">
  Each {{PerformanceEntry}} has an associated <dfn for="PerformanceEntry">navigation id</dfn>,
  a [=64-bit unsigned integer=], initially 0.

  The {{navigationId}} attribute's getter must return [=this=]'s [=PerformanceEntry/navigation id=].
</div>


Performance Timeline Integration {#sec-performance-timeline-integration}
------------------------------------------------------------------------

In [=queue a PerformanceEntry=], after step 1 (initializing the entry), add the following steps:

  1. If |newEntry|'s [=PerformanceEntry/navigation id=] is 0:
    1. If |global| is a {{Window}} object:
      1. Set |newEntry|'s [=PerformanceEntry/navigation id=] to
         |global|'s [=Window/current navigation id=].


Interaction Infrastructure {#sec-infrastructure}
=====================



Interaction Context Intro {#sec-interaction-context-intro}
-----------------

<div class="non-normative">
Soft navigation detection relies on the ability to track the causality of tasks and observe that
certain operations (e.g., a DOM node append) were triggered by a specific user interaction.

This specification leverages the TC39 [[ASYNC-CONTEXT]] proposal to handle this propagation. Every
new user interaction (as defined by Event Timing) or relevant navigation event creates a new
**InteractionContext**. This context is stored in a hidden, internal-only `AsyncContext.Variable`
(denoted as `[[ActiveInteractionContext]]`).

The web platform's integration with AsyncContext ensures that this variable is automatically
attached to asynchronous continuations (e.g., `setTimeout`, `fetch`, `await`), allowing the browser
to attribute later effects back to the original interaction.

In addition to script propagation, this specification defines how user interactions that modify the
DOM [=record a node as modified for interaction paint timing|establish=] a set of modified nodes
associated with the interaction, allowing subsequent rendering effects, like contentful paints, to
be traced back to the initiating interaction context even when no asynchronous script is currently
running.
</div>


The InteractionContext struct {#sec-interaction}
-----------------

<div dfn-for="InteractionContext">
  <dfn>InteractionContext</dfn> is a [=struct=] used to maintain the data required to detect a soft
  navigation from a single interaction. It has the following [=struct/items=]:

  * <dfn>id</dfn>, a [=64-bit unsigned integer=] respresenting the {{PerformanceEventTiming/interactionId}}
    associated with this context.
  * <dfn>context document</dfn>, a [=Document=].
  * <dfn>start time</dfn>, a number.
  * <dfn>navigation type</dfn>, a {{NavigationType}} or null, initially null.
  * <dfn>first URL value</dfn>, a string or null, initially null.
  * <dfn>first URL update timestamp</dfn>, a number, initially 0.
  * <dfn>first scroll timestamp</dfn>, a number, initially 0.
  * <dfn>first input timestamp</dfn>, a number, initially 0.
  * <dfn>first contentful paint</dfn>, an {{InteractionContentfulPaint}} or null, initially null.
  * <dfn>largest contentful paint</dfn>, an {{InteractionContentfulPaint}} or null, initially null.
  * <dfn>current largest contentful paint candidate</dfn>, a [=largest contentful paint candidate=]
    or null, initially null.
  * <dfn>last URL value</dfn>, a string or null, initially null.
  * <dfn>emitted</dfn>, a boolean, initially false.
</div>

Note: Future versions of this specification might track all URL updates that occur during an
interaction context to provide a more complete history of the navigation. The **last URL value** is
tracked internally to ensure accurate attribution of effects back to the final state of the
interaction, even if only the **first URL value** is currently exposed in the
{{PerformanceSoftNavigation}}'s name.


Infrastructure Algorithms {#sec-infra-algos}
-----------------

<div algorithm>
  To <dfn>get the current interaction context</dfn> given a [=Document=] |document|:

  1. Let |context| be the value of the internal `AsyncContext.Variable`
     `[[ActiveInteractionContext]]`.
  1. If |context| is not null and |context|'s [=InteractionContext/context document=] is not equal
     to |document|, return null.
  1. Return |context|.
</div>

<div algorithm>
  To <dfn>get or create the context for an interaction</dfn> given a [=Document=] |document| and a
  {{PerformanceEventTiming}} |timing entry|:

  1. Let |interaction id| be |timing entry|'s {{PerformanceEventTiming/interactionId}}.
  1. [=Assert=] |interaction id| is greater than 0.
  1. If |document|'s [=interaction id to interaction context=][|interaction id|] [=map/exists=],
     return |document|'s [=interaction id to interaction context=][|interaction id|].
  1. Let |interaction context| be a new [=InteractionContext=].
  1. Set |interaction context|'s [=InteractionContext/id=] to |interaction id|.
  1. Set |interaction context|'s [=InteractionContext/context document=] to |document|.
  1. Set |interaction context|'s [=InteractionContext/start time=] to |timing entry|'s
     {{PerformanceEntry/startTime}}.
  1. [=map/Set=] |document|'s [=interaction id to interaction context=][|interaction id|] to
     |interaction context|.
  1. Return |interaction context|.
</div>

<div algorithm>
  To <dfn>update the interaction contexts for an event</dfn> given a [=Document=] |document| and an
  [=Event=] |event|:

  1. Let |timestamp| be the [=current high resolution time=] given |document|'s [=relevant global object=].
  1. Let |is scroll| be true if |event|'s type is "scroll", and false otherwise.
  1. Let |is input| be true if |event|'s type is an event type that would trigger
     [=has dispatched input event=] (as defined in [[EVENT-TIMING]]), and false otherwise.
  1. If |is scroll| is false and |is input| is false, return.
  1. For each |interaction context| of |document|'s [=interaction id to interaction context=]'s
     values:
    1. If |is scroll| is true and |interaction context|'s [=InteractionContext/first scroll timestamp=]
       is 0:
      1. Set |interaction context|'s [=InteractionContext/first scroll timestamp=] to |timestamp|.
    1. If |is input| is true and |interaction context|'s [=InteractionContext/first input timestamp=]
       is 0:
      1. Set |interaction context|'s [=InteractionContext/first input timestamp=] to |timestamp|.
</div>

<div algorithm>
  To <dfn>set the current interaction context for event dispatch</dfn> given null or a
  {{PerformanceEventTiming}} object |timing entry|:

  1. If |timing entry| is null, return null.
  1. Let |interaction id| be |timing entry|'s {{PerformanceEventTiming/interactionId}}.
  1. If |interaction id| is 0, return null.
  1. Let |event| be |timing entry|'s [=associated event=].
  1. Let |document| be |event|'s [=relevant global object=]'s [=associated Document=].
  1. [=Update the interaction contexts for an event=] given |document| and |event|.
  1. Let |interaction context| be the result of [=get or create the context for an
     interaction|getting or createing the context for an interaction=] given |document| and
     |timing entry|.
  1. Set the value of the internal `AsyncContext.Variable` `[[ActiveInteractionContext]]` to
     |interaction context|.
  1. Return |interaction context|.
</div>

<div algorithm>
  To <dfn>unset the current interaction context after event dispatch</dfn>:

  1. Set the value of the internal `AsyncContext.Variable` `[[ActiveInteractionContext]]` to null.
</div>


Interaction Contentful Paints {#sec-interaction-contentful-paint}
=====================

The `InteractionContentfulPaint` interface {#sec-interaction-contentful-paint-interface}
-----------------

<pre class=idl>
[Exposed=Window]
interface InteractionContentfulPaint : PerformanceEntry {
    readonly attribute LargestContentfulPaint largestContentfulPaint;
    readonly attribute unsigned long long interactionId;

    [Default] object toJSON();
};

InteractionContentfulPaint includes PaintTimingMixin;
</pre>

<div dfn-for="InteractionContentfulPaint">

Each {{InteractionContentfulPaint}} has:
 * An associated <dfn>context</dfn>, an [=InteractionContext=].
 * An associated <dfn>largest contentful paint</dfn>, a {{LargestContentfulPaint}} entry.
 * An associated [=paint timing info=].

The {{largestContentfulPaint}} attribute's getter must return [=this=]'s
[=InteractionContentfulPaint/largest contentful paint=].

The {{InteractionContentfulPaint/interactionId}} attribute's getter must return [=this=]'s
[=InteractionContentfulPaint/context=]'s [=InteractionContext/id=].

The {{PerformanceEntry/name}} attribute's getter must return the empty string.

The {{PerformanceEntry/entryType}} attribute's getter must return `"interaction-contentful-paint"`.

The {{PerformanceEntry/startTime}} attribute's getter must return [=this=]'s
[=InteractionContentfulPaint/context=]'s [=InteractionContext/start time=].

The {{PerformanceEntry/duration}} attribute's getter must return the difference between the
[=default paint timestamp=] for [=this=]'s [=paint timing info=] and [=this=]'s
[=InteractionContentfulPaint/context=]'s [=InteractionContext/start time=].

When {{InteractionContentfulPaint/toJSON()}} is called, run [=default toJSON steps=].

Note: While the entry dynamically queries static interaction properties (like `interactionId` and
`startTime`) from its associated [=InteractionContext=], it captures a static snapshot of the
paint's [=paint timing info=] and the candidate {{LargestContentfulPaint}} entry at creation time to
ensure these metrics reflect the exact state of that visual update.

</div>


Interaction Contentful Paint Algorithms {#sec-interaction-contentful-paint-algos}
-----------------

<div algorithm>
  To <dfn>create an interaction contentful paint entry</dfn>, given a {{Window}} |window|, an
  [=InteractionContext=] |interaction context|, a {{LargestContentfulPaint}} |lcpEntry|, and a
  [=paint timing info=] |paintTimingInfo|:

  1. Let |entry| be a new {{InteractionContentfulPaint}} object in |window|'s
     [=global object/realm=].
  1. Set |entry|'s [=InteractionContentfulPaint/context=] to |interaction context|.
  1. Set |entry|'s [=InteractionContentfulPaint/largest contentful paint=] to |lcpEntry|.
  1. Set |entry|'s associated [=paint timing info=] to |paintTimingInfo|.
  1. Return |entry|.
</div>

<div algorithm>
  To <dfn>process a new attributed contentful paint candidate</dfn> given a
  [=largest contentful paint candidate=] |lcpCandidate|, a [=Document=] |document|, an
  [=InteractionContext=] |interaction context|, and a [=paint timing info=] |paintTimingInfo|:

  1. If |interaction context|'s [=InteractionContext/first scroll timestamp=] is greater than 0 and
     |lcpEntry|'s {{LargestContentfulPaint/renderTime}} is greater than |interaction context|'s
     [=InteractionContext/first scroll timestamp=], return.
  1. If |interaction context|'s [=InteractionContext/first input timestamp=] is greater than 0 and
     |lcpEntry|'s {{LargestContentfulPaint/renderTime}} is greater than |interaction context|'s
     [=InteractionContext/first input timestamp=], return.
  1. Let |lcpEntry| be the result of [=creating a LargestContentfulPaint entry=] with
     |lcpCandidate|, |paintTimingInfo|, and |document|.
  1. Let |global| be |document|'s [=relevant global object=].
  1. Let |paint timing info| be |lcpEntry|'s associated [=paint timing info=].
  1. Let |icpEntry| be the result of [=creating an interaction contentful paint entry=] given
     |global|, |interaction context|, |lcpEntry|, and |paint timing info|.
  1. [=queue a performanceentry|Queue=] |icpEntry|.
  1. Add |icpEntry| to |global|'s [=performance entry buffer=].
  1. If |interaction context|'s [=InteractionContext/first contentful paint=] is null:
    1. Set |interaction context|'s [=InteractionContext/first contentful paint=] to |icpEntry|.
  1. Set |interaction context|'s [=InteractionContext/largest contentful paint=] to |icpEntry|.
  1. Set |interaction context|'s [=InteractionContext/current largest contentful paint candidate=]
     to |lcpCandidate|.
</div>

Note: `InteractionContentfulPaint` entries are emitted to the performance timeline as they are
detected, independently of whether the interaction eventually results in a soft navigation. This
allows developers to monitor rendering updates for all interactions.

<div algorithm>
  To <dfn>report interaction contentful paints and soft navigations</dfn> given a {{Document}}
  |document|, a [=paint timing info=] |paintTimingInfo|, an [=ordered set=] of
  [=pending image records=] |paintedImages|, and an [=ordered set=] of [=/elements=]
  |paintedTextNodes|:

  1. Let |contextToCandidateSets| be a new [=/map=].
  1. [=set/For each=] |record| of |paintedImages|:
    1. Let |element| be |record|'s [=pending image record element|element=].
    1. Let |interaction context| be the result of [=getting the paint attribution interaction context=]
       for |element|.
    1. If |interaction context| is not null:
      1. If |contextToCandidateSets| does not [=map/contain=] |interaction context|, then set
         |contextToCandidateSets|[|interaction context|] to « «», «» ».
      1. [=set/Append=] |record| to |contextToCandidateSets|[|interaction context|][0].
  1. [=set/For each=] |element| of |paintedTextNodes|:
    1. Let |interaction context| be the result of [=getting the paint attribution interaction context=]
       for |element|.
    1. If |interaction context| is not null:
      1. If |contextToCandidateSets| does not [=map/contain=] |interaction context|, then set
         |contextToCandidateSets|[|interaction context|] to « «», «» ».
      1. [=set/Append=] |element| to |contextToCandidateSets|[|interaction context|][1].
  1. [=map/For each=] |interaction context| → |candidateSets| in |contextToCandidateSets|:
    1. Let |newCandidate| be the result of [=computing a new largest contentful paint candidate=]
       given |document|, |candidateSets|[0], |candidateSets|[1], and |interaction context|'s
       [=InteractionContext/current largest contentful paint candidate=].
    1. If |newCandidate| is not null:
      1. [=Process a new attributed contentful paint candidate=] given |newCandidate|, |document|,
         and |interaction context|, and |paintTimingInfo|.
      1. [=Evaluate soft navigation emission=] given |document| and |interaction context|.
</div>


Interaction Contentful Paint Attribution {#sec-interaction-contentful-paint-attribution}
-----------------

<div dfn-for="InteractionPaintTimingNodeState">
  An <dfn>InteractionPaintTimingNodeState</dfn> is a [=struct=] with the following [=struct/items=]:

  * <dfn>context</dfn>, an [=InteractionContext=], initially null.
  * <dfn>modification id</dfn>, a [=64-bit unsigned integer=], initially 0.
</div>

<br>

<div algorithm>
  To determine if an [=InteractionPaintTimingNodeState=] |node state| is <dfn>more recent than</dfn>
  an [=InteractionPaintTimingNodeState=] or null |other node state|:

  1. Return true if |other node state| is null or |node state|'s
     [=InteractionPaintTimingNodeState/modification id=] is greater than |other node state|'s
     [=InteractionPaintTimingNodeState/modification id=], and false otherwise.
</div>

<div algorithm>
  To <dfn>get the paint attribution interaction context</dfn> for a given [=Node=] |node|:

  1. Let |document| be |node|'s [=Node/node document=].
  1. Let |node state| be |document|'s [=document/propagated node state=][|node|]
     [=map/with default=] null.
  1. If |node state| is null return null, otherwise return |node state|'s
     [=InteractionPaintTimingNodeState/context=].
</div>

<div algorithm>
  To <dfn>record a node as modified for interaction paint timing</dfn> given a [=Node=]
  |target node|:

  1. Let |document| be |node|'s [=Node/node document=].
  1. If |target node| is not [=exposed for paint timing=] given |document|, return.
  1. Let |interaction context| be the result of [=getting the current interaction context=] given
     |document|.
  1. If |interaction context| is null, return.
  1. If |document|'s [=document/last modification context=] is not equal to |interaction context|:
    1. Set |document|'s [=document/last modification context=] to |interaction context|.
    1. Increment |document|'s [=document/current modification generation id=] by 1.
  1. Let |previous node state| be |document|'s [=document/marked node state=][|target node|]
     [=map/with default=] null.
  1. If |previous node state| is not null and |previous node state|'s
     [=InteractionPaintTimingNodeState/modification id=] equals |document|'s
     [=document/current modification generation id=], return.
  1. Let |node state| to a new [=InteractionPaintTimingNodeState=].
  1. Set |node state|'s [=InteractionPaintTimingNodeState/context=] to |interaction context|.
  1. Set |node state|'s [=InteractionPaintTimingNodeState/modification id=] to
     |document|'s [=document/current modification generation id=].
  1. [=map/Set=] |document|'s [=document/marked node state=][|node|] to |node state|.
  1. Set |document|'s [=document/is interaction paint timing dirty=] to true.
</div>

<div algorithm>
  To <dfn>update the interaction context for a document and its descendants</dfn> given a
  [=Document=] |document|:

  1. If |document|'s [=document/is interaction paint timing dirty=] is false, return.
  1. [=Update the interaction context for a node and its descendants=] given |document| and null.
  1. Set |document|'s [=document/is interaction paint timing dirty=] to false.
</div>

<div algorithm>
  To <dfn>update the interaction context for a node and its descendants</dfn> given a [=Node=]
  |node| and an [=InteractionPaintTimingNodeState=] |inherited node state| or null:

  1. Let |document| be |node|'s [=Node/node document=].
  1. Let |node state| be |document|'s [=document/marked node state=][|node|] [=map/with default=] null.
  1. If |node state| is not null:
    1. If |node state| is [=more recent than=] |inherited node state|:
        1. Set |inherited node state| to |node state|.
        1. If |node| is a {{Text}} [=node=], then [=map/remove=] |document|'s
           [=document/marked node state=][|node|].
    1. Otherwise, [=map/remove=] |document|'s [=document/marked node state=][|node|].
  1. If |inherited node state| is not null and |node| is [=timing-eligible=]:
    1. Let |attribution element| be the result of [=getting the attribution element=] for |node|.
    1. Let |previous propagated state| be [=document/propagated node state=][|attribution element|]
       [=map/with default=] null.
    1. If |inherited node state| is [=more recent than=] |previous propagated state|:
        1. Set [=document/propagated node state=][|attribution element|] to |inherited node state|.
        1. If |previous propagated state| is null or |previous propagated state|'s
           [=InteractionPaintTimingNodeState/context=] is not equal to |inherited node state|'s
           [=InteractionPaintTimingNodeState/context=], then [=reset paint tracking=] for
           |attribution element|.
  1. [=set/For each=] [=tree/child=] |child node| of |node|,
     [=update the interaction context for a node and its descendants=] given |child node| and
     |inherited node state|.
</div>

Note: For simplicity, this algorithm walks the entire DOM whenever the propagated state needs to to
be reprocessed. This can be optimized to only process parts of the DOM that are paintable, e.g.
subtrees that are known to be non-visible or skipped by existing mechanisms like
`content-visibility` or CSS containment could also be skipped during this process, as long as they
are updated before the next time they are painted. Also note that this can be further optimized by
merging these steps with another (pre-paint) tree walk, as long as the relevant state is updated
before paint.

Note: The [[CONTAINER-TIMING]] API provides a mechanism for grouping rendering effects by their
common DOM ancestor and report aggregated paint information to the performance timeline. In a future
version of this specification, we plan to expand Container Timing to support multiple clients for a
single container (i.e. the global "containertiming" attribute and per-interaction timing) to allow
implementing interaction paint timing in terms of Container Timing. Each [=record a node as modified
for interaction paint timing|recorded=] node would be considered a container for the interaction
that modified it, so that each interaction is associated with a set of containers. Then, this
specification would track the largest contentful paint that occurs in a marked container, for each
interaction.  Furthermore, we could expose other useful information that Container Timing tracks,
e.g. the aggregated total painted area of containers for each interaction.

Soft Navigations {#sec-soft-navs}
=====================

The `PerformanceSoftNavigation` interface {#sec-interface}
-----------------

<pre class=idl>
[Exposed=Window]
interface PerformanceSoftNavigation : PerformanceEntry {
    readonly attribute NavigationType navigationType;
    readonly attribute unsigned long long interactionId;
    InteractionContentfulPaint? getLargestInteractionContentfulPaint();

    [Default] object toJSON();
};

PerformanceSoftNavigation includes PaintTimingMixin;
</pre>

<div dfn-for="PerformanceSoftNavigation">

Each {{PerformanceSoftNavigation}} has:
 * An associated <dfn>context</dfn>, an [=InteractionContext=].
 * An associated [=paint timing info=].

The {{navigationType}} attribute's getter must return [=this=]'s
[=PerformanceSoftNavigation/context=]'s [=InteractionContext/navigation type=].

The {{PerformanceSoftNavigation/interactionId}} attribute's getter must return [=this=]'s
[=PerformanceSoftNavigation/context=]'s [=InteractionContext/id=].

The {{getLargestInteractionContentfulPaint()}} method must return [=this=]'s
[=PerformanceSoftNavigation/context=]'s [=InteractionContext/largest contentful paint=].

The {{PerformanceEntry/name}} attribute's getter must return [=this=]'s
[=PerformanceSoftNavigation/context=]'s [=InteractionContext/first URL value=].

The {{PerformanceEntry/entryType}} attribute's getter must return `"soft-navigation"`.

The {{PerformanceEntry/startTime}} attribute's getter must return [=this=]'s
[=PerformanceSoftNavigation/context=]'s [=InteractionContext/start time=].

The {{PerformanceEntry/duration}} attribute's getter must return the difference between [=this=]'s
{{PaintTimingMixin/presentationTime}} and [=this=]'s [=PerformanceSoftNavigation/context=]'s
[=InteractionContext/start time=] at the time of emission.

When {{PerformanceSoftNavigation/toJSON()}} is called, run [=default toJSON steps=].

</div>

Note: In practice, {{getLargestInteractionContentfulPaint()}} is expected to return a non-null
entry, as a confirmed soft navigation requires at least one detected interaction contentful paint to
trigger its emission.
<br><br>
However, future iterations could evaluate whether a soft navigation could be considered committed
immediately upon URL modification, prior to the first paint. In such a model, this method might
return null at the time of emission.
<br><br>
The primary design consideration for this timing is the attribution of other timeline entries (e.g.,
`LayoutShift`, `PerformanceResourceTiming`, `LongAnimationFrameTiming`, etc) that occur in the
interval between the URL modification and the first paint.  Many sites commit the new URL
immediately upon initiating a fetch request, for example, even while the current page remains in the
previous navigation state.  To ensure consistent timeline slicing, this specification attributes all
such entries to the *previous* navigation identifier until the first paint confirms the transition.

Soft Navigation Algorithms {#sec-soft-nav-algos}
-----------------

A <dfn export>soft navigation</dfn> is a same-document navigation that satisfies the following
conditions:
 * A same-document URL change occurs while an [=InteractionContext=] is active.
 * A contentful paint occurs that is attributed to the same [=InteractionContext=].

<div algorithm>
  To <dfn>evaluate soft navigation emission</dfn> given a [=Document=] |document| and an
  [=InteractionContext=] |interaction context|:

  1. If |interaction context|'s [=InteractionContext/emitted=] is true, return.
  1. If |document|'s [=document/active soft navigation candidate=] is not |interaction context|, return.
  1. If |interaction context|'s [=InteractionContext/first URL value=] is null, return.
  1. If |interaction context|'s [=InteractionContext/first contentful paint=] is null, return.
  1. Let |window| be |document|'s [=relevant global object=].
  1. Let |entry| be the result of [=creating a soft navigation entry=] given |window| and
     |interaction context|.
  1. [=Emit a soft navigation entry=] given |window| and |entry|.
  1. Set |interaction context|'s [=InteractionContext/emitted=] to true.
</div>

<div algorithm>
  To <dfn>create a soft navigation entry</dfn> given a {{Window}} |window|, and an
  [=InteractionContext=] |interaction context|:

  1. Let |entry| be a new {{PerformanceSoftNavigation}} object in |window|'s
     [=global object/realm=].
  1. Set |entry|'s [=PerformanceSoftNavigation/context=] to |interaction context|.
  1. Let |first paint| be |interaction context|'s [=InteractionContext/first contentful paint=].
  1. [=Assert=] |first paint| is not null.
  1. Set |entry|'s associated [=paint timing info=] to |first paint|'s associated [=paint timing info=].
  1. Return |entry|.
</div>

<div algorithm>
  To <dfn>emit a soft navigation entry</dfn> given a {{Window}} |window| and a
  {{PerformanceSoftNavigation}} |entry|:

  1. [=Increment the current navigation id=] given |window|.
  1. [=queue a performanceentry|Queue=] |entry|.
  1. Add |entry| to |window|'s [=performance entry buffer=].
</div>

Note: The `navigationId` for this {{PerformanceSoftNavigation}} entry is set automatically as
part of queuing it to the performance timeline, matching the behavior of other
{{PerformanceEntry}} types.

<div algorithm>
  To <dfn>process a same document commit</dfn> given a [=Document=] |document|, [=string=] |url|,
  and {{NavigationType}} |navigation type|:

  1. If |url| is equal to |document|'s [=Document/url=], return.
  1. Let |interaction context| be the result of [=getting the current interaction context=] given
     |document|.
  1. If |interaction context| is null, return.
  1. Set |interaction context|'s [=InteractionContext/last URL value=] to |url|.
  1. If |interaction context|'s [=InteractionContext/first URL update timestamp=] is null:
    1. Set |interaction context|'s [=InteractionContext/first URL update timestamp=] to the
       [=current high resolution time=] given |document|'s [=relevant global object=].
    1. Set |interaction context|'s [=InteractionContext/first URL value=] to |url|.
    1. Set |interaction context|'s [=InteractionContext/navigation type=] to |navigation type|.
  1. Set |document|'s [=document/active soft navigation candidate=] to |interaction context|.
  1. [=Evaluate soft navigation emission=] given |document| and |interaction context|.
</div>


Specification Integrations {#sec-integrations}
=================

DOM integration {#sec-dom-integration}
-----------------

### Document ### {#sec-html-document}

Each [=document=] has an <dfn for=document>interaction id to interaction context</dfn>, a [=map=],
initially empty.

Each [=document=] has an <dfn for=document>active soft navigation candidate</dfn>, an
[=InteractionContext=] or null, initially null.

Each [=document=] has a <dfn for=document>current modification generation id</dfn>, a
[=64-bit unsigned integer=] initilized to 0.

Note: The [=document/current modification generation id=] changes when a relevant DOM modification
occurs with a different [=InteractionContext=] from the previous modification. This allows grouping
together related modifications, which enables comparing [=InteractionPaintTimingNodeState=] objects
in terms of recency and optimizing which nodes need to be tracked.

Each [=document=] has a <dfn for=document>last modification context</dfn>, an [=InteractionContext=]
or null, initially null.

Each [=document=] has a <dfn for=document>marked node state</dfn>, a [=map=] of [=Node=] to
[=InteractionPaintTimingNodeState=], initially empty.

Each [=document=] has a <dfn for=document>propagated node state</dfn>, a [=map=] of [=Node=] to
[=InteractionPaintTimingNodeState=], initially empty.

Each [=document=] has an <dfn for=document>is interaction paint timing dirty</dfn>, a boolean,
initially false.

### Node ### {#sec-html-node}

<div algorithm="additions to node insert">
  At [=node insert=], or when a [=node=] |node| is modified in one of the following ways:

   * The `class` or `style` attribute of an element is modified.
   * A resource attribute (such as `src` on an `img` or `video` element) is modified.

  Run the following steps:

  1. [=Record a node as modified for interaction paint timing=] given |node|.
</div>


HTML integration {#sec-html}
-----------------

### History ### {#sec-html-history}

<div algorithm="additions to history step application">
  In [=update document for history step application=], before 5.5.1 (if `documentsEntryChanged` is
  true and if `documentIsNew` is false), [=process a same document commit=] given the [=Document=],
  the target entry's [=session history entry url|url=], and "{{NavigationType/traverse}}".
</div>
<br>
<div algorithm="additions to shared history push/replace steps">
  In the [shared history push/replace steps](https://html.spec.whatwg.org/multipage/nav-history-apis.html#shared-history-push/replace-steps)
  (as defined in [[HTML]]), after the URL is updated, [=process a same document commit=] given the
  [=Document=], the new URL, and the operation type (either "{{NavigationType/push}}" or
  "{{NavigationType/replace}}").
</div>

### Hard Navigation ### {#sec-html-hard-nav}

When a new {{Window}} is created (e.g., during a "hard" navigation), its
[=Window/current navigation id=] is initialized as specified in [[#sec-nav-id]].

<div algorithm="additions to Navigation Timing">
  In [[NAVIGATION-TIMING]], when creating the {{PerformanceNavigationTiming}} entry for the
  initial navigation, the user agent must set its `navigationId` to the {{Window}}'s
  [=Window/current navigation id=].
</div>


Event Timing integration {#sec-event-timing-integration}
-----------------

This specification extends the [[EVENT-TIMING]] definition of interactions to include additional
event types that are relevant for modern web applications and Single Page Applications.

The following event types are considered to be part of an [=interaction=] (as defined in [[EVENT-TIMING]]):
  * `navigate`
  * `popstate`
  * `hashchange`

When these events are dispatched as a result of a user interaction, the user agent must assign them
a unique {{PerformanceEventTiming/interactionId}} obtained by [=getting the next interactionId=]
for the document's [=relevant global object=]. If an event is triggered by a previous interaction
that already has an assigned {{PerformanceEventTiming/interactionId}}, the user agent should reuse
that same identifier.

Note:These events are only reported as primary interactions when they are the initiating event from
a user action (e.g., clicking the browser UI's back button). In most other scenarios—such as a
`click` handler manually manipulating history—the subsequent `popstate` or `navigate` events are not
considered independent user interactions.
<br><br>
While these programmatically triggered events might not have the `isTrusted` flag set, they are
correctly attributed back to the original interaction via [[ASYNC-CONTEXT]], as the history and
navigation APIs are treated as asynchronous continuations of the initiating task.

Note: The events `navigate`, `popstate`, and `hashchange` are used as internal signals for
tracking soft navigations and assigning `interactionId`. This specification does not require these
event types to be exposed as `PerformanceEventTiming` entries to the performance timeline, leaving
that determination to the [[EVENT-TIMING]] specification.

Note: The [[EVENT-TIMING]] specification is expected to be updated to explicitly define
`processingStart` and `processingEnd` hooks, and to ensure `interactionId` assignment happens early
enough for this integration. Today, `interactionId` assignment is typically deferred until the end
of the event processing.

Issue: This specification uses `unsigned long long` for **interactionId** to ensure a safe global
counter, while [[EVENT-TIMING]] currently defines it as `unsigned long`. This mismatch is expected
to be resolved in future versions of both specifications.

<div algorithm>
  To <dfn>get the next interactionId</dfn> for a {{Window}} |window|:

  1. Set |window|'s [=interaction count=] to |window|'s [=interaction count=] plus 1.
  1. Return |window|'s [=initial interactionId value=] plus (|window|'s [=interaction count=]
     times |window|'s [=interactionId increment=]).
</div>

<div algorithm="additions to DOM event dispatch">
  In the modifications to the DOM specification's [=event dispatch=] algorithm defined in [[EVENT-TIMING]]:

  1. Right after the step that sets |timingEntry| to the result of [=initialize and record event
     timing processing start=], run the following step:
    1. [=Set the current interaction context for event dispatch=] given |timingEntry|.
  1. Right before the step that calls [=record event timing processing end=], run the following step:
    1. [=Unset the current interaction context after event dispatch=].
</div>


Paint Timing integration {#sec-paint-timing-integration}
-----------------

This specification extends the [[PAINT-TIMING]] specification to reset paint tracking for elements
that have been modified by interactions and to trigger paint attribution for rendered documents.

<div algorithm="mark paint timing changes 1">
  Change [=mark paint timing=] to add the following step after step 1, given a {{Document}}
  |document|:

  1. [=Update the interaction context for a document and its descendants=] given |document|.
</div>

Issue(w3c/paint-timing#126): [=Mark paint time=] mixes together steps that should come before and
after the UA paints the document. The step added here is expected to occur before paint.

<div algorithm="mark paint timing changes 2">
  Change [=mark paint timing=] to add the following step after step 10.3 ([=report largest
  contentful paint=]), given a {{Document}} |document|, a [=paint timing info=] |paintTimingInfo|,
  an [=ordered set=] of [=pending image records=] |paintedImages|, and an [=ordered set=] of
  [=/elements=] |paintedTextNodes|:

  1. [=Report interaction contentful paints and soft navigations=] given |document|,
     |paintTimingInfo|, |paintedImages|, and |paintedTextNodes|.
</div>

Add the following algorithm:

<div algorithm>
 To <dfn>reset paint tracking</dfn> for a [=Node=] |node|:

  1. Reset the text element tracking |node|.
  1. Reset the image element tracking |node|.
</div>

Issue: This is a placeholder algorithm. We need to allow repaints for relevant elements, but the
repaints should not affect Element Timing or LCP. Text and images have different mechanisms for
detecting when a relevant paint has occurred, and both will need to be updated to support repaints.

Add the following algorithm:

<div algorithm>
  To <dfn>get the attribution element</dfn> for a [=Node=] |node|:

  1. If |node| is a {{Text}} [=node=], then return the {{Element}} that determines the
     [=containing block=] of |node|.
  1. Otherwise, return [=node=].
</div>

Largest Contentful Paint (LCP) integration {#sec-lcp-integration}
-----------------


Security & privacy considerations {#priv-sec}
===============================================
Exposing Soft Navigations to the performance timeline doesn't have security and privacy implications
on its own.  However, resetting the various paint timing entries as a result of a detected soft
navigation can have implications, especially before [visited links are
partitioned](https://github.com/explainers-by-googlers/Partitioning-visited-links-history).  As such, exposing
such paint operations without partitioning the :visited cache needs to only be done after careful
analysis of the paint operations in question, to make sure they don't expose the user's history
across origins.

Similarly, exposing detailed paint timing information (such as through Interaction Contentful Paint)
could potentially be used to observe paint updates when spelling or grammar error decorations (via
`::spelling-error` or `::grammar-error`) are applied. In the absence of mitigations, this could
allow an attacker to programmatically cycle through words in a text field to check if they are
present in the user's dictionary. However, browsers mitigate this by limiting spelling and grammar
checks to only occur once per user interaction (e.g. key press or click) to [prevent user dictionary
leaks](https://explainers-by-googlers.github.io/user-dictionary-leaks/). Since timing and paint
information is already observable by the developer through other standard APIs, exposing these timing
entries does not introduce any new information leaks beyond what is already constrained by the
browser's spelling/grammar highlight rate limits.




Appendix: Overlapping Interactions and Race Conditions {#sec-overlapping-interactions}
===========================================================================

<div class="non-normative">
<em>This section is non-normative.</em>

Web applications often process multiple user interactions in rapid succession. This specification
handles such overlapping interactions through the following model:

 - **Context Independence**: Each interaction manages its own [=InteractionContext=] independently.
   Multiple contexts can be "in flight" simultaneously, each tracking its own URL modifications and
   contentful paints.
 - **Active Candidate Singleton**: While many interactions can be active, the [=Document=]
   recognizes only one [=document/active soft navigation candidate=] at any given time.
 - **Preemption**: An interaction context becomes the [=document/active soft navigation candidate=]
   the moment it triggers its first same-document URL modification. If a subsequent interaction
   modification occurs, it preempts the previous one and becomes the new candidate.
 - **Emission Validation**: A {{PerformanceSoftNavigation}} is only emitted for the interaction
   context that is the [=document/active soft navigation candidate=] at the moment the emission
   criteria (URL change + contentful paint) are met. This ensures that soft navigation reporting
   remains consistent with the document's current visual and navigation state.
 - **Persistent Attribution**: Even if an interaction is preempted as a soft navigation candidate,
   it continues to attribute and report its own {{InteractionContentfulPaint}} entries as long as it
   remains active. This allows for accurate measurement of concurrent rendering updates that are not
   themselves considered "navigations."

</div>