@webview-native-ui/engine 1.0.0 → 1.0.2-0

package/src/controls/shared/dom.ts

@@ -0,0 +1,310 @@
+import { getUnprojectedVisibility } from '../../index.js';
+
+import { fadeMarker } from './crossfade.js';
+import { modalUsesVerticalBars } from './modal.js';
+
+import type { Frame } from '../definitions.js';
+
+export const marker = 'data-native-ui-projected';
+// Scoped runtimes (Stencil slot emulation) patch child accessors on upgraded
+// elements and may report none before hydration; the prototype getter still
+// reports the real light DOM.
+const childNodesGet = typeof Node === 'undefined' ? undefined : Object.getOwnPropertyDescriptor(Node.prototype, 'childNodes')?.get;
+export const childNodesOf = (element: Element): Node[] =>
+  childNodesGet ? Array.from(childNodesGet.call(element)) : Array.from(element.childNodes);
+export const childElements = (element: Element): HTMLElement[] =>
+  childNodesOf(element).filter(
+    (node) => node.nodeType === 1 && !(node as Element).hasAttribute('data-native-ui-projection-node'),
+  ) as HTMLElement[];
+export const prehiddenClass = 'native-ui-prehidden';
+export const prehideRootClass = 'native-ui-prehide';
+export const rejectedClass = 'native-ui-rejected';
+export const verticalBarsBackWebClass = 'ios-theme-vertical-bars-back-web-owned';
+const prehideClasses = new Set([prehiddenClass, prehideRootClass]);
+export const prehideOnlyMutation = (record: MutationRecord): boolean => {
+  if (record.attributeName !== 'class' || record.oldValue === null) return false;
+  const withoutPrehide = (value: string) =>
+    value
+      .split(/\s+/)
+      .filter((name) => name && !prehideClasses.has(name))
+      .join(' ');
+  return withoutPrehide(record.oldValue) === withoutPrehide((record.target as Element).getAttribute('class') ?? '');
+};
+
+export const withoutPrehide = <T>(element: HTMLElement, read: () => T): T => {
+  const changed: HTMLElement[] = [];
+  for (let current: HTMLElement | null = element; current; current = current.parentElement) {
+    if (current.classList.contains(prehiddenClass)) {
+      current.classList.remove(prehiddenClass);
+      changed.push(current);
+    }
+  }
+  const root = element.ownerDocument.documentElement;
+  if (element.matches('ion-back-button') && root.classList.contains(prehideRootClass)) {
+    root.classList.remove(prehideRootClass);
+    changed.push(root);
+  }
+  try {
+    return read();
+  } finally {
+    changed.forEach((current) => current.classList.add(current === root ? prehideRootClass : prehiddenClass));
+  }
+};
+export const isDark = (style: CSSStyleDeclaration): boolean => {
+  const themeScheme = style.getPropertyValue('--ios27-color-scheme').trim();
+  if (themeScheme) return themeScheme === 'dark';
+  const background = style.getPropertyValue('--ion-background-color-rgb').match(/\d+/g)?.slice(0, 3).map(Number);
+  if (background?.length === 3) return background[0] * 0.2126 + background[1] * 0.7152 + background[2] * 0.0722 < 128;
+  const schemes = (style.colorScheme ?? '').split(/\s+/);
+  if (schemes.includes('dark') && !schemes.includes('light')) return true;
+  if (schemes.includes('light') && !schemes.includes('dark')) return false;
+  return typeof window !== 'undefined' && !!window.matchMedia?.('(prefers-color-scheme: dark)').matches;
+};
+const permanentlyExcluded = '.ios-theme-disabled, .ios26-disabled, .ion-cloned-element, [hidden], [inert]';
+export const excluded = `${permanentlyExcluded}, .ion-page-hidden, .ion-page-invisible`;
+const enteringPages = new WeakSet<HTMLElement>();
+export const setVerticalBarsEnteringPage = (page: HTMLElement, entering: boolean): void => {
+  if (entering) enteringPages.add(page);
+  else enteringPages.delete(page);
+};
+export const verticalBarsEnteringPage = (element: HTMLElement): HTMLElement | undefined => {
+  const page = element.closest<HTMLElement>('.ion-page-invisible');
+  return page && enteringPages.has(page) && page.closest('ion-app.ios-theme-vertical-bars') ? page : undefined;
+};
+export const createVerticalBarsPageState = () => {
+  const departed = new WeakSet<HTMLElement>();
+  return {
+    isDeparted(element: HTMLElement, includeHorizontal = false): boolean {
+      const page = element.closest<HTMLElement>('.ion-page');
+      return !!page && departed.has(page) && (includeHorizontal || !!element.closest('ion-app.ios-theme-vertical-bars'));
+    },
+    lifecycle(event: Event): void {
+      // Avoid instanceof so stale listeners stay safe after global teardown.
+      const page = event.target && (event.target as Node).nodeType === 1 ? (event.target as HTMLElement) : undefined;
+      if (!page?.matches('.ion-page')) return;
+      const entering = event.type === 'ionViewWillEnter';
+      if (entering || event.type === 'ionViewDidEnter') departed.delete(page);
+      else if (event.type === 'ionViewWillLeave' || event.type === 'ionViewDidLeave') departed.add(page);
+      setVerticalBarsEnteringPage(page, entering);
+    },
+    cancel(entering?: HTMLElement, leaving?: HTMLElement): void {
+      if (entering) {
+        departed.add(entering);
+        setVerticalBarsEnteringPage(entering, false);
+      }
+      if (leaving) departed.delete(leaving);
+    },
+  };
+};
+const disabledButtonGroup = 'ion-buttons:is(.ios-theme-disabled, .ios26-disabled)';
+const nativeUIDisabledSelector = '.native-ui-disabled, [data-native-ui="disabled"]';
+
+export const isDisabledButtonGroupChild = (element: HTMLElement): boolean =>
+  element.matches('ion-button') && element.parentElement?.matches(disabledButtonGroup) === true;
+
+const verticalBarsTags = new Set(['ion-button', 'ion-back-button', 'ion-buttons', 'ion-menu-button', 'ion-tab-bar']);
+
+export const isVerticalBarsSource = (element: HTMLElement): boolean =>
+  !element.closest('[data-native-ui-placement="element"]') &&
+  (element.matches(
+    '[data-native-ui-placement="rail"][data-native-ui="button"], [data-native-ui-placement="rail"][data-native-ui="back-button"]',
+  ) ||
+    (verticalBarsTags.has(element.localName) &&
+      (element.matches('ion-tab-bar') || verticalBarsOwned(element)) &&
+      !element.closest('ion-menu, ion-popover') &&
+      modalUsesVerticalBars(element) &&
+      !!element.closest('ion-app.ios-theme-vertical-bars')));
+
+// Condense headers are the scrolling duplicate of a page's fixed header.
+// Keep this exclusion aligned with the entering-back prehide rule in vertical-bars.scss.
+const nonFixedToolbarSurface =
+  'ion-header[collapse="condense"], ion-header.header-collapse-condense, ion-content ion-header, ion-content ion-footer';
+
+export const isVerticalBarsBackPosition = (element: HTMLElement): boolean => {
+  if (element.closest(nonFixedToolbarSurface)) return false;
+  const page = element.closest('.ion-page');
+  if (!page) return true;
+  const candidates = Array.from(page.querySelectorAll<HTMLElement>('ion-back-button')).filter(
+    (back) =>
+      back.closest('.ion-page') === page &&
+      !back.matches('.ion-cloned-element') &&
+      !back.closest(`${nonFixedToolbarSurface}, ion-menu, ion-popover`) &&
+      modalUsesVerticalBars(back),
+  );
+  const rank = (back: HTMLElement) =>
+    inFixedToolbar(back) ? 0 : back.closest('ion-header ion-toolbar, ion-footer ion-toolbar') ? 1 : back.closest('ion-toolbar') ? 3 : 2;
+  const best = candidates.reduce<HTMLElement | undefined>(
+    (winner, back) => (!winner || rank(back) < rank(winner) ? back : winner),
+    undefined,
+  );
+  return best === element;
+};
+
+export const preferredVerticalBarsBack = <T extends HTMLElement>(elements: T[], doc: Document): T | undefined => {
+  const pages = Array.from(doc.querySelectorAll('.ion-page'));
+  const pageOrder = (element: Element) => pages.indexOf(element.closest('.ion-page')!);
+  return elements.sort((a, b) => pageOrder(b) - pageOrder(a) || Number(!!b.closest('ion-header')) - Number(!!a.closest('ion-header')))[0];
+};
+
+const excludedBy = (element: HTMLElement, selector: string): boolean => {
+  const owner = element.closest<HTMLElement>(selector);
+  return !!owner && !(element.parentElement === owner && isDisabledButtonGroupChild(element));
+};
+
+export const isPermanentlyExcluded = (element: HTMLElement): boolean => excludedBy(element, permanentlyExcluded);
+export const isExcluded = (element: HTMLElement, enteringPage?: HTMLElement): boolean =>
+  excludedBy(element, `${permanentlyExcluded}, .ion-page-hidden`) || (!!element.closest('.ion-page-invisible') && !enteringPage);
+
+// A shared native surface must not cover an opted-out descendant either.
+export const isNativeUIDisabled = (element: Element): boolean =>
+  !!element.closest(nativeUIDisabledSelector) || !!element.querySelector(nativeUIDisabledSelector);
+
+export const isVerticalBarsToolbarActionShape = (element: HTMLElement): boolean =>
+  element.matches('ion-menu-button') ||
+  (element.matches('ion-button') && !!element.querySelector('ion-icon[slot="icon-only"], svg[slot="icon-only"]'));
+
+// Placement belongs to the DOM identity for one routed-page epoch. Changes to
+// content/disabled state affect rendering, never its chosen surface.
+const verticalBarsPlacement = new WeakMap<HTMLElement, boolean>();
+export const setVerticalBarsPlacement = (element: HTMLElement, rail: boolean): void => {
+  verticalBarsPlacement.set(element, rail);
+};
+export const clearVerticalBarsPlacement = (element: HTMLElement): void => {
+  verticalBarsPlacement.delete(element);
+};
+// Explicit Web placement remains authoritative even when added after initial capture.
+export const verticalBarsOwned = (element: HTMLElement): boolean =>
+  verticalBarsPlacement.get(element) === true &&
+  !element.closest('ion-buttons.ios-theme-horizontal-only, ion-button.ios-theme-horizontal-only');
+
+export const isVerticalBarsToolbarAction = (element: HTMLElement): boolean =>
+  verticalBarsOwned(element) && !isExcluded(element, verticalBarsEnteringPage(element)) && !isNativeUIDisabled(element);
+
+const overlays = 'ion-menu, ion-popover';
+
+/** Shared eligibility for a toolbar action candidate, before placement is decided (prehide) or consumed (projection). */
+export const verticalBarsActionCandidate = (element: HTMLElement): boolean =>
+  !element.matches('[data-native-ui="button"], [data-native-ui="back-button"]') &&
+  !element.querySelector('[data-native-ui="button"], [data-native-ui="back-button"]') &&
+  inFixedToolbar(element) &&
+  !element.closest('ion-buttons.ios-theme-horizontal-only, ion-button.ios-theme-horizontal-only') &&
+  !isPermanentlyExcluded(element) &&
+  !isNativeUIDisabled(element) &&
+  !element.closest(overlays) &&
+  modalUsesVerticalBars(element);
+
+/** Shared eligibility for a back-button candidate; the back button may sit outside a fixed toolbar. */
+export const verticalBarsBackCandidate = (element: HTMLElement): boolean =>
+  !element.hasAttribute('data-native-ui') &&
+  isVerticalBarsBackPosition(element) &&
+  !element.closest('ion-buttons.ios-theme-horizontal-only') &&
+  !isPermanentlyExcluded(element) &&
+  !isNativeUIDisabled(element) &&
+  !element.closest(overlays) &&
+  modalUsesVerticalBars(element);
+
+export const verticalBarsToolbarActions = (element: HTMLElement): HTMLElement[] =>
+  // Back buttons use the dedicated rail slot; they are never toolbar actions.
+  childElements(element).filter((child) => !child.matches('ion-back-button') && isVerticalBarsToolbarAction(child));
+
+export const isVerticalBarsToolbarGroup = (element: HTMLElement): boolean => {
+  return (
+    element.matches('ion-buttons') &&
+    verticalBarsOwned(element) &&
+    !element.matches('.ios-theme-disabled, .ios26-disabled') &&
+    !isNativeUIDisabled(element)
+  );
+};
+
+export const toolbarTextMarker = 'data-native-ui-toolbar-text';
+
+export const syncToolbarText = (doc: Document): void => {
+  for (const toolbar of Array.from(
+    doc.querySelectorAll<HTMLElement>(`ion-app.ios-theme-vertical-bars ion-toolbar, ion-toolbar[${toolbarTextMarker}]`),
+  )) {
+    toolbar.toggleAttribute(
+      toolbarTextMarker,
+      !!toolbar.closest('ion-app.ios-theme-vertical-bars') &&
+        childNodesOf(toolbar).some((node) => node.nodeType === Node.TEXT_NODE && !!node.textContent?.trim()),
+    );
+  }
+};
+
+export const activateProjectedElement = (element: HTMLElement): void => {
+  const target = element.matches('ion-button, ion-back-button, ion-menu-button')
+    ? element.shadowRoot?.querySelector<HTMLElement>('[part~="native"]')
+    : undefined;
+  (target ?? element).click();
+};
+
+export const unprojected = <T>(elements: Iterable<HTMLElement>, read: () => T): T => {
+  const list = Array.from(elements);
+  const hidden = list.filter((element) => element.hasAttribute(marker));
+  const snapshotHidden = list.filter((element) => element.hasAttribute('data-native-ui-snapshot-source'));
+  const webHidden = list.filter((element) => element.hasAttribute('data-native-ui-web-source'));
+  hidden.forEach((element) => element.removeAttribute(marker));
+  snapshotHidden.forEach((element) => element.removeAttribute('data-native-ui-snapshot-source'));
+  webHidden.forEach((element) => element.removeAttribute('data-native-ui-web-source'));
+  try {
+    return read();
+  } finally {
+    hidden.forEach((element) => element.setAttribute(marker, ''));
+    snapshotHidden.forEach((element) => element.setAttribute('data-native-ui-snapshot-source', ''));
+    webHidden.forEach((element) => element.setAttribute('data-native-ui-web-source', ''));
+  }
+};
+
+const readVisible = (element: HTMLElement, allowOutsideViewport: boolean): boolean => {
+  const enteringPage = isVerticalBarsSource(element) ? verticalBarsEnteringPage(element) : undefined;
+  if (!element.isConnected || isExcluded(element, enteringPage) || isNativeUIDisabled(element)) return false;
+  for (let current: HTMLElement | null = element; current; current = current.parentElement) {
+    const style = getComputedStyle(current);
+    if (
+      style.display === 'none' ||
+      (style.visibility !== 'visible' && getUnprojectedVisibility(current) !== 'visible') ||
+      (Number(style.opacity) === 0 && !current.hasAttribute(fadeMarker) && current !== enteringPage)
+    )
+      return false;
+    // Ordinary controls on moving/collapsing/custom transformed surfaces stay in Web coordinates.
+    // VerticalBars rail controls are placed independently of their Web coordinates and must remain
+    // owned while Ionic transforms the content behind an open menu.
+    if (
+      !allowOutsideViewport &&
+      style.transform !== 'none' &&
+      !new DOMMatrixReadOnly(style.transform).isIdentity &&
+      current !== element &&
+      !current.matches('ion-tab-bar')
+    )
+      return false;
+  }
+  const rect = element.getBoundingClientRect();
+  return (
+    rect.width > 0 &&
+    rect.height > 0 &&
+    (allowOutsideViewport || (rect.left >= -1 && rect.top >= -1 && rect.right <= innerWidth + 1 && rect.bottom <= innerHeight + 1))
+  );
+};
+
+export const visible = (element: HTMLElement, allowOutsideViewport = false): boolean =>
+  withoutPrehide(element, () => readVisible(element, allowOutsideViewport));
+
+export const frame = (rect: DOMRect, origin?: DOMRect): Frame => ({
+  x: rect.x - (origin?.x ?? 0),
+  y: rect.y - (origin?.y ?? 0),
+  width: rect.width,
+  height: rect.height,
+});
+
+export const text = (element: Element): string => {
+  if (element.matches('ion-icon, svg, ion-badge, .ios27-segment-lens, .ion-cloned-element')) return '';
+  return childNodesOf(element)
+    .map((node) => (node.nodeType === 3 ? node.textContent : node.nodeType === 1 ? text(node as Element) : ''))
+    .join('')
+    .replace(/\s+/g, ' ')
+    .trim();
+};
+
+export const inFixedToolbar = (element: Element): boolean => {
+  const edge = element.closest('ion-toolbar')?.parentElement;
+  return !!edge?.matches('ion-header, ion-footer') && !element.closest('ion-content') && !element.closest(nonFixedToolbarSurface);
+};

