@hyperframes/studio 0.8.143 → 0.8.145

package/src/components/editor/domEditingTextFields.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from "vitest";
+import { Window } from "happy-dom";
+import {
+  PREVIEW_RASTER_ATTR,
+  STUDIO_PREVIEW_UPCOMING_ATTR,
+} from "@hyperframes/core/studio-preview-mark";
 import { serializeDomEditTextFields } from "./domEditing";
+import { collectDomEditTextFields } from "./domEditingLayers";
 
 describe("serializeDomEditTextFields — mixed content", () => {
   it("round-trips text-node + child element fields", () => {
@@ -58,3 +64,15 @@ describe("serializeDomEditTextFields — mixed content", () => {
     ).toBe("A < B & C > D");
   });
 });
+
+describe("collectDomEditTextFields — preview marks", () => {
+  it("keeps preview-only attributes out of a saved text edit", () => {
+    const { document } = new Window();
+    document.body.innerHTML = `<h1>Hello <span class="word" ${PREVIEW_RASTER_ATTR} ${STUDIO_PREVIEW_UPCOMING_ATTR}>world</span></h1>`;
+    const heading = document.querySelector("h1") as unknown as HTMLElement;
+    const saved = serializeDomEditTextFields(collectDomEditTextFields(heading));
+    expect(saved).toContain('<span class="word" data-hf-text-key=');
+    expect(saved).not.toContain(PREVIEW_RASTER_ATTR);
+    expect(saved).not.toContain(STUDIO_PREVIEW_UPCOMING_ATTR);
+  });
+});

package/src/components/editor/manualEditsDom.ts

@@ -36,7 +36,7 @@ import {
 } from "./manualEditsTypes";
 import { gsapWritesChannels } from "../../hooks/gsapRuntimeKeyframes";
 import { splitTopLevelWhitespace } from "./manualEditsStyleHelpers";
-import { roundTo3, roundToLayoutPx } from "../../utils/rounding";
+import { roundTo3, roundToLayoutSize } from "../../utils/rounding";
 import { BOX_SIZE_STYLE_PROPS } from "./manualEditsDomPatches";
 
 /* ── Gesture tracking ─────────────────────────────────────────────── */
@@ -402,7 +402,7 @@ function readParentFlexBasisPixels(
   if (display !== "flex" && display !== "inline-flex") return null;
 
   const direction = readStyleOrComputed(parent, "flex-direction").trim();
-  return roundToLayoutPx(Math.max(1, direction.startsWith("column") ? size.height : size.width));
+  return direction.startsWith("column") ? size.height : size.width;
 }
 
 function restoreStaleStudioScaleResize(element: HTMLElement): void {
@@ -477,22 +477,21 @@ function writeStudioBoxSizeVars(
   }
 
   element.setAttribute(STUDIO_BOX_SIZE_ATTR, "true");
-  element.style.setProperty(STUDIO_WIDTH_PROP, `${roundToLayoutPx(Math.max(1, size.width))}px`);
-  element.style.setProperty(STUDIO_HEIGHT_PROP, `${roundToLayoutPx(Math.max(1, size.height))}px`);
+  element.style.setProperty(STUDIO_WIDTH_PROP, `${size.width}px`);
+  element.style.setProperty(STUDIO_HEIGHT_PROP, `${size.height}px`);
 }
 
 function applyStudioBoxSizeDimensions(
   element: HTMLElement,
-  size: { width: number; height: number },
-): void {
+  wantedSize: { width: number; height: number },
+): { width: number; height: number } {
+  const size = roundToLayoutSize(wantedSize);
   writeStudioBoxSizeVars(element, size);
   restoreStaleStudioScaleResize(element);
 
-  const width = roundToLayoutPx(Math.max(1, size.width));
-  const height = roundToLayoutPx(Math.max(1, size.height));
   element.style.setProperty("box-sizing", "border-box");
-  element.style.setProperty("width", `${width}px`);
-  element.style.setProperty("height", `${height}px`);
+  element.style.setProperty("width", `${size.width}px`);
+  element.style.setProperty("height", `${size.height}px`);
   element.style.setProperty("min-width", "0px");
   element.style.setProperty("min-height", "0px");
   element.style.setProperty("max-width", "none");
@@ -507,6 +506,7 @@ function applyStudioBoxSizeDimensions(
   if (computedDisplay === "inline") {
     element.style.setProperty("display", "inline-block");
   }
+  return size;
 }
 
 export function applyStudioBoxSize(
@@ -533,12 +533,12 @@ export function forgetStudioBoxSizeDraftBase(element: HTMLElement): void {
 export function applyStudioBoxSizeDraft(
   element: HTMLElement,
   size: { width: number; height: number },
-): void {
+): { width: number; height: number } {
   if (!boxSizeDraftBases.has(element)) {
     boxSizeDraftBases.set(element, { width: element.offsetWidth, height: element.offsetHeight });
   }
   promoteInlineForTransform(element);
-  applyStudioBoxSizeDimensions(element, size);
+  return applyStudioBoxSizeDimensions(element, size);
 }
 
 /* ── Rotation apply ───────────────────────────────────────────────── */

package/src/components/editor/previewGestureStarts.ts

@@ -99,10 +99,10 @@ export function createPreviewGestureStarts(
   const drawPressedBox = (origin: OverlayRect | null): WaitingPressState["draw"] =>
     origin && ((dx, dy) => opts.setOverlayRect(shiftedOverlayRect(origin, dx, dy)));
 
-  // A corner resize scales about the element's centre by the pointer's distance from it, as the resize does.
+  // A corner resize scales about the element's centre by the grabbed corner's distance from it, as the resize does.
   const drawResizedBox = (
     origin: OverlayRect | null,
-    press: { x: number; y: number },
+    grabbed: { x: number; y: number },
   ): WaitingPressState["draw"] => {
     if (!origin) return null;
     const bounds = opts.overlayRef.current?.getBoundingClientRect();
@@ -111,8 +111,12 @@ export function createPreviewGestureStarts(
       y: (bounds?.top ?? 0) + origin.top + origin.height / 2,
     };
     return (dx, dy) => {
-      const pointer = { x: press.x + dx, y: press.y + dy };
-      const scale = resolveCenterResizeScale({ pointer, pointerStart: press, centerStart: centre });
+      const pointer = { x: grabbed.x + dx, y: grabbed.y + dy };
+      const scale = resolveCenterResizeScale({
+        pointer,
+        pointerStart: grabbed,
+        centerStart: centre,
+      });
       const [width, height] = [origin.width * scale, origin.height * scale];
       opts.setOverlayRect({
         ...origin,
@@ -248,6 +252,7 @@ export function createPreviewGestureStarts(
       selection?: DomEditSelection;
       rect?: OverlayRect | null;
       resizeHandle?: ResizeHandle;
+      resizeCorner?: { x: number; y: number };
     },
   ) => {
     // A replay edits what was pressed, though another element may be selected by then.
@@ -255,7 +260,10 @@ export function createPreviewGestureStarts(
     let draw: WaitingPressState["draw"] = null;
     if (kind === "drag") draw = drawPressedBox(opts.overlayRectRef.current);
     if (kind === "resize")
-      draw = drawResizedBox(opts.overlayRectRef.current, { x: e.clientX, y: e.clientY });
+      draw = drawResizedBox(
+        opts.overlayRectRef.current,
+        options?.resizeCorner ?? { x: e.clientX, y: e.clientY },
+      );
     return startOnShownPreview(
       e,
       () => {
@@ -272,6 +280,7 @@ export function createPreviewGestureStarts(
             selection,
             rect,
             resizeHandle: options?.resizeHandle,
+            resizeCorner: options?.resizeCorner,
             at,
           })
         );

package/src/components/editor/resizeDraft.ts

@@ -6,14 +6,15 @@ import {
   elementCornerOverlayPoints,
   overlayCornersCentroid,
 } from "./domEditOverlayGeometry";
-import { computeNextResizeAnchor } from "./domEditResizeLocal";
+import { computeNextResizeAnchor, resizeRemainderShift } from "./domEditResizeLocal";
+import type { ResizeDraftSizes } from "./domEditResizeLocal";
 import { applyManualOffsetDragDraft } from "./manualOffsetDrag";
 
 type Corners = ReturnType<typeof elementCornerOverlayPoints>;
 
 /**
  * The residual center-pin offset for this frame. With measurable corners and a
- * fixed-center start, accumulate `fixedStart - centerNow` onto the previous
+ * fixed-center start, accumulate `fixedStart + shift - centerNow` onto the previous
  * anchor so it CONVERGES rather than oscillating: `applyManualOffsetDragDraft`
  * treats its argument as the absolute offset, and `centerNow` (measured on the
  * live element) already carries the previous frame's offset, so the difference
@@ -25,10 +26,15 @@ function resolveResizeAnchor(
   g: GestureState,
   corners: Corners | null,
   measureOrientedRect: () => OverlayRect | null,
+  sizes: ResizeDraftSizes,
 ): { dx: number; dy: number } {
   const fixedStart = g.resizeFixedCenterStart;
   if (corners && fixedStart) {
-    return computeNextResizeAnchor(g.lastResizeAnchor, fixedStart, overlayCornersCentroid(corners));
+    const press = g.resizePressFromCorner ?? { x: 0, y: 0 };
+    const grab = { x: g.startX - press.x - g.centerX, y: g.startY - press.y - g.centerY };
+    const shift = resizeRemainderShift(corners, grab, sizes);
+    const target = { x: fixedStart.x + shift.x, y: fixedStart.y + shift.y };
+    return computeNextResizeAnchor(g.lastResizeAnchor, target, overlayCornersCentroid(corners));
   }
   const fallbackRect = measureOrientedRect();
   return resolveResizeCenterAnchorOffset({
@@ -52,11 +58,12 @@ function resolveAnchoredResizeDraft(
   overlayEl: HTMLDivElement | null,
   iframe: HTMLIFrameElement | null,
   measureOrientedRect: () => OverlayRect | null,
+  sizes: ResizeDraftSizes,
 ): OverlayRect {
   // Measure real corners ONCE — reused for the anchor and the fallback size.
   const corners =
     overlayEl && iframe ? elementCornerOverlayPoints(overlayEl, iframe, element) : null;
-  const anchor = resolveResizeAnchor(g, corners, measureOrientedRect);
+  const anchor = resolveResizeAnchor(g, corners, measureOrientedRect, sizes);
   g.lastResizeAnchor = anchor;
   applyManualOffsetDragDraft(member, anchor.dx, anchor.dy);
   // Re-measure AFTER the anchor translate so it hugs the element every frame.
@@ -80,6 +87,7 @@ export function resolveResizeDraftRect(
   overlayEl: HTMLDivElement | null,
   iframe: HTMLIFrameElement | null,
   measureOrientedRect: () => OverlayRect | null,
+  sizes: ResizeDraftSizes,
 ): OverlayRect {
   if (g.pathOffsetMember) {
     return resolveAnchoredResizeDraft(
@@ -89,6 +97,7 @@ export function resolveResizeDraftRect(
       overlayEl,
       iframe,
       measureOrientedRect,
+      sizes,
     );
   }
   // Re-measure the element's oriented box AFTER the size write. The size draft

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -250,14 +250,15 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       if (g.pathOffsetMember) applyManualOffsetDragDraft(g.pathOffsetMember, dx, dy);
     } else {
       // Corner resize scales proportionally about the center, without edge snapping.
+      const grab = g.resizePressFromCorner ?? { x: 0, y: 0 };
       const nextSize = resolveCenterResizeSize({
         baseWidth: g.actualWidth,
         baseHeight: g.actualHeight,
-        pointer: { x: e.clientX, y: e.clientY },
-        pointerStart: { x: g.startX, y: g.startY },
+        pointer: { x: e.clientX - grab.x, y: e.clientY - grab.y },
+        pointerStart: { x: g.startX - grab.x, y: g.startY - grab.y },
         centerStart: { x: g.centerX, y: g.centerY },
       });
-      applyStudioBoxSizeDraft(sel.element, nextSize);
+      const writtenSize = applyStudioBoxSizeDraft(sel.element, nextSize);
 
       const overlayEl = opts.overlayRef.current;
       const iframe = opts.iframeRef.current;
@@ -270,6 +271,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         overlayEl,
         iframe,
         measureOrientedRect,
+        { wanted: nextSize, written: writtenSize },
       );
       logResizeMove({
         pointer: { x: e.clientX, y: e.clientY },

package/src/components/renders/GpuEncodingToggle.tsx

@@ -0,0 +1,28 @@
+export function GpuEncodingToggle({
+  format,
+  checked,
+  disabled,
+  onToggle,
+}: {
+  format: "mp4" | "webm" | "mov";
+  checked: boolean;
+  disabled: boolean;
+  onToggle: () => void;
+}) {
+  // GPU encoders exist for H.264/H.265 only, so only MP4 can use one.
+  if (format !== "mp4") return null;
+  return (
+    <label
+      className={`flex items-center gap-2 text-step-10 text-text-4 ${disabled ? "opacity-40 cursor-not-allowed" : "cursor-pointer"}`}
+    >
+      <input
+        type="checkbox"
+        checked={checked}
+        disabled={disabled}
+        onChange={onToggle}
+        className="accent-studio-accent"
+      />
+      <span>Use GPU encoding</span>
+    </label>
+  );
+}

package/src/components/renders/RenderQueue.test.tsx

@@ -142,7 +142,7 @@ describe("RenderQueue controls", () => {
       exportButtonIn(host).dispatchEvent(new MouseEvent("click", { bubbles: true }));
     });
 
-    expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "landscape-4k", 30);
+    expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "landscape-4k", 30, false);
   });
 
   it("refuses a resolution the composition cannot reach, and says why", async () => {
@@ -172,7 +172,23 @@ describe("RenderQueue controls", () => {
       exportButtonIn(host).dispatchEvent(new MouseEvent("click", { bubbles: true }));
     });
 
-    expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "auto", 30);
+    expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "auto", 30, false);
+  });
+
+  it("exports with GPU encoding once the box is ticked, and remembers it", () => {
+    const onStartRender: Mock<StartRenderHandler> = vi.fn();
+    const host = mountRenderQueue(onStartRender);
+    const gpu = [...host.querySelectorAll("label")].find((label) =>
+      label.textContent?.includes("Use GPU encoding"),
+    );
+
+    act(() => gpu?.querySelector("input")?.click());
+    act(() => {
+      exportButtonIn(host).dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+
+    expect(onStartRender).toHaveBeenCalledWith("mp4", "standard", "auto", 30, true);
+    expect(getPersistedRenderSettings().gpu).toBe(true);
   });
 
   it("persists a changed format as the literal union value", async () => {
@@ -185,7 +201,9 @@ describe("RenderQueue controls", () => {
       format: "mov",
       quality: "standard",
       fps: 30,
+      gpu: false,
     });
+    expect(host.textContent).not.toContain("Use GPU encoding");
   });
 });
 

package/src/components/renders/RenderQueue.tsx

@@ -11,6 +11,7 @@ import { Tooltip } from "../ui/Tooltip";
 import { resolveFloatingPanelPosition, type FloatingPosition } from "../editor/floatingPanel";
 import type { RenderJob, ResolutionPreset } from "./useRenderQueue";
 import { getPersistedRenderSettings, persistRenderSettings } from "./renderSettings";
+import { GpuEncodingToggle } from "./GpuEncodingToggle";
 import { trackStudioEvent } from "../../utils/studioTelemetry";
 
 export interface CompositionDimensions {
@@ -23,6 +24,7 @@ export type StartRenderHandler = (
   quality: "draft" | "standard" | "high",
   resolution: ResolutionPreset | "auto",
   fps: 24 | 30 | 60,
+  gpu?: boolean,
 ) => void | Promise<void>;
 
 export interface RenderQueueProps {
@@ -303,6 +305,7 @@ function FormatExportButton({
   const [quality, setQuality] = useState<"draft" | "standard" | "high">(persisted.quality);
   const [resolution, setResolution] = useState<RenderScale>("auto");
   const [fps, setFps] = useState<24 | 30 | 60>(persisted.fps);
+  const [gpu, setGpu] = useState(persisted.gpu);
 
   // Only a definite "not installed" blocks Export. A null status means the
   // probe gave no answer, and refusing to export on no answer would break
@@ -385,6 +388,15 @@ function FormatExportButton({
           </div>
         )}
       </div>
+      <GpuEncodingToggle
+        format={format}
+        checked={gpu}
+        disabled={isRendering}
+        onToggle={() => {
+          setGpu(!gpu);
+          persistRenderSettings(format, quality, fps, !gpu);
+        }}
+      />
       <Button
         variant="primary"
         size="md"
@@ -398,7 +410,7 @@ function FormatExportButton({
           if (isRendering || missingFfmpeg) return;
           const outputResolution = resolveResolution(resolution, compositionDimensions);
           trackStudioEvent("render_start", { format, quality, resolution: outputResolution, fps });
-          void onStartRender(format, quality, outputResolution, fps);
+          void onStartRender(format, quality, outputResolution, fps, gpu);
         }}
         // Width only. A type size or a weight here would win the merge against
         // the size recipe and leave this Export a step away from the header's

package/src/components/renders/RenderQueuePanel.tsx

@@ -29,7 +29,7 @@ export const RenderQueuePanel = memo(function RenderQueuePanel() {
       ffmpeg={renderQueue.ffmpeg}
       ffmpegChecking={renderQueue.ffmpegChecking}
       onRecheckFfmpeg={renderQueue.recheckFfmpeg}
-      onStartRender={async (format, quality, resolution, fps) => {
+      onStartRender={async (format, quality, resolution, fps, gpu) => {
         await waitForPendingDomEditSaves();
         // No `composition`: startRender targets the active one by default.
         await renderQueue.startRender({
@@ -37,6 +37,7 @@ export const RenderQueuePanel = memo(function RenderQueuePanel() {
           quality,
           format,
           resolution,
+          gpu,
           // Render what the user is previewing: active variable overrides
           // from the Variables panel ride along (undefined = defaults).
           variables: usePreviewVariablesStore.getState().values ?? undefined,

package/src/components/renders/renderSettings.ts

@@ -4,6 +4,7 @@ export interface PersistedRenderSettings {
   format: "mp4" | "webm" | "mov";
   quality: "draft" | "standard" | "high";
   fps: 24 | 30 | 60;
+  gpu: boolean;
 }
 
 export function getPersistedRenderSettings(): PersistedRenderSettings {
@@ -17,21 +18,23 @@ export function getPersistedRenderSettings(): PersistedRenderSettings {
           ? parsed.quality
           : "standard",
         fps: [24, 30, 60].includes(parsed.fps) ? parsed.fps : 30,
+        gpu: parsed.gpu === true,
       };
     }
   } catch {
     /* ignore */
   }
-  return { format: "mp4", quality: "standard", fps: 30 };
+  return { format: "mp4", quality: "standard", fps: 30, gpu: false };
 }
 
 export function persistRenderSettings(
   format: PersistedRenderSettings["format"],
   quality: PersistedRenderSettings["quality"],
   fps: PersistedRenderSettings["fps"],
+  gpu: boolean = getPersistedRenderSettings().gpu,
 ): void {
   try {
-    localStorage.setItem(RENDER_SETTINGS_KEY, JSON.stringify({ format, quality, fps }));
+    localStorage.setItem(RENDER_SETTINGS_KEY, JSON.stringify({ format, quality, fps, gpu }));
   } catch {
     /* ignore */
   }

package/src/components/renders/useRenderQueue.ts

@@ -32,6 +32,7 @@ export interface StartRenderOptions {
   format?: "mp4" | "webm" | "mov";
   /** `"auto"` (default) renders at the composition's authored dimensions. */
   resolution?: ResolutionPreset | "auto";
+  gpu?: boolean;
   /**
    * Render a specific composition file. Omit it to render the composition the
    * user currently has open — only the sidebar's per-composition Render button
@@ -234,6 +235,7 @@ export function useRenderQueue(
         resolution?: string;
         composition?: string;
         variables?: Record<string, unknown>;
+        gpu?: boolean;
         telemetryDistinctId?: string;
         telemetryOptOut?: boolean;
       } = {
@@ -258,6 +260,7 @@ export function useRenderQueue(
       }
       if (resolution && resolution !== "auto") body.resolution = resolution;
       if (composition) body.composition = composition;
+      if (opts.gpu) body.gpu = true;
       if (opts.variables && Object.keys(opts.variables).length > 0) {
         body.variables = opts.variables;
       }

package/src/components/renders/useRenderQueueComposition.test.tsx

@@ -53,3 +53,15 @@ describe("render target composition", () => {
     expect(body["composition"]).toBeUndefined();
   });
 });
+
+describe("GPU encoding", () => {
+  it("asks the server for GPU encoding when the export asks for it", async () => {
+    const body = await renderBody(null, { format: "mp4", gpu: true });
+    expect(body["gpu"]).toBe(true);
+  });
+
+  it("leaves GPU encoding off by default", async () => {
+    const body = await renderBody(null, { format: "mp4" });
+    expect(body["gpu"]).toBeUndefined();
+  });
+});

package/src/components/ui/Menu.test.tsx

@@ -48,6 +48,13 @@ function clickWithMouse(target: Element): void {
   });
 }
 
+function rightClick(target: Element): void {
+  const init = { bubbles: true, cancelable: true, composed: true };
+  act(() => {
+    target.dispatchEvent(new MouseEvent("contextmenu", init));
+  });
+}
+
 function key(k: string, target: Element | null = document.activeElement): void {
   const init = { key: k, bubbles: true, cancelable: true, composed: true };
   act(() => {
@@ -241,11 +248,7 @@ describe("ContextMenu", () => {
     expect(trigger().textContent).toBe("clip");
     expect(popup()).toBeNull();
 
-    act(() => {
-      trigger().dispatchEvent(
-        new MouseEvent("contextmenu", { bubbles: true, cancelable: true, composed: true }),
-      );
-    });
+    rightClick(trigger());
     await settle();
     expect(popup()).not.toBeNull();
 
@@ -257,6 +260,65 @@ describe("ContextMenu", () => {
   });
 });
 
+describe("container={null}", () => {
+  /** Rendered inline means inside the trigger's own parent, not a portal on the body. */
+  function expectInlineBeside(menu: HTMLElement | null): void {
+    expect(menu).not.toBeNull();
+    expect(trigger().parentElement?.contains(menu)).toBe(true);
+  }
+
+  it("opens a Menu inline, next to its trigger, and closes on Escape", async () => {
+    render(
+      <div>
+        <Menu container={null} trigger={<button data-testid="trigger">Actions</button>}>
+          <MenuItem>Bring to front</MenuItem>
+        </Menu>
+      </div>,
+    );
+    clickWithMouse(trigger());
+    await settle();
+    expectInlineBeside(popup());
+
+    key("Escape");
+    await settle();
+    expect(popup()).toBeNull();
+  });
+
+  it("opens a ContextMenu inline, next to its area", async () => {
+    render(
+      <div>
+        <ContextMenu container={null} trigger={<div data-testid="trigger">clip</div>}>
+          <MenuItem>Split</MenuItem>
+        </ContextMenu>
+      </div>,
+    );
+    rightClick(trigger());
+    await settle();
+    expectInlineBeside(popup());
+  });
+
+  it("opens a Popover inline on its first render", async () => {
+    render(
+      <div>
+        <Popover
+          container={null}
+          defaultOpen
+          trigger={<button data-testid="trigger">Speed</button>}
+        >
+          <span>1x</span>
+        </Popover>
+      </div>,
+    );
+    await settle();
+    expectInlineBeside(document.querySelector<HTMLElement>("[role=dialog]"));
+  });
+
+  it("still portals to the body when no container is passed", async () => {
+    await openActionMenu();
+    expect(trigger().parentElement?.contains(popup())).toBe(false);
+  });
+});
+
 describe("Popover", () => {
   it("leaves the keys of a text field inside it alone", async () => {
     // The Menu owns ArrowDown and typeahead; a Popover must not, or the rename

package/src/components/ui/Menu.tsx

@@ -5,6 +5,7 @@
 
 import { ContextMenu as BaseContextMenu } from "@base-ui/react/context-menu";
 import { Menu as BaseMenu } from "@base-ui/react/menu";
+import { useRef } from "react";
 import type { ComponentPropsWithoutRef, ElementType, ReactElement, ReactNode } from "react";
 import { cn } from "./cn";
 
@@ -20,7 +21,19 @@ type StyledProps<T extends ElementType> = Omit<ComponentPropsWithoutRef<T>, "cla
 export type PopupPreviewState = "open";
 
 /** Where the portal puts the popup. `null` keeps it inline, next to its trigger. */
-type PortalContainer = ComponentPropsWithoutRef<typeof BaseMenu.Portal>["container"];
+export type PortalContainer = ComponentPropsWithoutRef<typeof BaseMenu.Portal>["container"];
+
+const CONTENTS = { display: "contents" } as const;
+
+/** Base UI reads a `null` container as "not resolved yet" and renders nothing, so give `null` a host by the trigger. */
+export function useInlinePortal(container: PortalContainer) {
+  const host = useRef<HTMLSpanElement>(null);
+  if (container !== null) return { host: null, portal: { container } };
+  return {
+    host: <span ref={host} style={CONTENTS} />,
+    portal: { container: host, style: CONTENTS },
+  };
+}
 
 /** Matches Tooltip's gap from its trigger, and its viewport margin. */
 const SIDE_OFFSET = 6;
@@ -77,7 +90,7 @@ interface PositionedProps {
   side?: "top" | "bottom" | "left" | "right";
   align?: "start" | "center" | "end";
   sideOffset?: number;
-  /** Portal target. Pass the shadow root when the trigger lives in one. */
+  /** Portal target. Pass the shadow root when the trigger lives in one; `null` keeps it inline. */
   container?: PortalContainer;
   /** Names the popup for assistive tech. A menu with no name is unlabelled. */
   "aria-label"?: string;
@@ -109,10 +122,12 @@ export function Menu({
   "data-preview-state": previewState,
   ...root
 }: MenuProps) {
+  const inline = useInlinePortal(container);
   return (
     <BaseMenu.Root {...root}>
       <BaseMenu.Trigger render={trigger} />
-      <BaseMenu.Portal container={container}>
+      {inline.host}
+      <BaseMenu.Portal {...inline.portal}>
         <BaseMenu.Positioner
           side={side}
           align={align}
@@ -153,10 +168,12 @@ export function ContextMenu({
   "data-preview-state": previewState,
   ...root
 }: Omit<ContextMenuProps, "side" | "align" | "sideOffset">) {
+  const inline = useInlinePortal(container);
   return (
     <BaseContextMenu.Root {...root}>
       <BaseContextMenu.Trigger render={trigger} />
-      <BaseContextMenu.Portal container={container}>
+      {inline.host}
+      <BaseContextMenu.Portal {...inline.portal}>
         <BaseContextMenu.Positioner collisionPadding={VIEWPORT_MARGIN} className={POPUP_LAYER}>
           <BaseContextMenu.Popup
             aria-label={ariaLabel}

package/src/components/ui/Popover.tsx

@@ -6,9 +6,13 @@
 import { Popover as BasePopover } from "@base-ui/react/popover";
 import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
 import { cn } from "./cn";
-import { POPUP_LAYER, popupSurface, type PopupPreviewState } from "./Menu";
-
-type PortalContainer = ComponentPropsWithoutRef<typeof BasePopover.Portal>["container"];
+import {
+  POPUP_LAYER,
+  popupSurface,
+  useInlinePortal,
+  type PopupPreviewState,
+  type PortalContainer,
+} from "./Menu";
 
 /** Matches Menu's gap from its trigger, and its viewport margin. */
 const SIDE_OFFSET = 6;
@@ -33,7 +37,7 @@ interface PopoverProps extends Omit<ComponentPropsWithoutRef<typeof BasePopover.
   sideOffset?: number;
   /** Points the popup at its trigger. Off by default; the default gap from the trigger grows by the arrow's height. */
   arrow?: boolean;
-  /** Portal target. Pass the shadow root when the trigger lives in one. */
+  /** Portal target. Pass the shadow root when the trigger lives in one; `null` keeps it inline. */
   container?: PortalContainer;
   /** Names the popup for assistive tech. */
   "aria-label"?: string;
@@ -60,10 +64,12 @@ export function Popover({
   "data-preview-state": previewState,
   ...root
 }: PopoverProps) {
+  const inline = useInlinePortal(container);
   return (
     <BasePopover.Root {...root}>
       <BasePopover.Trigger render={trigger} />
-      <BasePopover.Portal container={container}>
+      {inline.host}
+      <BasePopover.Portal {...inline.portal}>
         <BasePopover.Positioner
           side={side}
           align={align}