Overview.bs

<pre class="metadata">
Title: CSS Viewport Module Level 1
Level: 1
Shortname: css-viewport
Group: CSSWG
Status: FPWD
Date: 2024-01-25
Prepare for TR: yes
Work Status: Exploring
TR: http://www.w3.org/TR/css-viewport-1/
ED: https://drafts.csswg.org/css-viewport-1/
Previous Version: http://www.w3.org/TR/2016/WD-css-device-adapt-1-20160329/
Editor: Florian Rivoal, Invited Expert, https://florian.rivoal.net, w3cid 43241
Editor: Emilio Cobos Álvarez, Mozilla, emilio@mozilla.com, w3cid 106537
Former Editor: Matt Rakow, Microsoft, w3cid 62267
Former Editor: Rune Lillesveen, Opera Software, rune@opera.com
Former Editor: Ryan Betts, Adobe Systems, rbetts@adobe.com
Former Editor: Øyvind Stenhaug, Opera Software, oyvinds@opera.com
Abstract: This specification provides a way for an author to specify, in CSS, the size, zoom factor, and orientation of the viewport that is used as the base for the initial containing block.
Issue Tracking: CSSWG GitHub https://github.com/w3c/csswg-drafts/labels/css-viewport-1
Ignored Vars: <viewport-length>
</pre>

<pre class="anchors">
spec: virtual-keyboard; urlPrefix: https://w3c.github.io/virtual-keyboard
	type: interface; text: VirtualKeyboard; url: dom-virtualkeyboard
	type: attribute; text: overlaysContent; for: VirtualKeyboard; url: dom-virtualkeyboard-overlayscontent
</pre>

<pre class="anchors">
spec: fenced-frames; urlPrefix: https://wicg.github.io/fenced-frame/
	type: interface; text: FencedFrames
</pre>

<pre class=link-defaults>
	spec:webdriver2; type:dfn; text:remote end steps
	spec:webdriver2; type:dfn; text:error
</pre>

<h2 id="intro">
Introduction</h2>

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

CSS 2.1 [[!CSS21]] specifies an
<a href="https://www.w3.org/TR/CSS21/visudet.html#containing-block-details">
initial containing block</a> for [=continuous media=] that has the dimensions
of the <a href="https://www.w3.org/TR/CSS21/visuren.html#viewport">
viewport</a>. Since the viewport is generally no larger than the display,
devices with smaller displays such as phones or tablets typically present
a smaller viewport than larger devices like desktop or laptops.

Unfortunately, many documents have historically been designed against larger
viewports and exhibit a variety of bugs when viewed in smaller viewports.
These include unintended layout wrapping, clipped content, awkward scrollable
bounds, and script errors. To avoid these issues, mobile browsers generally
use a fixed initial containing block width that mimics common desktop browser
window size (typically 980-1024px). The resulting layout is then scaled down
to fit in the available screen space.

Although this approach mitigates the issues mentioned above, the downscaling
means the CSS pixel size will be smaller than
<a href="https://www.w3.org/TR/CSS21/syndata.html#length-units">recommended</a>
by CSS 2.1. Users will likely need to zoom on the content to view it
comfortably.

This mitigation is unnecessary for sites that have been designed to work
well on small viewports.

Issue: This specification is written from an implementation-centric point of view,
making it arguably difficult to read.
Significant editorial work may be needed
to make it more understandable to different audiences.
It also should clarify which viewport is referred to by various js APIs.
See <a href="http://www.quirksmode.org/blog/archives/2015/09/a_new_device_ad.html">this blog post by ppk</a>
for a good discussion of these issues.

Issue: Various issues about this specification and related specifications
are listed in <a href="https://www.w3.org/Graphics/SVG/WG/wiki/Proposals/Investigation_of_APIs_for_Level_of_detail#The_issues_on_existing_APIs">this report</a>.
</div>

<h2 id="the-viewport">
The viewport</h2>

In CSS 2.1 a <a href="https://www.w3.org/TR/CSS21/visuren.html#viewport">viewport</a>
is a feature of a user agent for [=continuous media=] and used to
establish the initial containing block for [=continuous media=].
For [=paged media=], the initial containing block is based on the page area.
The page area can be set through ''@page'' rules.