package/src/controls/shared/events.ts

@@ -0,0 +1,14 @@
+export const CSS_MOTION_EVENTS = {
+  transitionRun: 'transitionrun',
+  transitionEnd: 'transitionend',
+  transitionCancel: 'transitioncancel',
+  animationStart: 'animationstart',
+  animationEnd: 'animationend',
+  animationCancel: 'animationcancel',
+} as const;
+
+// Ionic adapter event names. Generic DOM sources do not require this lifecycle.
+export const LIFECYCLE_WILL_ENTER = 'ionViewWillEnter';
+export const LIFECYCLE_WILL_LEAVE = 'ionViewWillLeave';
+export const LIFECYCLE_DID_ENTER = 'ionViewDidEnter';
+export const LIFECYCLE_DID_LEAVE = 'ionViewDidLeave';

package/src/controls/shared/horizontal-navigation.ts

@@ -0,0 +1,106 @@
+import type { Candidate } from './candidate.js';
+import { inFixedToolbar } from './dom.js';
+
+export const navigationMarker = 'data-native-ui-navigation-source';
+export const horizontalToolbar = (candidate: Candidate): boolean =>
+  candidate.control.placement !== 'vertical-bars' &&
+  ['button', 'button-group', 'back-button', 'menu-button'].includes(candidate.control.kind) &&
+  inFixedToolbar(candidate.element);
+
+/** Prepare stationary toolbar endpoints before playback. Native presentation follows
+ * the page clock; source actions change only when navigation commits.
+ */
+export const createHorizontalNavigation = () => {
+  let sequence = 0;
+  let current:
+    | {
+        id: number;
+        destination: Candidate[];
+        prepared: boolean;
+        native: boolean;
+        scopes: Set<HTMLElement>;
+        frozen: Candidate[];
+        phase: 'playing' | 'settling' | 'committing';
+        masked: Set<HTMLElement>;
+        leased: boolean;
+      }
+    | undefined;
+  const clear = () => {
+    current?.masked.forEach((element) => element.removeAttribute(navigationMarker));
+    current = undefined;
+  };
+  return {
+    get current() {
+      return current;
+    },
+    begin(scopes: HTMLElement[], acknowledged: Candidate[], leased = false) {
+      if (current && ((leased && current.leased) || current.phase !== 'playing')) clear();
+      if (!current)
+        current = {
+          id: ++sequence,
+          destination: [],
+          prepared: false,
+          native: false,
+          scopes: new Set(),
+          frozen: acknowledged
+            .filter((candidate) => horizontalToolbar(candidate) && scopes.some((scope) => scope.contains(candidate.element)))
+            .map((candidate) => ({ ...candidate, icons: [] })),
+          phase: 'playing',
+          masked: new Set(),
+          leased,
+        };
+      scopes.forEach((scope) => current!.scopes.add(scope));
+      current.leased ||= leased;
+      return current;
+    },
+    mask(candidates: Candidate[], all = false) {
+      if (!current || current.phase !== 'playing') return;
+      for (const candidate of candidates.filter(horizontalToolbar)) {
+        // Only hide a destination that already has a retained native counterpart.
+        // New controls stay Web until native acknowledges their preparation.
+        if (!all && !current.frozen.some((source) => source.control.transitionId === candidate.control.transitionId)) continue;
+        for (const source of candidate.sources ?? [candidate.element]) {
+          source.setAttribute(navigationMarker, '');
+          current.masked.add(source);
+        }
+      }
+    },
+    unmask(candidates: Candidate[]) {
+      for (const candidate of candidates) {
+        for (const source of candidate.sources ?? [candidate.element]) {
+          source.removeAttribute(navigationMarker);
+          current?.masked.delete(source);
+        }
+      }
+    },
+    measure<T>(read: () => T): T {
+      const masked = [...(current?.masked ?? [])];
+      masked.forEach((element) => element.removeAttribute(navigationMarker));
+      try {
+        return read();
+      } finally {
+        masked.forEach((element) => element.setAttribute(navigationMarker, ''));
+      }
+    },
+    retain(candidates: Candidate[]): Candidate[] {
+      if (!current || current.phase === 'committing') return candidates;
+      const frozen = new Set(current.frozen.map((candidate) => candidate.element));
+      return [
+        ...candidates.filter(
+          (candidate) =>
+            !frozen.has(candidate.element) &&
+            !(horizontalToolbar(candidate) && [...current!.scopes].some((scope) => scope.contains(candidate.element))),
+        ),
+        ...current.frozen,
+      ];
+    },
+    owns(element: HTMLElement): boolean {
+      return (
+        !!current &&
+        (current.frozen.some((candidate) => candidate.element === element || candidate.element.contains(element)) ||
+          ([...current.scopes].some((scope) => scope.contains(element)) && inFixedToolbar(element)))
+      );
+    },
+    clear,
+  };
+};

