@astryxdesign/core 0.7.6 → 0.7.7-canary.1d04d40

package/dist/motion/uikit/springs.js

@@ -488,6 +488,42 @@ export const BANNER_SPRING = {
   damping: 500
 };
 
+/**
+ * UISlider's release: after a finger lifts, the thumb settles on this spring
+ * toward 0.4 of the release's momentum projection. It is critically damped,
+ * so it never overshoots a target ahead of it.
+ * @source measured: UIKit lab, iOS 26.2 simulator, iPhone 17 Pro. The
+ *   `UIViewSpringAnimationBehavior` at the lift reads response 0.4 and
+ *   damping ratio 1. Four releases fit it per frame (the UIKit slider
+ *   table). Oct 23 2026
+ */
+export const SLIDER_RELEASE_SPRING = {
+  response: 0.4,
+  dampingRatio: 1
+};
+
+/**
+ * UISlider's lift: a finger's touch-down scales the thumb up on this spring.
+ * @source measured: UIKit lab, iOS 26.2 simulator, iPhone 17 Pro. The
+ *   thumb's scale per frame after touch-down (the UIKit slider table).
+ *   Oct 23 2026
+ */
+export const SLIDER_LIFT_SPRING = {
+  response: 0.215,
+  dampingRatio: 0.6
+};
+
+/**
+ * UISlider's drop: the lift's end scales the thumb back down on this spring.
+ * @source measured: UIKit lab, iOS 26.2 simulator, iPhone 17 Pro. The
+ *   thumb's scale per frame after the lift (the UIKit slider table).
+ *   Oct 23 2026
+ */
+export const SLIDER_DROP_SPRING = {
+  response: 0.5,
+  dampingRatio: 0.7
+};
+
 /**
  * Every spring above, by row name: the table the existing readers use. A
  * component imports only the rows it plays (`architecture:component-style-authoring`
@@ -527,11 +563,16 @@ export const springs = {
   switchThumbStretch: SWITCH_THUMB_STRETCH_SPRING,
   segmentedThumb: SEGMENTED_THUMB_SPRING,
   keyboard: KEYBOARD_SPRING,
-  banner: BANNER_SPRING
+  banner: BANNER_SPRING,
+  sliderRelease: SLIDER_RELEASE_SPRING,
+  sliderLift: SLIDER_LIFT_SPRING,
+  sliderDrop: SLIDER_DROP_SPRING
 };
 
 /**
- * The springs spec:AST-094 FR4 names: the only ones that are motion roles.
+ * The only springs that are motion roles. The touch presentations' record
+ * names some, and a component's own record names others, such as Slider's
+ * three. The generated motion role table lists each with its record.
  * The registry takes these rows alone, so registering ships no other spring.
  */
 const SPRING_ROLES = {
@@ -549,11 +590,14 @@ const SPRING_ROLES = {
   subMenuBack: SUB_MENU_BACK_SPRING,
   contextMenuLift: CONTEXT_MENU_LIFT_SPRING,
   contextMenuDismiss: CONTEXT_MENU_DISMISS_SPRING,
-  contextMenuMorph: CONTEXT_MENU_MORPH_SPRING
+  contextMenuMorph: CONTEXT_MENU_MORPH_SPRING,
+  sliderRelease: SLIDER_RELEASE_SPRING,
+  sliderLift: SLIDER_LIFT_SPRING,
+  sliderDrop: SLIDER_DROP_SPRING
 };
 
 /**
- * Registers the springs spec:AST-094 FR4 names as internal motion roles
+ * Registers the role springs (`SPRING_ROLES`) as internal motion roles
  * (motion/roles.ts), by their row names (`springs.settle`). Every other
  * spring, UIKit's menu spring under Reduce Motion and the keyboard's
  * included, is not a role. Nothing registers on import: the touch code that

package/dist/utils/selectionLock.d.ts

@@ -10,4 +10,47 @@ export declare function locksSelectionFor(pointerType: string): boolean;
  * any holder holds. Idempotent release.
  */
 export declare function lockSelection(elements: Iterable<Element>, target: EventTarget | null): () => void;
+/** How a drag's selection hold ends: at a lift, or at a cancel. */
+export interface DragSelectionReleaseOptions {
+    /**
+     * The press was cancelled (a pointercancel, a blur, a detach), so no
+     * mouseup or click follows: the hold ends at once. Called again after a
+     * lift, it ends the hold's last task at once too.
+     */
+    isCancel?: boolean;
+}
+/**
+ * Refuse a new selection while a mouse or pen drag that a recognizer claimed
+ * runs, until the returned function runs. `kept` is the page's selection
+ * when the press began, and it stays. Anything that replaces it while the
+ * drag runs is put back to it. That includes the press's own collapse and a
+ * selection the drag started before its claim. So the drag takes no new
+ * selection and never clears an existing one. `elements` refuse a
+ * selection with inline styles, on every engine. The document refuses one
+ * too, because WebKit extends a drag's selection over text outside the
+ * elements without another `selectstart`. So a `selectstart` anywhere is
+ * refused, and the selection is put back. A `selectstart` does not leave its
+ * shadow tree. So the document refuses only one that starts outside every
+ * shadow tree, and a claiming element inside one refuses its own. The
+ * press's own `mouseup` and `click` come after its `pointerup` in the same
+ * task, and WebKit settles the drag's selection there. So the document's
+ * hold ends a task after a lift. A cancel ends it at once, because nothing
+ * follows a cancel. `onReleased` runs once the document's hold has ended.
+ * The page listeners exist only during a press. Idempotent.
+ */
+export declare function lockDragSelection(elements: Iterable<Element>, view: Window | null | undefined, kept: ReadonlyArray<AbstractRange>, onReleased?: () => void): (options?: DragSelectionReleaseOptions) => void;
+/**
+ * The page's selection now, its ranges copied; none for a collapsed or empty
+ * one. A drag's hold keeps what this read when the press began.
+ */
+export declare function selectionRangesOf(view: Window | null | undefined): ReadonlyArray<AbstractRange>;
+/**
+ * Whether a press at (`x`, `y`) lands on text a drag would select. That is a
+ * text field, or a character of non-empty text whose element allows a
+ * selection. A native button's label, slotted or not, is not selectable text,
+ * because the engine starts no selection from a drag inside a button. A point
+ * beside text, which a caret query snaps to the nearest character, lands on
+ * none. Where the engine has no caret query, nothing is selectable text.
+ */
+export declare function startsOnSelectableText(doc: Document, x: number, y: number, target: EventTarget | null): boolean;
 //# sourceMappingURL=selectionLock.d.ts.map

package/dist/utils/selectionLock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selectionLock.d.ts","sourceRoot":"","sources":["../../src/utils/selectionLock.ts"],"names":[],"mappings":"AAkDA;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE9D;AAWD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAC3B,MAAM,EAAE,WAAW,GAAG,IAAI,GACzB,MAAM,IAAI,CAyEZ"}
+{"version":3,"file":"selectionLock.d.ts","sourceRoot":"","sources":["../../src/utils/selectionLock.ts"],"names":[],"mappings":"AAoDA;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE9D;AAWD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAC3B,MAAM,EAAE,WAAW,GAAG,IAAI,GACzB,MAAM,IAAI,CA4BZ;AAED,mEAAmE;AACnE,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,IAAI,EAAE,aAAa,CAAC,aAAa,CAAC,EAClC,UAAU,CAAC,EAAE,MAAM,IAAI,GACtB,CAAC,OAAO,CAAC,EAAE,2BAA2B,KAAK,IAAI,CA+EjD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B,aAAa,CAAC,aAAa,CAAC,CAiB9B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,QAAQ,EACb,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,WAAW,GAAG,IAAI,GACzB,OAAO,CA+CT"}

package/dist/utils/selectionLock.js

@@ -3,11 +3,12 @@
 /**
  * @file selectionLock.ts
  * @input The elements a held touch contact presses, and the touch's target
- * @output lockSelection: no text selection and no touch callout under the
- *   held finger until the release runs; and locksSelectionFor: which contacts
- *   take it
- * @position Brought by the recognizers whose hold does something. The gesture
- *   host calls it and never imports it.
+ * @output lockSelection and locksSelectionFor give a held finger's lock.
+ *   lockDragSelection gives a claimed mouse or pen drag's hold, which keeps
+ *   the page's selection. startsOnSelectableText and selectionRangesOf are
+ *   what a mouse or pen press reads.
+ * @position Recognizers whose hold does something bring lockSelection; the
+ *   gesture host imports the drag hold and the press reads.
  *
  * SYNC: When modified, update GestureHost.ts and utils/pressFeedback.ts; the
  * iOS query matches utils/touchPresentation.ts.
@@ -27,7 +28,8 @@
 //
 // A mouse never takes the lock, so its released behavior stays (AST-017).
 
-import { containsAlongFlatTree } from "./flatTree.js";
+import { containsAlongFlatTree, parentAcrossShadow } from "./flatTree.js";
+import { subscribeInput } from "./inputStream.js";
 import { isIosWebKit } from "./touchQueries.js";
 
 /** What a held finger must not start on a control or a cell. */
@@ -77,6 +79,392 @@ export function lockSelection(elements, target) {
       }
     };
   }