This specification introduces a way of overriding the size of the viewport
provided by the user agent (UA). Because of this, we need to introduce the
difference between the ''initial viewport'' and the ''actual viewport''.

<dl>
	<dt><dfn>initial viewport</dfn></dt>
	<dd>
		This refers to the viewport before any UA or author styles have
		overridden the viewport given by the window or viewing area of the UA.
		Note that the ''initial viewport'' size will change with the
		size of the window or viewing area.</dd>
	<dt><dfn>actual viewport</dfn></dt>
	<dd>
		This is the viewport you get after processing the viewport
		<code>&lt;meta&gt;</code> tag.
	</dd>
</dl>

ISSUE: Make ''actual viewport'' the layout viewport, define visual viewport.

When the ''actual viewport'' cannot fit inside the window or
viewing area, either because the ''actual viewport'' is
larger than the ''initial viewport'' or the zoom factor
causes only parts of the ''actual viewport'' to be visible,
the UA should offer a scrolling or panning mechanism.

It is recommended that initially the upper-left corners of the
''actual viewport'' and the window or viewing area are aligned if the
base direction of the document is ltr. Similarly, that the upper-right
corners are aligned when the base direction is rtl. The base direction
for a document is defined as the computed value of the 'direction'
property for the first <code class=html>&lt;BODY&gt;</code> element of
an HTML or XHTML document. For other document types, it is the
computed 'direction' for the root element.

<h3 id="display-feature"><dfn>Display feature</dfn> definition</h3>
A display feature is a hardware feature that acts as a divider
and creates logically separate region of the viewport called {{segments}}.
It can be a fold area of a device with a foldable screen or a physical
split occupying a logical space within the viewport for example some dual
screen models.

Below is an illustration describing the concept of display features and how
they divide the viewport in {{segments}}:

<img src="display_features_general.svg" alt="Two images,
showing two display feature configurations and the respective segments.
One image is showing an vertical display feature, the other is showing
an horizontal display feature" style="width: 70%;height: auto; margin:auto; display: flex;">


<h2 id="viewport-meta">
Viewport <code class=html>&lt;meta&gt;</code> element</h2>

Issue: Specify me

<h3 id="meta-properties">
Properties</h3>

The recognized properties in the viewport
<code class=html>&lt;meta&gt;</code> element are:

<ul>
	<li><code class="index" lt="width!!viewport meta">width</code></li>
	<li><code class="index" lt="height!!viewport meta">height</code></li>
	<li><code class="index">initial-scale</code></li>
	<li><code class="index">minimum-scale</code></li>
	<li><code class="index">maximum-scale</code></li>
	<li><code class="index">user-scalable</code></li>
	<li><code class="index">interactive-widget</code></li>
</ul>

<h3 id="parsing-algorithm">
Parsing algorithm</h3>

Below is an algorithm for parsing the <code class=html>content</code>
attribute of the <code class=html>&lt;meta&gt;</code> tag produced
from testing Safari on the iPhone. <span class="note"> The testing was
done on an iPod touch running iPhone OS 4. The UA string of the
browser: <code>"Mozilla/5.0 (iPod; U; CPU iPhone OS 4_0 like Mac OS X;
en-us) AppleWebKit/532.9 (KHTML, like Gecko) Version/4.0.5
Mobile/8A293 Safari/6531.22.7"</code>.</span> The pseudo code notation
used is based on the notation used in [[Algorithms]].

The whitespace class contains the following characters (ascii):

<ul>
	<li>Horizontal tab (0x09)</li>
	<li>Line feed (0x0a)</li>
	<li>Carriage return (0x0d)</li>
	<li>Space (0x20)</li>
</ul>

The recognized separator between property/value pairs is comma for the
Safari implementation. Some implementations have supported both commas
and semicolons. Because of that, existing content use semicolons instead
of commas. Authors should be using comma in order to ensure content works
as expected in all UAs, but implementors may add support for both to ensure
interoperability for existing content.

The separator class contains the following characters (ascii), with
comma as the preferred separator and semicolon as optional:

<ul>
	<li>Comma (0x2c)</li>
	<li>Semicolon (0x3b)</li>
</ul>

