@codecademy/gamut

Index: package/dist/PopoverContainer/utils.d.ts
===================================================================
--- package/dist/PopoverContainer/utils.d.ts
+++ package/dist/PopoverContainer/utils.d.ts
@@ -1,11 +1,20 @@
 import { CSSObject } from '@codecademy/variance';
-import { PopoverPositionConfig, TargetRef } from './types';
+import { Alignments, PopoverPositionConfig, TargetRef } from './types';
 export interface PopoverPositionResult {
+    /** Edge insets pinning the popover to the container (`left` / `right` / `top` / `bottom`). */
     styles: CSSObject;
-    /** Applied as inline style to bypass logical property conversion when logical properties produce wrong results */
-    physicalStyles?: CSSObject;
+    /**
+     * Direction-neutral transforms/coords—semantic mirroring happens first via
+     * {@link mirrorAlignment}; merged after `styles`.
+     */
+    dirNeutralStyles?: CSSObject;
 }
+/**
+ * Mirrors placement on the inline axis when the target is RTL so e.g. `bottom-left`
+ * uses the same geometry as `bottom-right` in LTR.
+ */
+export declare const mirrorAlignment: (alignment: Alignments, isRtl: boolean) => Alignments;
 export declare const findResizingParent: (element: HTMLElement) => HTMLElement | null;
 /**
  * Finds all scrolling parents of an element.
  * This is useful for detecting scroll events on parents that may not be the direct parent.
@@ -30,21 +39,18 @@
 };
 /**
  * Computes the absolute position styles for a popover relative to a target element.
  *
- * Returns two style objects:
- * - `styles`: position edge values (left/right/top/bottom) passed as variance props so
- *   they are converted to logical properties (inset-inline-start etc.) when
- *   `useLogicalProperties` is enabled. Corner and edge alignments automatically flip
- *   sides in RTL layouts as a result.
- * - `physicalStyles`: applied as an inline `style` prop, bypassing logical conversion.
- *   Used for transforms (CSS transforms have no logical equivalent — `translate(-100%, 0)`
- *   always shifts physically left) and for centered alignments whose `left` value is a
- *   physical screen coordinate that must not flip in RTL.
+ * When `isRtl` is true, {@link mirrorAlignment} maps the requested placement to the
+ * mirrored corner/edge on the inline axis before computing offsets (same viewport math
+ * as LTR).
  *
- * When `invertAxis` is set and `isRtl` is true, the x-transform coefficient is negated
- * so that the shift moves toward the target rather than away from it after logical
- * positions have flipped the element to the opposite physical side.
+ * Returns two fragments that callers merge into inline `style` (they are not Gamut variance
+ * props on the host, so nothing here is swapped to logical properties via `system.positioning`).
+ *
+ * - `styles`: corner/edge inset lengths (`left` / `right` / `top` / `bottom`).
+ * - `dirNeutralStyles`: transforms/coords not further remapped for RTL/logical placement
+ *   after {@link mirrorAlignment}; merged after `styles`.
  */
 export declare const getPosition: ({ alignment, container, offset, x, y, invertAxis, isRtl, }: PopoverPositionConfig & {
     isRtl?: boolean;
 }) => PopoverPositionResult;