+  return lockStyles(set);
+}
+
+/** How a drag's selection hold ends: at a lift, or at a cancel. */
+
+/**
+ * Refuse a new selection while a mouse or pen drag that a recognizer claimed
+ * runs, until the returned function runs. `kept` is the page's selection
+ * when the press began, and it stays. Anything that replaces it while the
+ * drag runs is put back to it. That includes the press's own collapse and a
+ * selection the drag started before its claim. So the drag takes no new
+ * selection and never clears an existing one. `elements` refuse a
+ * selection with inline styles, on every engine. The document refuses one
+ * too, because WebKit extends a drag's selection over text outside the
+ * elements without another `selectstart`. So a `selectstart` anywhere is
+ * refused, and the selection is put back. A `selectstart` does not leave its
+ * shadow tree. So the document refuses only one that starts outside every
+ * shadow tree, and a claiming element inside one refuses its own. The
+ * press's own `mouseup` and `click` come after its `pointerup` in the same
+ * task, and WebKit settles the drag's selection there. So the document's
+ * hold ends a task after a lift. A cancel ends it at once, because nothing
+ * follows a cancel. `onReleased` runs once the document's hold has ended.
+ * The page listeners exist only during a press. Idempotent.
+ */
+export function lockDragSelection(elements, view, kept, onReleased) {
+  const doc = view?.document ?? null;
+  const roots = shadowRootsOfRanges(kept);
+  const restore = () => {
+    const selection = view?.getSelection();
+    // The focused field keeps its own selection (a drag never starts in one).
+    if (selection == null || isTextEntry(deepActiveElement(doc))) {
+      return;
+    }
+    const held = heldRanges(selection, roots);
+    if (kept.length === 0) {
+      if (held.some(range => !range.collapsed)) {
+        selection.removeAllRanges();
+      }
+      return;
+    }
+    // A render can remove what the kept selection held: then there is
+    // nothing to put back.
+    if (sameRanges(held, kept) || !kept.every(isValidRange)) {
+      return;
+    }
+    selectRanges(selection, kept);
+  };
+  restore();
+  const set = new Set(elements);
+  const refuse = event => {
+    if (!isTextEntry(event.target)) {
+      event.preventDefault();
+    }
+  };
+  for (const element of set) {
+    element.addEventListener('selectstart', refuse);
+  }
+  const stopDocument = view == null ? [] : [subscribeInput(view, 'selectstart', refuse, {
+    cancels: true
+  }), subscribeInput(view, 'selectionchange', restore)];
+  const unlockStyles = lockStyles(set);
+  let stage = 'held';
+  let timer = null;
+  const releaseDocument = () => {
+    if (stage === 'done') {
+      return;
+    }
+    stage = 'done';
+    if (timer != null) {
+      view?.clearTimeout(timer);
+      timer = null;
+    }
+    try {
+      restore();
+    } finally {
+      for (const stop of stopDocument) {
+        stop();
+      }
+      onReleased?.();
+    }
+  };
+  return ({
+    isCancel = false
+  } = {}) => {
+    if (stage === 'held') {
+      stage = 'lifted';
+      for (const element of set) {
+        element.removeEventListener('selectstart', refuse);
+      }
+      unlockStyles();
+      // A lift's own mouseup and click follow in its task and must still
+      // meet the hold; nothing follows a cancel, which ends it at once.
+      if (view == null || isCancel) {
+        releaseDocument();
+      } else {
+        timer = view.setTimeout(releaseDocument, 0);
+      }
+    } else if (stage === 'lifted' && isCancel) {
+      releaseDocument();
+    }
+  };
+}
+
+/**
+ * The page's selection now, its ranges copied; none for a collapsed or empty
+ * one. A drag's hold keeps what this read when the press began.
+ */
+export function selectionRangesOf(view) {
+  const selection = view?.getSelection();
+  if (selection == null) {
+    return [];
+  }
+  const composed = composedRangesOf(selection, []);
+  if (composed != null) {
+    return composed.filter(range => !range.collapsed).map(liveWhereItCan);
+  }
+  if (selection.isCollapsed) {
+    return [];
+  }
+  const ranges = [];
+  for (let index = 0; index < selection.rangeCount; index++) {
+    ranges.push(selection.getRangeAt(index).cloneRange());
+  }
+  return ranges;
+}
+
+/**
+ * Whether a press at (`x`, `y`) lands on text a drag would select. That is a
+ * text field, or a character of non-empty text whose element allows a
+ * selection. A native button's label, slotted or not, is not selectable text,
+ * because the engine starts no selection from a drag inside a button. A point
+ * beside text, which a caret query snaps to the nearest character, lands on
+ * none. Where the engine has no caret query, nothing is selectable text.
+ */
+export function startsOnSelectableText(doc, x, y, target) {
+  if (isTextEntry(target)) {
+    return true;
+  }
+  const caret = caretAt(doc, x, y, [...ownShadowRoot(target), ...openShadowRootsOf(target)]);
+  if (caret == null) {
+    return false;
+  }
+  const {
+    node,
+    offset
+  } = caret;
+  if (node.nodeType !== 3 || (node.textContent ?? '').trim() === '') {
+    return false;
+  }
+  // Text directly under a shadow root takes its host's style.
+  const element = node.parentElement ?? (node.parentNode?.nodeType === 11 ? node.parentNode.host : null);
+  if (element == null || !allowsSelection(element) || isInButton(node)) {
+    return false;
+  }
+  const length = (node.textContent ?? '').length;
+  const range = doc.createRange();
+  if (typeof range.getClientRects !== 'function') {
+    return false;
+  }
+  for (const start of [offset - 1, offset]) {
+    if (start < 0 || start >= length) {
+      continue;
+    }
+    range.setStart(node, start);
+    range.setEnd(node, start + 1);
+    for (const rect of Array.from(range.getClientRects())) {
+      if (x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/** Whether `node` is inside a native button, along the flat tree. */
+function isInButton(node) {
+  for (let at = node; at != null; at = parentAcrossShadow(at)) {
+    if (at.nodeType === 1 && at.localName === 'button') {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** The caret position the engine puts at a point, by either query. */
+function caretAt(doc, x, y, shadowRoots) {
+  const queries = doc;
+  if (typeof queries.caretPositionFromPoint === 'function') {
+    // Without the roots, a point over shadow text answers at its host.
+    const position = shadowRoots.length > 0 ? queries.caretPositionFromPoint(x, y, {
+      shadowRoots: [...shadowRoots]
+    }) : queries.caretPositionFromPoint(x, y);
+    return position == null ? null : {
+      node: position.offsetNode,
+      offset: position.offset
+    };
+  }
+  if (typeof queries.caretRangeFromPoint === 'function') {
+    const range = queries.caretRangeFromPoint(x, y);
+    return range == null ? null : {
+      node: range.startContainer,
+      offset: range.startOffset
+    };
+  }
+  return null;
+}
+
+/** Whether an element's text can be selected (`user-select` is not none). */
+function allowsSelection(element) {
+  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+  if (style == null) {
+    return false;
+  }
+  return style.getPropertyValue('user-select') !== 'none' && style.getPropertyValue('-webkit-user-select') !== 'none';
+}
+
+/**
+ * The ranges `selection` holds, with boundaries inside `shadowRoots` where the
+ * engine reads composed ranges.
+ */
+function heldRanges(selection, shadowRoots) {
+  const composed = composedRangesOf(selection, shadowRoots);
+  if (composed != null) {
+    return composed;
+  }
+  const ranges = [];
+  for (let index = 0; index < selection.rangeCount; index++) {
+    ranges.push(selection.getRangeAt(index));
+  }
+  return ranges;
+}
+
+/**
+ * A live copy of `range` when both boundaries share a root, so it follows
+ * DOM changes. A range across roots stays static: no live range holds it.
+ */
+function liveWhereItCan(range) {
+  const live = range.startContainer.ownerDocument?.createRange();
+  if (live == null || range.startContainer.getRootNode() !== range.endContainer.getRootNode()) {
+    return range;
+  }
+  live.setStart(range.startContainer, range.startOffset);
+  live.setEnd(range.endContainer, range.endOffset);
+  return live;
+}
+
+/** Whether both of `range`'s boundaries still exist in the document. */
+function isValidRange(range) {
+  return isValidBoundary(range.startContainer, range.startOffset) && isValidBoundary(range.endContainer, range.endOffset);
+}
+function isValidBoundary(node, offset) {
+  const length = node.nodeType === 3 || node.nodeType === 4 || node.nodeType === 8 ? node.length : node.childNodes.length;
+  return node.isConnected && offset >= 0 && offset <= length;
+}
+
+/** Whether two range lists have the same boundaries, in order. */
+function sameRanges(held, kept) {
+  return held.length === kept.length && kept.every((range, index) => {
+    const other = held[index];
+    return other.startContainer === range.startContainer && other.startOffset === range.startOffset && other.endContainer === range.endContainer && other.endOffset === range.endOffset;
+  });
+}
+
+/**
+ * Put `ranges` back as the selection. One range goes through
+ * `setBaseAndExtent`, which also reaches inside a shadow root.
+ */
+function selectRanges(selection, ranges) {
+  const [only] = ranges;
+  if (ranges.length === 1 && typeof selection.setBaseAndExtent === 'function') {
+    selection.setBaseAndExtent(only.startContainer, only.startOffset, only.endContainer, only.endOffset);
+    return;
+  }
+  selection.removeAllRanges();
+  for (const range of ranges) {
+    const copy = range.startContainer.ownerDocument?.createRange();
+    if (copy == null) {
+      continue;
+    }
+    copy.setStart(range.startContainer, range.startOffset);
+    copy.setEnd(range.endContainer, range.endOffset);
+    selection.addRange(copy);
+  }
+}
+
+/**
+ * The selection's composed ranges, reaching into each open shadow root a
+ * boundary lands on; null where the engine has no `getComposedRanges`.
+ * Without the roots, a selection inside a shadow root reads as one around
+ * its host.
+ */
+function composedRangesOf(selection, known) {
+  const query = selection.getComposedRanges;
+  if (typeof query !== 'function') {
+    return null;
+  }
+  // Engines take the roots as a dictionary, or, in older releases, as
+  // arguments.
+  const read = roots => {
+    try {
+      return query.call(selection, {
+        shadowRoots: roots
+      });
+    } catch {
+      try {
+        return query.call(selection, ...roots);
+      } catch {
+        return null;
+      }
+    }
+  };
+  const roots = [...known];
+  for (;;) {
+    const ranges = read([...roots]);
+    if (ranges == null) {
+      return null;
+    }
+    const found = new Set();
+    for (const range of ranges) {
+      for (const [node, offset] of [[range.startContainer, range.startOffset], [range.endContainer, range.endOffset]]) {
+        for (const child of [node.childNodes[offset], node.childNodes[offset - 1]]) {
+          const root = child?.nodeType === 1 ? child.shadowRoot : null;
+          if (root != null && !roots.includes(root)) {
+            found.add(root);
+          }
+        }
+      }
+    }
+    if (found.size === 0) {
+      return ranges;
+    }
+    roots.push(...found);
+  }
+}
+
+/** The open shadow roots on the root chains of `ranges`' boundaries. */
+function shadowRootsOfRanges(ranges) {
+  const roots = new Set();
+  for (const range of ranges) {
+    for (const root of [...openShadowRootsOf(range.startContainer), ...openShadowRootsOf(range.endContainer)]) {
+      roots.add(root);
+    }
+  }
+  return [...roots];
+}
+
+/**
+ * The open shadow root `target` hosts, if any. A press on text directly under
+ * a shadow root targets its host.
+ */
+function ownShadowRoot(target) {
+  const root = target?.nodeType === 1 ? target.shadowRoot : null;
+  return root == null ? [] : [root];
+}
+
+/** The open shadow roots on `target`'s root chain, innermost first. */
+function openShadowRootsOf(target) {
+  const roots = [];
+  let root = target != null && typeof target.nodeType === 'number' ? target.getRootNode() : null;
+  while (root != null && root.nodeType === 11) {
+    const host = root.host;
+    if (host == null) {
+      break;
+    }
+    if (root.mode === 'open') {
+      roots.push(root);
+    }
+    root = host.getRootNode();
+  }
+  return roots;
+}
+
+/** The focused element, inside open shadow roots too. */
+function deepActiveElement(doc) {
+  let active = doc?.activeElement ?? null;
+  while (active?.shadowRoot?.activeElement != null) {
+    active = active.shadowRoot.activeElement;
+  }
+  return active;
+}
+
+/**
+ * The selection-lock styles on `set`, refcounted per element; idempotent
+ * release.
+ */
+function lockStyles(set) {
   const locked = [];
   for (const element of set) {
     const style = styleOf(element);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.6",
+  "version": "0.7.7-canary.1d04d40",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -860,6 +860,9 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/a11y-spec": "0.7.7-canary.1d04d40",
+    "@astryxdesign/cli": "0.7.7-canary.1d04d40",
+    "@astryxdesign/interaction-harness": "0.7.7-canary.1d04d40",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -870,10 +873,7 @@
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
-    "tailwindcss": "^4.3.2",
-    "@astryxdesign/cli": "0.7.6",
-    "@astryxdesign/a11y-spec": "0.0.0",
-    "@astryxdesign/interaction-harness": "0.0.0"
+    "tailwindcss": "^4.3.2"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/AppShell/AppShell.doc.mjs

@@ -45,6 +45,11 @@ export const docs = {
         description:
           'Start the page heading inside `children`. AppShell owns the skip link, the banner landmark and the main landmark, but it renders no heading, so the first heading in the content area is the page h1.',
       },
+      {
+        guidance: true,
+        description:
+          'On phones, opt the page into the full screen with `viewport-fit=cover` in the viewport meta tag (`width=device-width, initial-scale=1, viewport-fit=cover`). AppShell then extends its header under the status bar and out to the screen sides, and keeps the header\'s items and the end of the content inside the device\'s safe area. An installed web app can also draw under the status bar with `<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">`. In landscape only the header is inset: an inline SideNav and the content\'s sides still reach under a notch, so keep content padding there. A shell with no header region or phone top bar keeps no top inset; keep top padding there.',
+      },
       {
         guidance: false,
         description:
@@ -343,6 +348,11 @@ export const docsDense = {
         description:
           'Give every nav slot an accessible name: TopNav and SideNav are separate navigation landmarks, so pass `label` to each.',
       },
+      {
+        guidance: true,
+        description:
+          'Phones: add `viewport-fit=cover` to the viewport meta; the header then reaches under the status bar while its items and the content end stay in the safe area. Landscape: only the header is inset (not an inline SideNav or the content sides). No header region or phone top bar: no top inset, so keep top padding. Installed web apps: `apple-mobile-web-app-status-bar-style` `black-translucent`.',
+      },
       {
         guidance: true,
         description:

package/src/AppShell/AppShell.tsx

@@ -471,6 +471,38 @@ const styles = stylex.create({
     top: 0,
     zIndex: 1,
   },
+  // The insets are zero unless the page sets `viewport-fit=cover`. The header
+  // background goes under the status bar and to the screen sides, as a UIKit
+  // bar does.
+  headerSafeAreaTop: {
+    paddingBlockStart: 'env(safe-area-inset-top, 0px)',
+  },
+  // The insets are physical sides, so a right-to-left context swaps them on
+  // the inline sides.
+  headerSafeAreaSides: {
+    paddingInlineStart: {
+      default: 'env(safe-area-inset-left, 0px)',
+      ':is([dir="rtl"] *)': 'env(safe-area-inset-right, 0px)',
+    },
+    paddingInlineEnd: {
+      default: 'env(safe-area-inset-right, 0px)',
+      ':is([dir="rtl"] *)': 'env(safe-area-inset-left, 0px)',
+    },
+  },
+  // In `auto`, the banner's wrapper and the phone top bar both stick. Below a
+  // banner, the bar sticks under the top inset, so its items stay clear of the
+  // status bar.
+  headerStickyBelowTopInset: {
+    top: 'env(safe-area-inset-top, 0px)',
+  },
+  // Main adds the bottom inset to the padding that LayoutContent publishes for
+  // `contentPadding`. The published value excludes the inset, so a bleed child
+  // subtracts only `contentPadding`. Main is border-box, so a child that fills
+  // it ends above the inset.
+  mainSafeAreaEnd: {
+    paddingBlockEnd:
+      'calc(var(--container-padding-block-end, 0px) + env(safe-area-inset-bottom, 0px))',
+  },
   // Sticky sideNav for auto height mode — sticks within the wrapper.
   // This div replaces the panel as the direct flex child of the middle
   // (horizontal) container, so it needs the same flex properties that
@@ -891,7 +923,12 @@ export function AppShell({
       role="banner"
       {...mergeProps(
         themeProps('app-shell-header', {variant}),
-        stylex.props(headerAreaStyle, isAuto && styles.headerSticky),
+        stylex.props(
+          headerAreaStyle,
+          isAuto && styles.headerSticky,
+          styles.headerSafeAreaTop,
+          styles.headerSafeAreaSides,
+        ),
       )}>
       {headerInner}
     </div>
@@ -1184,6 +1221,7 @@ export function AppShell({
         drawsMainFocusRing
           ? [focusOutlineStyles.focusVisible, styles.mainScrollRegionInset]
           : styles.mainFocusTarget,
+        styles.mainSafeAreaEnd,
       ]}>
       {children}
     </LayoutContent>
@@ -1230,7 +1268,15 @@ export function AppShell({
         role={headerContent == null ? 'banner' : undefined}
         {...mergeProps(
           themeProps('app-shell-header', {variant}),
-          stylex.props(headerAreaStyle, isAuto && styles.headerSticky),
+          stylex.props(
+            headerAreaStyle,
+            isAuto && styles.headerSticky,
+            styles.headerSafeAreaSides,
+            // Under a banner, the banner's wrapper pads the top inset. This top
+            // bar takes only the side insets.
+            headerContent == null && styles.headerSafeAreaTop,
+            isAuto && headerContent != null && styles.headerStickyBelowTopInset,
+          ),
         )}>
         <LayoutHeader padding={0} hasDivider={navHasDividers}>
           <div