<style>
	/* Style for algorithm pseudo code. */

	#algorithm {
		font-family: serif;
		font-size: 1em;
		white-space: pre;
		margin: 1em;
		padding: 1em;
	}

	#algorithm .method {
		counter-reset: statement;
		line-height: 1.5em;
	}

	#algorithm .method-name {
		font-variant: small-caps;
	}

	#algorithm .statement {
		counter-increment: statement;
	}

	#algorithm .statement:before {
		content: counter(statement) "   ";
		display: inline-block;
		width: 2em;
	}

	#algorithm .keyword {
		font-weight: bold;
	}
</style>

<pre id="algorithm">
	<span class="method"><span class="method-name">Parse-Content</span>(<span class="variable">S</span>)</span>
	<span class="statement"><span class="variable">i</span> &larr; 1</span>
	<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>]</span>
	<span class="statement">	<span class="keyword">do</span> <span class="keyword">while</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] in [whitespace, separator, '=']</span>
	<span class="statement">		<span class="keyword">do</span> <span class="variable">i</span> &larr; <span class="variable">i</span> + 1</span>
	<span class="statement">	<span class="keyword">if</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>]</span>
	<span class="statement">		<span class="keyword">then</span> <span class="variable">i</span> &larr; <span class="method-name">Parse-Property</span>(<span class="variable">S</span>, <span class="variable">i</span>)</span>

	<span class="method"><span class="method-name">Parse-Property</span>(<span class="variable">S</span>, <span class="variable">i</span>)</span>
	<span class="statement"><span class="variable">start</span> &larr; <span class="variable">i</span></span>
	<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] <span class="keyword">not</span> in [whitespace, separator, '=']</span>
	<span class="statement">	<span class="keyword">do</span> <span class="variable">i</span> &larr; <span class="variable">i</span> + 1</span>
	<span class="statement"><span class="keyword">if</span> <span class="variable">i</span> &gt; <span class="op">length</span>[<span class="variable">S</span>] or <span class="variable">S</span>[<span class="variable">i</span>] in [separator]</span>
	<span class="statement">	<span class="keyword">then</span> <span class="keyword">return</span> <span class="variable">i</span></span>
	<span class="statement"><span class="variable">property-name</span> &larr; <span class="variable">S</span>[<span class="variable">start</span> .. (<span class="variable">i</span> - 1)]</span>
	<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] <span class="keyword">not</span> in [separator, '=']</span>
	<span class="statement">	<span class="keyword">do</span> <span class="variable">i</span> &larr; <span class="variable">i</span> + 1</span>
	<span class="statement"><span class="keyword">if</span> <span class="variable">i</span> &gt; <span class="op">length</span>[<span class="variable">S</span>] or <span class="variable">S</span>[<span class="variable">i</span>] in [separator]</span>
	<span class="statement">	<span class="keyword">then</span> <span class="keyword">return</span> <span class="variable">i</span></span>
	<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] in [whitespace, '=']</span>
	<span class="statement">	<span class="keyword">do</span> <span class="variable">i</span> &larr; <span class="variable">i</span> + 1</span>
	<span class="statement"><span class="keyword">if</span> <span class="variable">i</span> &gt; <span class="op">length</span>[<span class="variable">S</span>] or <span class="variable">S</span>[<span class="variable">i</span>] in [separator]</span>
	<span class="statement">	<span class="keyword">then</span> <span class="keyword">return</span> <span class="variable">i</span></span>
	<span class="statement"><span class="variable">start</span> &larr; <span class="variable">i</span></span>
	<span class="statement"><span class="keyword">while</span> <span class="variable">i</span> &le; <span class="op">length</span>[<span class="variable">S</span>] and <span class="variable">S</span>[<span class="variable">i</span>] <span class="keyword">not</span> in [whitespace, separator, '=']</span>
	<span class="statement">	<span class="keyword">do</span> <span class="variable">i</span> &larr; <span class="variable">i</span> + 1</span>
	<span class="statement"><span class="variable">property-value</span> &larr; <span class="variable">S</span>[<span class="variable">start</span> .. (<span class="variable">i</span> - 1)]</span>
	<span class="statement"><span class="method-name">Set-Property</span>(<span class="variable">property-name</span>, <span class="variable">property-value</span>)</span>
	<span class="statement"><span class="keyword">return</span> <span class="variable">i</span></span>
