@hyperframes/studio 0.7.54 → 0.7.56

package/src/components/StudioRightPanel.tsx

@@ -446,12 +446,14 @@ export function StudioRightPanel({
 
   return (
     <>
+      {/* Vertical resize divider: 3px visible seam, 8px pointer-capture zone via
+          the absolutely-positioned inner hit area. */}
       <div
         role="separator"
         aria-label="Resize inspector panel"
         aria-orientation="vertical"
         tabIndex={0}
-        className="group w-2 flex-shrink-0 cursor-col-resize flex items-center justify-center outline-none focus-visible:bg-studio-accent/20"
+        className="group relative w-[3px] flex-shrink-0 cursor-col-resize outline-none focus-visible:bg-studio-accent/20"
         style={{ touchAction: "none" }}
         onPointerDown={(e) => handlePanelResizeStart("right", e)}
         onPointerMove={handlePanelResizeMove}
@@ -465,10 +467,13 @@ export function StudioRightPanel({
           setRightWidth(Math.max(160, Math.min(600, rightWidth + delta)));
         }}
       >
-        <div className="h-[52px] w-px bg-white/12 transition-colors group-hover:bg-white/18 group-active:bg-white/24" />
+        {/* Expanded hit zone: 8px wide, centered on the 3px seam */}
+        <div className="absolute inset-y-0 -left-[2.5px] w-2" />
+        {/* Visible hairline */}
+        <div className="absolute top-1/2 left-0 h-[52px] w-[3px] -translate-y-1/2 bg-white/12 transition-colors group-hover:bg-white/18 group-active:bg-white/24" />
       </div>
       <div
-        className="flex min-w-0 flex-shrink-0 flex-col overflow-hidden border-l border-neutral-800 bg-neutral-900"
+        className="flex min-w-0 flex-shrink-0 flex-col overflow-hidden rounded-lg border border-neutral-800 bg-neutral-900"
         style={{ width: rightWidth }}
       >
         {captionEditMode ? (

package/src/components/TimelineToolbar.test.tsx

@@ -2,7 +2,7 @@
 
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 import { usePlayerStore } from "../player/store/playerStore";
 import { TimelineToolbar } from "./TimelineToolbar";
 
@@ -18,7 +18,7 @@ function renderToolbar() {
   document.body.append(host);
   const root = createRoot(host);
   act(() => {
-    root.render(<TimelineToolbar toggleTimelineVisibility={vi.fn()} />);
+    root.render(<TimelineToolbar />);
   });
   return { host, root };
 }

package/src/components/TimelineToolbar.tsx

@@ -1,4 +1,5 @@
-import { useRef } from "react";
+import { useEffect, useRef } from "react";
+import { Magnet, MagnifyingGlassMinus, MagnifyingGlassPlus } from "@phosphor-icons/react";
 import {
   useEnableKeyframes,
   isPlayheadWithinTween,
@@ -9,9 +10,10 @@ import { useKeyframeKeyboard } from "../hooks/useKeyframeKeyboard";
 import {
   getNextTimelineZoomPercent,
   getTimelineZoomPercent,
+  timelineZoomPercentToSlider,
+  timelineSliderToZoomPercent,
 } from "../player/components/timelineZoom";
 import { useTimelineZoom } from "../player/components/useTimelineZoom";
-import { getTimelineToggleTitle } from "../utils/timelineDiscovery";
 import { usePlayerStore, type TimelineElement } from "../player";
 import {
   STUDIO_KEYFRAMES_ENABLED,
@@ -30,7 +32,6 @@ interface DomEditSessionSlice extends EnableKeyframesSession {
 }
 
 interface TimelineToolbarProps {
-  toggleTimelineVisibility: () => void;
   domEditSession?: DomEditSessionSlice;
   onSplitElement?: (element: TimelineElement, splitTime: number) => void;
 }
@@ -72,18 +73,20 @@ function useKeyframeToggle(session?: DomEditSessionSlice) {
 }
 
 // fallow-ignore-next-line complexity
-export function TimelineToolbar({
-  toggleTimelineVisibility,
-  domEditSession,
-  onSplitElement,
-}: TimelineToolbarProps) {
+export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineToolbarProps) {
   const activeTool = usePlayerStore((s) => s.activeTool);
   const setActiveTool = usePlayerStore((s) => s.setActiveTool);
+  const timelineSnapEnabled = usePlayerStore((s) => s.timelineSnapEnabled);
+  const setTimelineSnapEnabled = usePlayerStore((s) => s.setTimelineSnapEnabled);
   const autoKeyframeEnabled = usePlayerStore((s) => s.autoKeyframeEnabled);
   const setAutoKeyframeEnabled = usePlayerStore((s) => s.setAutoKeyframeEnabled);
   // Subscribe so the add-beat button reacts to playhead movement and analysis load.
   const currentTime = usePlayerStore((s) => s.currentTime);
   const beatAnalysisReady = usePlayerStore((s) => s.beatAnalysis !== null);
+  // Subscribe (not getState) so the split button enables/disables the moment
+  // the selection changes, not only on the next playhead tick.
+  const selectedElementId = usePlayerStore((s) => s.selectedElementId);
+  const elements = usePlayerStore((s) => s.elements);
   const { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent } = useTimelineZoom();
   const displayedTimelineZoomPercent = getTimelineZoomPercent(zoomMode, manualZoomPercent);
   const {
@@ -99,28 +102,48 @@ export function TimelineToolbar({
     onAddKeyframe: onToggleKeyframe,
   });
 
+  // "N" toggles timeline snapping (industry convention: Resolve/FCP).
+  // Skip when typing in an input/contenteditable.
+  useEffect(() => {
+    // fallow-ignore-next-line complexity
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== "n" && e.key !== "N") return;
+      if (e.metaKey || e.ctrlKey || e.altKey) return;
+      const target = e.target instanceof HTMLElement ? e.target : null;
+      if (target?.isContentEditable) return;
+      const tag = target?.tagName?.toLowerCase() ?? "";
+      if (tag === "input" || tag === "textarea" || tag === "select") return;
+      const store = usePlayerStore.getState();
+      store.setTimelineSnapEnabled(!store.timelineSnapEnabled);
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, []);
+
+  // CapCut-flat icon buttons: no per-button border/box chrome — a transparent
+  // 28px hit area with a subtle rounded hover wash, consistent 16px glyphs.
+  const flatBtn = "flex h-7 w-7 items-center justify-center rounded-md transition-colors";
+  const flatIdle = `${flatBtn} text-neutral-400 hover:bg-white/[0.06] hover:text-neutral-200 active:scale-[0.98]`;
+  const flatActive = `${flatBtn} bg-white/[0.08] text-neutral-100 active:scale-[0.98]`;
+  const flatDisabled = `${flatBtn} text-neutral-700 cursor-not-allowed`;
+
   return (
-    <div className="border-b border-neutral-800/40 bg-neutral-950/96">
-      <div className="flex items-center justify-between px-3 py-2">
-        <div className="flex items-center gap-3">
-          <div className="text-[10px] font-medium uppercase tracking-[0.16em] text-neutral-500">
-            Timeline
-          </div>
+    // The "TIMELINE" label is dropped for CapCut-like density — the pane's
+    // position (tracks right below) makes it self-evident.
+    <div className="border-b border-neutral-800/60">
+      <div className="flex items-center justify-between px-2 py-0.5">
+        <div className="flex items-center gap-0.5">
           {STUDIO_RAZOR_TOOL_ENABLED && (
-            <div className="flex items-center border border-neutral-800 rounded overflow-hidden">
+            <>
               <Tooltip label="Selection tool (V)">
                 <button
                   type="button"
                   onClick={() => setActiveTool("select")}
                   aria-label="Selection tool"
                   aria-pressed={activeTool === "select"}
-                  className={`flex h-6 w-6 items-center justify-center transition-colors active:scale-[0.98] ${
-                    activeTool === "select"
-                      ? "bg-neutral-700 text-neutral-200"
-                      : "text-neutral-500 hover:text-neutral-300"
-                  }`}
+                  className={activeTool === "select" ? flatActive : flatIdle}
                 >
-                  <svg width="12" height="12" viewBox="0 0 12 12" fill="currentColor">
+                  <svg width="16" height="16" viewBox="0 0 12 12" fill="currentColor">
                     <path d="M2 0.5L10 6L6.5 6.5L8.5 11L6.5 11.5L4.5 7L2 9Z" />
                   </svg>
                 </button>
@@ -131,46 +154,65 @@ export function TimelineToolbar({
                   onClick={() => setActiveTool("razor")}
                   aria-label="Razor tool"
                   aria-pressed={activeTool === "razor"}
-                  className={`flex h-6 w-6 items-center justify-center transition-colors active:scale-[0.98] ${
-                    activeTool === "razor"
-                      ? "bg-neutral-700 text-neutral-200"
-                      : "text-neutral-500 hover:text-neutral-300"
-                  }`}
+                  className={activeTool === "razor" ? flatActive : flatIdle}
                 >
-                  <Scissors size={11} />
+                  <Scissors size={16} />
                 </button>
               </Tooltip>
-            </div>
+              {/* Divider: tool-mode | editing-actions */}
+              <div aria-hidden="true" className="mx-1 h-4 w-px bg-neutral-800" />
+            </>
           )}
-          {STUDIO_KEYFRAMES_ENABLED && onToggleKeyframe && (
+          <Tooltip label={timelineSnapEnabled ? "Snapping on (N)" : "Snapping off (N)"}>
+            <button
+              type="button"
+              onClick={() => setTimelineSnapEnabled(!timelineSnapEnabled)}
+              aria-label="Toggle timeline snapping"
+              aria-pressed={timelineSnapEnabled}
+              className={timelineSnapEnabled ? flatActive : flatIdle}
+            >
+              <Magnet size={16} weight="bold" aria-hidden="true" />
+            </button>
+          </Tooltip>
+          {STUDIO_KEYFRAMES_ENABLED && (
+            // Always rendered (CapCut-style): with no keyframeable selection the
+            // button fades to a disabled state instead of unmounting, so the
+            // toolbar layout never shifts.
             <Tooltip
               label={
-                keyframeState === "active"
-                  ? "Remove keyframe at playhead (K)"
-                  : keyframeState === "inactive"
-                    ? keyframeWillExtend
-                      ? "Add keyframe at playhead, extends animation (K)"
-                      : "Add keyframe at playhead (K)"
-                    : "Add keyframe (K)"
+                !onToggleKeyframe
+                  ? "Select an animated element to add keyframes"
+                  : keyframeState === "active"
+                    ? "Remove keyframe at playhead (K)"
+                    : keyframeState === "inactive"
+                      ? keyframeWillExtend
+                        ? "Add keyframe at playhead, extends animation (K)"
+                        : "Add keyframe at playhead (K)"
+                      : "Add keyframe (K)"
               }
             >
               <button
                 type="button"
+                disabled={!onToggleKeyframe}
                 onClick={onToggleKeyframe}
                 aria-label={
                   keyframeState === "active"
                     ? "Remove keyframe at playhead"
                     : "Add keyframe at playhead"
                 }
-                className={`flex h-7 w-7 items-center justify-center rounded transition-colors active:scale-[0.98] ${
-                  keyframeState === "active"
-                    ? "text-studio-accent"
-                    : keyframeState === "inactive"
-                      ? "text-neutral-400 hover:text-studio-accent"
-                      : "text-neutral-600 hover:text-neutral-400"
-                }`}
+                className={
+                  !onToggleKeyframe
+                    ? flatDisabled
+                    : `${flatBtn} active:scale-[0.98] hover:bg-white/[0.06] ${
+                        keyframeState === "active"
+                          ? "text-studio-accent"
+                          : keyframeState === "inactive"
+                            ? "text-neutral-400 hover:text-studio-accent"
+                            : "text-neutral-600 hover:text-neutral-400"
+                      }`
+                }
               >
-                <svg width="18" height="18" viewBox="0 0 10 10" fill="currentColor">
+                <svg width="16" height="16" viewBox="0 0 10 10" fill="currentColor">
                   {keyframeState === "active" ? (
                     <path d="M5 0.5L9.5 5L5 9.5L0.5 5Z" />
                   ) : (
@@ -198,13 +240,13 @@ export function TimelineToolbar({
                 onClick={() => setAutoKeyframeEnabled(!autoKeyframeEnabled)}
                 aria-label="Auto-record manual edits as keyframes"
                 aria-pressed={autoKeyframeEnabled}
-                className={`flex h-7 w-7 items-center justify-center rounded transition-colors active:scale-[0.98] ${
+                className={`${flatBtn} active:scale-[0.98] hover:bg-white/[0.06] ${
                   autoKeyframeEnabled
                     ? "text-red-400 hover:text-red-300"
                     : "text-neutral-600 hover:text-neutral-400"
                 }`}
               >
-                <svg width="18" height="18" viewBox="0 0 10 10" fill="none">
+                <svg width="16" height="16" viewBox="0 0 10 10" fill="none">
                   {/* Same diamond outline as the Add-keyframe icon, with a
                       record-style dot inside: filled = auto-recording,
                       hollow = manual edits won't be keyframed. */}
@@ -225,7 +267,7 @@ export function TimelineToolbar({
             (() => {
               // Render the button unconditionally (disabled when unusable):
               // mounting/unmounting mid-task shifts the neighboring controls.
-              const { selectedElementId, elements, currentTime } = usePlayerStore.getState();
+              // Mirrors the S-key gate: selected clip + playhead strictly inside it.
               const el = selectedElementId
                 ? elements.find((e) => (e.key ?? e.id) === selectedElementId)
                 : null;
@@ -236,7 +278,7 @@ export function TimelineToolbar({
                 <Tooltip
                   label={
                     canSplit
-                      ? "Split clip at playhead (S)"
+                      ? "Split at playhead (S)"
                       : splittable
                         ? "Move the playhead inside the clip to split"
                         : "Select a clip to split"
@@ -245,64 +287,84 @@ export function TimelineToolbar({
                   <button
                     type="button"
                     disabled={!canSplit}
-                    aria-label="Split clip at playhead"
+                    aria-label="Split at playhead"
                     onClick={() => {
                       if (canSplit && el) onSplitElement(el, currentTime);
                     }}
-                    className={`flex h-7 w-7 items-center justify-center rounded transition-colors ${
-                      canSplit
-                        ? "text-neutral-500 hover:text-neutral-200 active:scale-[0.98]"
-                        : "text-neutral-700 cursor-not-allowed"
-                    }`}
-                  >
-                    <Scissors size={15} />
-                  </button>
-                </Tooltip>
-              );
-            })()}
-          {beatAnalysisReady &&
-            (() => {
-              const canAdd = canAddBeatAt(currentTime);
-              return (
-                <Tooltip
-                  label={canAdd ? "Add beat at playhead" : "A beat already exists at the playhead"}
-                >
-                  <button
-                    type="button"
-                    disabled={!canAdd}
-                    aria-label="Add beat at playhead"
-                    onClick={() => {
-                      if (canAdd) addBeatAtCompositionTime(currentTime);
-                    }}
-                    className={`flex h-7 w-7 items-center justify-center rounded transition-colors ${
-                      canAdd
-                        ? "text-neutral-500 hover:text-[#22c55e] active:scale-[0.98]"
-                        : "text-neutral-700 cursor-not-allowed"
-                    }`}
+                    className={canSplit ? flatIdle : flatDisabled}
                   >
-                    <svg width="16" height="16" viewBox="0 0 24 24" fill="none">
-                      <path
-                        d="M21 10C21 12.2091 16.9706 14 12 14M21 10C21 7.79086 16.9706 6 12 6C7.02944 6 3 7.79086 3 10M21 10V16C21 18.2091 16.9706 20 12 20M12 14C7.02944 14 3 12.2091 3 10M12 14V20M3 10V16C3 18.2091 7.02944 20 12 20M7 19.3264V13.3264M17 19.3264V13.3264M12 10L20 4"
-                        stroke="currentColor"
-                        strokeWidth="2"
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                      />
+                    {/* "][" split glyph: two outward-facing brackets with a center gap */}
+                    <svg
+                      width="16"
+                      height="16"
+                      viewBox="0 0 16 16"
+                      fill="none"
+                      stroke="currentColor"
+                      strokeWidth="1.6"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      aria-hidden="true"
+                    >
+                      {/* Right bracket of left half: ] */}
+                      <path d="M5 3 L7 3 L7 13 L5 13" />
+                      {/* Left bracket of right half: [ */}
+                      <path d="M11 3 L9 3 L9 13 L11 13" />
                     </svg>
                   </button>
                 </Tooltip>
               );
             })()}
+          {(() => {
+            // Always rendered (CapCut-style): before beat analysis loads (or when
+            // the project has no analyzed music) the button fades to a disabled
+            // state instead of unmounting, so the toolbar layout never shifts.
+            const canAdd = beatAnalysisReady && canAddBeatAt(currentTime);
+            return (
+              <Tooltip
+                label={
+                  !beatAnalysisReady
+                    ? "Add a music track with beat analysis to place beats"
+                    : canAdd
+                      ? "Add beat at playhead"
+                      : "A beat already exists at the playhead"
+                }
+              >
+                <button
+                  type="button"
+                  disabled={!canAdd}
+                  aria-label="Add beat at playhead"
+                  onClick={() => {
+                    if (canAdd) addBeatAtCompositionTime(currentTime);
+                  }}
+                  className={
+                    canAdd
+                      ? `${flatBtn} text-neutral-400 hover:bg-white/[0.06] hover:text-[#22c55e] active:scale-[0.98]`
+                      : flatDisabled
+                  }
+                >
+                  <svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+                    <path
+                      d="M21 10C21 12.2091 16.9706 14 12 14M21 10C21 7.79086 16.9706 6 12 6C7.02944 6 3 7.79086 3 10M21 10V16C21 18.2091 16.9706 20 12 20M12 14C7.02944 14 3 12.2091 3 10M12 14V20M3 10V16C3 18.2091 7.02944 20 12 20M7 19.3264V13.3264M17 19.3264V13.3264M12 10L20 4"
+                      stroke="currentColor"
+                      strokeWidth="2"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                    />
+                  </svg>
+                </button>
+              </Tooltip>
+            );
+          })()}
         </div>
-        <div className="flex items-center gap-1">
+        <div className="flex items-center gap-0.5">
           <Tooltip label="Fit timeline to width">
             <button
               type="button"
               onClick={() => setZoomMode("fit")}
-              className={`h-7 px-2.5 rounded-md border text-[11px] font-medium transition-colors ${
+              className={`h-7 px-2 rounded-md text-[11px] font-medium transition-colors ${
                 zoomMode === "fit"
-                  ? "border-studio-accent/30 bg-studio-accent/10 text-studio-accent"
-                  : "border-neutral-800 text-neutral-400 hover:border-neutral-700 hover:text-neutral-200"
+                  ? "bg-studio-accent/10 text-studio-accent"
+                  : "text-neutral-400 hover:bg-white/[0.06] hover:text-neutral-200"
               }`}
             >
               Fit
@@ -311,55 +373,51 @@ export function TimelineToolbar({
           <Tooltip label="Zoom out">
             <button
               type="button"
+              aria-label="Zoom out"
               onClick={() => {
                 setZoomMode("manual");
                 setManualZoomPercent(
                   getNextTimelineZoomPercent("out", zoomMode, manualZoomPercent),
                 );
               }}
-              className="h-7 w-7 rounded-md border border-neutral-800 text-neutral-400 transition-colors hover:border-neutral-700 hover:text-neutral-200"
+              className={flatIdle}
             >
-              -
+              <MagnifyingGlassMinus size={16} aria-hidden="true" />
             </button>
           </Tooltip>
-          <div className="min-w-[58px] text-center text-[10px] font-medium tabular-nums text-neutral-500">
-            {`${displayedTimelineZoomPercent}%`}
-          </div>
+          <input
+            type="range"
+            min="0"
+            max="100"
+            value={timelineZoomPercentToSlider(displayedTimelineZoomPercent)}
+            title={`${displayedTimelineZoomPercent}%`}
+            aria-label="Timeline zoom"
+            onChange={(e) => {
+              setZoomMode("manual");
+              setManualZoomPercent(timelineSliderToZoomPercent(Number(e.target.value)));
+            }}
+            className="mx-1 w-[96px] cursor-pointer appearance-none bg-transparent [&::-webkit-slider-runnable-track]:h-[2px] [&::-webkit-slider-runnable-track]:rounded-full [&::-webkit-slider-runnable-track]:bg-neutral-700 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-[10px] [&::-webkit-slider-thumb]:h-[10px] [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-white [&::-webkit-slider-thumb]:-mt-1 [&::-webkit-slider-thumb]:shadow-[0_0_0_2px_#0a0a0a,0_1px_3px_rgba(0,0,0,0.5)] [&::-webkit-slider-thumb]:cursor-grab [&::-webkit-slider-thumb:active]:cursor-grabbing"
+          />
           <Tooltip label="Zoom in">
             <button
               type="button"
+              aria-label="Zoom in"
               onClick={() => {
                 setZoomMode("manual");
                 setManualZoomPercent(getNextTimelineZoomPercent("in", zoomMode, manualZoomPercent));
               }}
-              className="h-7 w-7 rounded-md border border-neutral-800 text-neutral-400 transition-colors hover:border-neutral-700 hover:text-neutral-200"
+              className={flatIdle}
             >
-              +
-            </button>
-          </Tooltip>
-          <Tooltip label={getTimelineToggleTitle(true)}>
-            <button
-              type="button"
-              onClick={toggleTimelineVisibility}
-              className="ml-1 flex h-7 w-7 items-center justify-center rounded-md text-neutral-500 transition-colors hover:bg-neutral-900 hover:text-neutral-200"
-              aria-label="Hide timeline editor"
-            >
-              <svg
-                width="14"
-                height="14"
-                viewBox="0 0 24 24"
-                fill="none"
-                stroke="currentColor"
-                strokeWidth="1.8"
-                strokeLinecap="round"
-                strokeLinejoin="round"
-                aria-hidden="true"
-              >
-                <path d="M5 7h14" />
-                <path d="m8 11 4 4 4-4" />
-              </svg>
+              <MagnifyingGlassPlus size={16} aria-hidden="true" />
             </button>
           </Tooltip>
+          {/* Numeric zoom readout (main-parity): "Fit" in fit mode, N% in manual. */}
+          <span
+            className="ml-1 w-[38px] text-right font-mono text-[11px] tabular-nums text-neutral-500 select-none"
+            aria-label="Timeline zoom level"
+          >
+            {zoomMode === "fit" ? "Fit" : `${displayedTimelineZoomPercent}%`}
+          </span>
         </div>
       </div>
     </div>

package/src/components/editor/CanvasContextMenu.test.tsx

@@ -0,0 +1,115 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { installReactActEnvironment, makeSelection } from "../../hooks/domSelectionTestHarness";
+import { CanvasContextMenu } from "./CanvasContextMenu";
+import type { DomEditSelection } from "./domEditing";
+
+installReactActEnvironment();
+
+let host: HTMLDivElement;
+let root: Root | null = null;
+
+beforeEach(() => {
+  host = document.createElement("div");
+  document.body.append(host);
+});
+
+afterEach(() => {
+  act(() => root?.unmount());
+  root = null;
+  document.body.innerHTML = "";
+});
+
+function renderMenu(props: {
+  selection: DomEditSelection;
+  onApplyZIndex?: () => void;
+  onDelete?: (selection: DomEditSelection) => void;
+}) {
+  root = createRoot(host);
+  act(() => {
+    root!.render(
+      React.createElement(CanvasContextMenu, {
+        x: 10,
+        y: 10,
+        selection: props.selection,
+        onClose: () => {},
+        onApplyZIndex: props.onApplyZIndex,
+        onDelete: props.onDelete,
+      }),
+    );
+  });
+}
+
+/** All menu buttons live in the portal under document.body. */
+function menuButtons(): HTMLButtonElement[] {
+  return [...document.body.querySelectorAll("button")];
+}
+
+function hasDeleteItem(): boolean {
+  return menuButtons().some((b) => b.textContent?.includes("Delete"));
+}
+
+function zOrderButtons(): HTMLButtonElement[] {
+  return menuButtons().filter((b) => !b.textContent?.includes("Delete"));
+}
+
+describe("CanvasContextMenu — handler gating", () => {
+  it("renders all four z-order items, a divider, and Delete when both handlers are present", () => {
+    const el = document.createElement("div");
+    el.id = "target";
+    document.body.append(el);
+
+    renderMenu({
+      selection: makeSelection("Target", el),
+      onApplyZIndex: vi.fn(),
+      onDelete: vi.fn(),
+    });
+
+    expect(zOrderButtons()).toHaveLength(4);
+    expect(hasDeleteItem()).toBe(true);
+    // The divider only appears between the two groups.
+    expect(document.body.querySelector(".border-t")).not.toBeNull();
+  });
+
+  it("hides every item and does NOT render the menu when no handlers are present", () => {
+    const el = document.createElement("div");
+    el.id = "target";
+    // A z-index that a stray optimistic write would clobber — assert it is
+    // untouched, since the menu must not mutate the DOM without a persist path.
+    el.style.zIndex = "3";
+    document.body.append(el);
+
+    renderMenu({ selection: makeSelection("Target", el) });
+
+    // No menu opened at all — no buttons, no dead-end items, no DOM mutation.
+    expect(menuButtons()).toHaveLength(0);
+    expect(document.body.querySelector(".fixed.z-50")).toBeNull();
+    expect(el.style.zIndex).toBe("3");
+  });
+
+  it("shows only the z-order items (no Delete, no divider) when onDelete is absent", () => {
+    const el = document.createElement("div");
+    el.id = "target";
+    document.body.append(el);
+
+    renderMenu({ selection: makeSelection("Target", el), onApplyZIndex: vi.fn() });
+
+    expect(zOrderButtons()).toHaveLength(4);
+    expect(hasDeleteItem()).toBe(false);
+    expect(document.body.querySelector(".border-t")).toBeNull();
+  });
+
+  it("shows only Delete (no z-order items, no divider) when onApplyZIndex is absent", () => {
+    const el = document.createElement("div");
+    el.id = "target";
+    document.body.append(el);
+
+    renderMenu({ selection: makeSelection("Target", el), onDelete: vi.fn() });
+
+    expect(zOrderButtons()).toHaveLength(0);
+    expect(hasDeleteItem()).toBe(true);
+    expect(document.body.querySelector(".border-t")).toBeNull();
+  });
+});