package/src/controls/shared/icons.ts

@@ -0,0 +1,64 @@
+export const iconSource = (svg: SVGElement, mirrored?: boolean): string | undefined => {
+  // A small, local SVG subset. Never load external content while projecting UI.
+  if (
+    svg.querySelector('script, foreignObject, image, use, animate, animateTransform, set, style, text') ||
+    /url\((?!["']?#)/.test(svg.outerHTML)
+  )
+    return undefined;
+  // Ionicons flips the wrapper, not the SVG, for directional icons in RTL.
+  if (mirrored === undefined && svg.parentElement?.matches('.icon-inner')) {
+    const transform = new DOMMatrixReadOnly(getComputedStyle(svg.parentElement).transform);
+    mirrored = transform.is2D && transform.a === -1 && transform.d === 1 && !transform.b && !transform.c && !transform.e && !transform.f;
+  }
+  const copy = svg.cloneNode(true) as SVGElement;
+  const originals = [svg, ...Array.from(svg.querySelectorAll('*'))];
+  const copies = [copy, ...Array.from(copy.querySelectorAll('*'))];
+  originals.forEach((node, index) => {
+    const style = getComputedStyle(node);
+    for (const property of ['fill', 'stroke', 'stroke-width', 'opacity', 'fill-opacity', 'stroke-opacity', 'color']) {
+      (copies[index] as SVGElement).style.setProperty(property, style.getPropertyValue(property));
+    }
+  });
+  copy.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
+  if (mirrored) {
+    copy.style.transform = 'scaleX(-1)';
+    copy.style.transformOrigin = 'center';
+  }
+  return new XMLSerializer().serializeToString(copy);
+};
+
+export const createIconRenderer = () => {
+  const cache = new Map<string, Promise<string>>();
+  return {
+    clear: () => cache.clear(),
+    async render(source: string, width: number, height: number): Promise<string> {
+      const scale = devicePixelRatio || 1;
+      const key = `${width}:${height}:${scale}:${source}`;
+      const cached = cache.get(key);
+      if (cached) return cached;
+      const rendering = (async () => {
+        const url = URL.createObjectURL(new Blob([source], { type: 'image/svg+xml' }));
+        try {
+          const image = new Image();
+          image.src = url;
+          await image.decode();
+          const canvas = document.createElement('canvas');
+          canvas.width = Math.ceil(width * scale);
+          canvas.height = Math.ceil(height * scale);
+          canvas.getContext('2d')!.drawImage(image, 0, 0, canvas.width, canvas.height);
+          return canvas.toDataURL('image/png').split(',')[1];
+        } finally {
+          URL.revokeObjectURL(url);
+        }
+      })();
+      if (cache.size >= 128) cache.delete(cache.keys().next().value!);
+      cache.set(key, rendering);
+      try {
+        return await rendering;
+      } catch (error) {
+        if (cache.get(key) === rendering) cache.delete(key);
+        throw error;
+      }
+    },
+  };
+};

package/src/controls/shared/modal-animation.ts

@@ -0,0 +1,109 @@
+import type { Frame } from '../definitions.js';
+
+/** One immutable presentation, played by Core Animation on the same elapsed clock. */
+export interface ModalAnimation {
+  id: number;
+  startedAt: number;
+  duration: number;
+  fromY: number;
+  opacity: number;
+  easing: number[];
+}
+
+let sequence = 0;
+export const readModalAnimation = (content: HTMLElement): { animation: ModalAnimation; frame: Frame } | undefined => {
+  const win = content.ownerDocument.defaultView!;
+  if (Math.abs(content.offsetWidth - win.innerWidth) > 1 || Math.abs(content.offsetLeft) > 1) return;
+  const animation = content
+    .getAnimations()
+    .find((item) => item.playState === 'running' && (item.effect as KeyframeEffect)?.getKeyframes().some((frame) => frame['transform']));
+  if (!animation || animation.playbackRate !== 1) return;
+  const effect = animation.effect as KeyframeEffect;
+  const timing = effect.getTiming();
+  const frames = effect.getKeyframes();
+  if (
+    frames.length !== 2 ||
+    typeof timing.duration !== 'number' ||
+    timing.duration <= 0 ||
+    timing.duration > 60_000 ||
+    !Number.isFinite(timing.duration) ||
+    frames.some((frame) => frame.easing !== 'linear') ||
+    Number(frames[1]['opacity'] ?? 1) !== 1 ||
+    timing.iterations !== 1 ||
+    timing.direction !== 'normal' ||
+    timing.delay !== 0
+  )
+    return;
+  const translate = (value: unknown) => {
+    const match = /^translateY\((-?[\d.]+)(px|%|vh)\)$/.exec(String(value));
+    if (!match) return;
+    const factor = match[2] === '%' ? content.offsetHeight / 100 : match[2] === 'vh' ? win.innerHeight / 100 : 1;
+    return Number(match[1]) * factor;
+  };
+  const from = translate(frames[0]['transform']);
+  const to = translate(frames[1]['transform']);
+  const curve = /^cubic-bezier\(([^)]+)\)$/.exec(timing.easing ?? 'linear');
+  const easing = (timing.easing ?? 'linear') === 'linear' ? [0, 0, 1, 1] : curve?.[1].split(',').map(Number);
+  if (from === undefined || to === undefined || !easing || easing.length !== 4 || !easing.every(Number.isFinite)) return;
+  const opacity = Number(frames[0]['opacity'] ?? 1);
+  if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1 || easing[0] < 0 || easing[0] > 1 || easing[2] < 0 || easing[2] > 1) return;
+  const matrix = new DOMMatrixReadOnly(win.getComputedStyle(content).transform);
+  if (matrix.a !== 1 || matrix.d !== 1 || matrix.b !== 0 || matrix.c !== 0 || matrix.m41 !== 0) return;
+  const rect = content.getBoundingClientRect();
+  const scale = win.devicePixelRatio || 1;
+  const pixel = (value: number) => Math.round(value * scale) / scale;
+  const y = Math.max(0, pixel(rect.top - matrix.m42 + to));
+  const height = Math.min(pixel(rect.height), win.innerHeight - y);
+  if (height <= 0) return;
+  return {
+    animation: {
+      id: ++sequence,
+      startedAt: Date.now() - Number(animation.currentTime ?? 0),
+      duration: timing.duration,
+      fromY: from - to,
+      opacity,
+      easing,
+    },
+    frame: { x: 0, y, width: win.innerWidth, height },
+  };
+};
+
+/** Keep layout at the destination size; the wrapper transform reveals the sheet.
+ * Only Ionic's standard sheet-entry height animation is changed. Its final size,
+ * duration, wrapper motion and later breakpoint animations remain Ionic-owned.
+ */
+export const prepareSheetLayout = (modal: HTMLElement & { initialBreakpoint?: number }): void => {
+  if (!modal.matches('.modal-sheet.modal-no-expand-scroll')) return;
+  const breakpoint = modal.initialBreakpoint;
+  if (breakpoint === undefined || !Number.isFinite(breakpoint) || breakpoint <= 0 || breakpoint > 1) return;
+  const page = modal.querySelector<HTMLElement>(':scope > .ion-page');
+  for (const animation of page?.getAnimations?.() ?? []) {
+    const effect = animation.effect;
+    if (animation.playState !== 'running' || !(effect instanceof KeyframeEffect) || effect.target !== page) continue;
+    const frames = effect.getKeyframes();
+    if (
+      frames.length !== 2 ||
+      !frames.every(
+        (frame, index) =>
+          frame.offset === index &&
+          frame.easing === 'linear' &&
+          Number(frame['opacity']) === 1 &&
+          typeof frame['maxHeight'] === 'string' &&
+          /^\d+(?:\.\d+)?%$/.test(frame['maxHeight']) &&
+          Math.abs(parseFloat(frame['maxHeight']) - (index === 0 ? 1 - breakpoint : breakpoint) * 100) < 0.000001 &&
+          (frame.composite === 'auto' || frame.composite === 'replace') &&
+          Object.keys(frame).every((key) => ['offset', 'computedOffset', 'easing', 'composite', 'opacity', 'maxHeight'].includes(key)),
+      )
+    )
+      continue;
+    effect.setKeyframes(
+      frames.map((frame) => ({
+        offset: frame.offset,
+        easing: frame.easing,
+        composite: frame.composite,
+        opacity: frame['opacity'],
+        maxHeight: frames[1]['maxHeight'],
+      })),
+    );
+  }
+};