</pre>

<span class="method-name">Set-Property</span> matches the
<a href="#meta-properties">listed property names</a> case-insensitively.
The <code class="variable">property-value</code> strings are interpreted
as follows:

<ol>
	<li>
		If a prefix of <code class="variable">property-value</code>
		can be converted to a number using <code>strtod</code>, the
		value will be that number. The remainder of the string is
		ignored.
	</li>
	<li>
		If the value can not be converted to a number as described above,
		the whole <code class="variable">property-value</code> string
		will be matched with the following strings
		case-insensitively: <code class="index">yes</code>,
		<code class="index">no</code>, <code class="index" lt="device-width!!viewport meta">device-width</code>,
		<code  class="index" lt="device-height!!viewport meta">device-height</code>
	</li>
	<li>
		If the string did not match any of the known strings, the
		value is unknown.
	</li>
</ol>

<h3 id="extend-to-zoom">''extend-to-zoom''</h3>

Issue: Specify extend-to-zoom behavior by the viewport meta tag

<h3 id="interactive-widget-section">''interactive-widget''</h3>

Issue: Move the definition of ''visual viewport'' from CSSOM-View to this spec.

The <dfn export><code>interactive-widget</code></dfn> property specifies the effect that interactive UI
widgets have on the page's viewports. It defines whether widgets overlay a given viewport or whether
the viewport is shrunken so that it remains fully visible while the widget is showing. Interactive
UI widgets are transient user agent or operating system UI through which a user can provide input.

<div class="note">The most common such UI widget is a virtual keyboard.</div>

The following is a list of valid values for [=interactive-widget=] and the associated
viewport-resizing behavior:

<dl>
	<dt><dfn><code>overlays-content</code></dfn></dt>
	<dd>
		Interactive UI widgets MUST NOT [=resize=] the [=initial viewport=] nor
		the <a spec="CSSOM-VIEW">visual viewport</a>. The user agent must perform the same steps
		as when {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} is set to
		<code>true</code>.
	</dd>
	<dt><dfn><code>resizes-content</code></dfn></dt>
	<dd>
		Interactive UI widgets MUST [=resize=] the [=initial viewport=] by the interactive widget.
	<div class="note">
		Since the <a spec="CSSOM-VIEW">visual viewport</a>'s size is derived from the
		[=initial viewport=], [=resizes-content=] will cause a resize of both the initial and visual
		viewports.
	</div>
	</dd>
	<dt><dfn><code>resizes-visual</code></dfn></dt>
	<dd>
		Interactive UI widgets MUST [=resize=] the <a spec="CSSOM-VIEW">visual viewport</a> but MUST
		NOT [=resize=] the <a spec="CSS-VIEWPORT">initial viewport</a>.
	</dd>
</dl>

If no value, or an invalid value, is set for [=interactive-widget=], the behavior implied by
[=resizes-visual=] is used as the default.

To <dfn lt="resize">resize a viewport by an interactive widget</dfn>, subtract from it the
intersection of the viewport rect with the widget's OS reported bounding rect. In cases where this
would result in a non-rectangular viewport, the behavior is user agent defined.

<div class="note">
	Some examples where the result would non rectangular: a
	<a href="https://support.apple.com/en-ca/HT207521">floating or split keyboard</a>, or a keyboard that
	<a href="https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/VirtualKeyboardAPI/explainer.md#motivation">
	occupies only part</a> of the viewport.
</div>

<h4 id="interaction-with-virtualkeyboard-overlayscontent">
	Interaction with virtualKeyboard.overlaysContent
</h4>

[[!VIRTUAL-KEYBOARD]] provides an imperative API to apply the [=overlays-content=] behavior via
the {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} attribute. This attribute
shadows the value set to [=interactive-widget=], namely:

When {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} is set to
<code>true</code>, the UA MUST ignore any value set to [=interactive-widget=] when determining the
resizing behavior of interactive widgets.

When {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} is set to
<code>false</code>, the UA MUST use the value set to [=interactive-widget=], or the default behavior
if a value is not set, when determining the resizing behavior of interactive widgets.

