@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/dist/Layer/layerAnimations.stylex.js

@@ -41,8 +41,17 @@ const enterStart = "xu7jd1z-B";
 // (translateY) entrances are direction-neutral and are left as-is.
 const enterEndRtl = "xu7jd1z-B";
 const enterStartRtl = "xwmkjkf-B";
+
+// Reduce Motion under a finger: the same entrance without its travel. A touch
+// presentation substitutes a cross-fade for motion, never a jump.
+const fadeIn = "x18re5ia-B";
 const animationBase = {
-  animationDuration: durationVars['--duration-fast-max'],
+  animationDuration: {
+    default: durationVars['--duration-fast-max'],
+    // The cross-fade is 200 ms or less, whatever the theme's duration
+    // (design:reduced-motion DR2).
+    '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': `min(${durationVars['--duration-fast-max']}, 200ms)`
+  },
   animationTimingFunction: easeVars['--ease-standard'],
   animationFillMode: 'backwards'
 };
@@ -55,33 +64,37 @@ const animationBase = {
  *
  * Each entry disables its keyframe animation under
  * `prefers-reduced-motion: reduce` so the layer appears instantly instead of
- * translating/scaling in (infra-6).
+ * translating/scaling in (infra-6). Under a finger (the primary pointer is
+ * coarse) it fades in instead, opacity only and in 200 ms or less: on a touch
+ * screen Reduce Motion replaces motion with a cross-fade rather than a jump
+ * (design:reduced-motion DR2, DR3), as iOS does for its menus, popovers and
+ * tips.
  */
 export const layerAnimations = {
   below: {
-    kKVMdj: "xl1vlw0 x1aquc0h",
-    k44tkh: "x9uej1z",
+    kKVMdj: "xl1vlw0 xa4pr1u xajy0lc",
+    k44tkh: "x9uej1z x13pi3j7",
     kyAemX: "x128ha8g",
     kWV6AL: "xskzprw",
     $$css: true
   },
   above: {
-    kKVMdj: "x3psbcj x1aquc0h",
-    k44tkh: "x9uej1z",
+    kKVMdj: "x3psbcj xa4pr1u xajy0lc",
+    k44tkh: "x9uej1z x13pi3j7",
     kyAemX: "x128ha8g",
     kWV6AL: "xskzprw",
     $$css: true
   },
   end: {
-    kKVMdj: "x1i331go x1vxsm5i x1aquc0h",
-    k44tkh: "x9uej1z",
+    kKVMdj: "x1i331go x1vxsm5i xa4pr1u xajy0lc",
+    k44tkh: "x9uej1z x13pi3j7",
     kyAemX: "x128ha8g",
     kWV6AL: "xskzprw",
     $$css: true
   },
   start: {
-    kKVMdj: "xck01x9 x18lne9g x1aquc0h",
-    k44tkh: "x9uej1z",
+    kKVMdj: "xck01x9 x18lne9g xa4pr1u xajy0lc",
+    k44tkh: "x9uej1z x13pi3j7",
     kyAemX: "x128ha8g",
     kWV6AL: "xskzprw",
     $$css: true

package/dist/Layer/layerSlideRules.d.ts

@@ -1,7 +1,9 @@
 /**
  * @file layerSlideRules.ts
  * @input A layer's placement and alignment
- * @output The `@position-try` rules for its slide options and their names
+ * @output The `@position-try` rules for its slide options and their names, and
+ *   the beside and fit options of a layer that must never settle over its
+ *   anchor
  * @position Layer runtime geometry; the slide of spec:AST-059 FR4
  *
  * The slide is a position option whose area spans the whole alignment axis,
@@ -14,6 +16,23 @@
  * gutter on both alignment-axis edges, and the clearance facing the anchor
  * with the gutter on the far edge of the side it lands on.
  *
+ * A layer that must never settle over its anchor (spec:AST-059 FR4, Tooltip)
+ * has a second fallback list, for when its settled box covers its anchor:
+ * content taller than the room above and below its trigger. `beside` lands on a
+ * side across the alignment axis, spanning the whole block axis, at the
+ * content's own inline size, so it fits only where the layer fits without
+ * squeezing. `fit` lands above or below sized to the room on that side, so
+ * overflow scrolls inside the layer, and is never smaller than half of the room
+ * the trigger leaves on the block axis, so it fits only on the side with more
+ * room; the list tries both only after the layer's own position, `beside` and
+ * the opposite side at the layer's own size, so only content taller than the
+ * room on both sides is sized to a room. No option is sized to whatever room
+ * is left: a browser keeps a layer on the option it last used for as long as
+ * that option still fits, so such an option would hold an open layer on a side
+ * shrunk to a sliver after its anchor moved. Chromium applies a position
+ * option's width and height properties but not their min/max forms, so the
+ * sizes are `inline-size` and `block-size`.
+ *
  * The rules are static — the anchor clearance travels through a custom
  * property — so one style sheet per document carries all of them. It is
  * installed from a layout effect, before the layer's first paint, rather than
@@ -27,7 +46,48 @@ import type { LayerAlignment, LayerPlacement } from './useLayer.js';
 export declare const LAYER_CLEARANCE_PROPERTY = "--_astryx-layer-clearance";
 type Side = 'same' | 'opposite';
 export declare function slideRuleName(placement: LayerPlacement, alignment: LayerAlignment, side: Side): string;
-/** Every slide rule, for every placement and alignment. */
+/** The name of the `beside` option that lands on `side`, across the block axis. */
+export declare function besideRuleName(side: 'start' | 'end'): string;
+/**
+ * The name of the `fit` option that lands on `side` sized to the room there,
+ * which fits only while that side holds at least half of the room the trigger
+ * leaves on the block axis.
+ */
+export declare function fitRuleName(side: 'above' | 'below'): string;
+/**
+ * The fallback list of a layer that must never settle over its anchor, once
+ * the standard list has failed it (FR4). After the layer's own position (the
+ * preferred block side, at its own size): beside the trigger on the inline
+ * end, then the inline start, then the opposite block side at its own size,
+ * and only then the preferred block side and the opposite one sized to the
+ * room there, each only while it is the roomier side. Every option before the
+ * last two keeps the layer at its own size, so a layer whose content fits
+ * somewhere is never stretched to a room; the last two are for content taller
+ * than the room on both sides. Chromium tries no more than five options, so
+ * this replaces the standard list rather than extending it. Side placements
+ * already slide along the block axis at full height, so they have none.
+ */
+export declare function getAnchorClearFallbacks(placement: LayerPlacement): string;
+/** The custom property a layer writes its anchor-clear fallback list to. */
+export declare const LAYER_CLEAR_FALLBACKS_PROPERTY = "--_astryx-layer-clear-fallbacks";
+/** The custom property its `position-try-fallbacks` reads first. */
+export declare const LAYER_TRY_FALLBACKS_PROPERTY = "--_astryx-layer-try-fallbacks";
+/**
+ * The attribute the runtime sets on a layer whose settled box covered its
+ * anchor; it switches the layer to its anchor-clear list.
+ */
+export declare const LAYER_CLEARS_ANCHOR_ATTRIBUTE = "data-astryx-clears-anchor";
+/**
+ * The attribute the runtime sets on a layer that keeps its anchor clear while
+ * its content overflows the box it was given; only then does it scroll, so a
+ * layer that fits stays a plain box and a wheel over it still scrolls the
+ * page.
+ */
+export declare const LAYER_SCROLLS_ATTRIBUTE = "data-astryx-layer-scrolls";
+/**
+ * Every slide rule, for every placement and alignment, and the beside and fit
+ * rules.
+ */
 export declare function slideRulesCss(): string;
 export declare const SLIDE_RULES_ID = "astryx-layer-slide-rules";
 /**

package/dist/Layer/layerSlideRules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layerSlideRules.d.ts","sourceRoot":"","sources":["../../src/Layer/layerSlideRules.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,YAAY,CAAC;AAG/D,kEAAkE;AAClE,eAAO,MAAM,wBAAwB,8BAA8B,CAAC;AAEpE,KAAK,IAAI,GAAG,MAAM,GAAG,UAAU,CAAC;AAEhC,wBAAgB,aAAa,CAC3B,SAAS,EAAE,cAAc,EACzB,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,IAAI,GACT,MAAM,CAER;AAmFD,2DAA2D;AAC3D,wBAAgB,aAAa,IAAI,MAAM,CAOtC;AAED,eAAO,MAAM,cAAc,6BAA6B,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAQpD"}
+{"version":3,"file":"layerSlideRules.d.ts","sourceRoot":"","sources":["../../src/Layer/layerSlideRules.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,YAAY,CAAC;AAG/D,kEAAkE;AAClE,eAAO,MAAM,wBAAwB,8BAA8B,CAAC;AAEpE,KAAK,IAAI,GAAG,MAAM,GAAG,UAAU,CAAC;AAEhC,wBAAgB,aAAa,CAC3B,SAAS,EAAE,cAAc,EACzB,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,IAAI,GACT,MAAM,CAER;AAmFD,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAE3D;AA2CD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,cAAc,GAAG,MAAM,CAMzE;AAED,4EAA4E;AAC5E,eAAO,MAAM,8BAA8B,oCAAoC,CAAC;AAEhF,oEAAoE;AACpE,eAAO,MAAM,4BAA4B,kCAAkC,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,6BAA6B,8BAA8B,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAUnE;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CActC;AAED,eAAO,MAAM,cAAc,6BAA6B,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAQpD"}

package/dist/Layer/layerSlideRules.js

@@ -3,7 +3,9 @@
 /**
  * @file layerSlideRules.ts
  * @input A layer's placement and alignment
- * @output The `@position-try` rules for its slide options and their names
+ * @output The `@position-try` rules for its slide options and their names, and
+ *   the beside and fit options of a layer that must never settle over its
+ *   anchor
  * @position Layer runtime geometry; the slide of spec:AST-059 FR4
  *
  * The slide is a position option whose area spans the whole alignment axis,
@@ -16,6 +18,23 @@
  * gutter on both alignment-axis edges, and the clearance facing the anchor
  * with the gutter on the far edge of the side it lands on.
  *
+ * A layer that must never settle over its anchor (spec:AST-059 FR4, Tooltip)
+ * has a second fallback list, for when its settled box covers its anchor:
+ * content taller than the room above and below its trigger. `beside` lands on a
+ * side across the alignment axis, spanning the whole block axis, at the
+ * content's own inline size, so it fits only where the layer fits without
+ * squeezing. `fit` lands above or below sized to the room on that side, so
+ * overflow scrolls inside the layer, and is never smaller than half of the room
+ * the trigger leaves on the block axis, so it fits only on the side with more
+ * room; the list tries both only after the layer's own position, `beside` and
+ * the opposite side at the layer's own size, so only content taller than the
+ * room on both sides is sized to a room. No option is sized to whatever room
+ * is left: a browser keeps a layer on the option it last used for as long as
+ * that option still fits, so such an option would hold an open layer on a side
+ * shrunk to a sliver after its anchor moved. Chromium applies a position
+ * option's width and height properties but not their min/max forms, so the
+ * sizes are `inline-size` and `block-size`.
+ *
  * The rules are static — the anchor clearance travels through a custom
  * property — so one style sheet per document carries all of them. It is
  * installed from a layout effect, before the layer's first paint, rather than
@@ -88,9 +107,111 @@ function rule(placement, alignment, side) {
 const PLACEMENTS = ['above', 'below', 'start', 'end'];
 const ALIGNMENTS = ['start', 'center', 'end'];
 
-/** Every slide rule, for every placement and alignment. */
+/** The name of the `beside` option that lands on `side`, across the block axis. */
+export function besideRuleName(side) {
+  return `--astryx-layer-beside-${side}`;
+}
+
+/**
+ * The name of the `fit` option that lands on `side` sized to the room there,
+ * which fits only while that side holds at least half of the room the trigger
+ * leaves on the block axis.
+ */
+export function fitRuleName(side) {
+  return `--astryx-layer-fit-${side}`;
+}
+
+/**
+ * `beside`: the slide's geometry on an inline side, at the content's own
+ * inline size. A content-sized layer would otherwise wrap to whatever sliver
+ * of room the trigger leaves and always fit.
+ */
+function besideRule(side) {
+  return `@position-try ${besideRuleName(side)}{position-area:${areaFor(side)};${placementMargins(side)}${alignmentMargins(side)}inline-size:max-content;}`;
+}
+
+/** The block size of the room on one block side: the area minus its margins. */
+function roomCap(gutter) {
+  return `calc(100% - ${CLEARANCE} - ${gutter})`;
+}
+
+/**
+ * Half of the room the trigger leaves on the block axis, minus one side's
+ * margins and one pixel: a side whose room is at least this much is the
+ * roomier side. The pixel lets both sides fit when the trigger sits at the
+ * viewport's middle, where rounding could otherwise fail both.
+ */
+function halfRoom(viewport, gutter) {
+  return `calc((${viewport} - anchor-size(block)) / 2 - ${CLEARANCE} - ${gutter} - 1px)`;
+}
+
+/**
+ * `fit`: the slide's geometry on a block side, sized to the room on that
+ * side; the layer scrolls what does not fit (FR3). It is at least half of the
+ * room the trigger leaves, so it overflows, and does not fit, on the side
+ * with less room.
+ */
+function fitRule(side) {
+  const size = (viewport, gutter) => `max(${roomCap(gutter)}, ${halfRoom(viewport, gutter)})`;
+  const blockSize = pair('block-size', size('100vh', layerViewportInset.gutterBlockFallback), size('100dvb', layerViewportInset.gutterBlock));
+  return `@position-try ${fitRuleName(side)}{position-area:${areaFor(side)};${placementMargins(side)}${alignmentMargins(side)}${blockSize}}`;
+}
+
+/**
+ * The fallback list of a layer that must never settle over its anchor, once
+ * the standard list has failed it (FR4). After the layer's own position (the
+ * preferred block side, at its own size): beside the trigger on the inline
+ * end, then the inline start, then the opposite block side at its own size,
+ * and only then the preferred block side and the opposite one sized to the
+ * room there, each only while it is the roomier side. Every option before the
+ * last two keeps the layer at its own size, so a layer whose content fits
+ * somewhere is never stretched to a room; the last two are for content taller
+ * than the room on both sides. Chromium tries no more than five options, so
+ * this replaces the standard list rather than extending it. Side placements
+ * already slide along the block axis at full height, so they have none.
+ */
+export function getAnchorClearFallbacks(placement) {
+  if (placement !== 'above' && placement !== 'below') {
+    return '';
+  }
+  const opposite = placement === 'above' ? 'below' : 'above';
+  return `${besideRuleName('end')}, ${besideRuleName('start')}, flip-block, ${fitRuleName(placement)}, ${fitRuleName(opposite)}`;
+}
+
+/** The custom property a layer writes its anchor-clear fallback list to. */
+export const LAYER_CLEAR_FALLBACKS_PROPERTY = '--_astryx-layer-clear-fallbacks';
+
+/** The custom property its `position-try-fallbacks` reads first. */
+export const LAYER_TRY_FALLBACKS_PROPERTY = '--_astryx-layer-try-fallbacks';
+
+/**
+ * The attribute the runtime sets on a layer whose settled box covered its
+ * anchor; it switches the layer to its anchor-clear list.
+ */
+export const LAYER_CLEARS_ANCHOR_ATTRIBUTE = 'data-astryx-clears-anchor';
+
+/**
+ * The attribute the runtime sets on a layer that keeps its anchor clear while
+ * its content overflows the box it was given; only then does it scroll, so a
+ * layer that fits stays a plain box and a wheel over it still scrolls the
+ * page.
+ */
+export const LAYER_SCROLLS_ATTRIBUTE = 'data-astryx-layer-scrolls';
+
+/**
+ * Switches a layer that set the attribute to its anchor-clear list, and lets
+ * a layer whose content overflows scroll it.
+ */
+function clearSwitchCss() {
+  return `[${LAYER_CLEARS_ANCHOR_ATTRIBUTE}]{${LAYER_TRY_FALLBACKS_PROPERTY}:var(${LAYER_CLEAR_FALLBACKS_PROPERTY});}[${LAYER_SCROLLS_ATTRIBUTE}]{overflow-y:auto;overscroll-behavior-block:contain;}`;
+}
+
+/**
+ * Every slide rule, for every placement and alignment, and the beside and fit
+ * rules.
+ */
 export function slideRulesCss() {
-  return PLACEMENTS.flatMap(placement => ALIGNMENTS.flatMap(alignment => [rule(placement, alignment, 'same'), rule(placement, alignment, 'opposite')])).join('');
+  return [...PLACEMENTS.flatMap(placement => ALIGNMENTS.flatMap(alignment => [rule(placement, alignment, 'same'), rule(placement, alignment, 'opposite')])), besideRule('end'), besideRule('start'), fitRule('above'), fitRule('below'), clearSwitchCss()].join('');
 }
 export const SLIDE_RULES_ID = 'astryx-layer-slide-rules';
 

package/dist/Layer/layerStack.d.ts

@@ -43,10 +43,11 @@ export interface LayerStackEntry {
     seq: number;
     behavior: LayerEscapeBehavior;
     /**
-     * The layer's container element, read lazily at press time. Used only to
-     * break ties between layers the React tree reports at the same depth — a raw
+     * The layer's container element, read lazily at press time. Used to break
+     * ties between layers the React tree reports at the same depth — a raw
      * `useFocusTrap` cannot wrap its content in a depth provider (it renders
-     * nothing), so DOM containment is the only nesting signal those have.
+     * nothing), so DOM containment is the only nesting signal those have — and,
+     * once at registration, to find the document the layer lives in.
      */
     getContainer?: () => HTMLElement | null;
     /**
@@ -78,14 +79,16 @@ export interface LayerStackEntry {
  * recover from, and the alternative — matching the composing element against
  * a layer's container — cannot work for the layers that do not have one.
  *
- * A composition already running when the first layer registers is invisible
- * here: the listeners go on with the stack's own.
+ * A composition already running when a document's first layer registers is
+ * invisible here: the listeners go on with the stack's own. Page-wide means
+ * every document that holds a layer.
  */
 export declare function isTextComposing(): boolean;
 /**
- * Whether `token` identifies the top-most layer. Overlays that still own a
- * dismissal channel the stack does not model yet (outside-press, swipe) can
- * gate on this so every channel agrees on who is on top.
+ * Whether `token` identifies the top-most layer of its own document. Overlays
+ * that still own a dismissal channel the stack does not model yet
+ * (outside-press, swipe) can gate on this so every channel agrees on who is on
+ * top.
  */
 export declare function isTopmostLayer(token: object): boolean;
 /**
@@ -103,6 +106,6 @@ export declare function dispatchLayerEscapeKeyDown(event: KeyboardEvent): void;
  * function; callers own calling it.
  */
 export declare function registerLayer(entry: Omit<LayerStackEntry, 'seq'>): () => void;
-/** Test-only: drop all entries and detach the listener. */
+/** Test-only: drop all entries and detach every listener. */
 export declare function resetLayerStackForTests(): void;
 //# sourceMappingURL=layerStack.d.ts.map

package/dist/Layer/layerStack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layerStack.d.ts","sourceRoot":"","sources":["../../src/Layer/layerStack.ts"],"names":[],"mappings":"AAsEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,mBAAmB,CAAC;IAC9B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACxC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AA6ED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AA2BD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD;AAeD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CA4BrE;AA6BD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,KAAK,CAAC,GAAG,MAAM,IAAI,CAc7E;AAED,2DAA2D;AAC3D,wBAAgB,uBAAuB,IAAI,IAAI,CAM9C"}
+{"version":3,"file":"layerStack.d.ts","sourceRoot":"","sources":["../../src/Layer/layerStack.ts"],"names":[],"mappings":"AAqFA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,mBAAmB,CAAC;IAC9B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACxC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAqFD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAgCD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGrD;AAqCD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CA6BrE;AAiBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,KAAK,CAAC,GAAG,MAAM,IAAI,CAmC7E;AAED,6DAA6D;AAC7D,wBAAgB,uBAAuB,IAAI,IAAI,CAS9C"}

package/dist/Layer/layerStack.js

@@ -6,8 +6,8 @@
  * @file layerStack.ts
  * @input Uses the isImeKeyEvent predicate from utils/ime
  * @output Exports the shared layer dismissal stack: registration, top-most
- *   ordering, the document-level Escape listener, and its internal local-event
- *   dispatcher
+ *   ordering, the Escape listener on each document that holds a layer, and its
+ *   internal local-event dispatcher
  * @position Internal to the Layer system; consumed by useLayerDismissal, which
  *   is what overlays actually call. Not exported from the package root.
  *
@@ -26,12 +26,27 @@
  *
  * ## Only the top layer acts
  *
- * The stack owns ONE `keydown` listener on `document` and routes the press to
+ * The stack owns ONE `keydown` listener per document and routes the press to
  * the top-most layer itself. Overlays do not listen; they register and say what
  * they want done. The alternative — every layer listens and filters itself out
  * — is what forces `stopPropagation()` choreography between element-level and
  * document-level listeners, and it silently breaks whenever a layer forgets.
  *
+ * ## One listener per document
+ *
+ * A layer can live in a document other than the one this module was loaded
+ * in: an app may render into a same-origin iframe or a Document
+ * Picture-in-Picture window through a portal. A key press reaches only the
+ * document it happened in, so the listener goes on the layer's own document —
+ * its container's `ownerDocument` — with that document's first layer, and comes
+ * off with its last. A layer that names no container counts as the global
+ * `document`'s.
+ *
+ * The top-most layer is chosen among the layers of the document the press
+ * arrived in, the way each document keeps its own browser top layer. A press in
+ * one window never reaches past it to dismiss a layer in another, and one press
+ * still dismisses exactly one layer.
+ *
  * ## Bubble phase, not capture
  *
  * The listener is on the BUBBLE phase so content inside a layer can claim the
@@ -85,6 +100,8 @@ import { isImeKeyEvent } from "../utils/ime.js";
  * lose the whole dialog. Guessing wrong the other way costs one keystroke.
  */
 
+/** An entry and the document it was registered in. */
+
 const entries = [];
 // Registration order per layer identity. `useLayerDismissal` keeps one token
 // through effect re-registration while an active layer changes depth or behavior
@@ -95,7 +112,9 @@ const entries = [];
 // the browser top layer's show order.
 let seqByToken = new WeakMap();
 let nextSeq = 0;
-let isListening = false;
+// How many registered layers live in each document: the listeners go on a
+// document with its first layer and come off with its last.
+const layerCountByDocument = new Map();
 function seqFor(token) {
   const existing = seqByToken.get(token);
   if (existing !== undefined) {
@@ -154,9 +173,9 @@ function isPresentEntry(entry) {
   return entry.isPresent?.() ?? true;
 }
 
-// Whether a text composition is running anywhere on the page. Tracked from
+// The documents in which a text composition is running. Tracked from
 // composition events because the DOM offers no way to ask.
-let isComposing = false;
+const composingDocuments = new Set();
 
 /**
  * Whether the user is part-way through composing text with an IME.
@@ -175,28 +194,35 @@ let isComposing = false;
  * recover from, and the alternative — matching the composing element against
  * a layer's container — cannot work for the layers that do not have one.
  *
- * A composition already running when the first layer registers is invisible
- * here: the listeners go on with the stack's own.
+ * A composition already running when a document's first layer registers is
+ * invisible here: the listeners go on with the stack's own. Page-wide means
+ * every document that holds a layer.
  */
 export function isTextComposing() {
-  return isComposing;
+  return composingDocuments.size > 0;
 }
-function handleCompositionStart() {
-  isComposing = true;
+
+// The listeners sit on documents, so the current target is the document the
+// composition runs in.
+function handleCompositionStart(event) {
+  composingDocuments.add(event.currentTarget);
 }
 
 // Focus leaving the field ends the composition too. Clearing on blur as well
 // means a compositionend this listener never sees cannot leave the flag stuck
 // on, swallowing every later close request.
-function handleCompositionEnd() {
-  isComposing = false;
+function handleCompositionEnd(event) {
+  composingDocuments.delete(event.currentTarget);
 }
 
-/** The top-most present layer, or null when nothing is on screen. */
-function topPresentEntry() {
+/**
+ * The top-most present layer of `doc`, or null when nothing is on screen
+ * there.
+ */
+function topPresentEntry(doc) {
   let top = null;
   for (const entry of entries) {
-    if (!isPresentEntry(entry)) {
+    if (entry.ownerDocument !== doc || !isPresentEntry(entry)) {
       continue;
     }
     if (top == null || compareEntries(entry, top) > 0) {
@@ -207,17 +233,41 @@ function topPresentEntry() {
 }
 
 /**
- * Whether `token` identifies the top-most layer. Overlays that still own a
- * dismissal channel the stack does not model yet (outside-press, swipe) can
- * gate on this so every channel agrees on who is on top.
+ * Whether `token` identifies the top-most layer of its own document. Overlays
+ * that still own a dismissal channel the stack does not model yet
+ * (outside-press, swipe) can gate on this so every channel agrees on who is on
+ * top.
  */
 export function isTopmostLayer(token) {
-  return topPresentEntry()?.token === token;
+  const entry = entries.find(candidate => candidate.token === token);
+  return entry != null && topPresentEntry(entry.ownerDocument) === entry;
+}
+
+/** The global document, or null where there is no DOM. */
+function globalDocument() {
+  return typeof document === 'undefined' ? null : document;
+}
+
+/**
+ * The document a key press happened in: its target's, or the target itself
+ * when the press was dispatched at a document. Read from `nodeType` rather
+ * than `instanceof`, which names this module's window and so misses a node
+ * of another one.
+ */
+function documentOfEvent(event) {
+  const target = event.target;
+  if (target == null) {
+    return null;
+  }
+  return target.nodeType === 9 ? target : target.ownerDocument;
 }
 
-/** Resolve an Escape press against the stack. Returns whether it was handled. */
-function dispatchEscape() {
-  const top = topPresentEntry();
+/**
+ * Resolve an Escape press against the layers of `doc`. Returns whether it was
+ * handled.
+ */
+function dispatchEscape(doc) {
+  const top = topPresentEntry(doc);
   if (top == null) {
     return false;
   }
@@ -241,6 +291,7 @@ export function dispatchLayerEscapeKeyDown(event) {
   if (event.key !== 'Escape') {
     return;
   }
+  const doc = documentOfEvent(event) ?? globalDocument();
   // An IME user pressing Escape is cancelling a composition, not dismissing a
   // layer. Claim the press anyway, then stand down: left unclaimed, the browser
   // raises its own close request, which arrives at a layer's `cancel` handler
@@ -248,7 +299,7 @@ export function dispatchLayerEscapeKeyDown(event) {
   // guard that only returns behaves exactly like no guard at all. Claim it only
   // while a layer is on screen; with nothing to protect, the press is not ours.
   if (isImeKeyEvent(event)) {
-    if (topPresentEntry() != null) {
+    if (topPresentEntry(doc) != null) {
       event.preventDefault();
     }
     return;
@@ -258,7 +309,7 @@ export function dispatchLayerEscapeKeyDown(event) {
   if (event.defaultPrevented) {
     return;
   }
-  if (dispatchEscape()) {
+  if (dispatchEscape(doc)) {
     // Suppress the browser's own close-watcher so it cannot dismiss a second
     // layer behind our back. Propagation is left alone: consumers may
     // legitimately listen for Escape on window, and the stack's decision is
@@ -266,26 +317,18 @@ export function dispatchLayerEscapeKeyDown(event) {
     event.preventDefault();
   }
 }
-function startListening() {
-  if (isListening || typeof document === 'undefined') {
-    return;
-  }
-  document.addEventListener('keydown', dispatchLayerEscapeKeyDown);
-  document.addEventListener('compositionstart', handleCompositionStart, true);
-  document.addEventListener('compositionend', handleCompositionEnd, true);
-  document.addEventListener('blur', handleCompositionEnd, true);
-  isListening = true;
+function startListening(doc) {
+  doc.addEventListener('keydown', dispatchLayerEscapeKeyDown);
+  doc.addEventListener('compositionstart', handleCompositionStart, true);
+  doc.addEventListener('compositionend', handleCompositionEnd, true);
+  doc.addEventListener('blur', handleCompositionEnd, true);
 }
-function stopListening() {
-  if (!isListening || typeof document === 'undefined') {
-    return;
-  }
-  document.removeEventListener('keydown', dispatchLayerEscapeKeyDown);
-  document.removeEventListener('compositionstart', handleCompositionStart, true);
-  document.removeEventListener('compositionend', handleCompositionEnd, true);
-  document.removeEventListener('blur', handleCompositionEnd, true);
-  isComposing = false;
-  isListening = false;
+function stopListening(doc) {
+  doc.removeEventListener('keydown', dispatchLayerEscapeKeyDown);
+  doc.removeEventListener('compositionstart', handleCompositionStart, true);
+  doc.removeEventListener('compositionend', handleCompositionEnd, true);
+  doc.removeEventListener('blur', handleCompositionEnd, true);
+  composingDocuments.delete(doc);
 }
 
 /**
@@ -293,28 +336,48 @@ function stopListening() {
  * function; callers own calling it.
  */
 export function registerLayer(entry) {
+  // The document the layer lives in: its container's, else the global one.
+  const ownerDocument = entry.getContainer?.()?.ownerDocument ?? globalDocument();
   const full = {
     ...entry,
-    seq: seqFor(entry.token)
+    seq: seqFor(entry.token),
+    ownerDocument
   };
   entries.push(full);
-  startListening();
+  if (ownerDocument != null) {
+    const count = layerCountByDocument.get(ownerDocument) ?? 0;
+    layerCountByDocument.set(ownerDocument, count + 1);
+    if (count === 0) {
+      startListening(ownerDocument);
+    }
+  }
   return () => {
     const index = entries.indexOf(full);
-    if (index !== -1) {
-      entries.splice(index, 1);
+    if (index === -1) {
+      return;
+    }
+    entries.splice(index, 1);
+    if (ownerDocument == null) {
+      return;
     }
-    if (entries.length === 0) {
-      stopListening();
+    const count = layerCountByDocument.get(ownerDocument) ?? 1;
+    if (count > 1) {
+      layerCountByDocument.set(ownerDocument, count - 1);
+      return;
     }
+    layerCountByDocument.delete(ownerDocument);
+    stopListening(ownerDocument);
   };
 }
 
-/** Test-only: drop all entries and detach the listener. */
+/** Test-only: drop all entries and detach every listener. */
 export function resetLayerStackForTests() {
   entries.length = 0;
   seqByToken = new WeakMap();
   nextSeq = 0;
-  isComposing = false;
-  stopListening();
+  for (const doc of layerCountByDocument.keys()) {
+    stopListening(doc);
+  }
+  layerCountByDocument.clear();
+  composingDocuments.clear();
 }