Getting the value of {{VirtualKeyboard/overlaysContent|VirtualKeyboard.overlaysContent}} MUST return
only the value previously set to it.

<div class="note">
	That is, unless previously set, <code>VirtualKeyboard.overlaysContent</code> returns false
	even if <code>interactive-widget=overlays-content</code> is set via the <code>&lt;meta&gt;</code>
	tag.
</div>

<pre class=biblio>
{
	"Algorithms": {
		"authors": [
			"Thomas H. Cormen; et al"
		],
		"title": "Introduction to Algorithms, Second Edition, MIT Press",
		"publisher": "MIT Press"
	}
}
</pre>

<h2 id='zoom-property'>
	The 'zoom' property
</h2>

An element becomes zoomed when the 'zoom' property has a positive computed value different than 1
(or when a flat tree ancestor has zoom).

To apply zoom, the [=used value=] of a CSS property (including values inside of [=path()=] strings) is pre-multiplied
(before any other steps in the [=used value=] stage)
by the [=used value=] of 'zoom' for the element.
It also multiplies the [=natural size=] of all replaced elements,
background images,
and nested frames
(except for fenced frames [[!FENCED-FRAME]])
by the [=used value=] of 'zoom'.

Note: This results in a magnification or minification effect.

Note: Since this multiplication is on [=computed value=]s, it applies to
all inherited properties such as 'line-height' and 'font-size'.

Nested values of 'zoom' multiply, resulting in additional scaling of <<length>> values.
The [=used value=] for zoom is always its [=effective zoom=].

The 'zoom' property has no effect on <<length>> property values with computed values that are 'auto' or <<percentage>>.

Note: Unlike 'transform',
scaling the 'zoom' property affects layout.

Note: The computed value of 'font-size' is never <<percentage>>;
thus 'zoom' always applies.

Note: 'zoom' does not affect or prevent 'transform' scaling.

<pre class="propdef">
	Name: zoom
	Value: <<number [0,∞]>> || <<percentage [0,∞]>>
	Initial: 1
	Applies to: all <<length>> property values of all elements
	Inherited: no
	Percentages: Converted to <<number>>
	Media: visual
	Computed value: as specified, but with <<percentage>> converted to the equivalent <<number>>
	Animation type: not animatable
</pre>

The values of this property have the following meanings:

<dl dfn-for="zoom" dfn-type=value>
	<dt><dfn><<number>></dfn>
	<dd>
		Positive floating point number indicating a zoom factor.
		Numbers smaller than 1.0 indicate a "zoom out" or minification effect,
		while numbers greater than 1.0 indicate a "zoom in" or magnification effect.
		A 0 value is treated as if it was 1.

		Note: The treatment of 0 is a web compatibility quirk.

	<dt><dfn><<percentage>></dfn>
	<dd>
		Positive floating point number,
		followed by a percentage character ("%") which indicates a zoom factor multiplied by 100.
		A 0 percentage is treated as if it was 100%.

		Note: The treatment of 0 is a web compatibility quirk.

</dl>

Negative values for 'zoom' are illegal.

<div class="example">
	Example of the 'zoom' property applied during hover for magnification effect.

	<pre>
		&lt;div class="messageBox"&gt;
			&lt;div class="label"&gt;Text of the label&lt;/div&gt;
		&lt;/div&gt;

		&lt;style&gt;
		.messageBox {
		    width: 10em;
		    padding: 2em;
		    border: medium solid lightblue;
		}

		.messageBox:hover {
		    zoom: 150%;
		}

		.label {
		    background: lightgrey;
		    padding: 1em;
		    text-align: center;
		}
		&lt;/style&gt;
	</pre>

	Here is an llustration of the before and after hover state of the message box element:
	<img src="css_zoom_hover_example.png" alt="Two images,
	showing the zooming effect before and after zoom has applied. The second is 1.5 larger.">
</div>

<div class="example">
	Example of nested zoom.
	In this example, "Inner text" is 4x as large as "Outer text",
	and "Middle text" is 2x as large as "Outer text".

	<pre>
		&lt;div style="zoom: 2"&gt;
		  Middle text
			&lt;div style="zoom: 2"&gt;
			   Inner text
			&lt;div&gt;
		&lt;div&gt;
		Outer text
	</pre>	 
</div>

<div class="example">
	Example of replaced elements. In this example,
	the image and iframe will be twice as large as their default sizing.

	<pre>
	&lt;div style="zoom: 2"&gt;
		&lt;img src="..."&gt;
		&lt;iframe src="..."&gt;&lt;/iframe&gt;
	&lt;div&gt;
	</pre>	 
</div>

The <dfn export>effective zoom</dfn> of an element is the product of its computed
value of 'zoom' and all flat tree ancestors' computed values of 'zoom'.

The <dfn export>scaled</dfn> value of a CSS length is the [=used value=] of that length;
in particular it includes zoom.

The <dfn export>unscaled</dfn> value of a CSS length relative to an element is the [=scaled=] value divided by the element's [=effective zoom=].

<div class="note">
	The [=effective zoom=] of an element in a nested frame may be a value other than 1 even if 'zoom' is never set on an element in that frame. This can be observed by authors via APIs such as {{Window/devicePixelRatio}} and {{Element/getBoundingClientRect}}.
</div>

<h3 id='zoom-om'>
	DOM and CSSOM interaction
</h3>

	Computed style APIs (i.e., all values returned by {{getComputedStyle()}}) that are non-auto and non-percentage lengths must be [=unscaled=].

	The {{Element/getBoundingClientRect}},
	{{Element/getClientRects}},
	and {{IntersectionObserver}} APIs must return rects with [=scaled=]
	lengths.

	All other APIs related to element geometries must return [=unscaled=] lengths
	(except as detailed below).
	This is explained in detail in [[cssom-view#extensions-to-the-htmlelement-interface]].

	In cases where properties (such as {{Element/scrollTop}}) are propagated to the viewport,
	APIs for these lengths must be in viewport units,
	and not be divided by the zoom of the element.

	The {{Window/devicePixelRatio}} of a frame is multiplied by the [=effective zoom=] inherited by its parent frame.

<h2 id=extensions-to-the-window-interface>Extensions to the {{Window}} Interface</h2>

<pre class=idl>
partial interface Window {
[SameObject, Replaceable] readonly attribute Viewport viewport;
};
</pre>

<h2 id=viewport>Viewport</h2>

<h3 id="the-viewport-interface">The {{Viewport}} Interface</h3>

<pre class=idl>
[Exposed=Window]
interface Viewport {
	readonly attribute FrozenArray&lt;DOMRect>? segments;
};
</pre>

<h2 id='segments'>
	The <dfn attribute for=Viewport>segments</dfn> property
</h2>

The {{segments}} property is an array of {{DOMRect}} that represent the dimensions of each existing viewport segment.
Each {{DOMRect}} contains the geometry of the segment (x, y, width, height) in CSS ''<length>/px''.

Additonal details about the definition of a viewport segment can be found here: [[css-env-1#viewport-segments]].

The {{segments}} attribute getter steps are:
1. If the {{Viewport}}'s associated {{Document}} is not <a>fully active</a>, return null.
2. Let |topLevelTraversable| be |document|'s [=relevant global object=]'s [=/navigable=]'s [=browsing context/top-level traversable=].
3. If |topLevelTraversable|.[=[[DisplayFeaturesOverride]]=] is non-null, return {{Viewport}}'s [[css-env-1#viewport-segments|segments]] array calculated from |topLevelTraversable|.[=[[DisplayFeaturesOverride]]=].
4. Returns null if there is only a single viewport segment and abort these steps.
5. Otherwise, return the {{Viewport}}'s [[css-env-1#viewport-segments|segments]] array calculated from the hardware features.

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

The {{segments}} property represents an immutable snapshot of the device {{segments}} when the value was queried.
If the device state changes (rotation, window resize, <a spec="DEVICE-POSTURE">posture</a> change), the value previously retrieved will be invalid. Developers can listen to {{ScreenOrientation/onchange|Screen Orientation}}, {{Window/resize|Window Resize}}, or {{DevicePosture/onchange|Posture}} changes events to detect device state changes.

<div class="example">
If a viewport of 400px by 400px is split horizontally into two side-by-side segments, the {{segments}} array will have the following content:
<code highlight=javascript>[DOMRect(0, 0, 400, 200), DOMRect(0, 200, 400, 200)]</code>
</div>

</div>

<h2 class="no-num" id="changes">Appendix A. Changes</h2>

This appendix is <em>informative</em>.

<h3 class="no-num">Since the 
	<a href="http://www.w3.org/TR/2016/WD-css-device-adapt-1-20160329/">29 
		March 2016 Working Draft</a>
</h3>

<ul>
	<li>Added 'interactive-widgets' property to viewport meta</li>
	<li>Removed @viewport rule</li>
	<li>Renamed spec from device-adapt to css-viewport</li>
	<li>CSSViewportRule exposed to Window</li>
</ul>

<h3 class="no-num">Since the 
	<a href="https://www.w3.org/TR/2011/WD-css-device-adapt-20110915/">15 
		September 2011 First Public Working Draft</a>.
</h3>

<ul>
	<li>Made various editorial improvements and clarifications.
	<li>Added OM Interfaces.
	<li>Added semi-colon as separator in meta viewport.
	<li>Created UA stylesheets section.
	<li>Added recommendation for when to respect orientation property.
	<li>Dropped support for the resolution descriptor.
	<li>Decouple width/height and zoom, introducing ''extend-to-zoom'' value for meta viewport translation.
	<li>Made normative rules about interaction of @viewport and @media.
	<li>Allow 0 for <<viewport-length>> and '@viewport/zoom' values
	<li>Removed support for device-width/height.
	<li>Apply @viewport to top level document only.
	<li>Extend [[!CSS3-CONDITIONAL]] rather than CSS21 for nesting in @media.
	<li>Removed @viewport
</ul>

<h2 class="no-num" id="automation">Appendix B. Automation</h2>

<h3>Automation of the {{segments}} property</h3>
The {{segments}} property poses a challenge to test authors, as exercising this property
requires access to specific hardware devices. To address this challenge this document defines
[[WEBDRIVER2]] [=extension commands=] that allow users to control how the viewport is split by
one or more [=display feature| display features=] (such as a fold or a hinge between two separate displays).

A <dfn>display feature override</dfn> is a [=struct=] encapsulating the result of a single display feature.
It has a <dfn data-dfn-for="display feature override">orientation</dfn> (a string that is either "vertical" or "horizontal"),
a <dfn data-dfn-for="display feature override">mask length</dfn> (a positive number describing the length of the feature in CSS ''<length>/px''), and
an <dfn data-dfn-for="display feature override">offset</dfn> (which describe the distance from the origin of the viewport in CSS ''<length>/px'').

<h4 id="internal-slots">Internal slots</h4>
To support the [=extension commands=] below and their integration with
the {{segments}} attribute getter steps, [=browsing context/top-level traversables=] must have the following
internal slots:
<table class="def">
<thead>
	<tr>
	<th>
		Internal slot
	</th>
	<th>
		Description
	</th>
	</tr>
</thead>
<tbody>
	<tr>
	<td>
		<dfn data-dfn-for="top-level traversable">\[[DisplayFeaturesOverride]]</dfn>
	</td>
	<td>
		List of [=display feature override=] that overrides those provided by the hardware, or <code>null</code>.
	</td>
	</tr>
</tbody>
</table>

<h4 id="extension-commands">Extensions Commands</h4>

<h5 id="set-display-features">Set display features</h5>
<table class="def">
	<tr>
		<th>
			HTTP Method
		</th>
		<th>
			[=extension command URI Template|URI Template=]
		</th>
	</tr>
	<tr>
		<td>
			POST
		</td>
		<td>
			/session/{session id}/displayfeatures
		</td>
	</tr>
</table>

This [=extension command=] creates a setup that emulates a set of [=display feature override=] by taking a list of display features as
parameter.

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

	This section exists because the input format is not trivial. Here is a pseudo IDL example on
	how a [=display feature override=] is defined:
	<pre class="idl">
		enum OrientationType {
			"vertical",
			"horizontal"
		};

		interface DisplayFeature {
			readonly attribute OrientationType orientation;
			readonly attribute double offset;
			readonly attribute double maskLength;
		};
	</pre>

	Below is an illustration showing the various properties of a display feature:

	<img src="display_features.svg" alt="Two images,
	showing the meaning of each display feature attributes. One image is showing an
	vertical display feature, the other is showing an horizontal display feature" style="width: 70%;height: auto; margin:auto; display: flex;">

	<div class="example">
		To create a [=[[DisplayFeaturesOverride]]=] in the <a spec="WEBDRIVER2">current browsing context</a> of the [=session=] with ID 23,
		the [=local end=] would POST to `/session/23/displayfeatures` with the body:
		<pre class="lang-json">
		{
			"features": [
				{
					"orientation": "horizontal",
					"offset": 190,
					"maskLength": 20
				}
			]
		}
		</pre>
		Considering a viewport of 400px by 400px the command will result of a {{segments}} property with the following content:
		<code highlight=javascript>[DOMRect(0, 0, 400, 190), DOMRect(0, 210, 400, 190)]</code>
	</div>
</div>

<div>
The [=remote end steps=] are:
</div>
<ol>
	<li>Let |features| be the result of invoking <a spec="WEBDRIVER2">getting a property</a> "features" from
	|parameters|.
	</li>
	<li>If |features| is not a {{Array}}, return [=error=] with [=error
	code|WebDriver error code=] [=invalid argument=].
	</li>
	<li>Let |parsedFeatures| be a new <a spec=infra>list</a> of [=display feature override=].</li>
	<li>For each |feature item| in |features|:
		<ol>
			<li>If |feature item| is not an {{Object}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].</li>
			<li>Let |mask length| be the result of invoking <a spec="WEBDRIVER2">getting a property</a> "maskLength" from |feature item|.</li>
			<li>If |mask length| is not a {{Number}} or its value is {{Number/NaN}}, +∞, −∞, or negative return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
			<li>Let |offset| be the result of invoking <a spec="WEBDRIVER2">getting a property</a> "offset" from |feature item|.</li>
			<li>If |offset| is not a {{Number}} or its value is {{Number/NaN}}, +∞, −∞, or negative return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
			<li>Let |orientation| be the result of invoking <a spec="WEBDRIVER2">getting a property</a> "orientation" from |feature item|.</li>
			<li>If |orientation| is not a {{string}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].</li>
			<li>If |orientation| is neither "vertical" or "vertical", return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
			<li>If |orientation| is "vertical" and |mask length| + |offset| is greater than viewport width including the size of the rendered scrollbar, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].</li>
			<li>If |orientation| is "vertical" and |mask length| + |offset| is greater than viewport height including the size of the rendered scrollbar, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].</li>
			<li>Let |override| be a new [=display feature override=].</li>
			<li>Set |override|'s [=mask length=] to |mask length|.</li>
			<li>Set |override|'s [=orientation=] to |orientation|.</li>
			<li>Set |override|'s [=offset=] to |offset|.</li>
			<li>[=list/Append=] |override| to |parsedFeatures|.</li>
		</ol>
	</li>
	<li>Let |topLevelTraversable| be the <a spec="WEBDRIVER2">current browsing context</a>'s
	[=browsing context/top-level traversable=].
	</li>
	<li>Set |topLevelTraversable|.[=[[DisplayFeaturesOverride]]=] to |parsedFeatures|.
	</li>
	<li>Return [=success=] with data <code>null</code>.
	</li>
</ol>

<h5 id="clear-display-features">Clear display features</h5>
<table class="def">
	<tr>
		<th>
			HTTP Method
		</th>
	<th>
		[=extension command URI Template|URI Template=]
	</th>
	</tr>
	<tr>
		<td>
			DELETE
		</td>
		<td>
			/session/{session id}/displayfeatures
		</td>
	</tr>
</table>
<div>
	This [=extension command=] removes the display features override and returns
	control back to hardware.
</div>
<div>
	The [=remote end steps=] are:
</div>
<ol>
	<li>Let |topLevelTraversable| be the <a spec="WEBDRIVER2">current browsing context</a>'s 
	[=browsing context/top-level traversable=].
	</li>
	<li>Set |topLevelTraversable|. [=[[DisplayFeaturesOverride]]=] to <code>null</code>.
	</li>
	<li>Return [=success=] with data <code>null</code>.
	</li>
</ol>