@open-slide/core 1.6.0 → 1.7.0

package/dist/index.d.ts

@@ -52,9 +52,26 @@ declare function useSlidePageNumber(): {
   total: number;
 };
 
+//#endregion
+//#region src/app/lib/transition.d.ts
+type TransitionPhase = {
+  keyframes: Keyframe[] | PropertyIndexedKeyframes;
+  easing?: string;
+  duration?: number;
+  delay?: number;
+};
+type SlideTransition = {
+  duration: number;
+  easing?: string;
+  enter?: TransitionPhase;
+  exit?: TransitionPhase;
+};
+
 //#endregion
 //#region src/app/lib/sdk.d.ts
-type Page = ComponentType;
+type Page = ComponentType & {
+  transition?: SlideTransition;
+};
 type SlideMeta = {
   title?: string;
   theme?: string;
@@ -66,9 +83,10 @@ type SlideModule = {
   meta?: SlideMeta;
   design?: DesignSystem;
   notes?: (string | undefined)[];
+  transition?: SlideTransition;
 };
 declare const CANVAS_WIDTH = 1920;
 declare const CANVAS_HEIGHT = 1080;
 
 //#endregion
-export { CANVAS_HEIGHT, CANVAS_WIDTH, DesignFonts, DesignPalette, DesignSystem, DesignTypeScale, ImagePlaceholder, ImagePlaceholderProps, Locale, OpenSlideConfig, Page, Plural, SlideMeta, SlideModule, cssVarsToString, defaultDesign, designToCssVars, useSlidePageNumber };
+export { CANVAS_HEIGHT, CANVAS_WIDTH, DesignFonts, DesignPalette, DesignSystem, DesignTypeScale, ImagePlaceholder, ImagePlaceholderProps, Locale, OpenSlideConfig, Page, Plural, SlideMeta, SlideModule, SlideTransition, TransitionPhase, cssVarsToString, defaultDesign, designToCssVars, useSlidePageNumber };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-slide/core",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Runtime and CLI for open-slide — write slides in slides/, we handle the rest.",
   "type": "module",
   "exports": {

package/skills/slide-authoring/SKILL.md

@@ -308,6 +308,174 @@ const Footer = () => {
 
 `current` is 1-indexed (matches what readers see) and `total` is the slide's page count. The hook works in every render context (main viewer, thumbnails, overview grid, present mode, presenter window, HTML/PDF export) — the same `<Footer />` JSX is correct everywhere. Call the hook inside a component that's used **per page**; don't try to call it at module top level.
 
+## Page transitions
+
+The framework can run an enter/exit animation between every slide change. There's **no default** — pages snap unless you declare a `SlideTransition`. Snap-swap is a perfectly tasteful default; only opt in when motion adds something.
+
+`prefers-reduced-motion: reduce` is honored automatically. You don't write a fallback.
+
+### Contract
+
+Module-level for the whole deck; per-page to override. The **incoming page wins**: navigating A → B uses `pages[B].transition ?? module.transition`. Its `exit` plays on A, its `enter` plays on B. Going back B → A uses A's transition.
+
+```tsx
+import type { Page, SlideTransition } from '@open-slide/core';
+
+const Cover: Page = () => <section>…</section>;
+const Body:  Page = () => <section>…</section>;
+
+// Module-level default — every page inherits unless it overrides.
+export const transition: SlideTransition = { /* … */ };
+
+// Per-page override.
+Cover.transition = { /* … */ };
+
+export default [Cover, Body];
+```
+
+```ts
+type TransitionPhase = {
+  keyframes: Keyframe[] | PropertyIndexedKeyframes;  // WAAPI keyframes
+  duration?: number;  // ms (falls back to top-level duration)
+  easing?: string;    // CSS easing
+  delay?: number;     // ms — use to overlap exit + enter
+};
+type SlideTransition = {
+  duration: number;          // top-level fallback
+  easing?: string;           // top-level fallback
+  enter?: TransitionPhase;   // runs on incoming page
+  exit?:  TransitionPhase;   // runs on outgoing page
+};
+```
+
+The framework also exposes `--osd-dir` (`1` forward, `-1` backward) and `data-osd-dir` on the wrapper, so a single keyframe can mirror direction without a JS callback.
+
+### Design principles (hold the line)
+
+The single loudest signal of "made in PowerPoint" is six different transitions in one deck. Restraint is the rhythm.
+
+- **Pick one DNA, hold it across the deck.** Same duration band, same easing pair, same out-then-in stagger. Variation lives only in *which property* gets the small nudge — Y, X, opacity, scale, blur.
+- **Duration: 140–280 ms.** Exit 140–180 ms, enter 200–280 ms, enter delayed ~80 ms so they overlap but don't fight. Past 350 ms is video-editor territory; reserve for genuine state changes.
+- **Magnitude ceiling: 12 px or 3% scale.** A 6 px Y-rise reads as "next thought." A 1920 px translateX reads as "different document." Premium tools move barely enough to register.
+- **Opacity is always part of it.** Pure-transform transitions look stiff; pure-opacity transitions are the safest possible default.
+- **Easing: ease-in for exit, ease-out for enter.** `cubic-bezier(0.4, 0, 1, 1)` going out, `cubic-bezier(0, 0, 0.2, 1)` coming in. Never `linear` (feels like a slideshow). Reserve symmetric `ease-in-out` for state-anchored morphs only.
+
+### Tasteful family — six members, one DNA
+
+Use this set as a starting point. Pick one as the deck's house transition; optionally reserve a second for hero/cover slides and a third for genuine section breaks. The CSS-`calc` + `--osd-dir` trick lets a single definition mirror itself on backward navigation when needed.
+
+```tsx
+const EASE_OUT = 'cubic-bezier(0, 0, 0.2, 1)';
+const EASE_IN  = 'cubic-bezier(0.4, 0, 1, 1)';
+
+// RISE — house quiet. 6 px Y. Use as module default.
+export const transition: SlideTransition = {
+  duration: 200,
+  exit:  { duration: 140, easing: EASE_IN,
+           keyframes: [
+             { opacity: 1, transform: 'translateY(0)' },
+             { opacity: 0, transform: 'translateY(-4px)' },
+           ] },
+  enter: { duration: 200, delay: 80, easing: EASE_OUT,
+           keyframes: [
+             { opacity: 0, transform: 'translateY(6px)' },
+             { opacity: 1, transform: 'translateY(0)' },
+           ] },
+};
+
+// DISSOLVE — pure opacity. The quietest possible.
+const dissolve: SlideTransition = {
+  duration: 240,
+  exit:  { duration: 200, easing: EASE_IN,
+           keyframes: [{ opacity: 1 }, { opacity: 0 }] },
+  enter: { duration: 240, delay: 40, easing: EASE_OUT,
+           keyframes: [{ opacity: 0 }, { opacity: 1 }] },
+};
+
+// SETTLE — cover-grade. Rise + a hair of blur on enter only.
+Cover.transition = {
+  duration: 280,
+  exit:  { duration: 160, easing: EASE_IN,
+           keyframes: [
+             { opacity: 1, transform: 'translateY(0)' },
+             { opacity: 0, transform: 'translateY(-6px)' },
+           ] },
+  enter: { duration: 280, delay: 100, easing: EASE_OUT,
+           keyframes: [
+             { opacity: 0, transform: 'translateY(12px)', filter: 'blur(4px)' },
+             { opacity: 1, transform: 'translateY(0)',    filter: 'blur(0)'   },
+           ] },
+};
+
+// BLOOM — scale 0.97 → 1, no translate. Materializes in place.
+const bloom: SlideTransition = {
+  duration: 240,
+  exit:  { duration: 160, easing: EASE_IN,
+           keyframes: [
+             { opacity: 1, transform: 'scale(1)' },
+             { opacity: 0, transform: 'scale(1.01)' },
+           ] },
+  enter: { duration: 240, delay: 80, easing: EASE_OUT,
+           keyframes: [
+             { opacity: 0, transform: 'scale(0.97)' },
+             { opacity: 1, transform: 'scale(1)' },
+           ] },
+};
+
+// FALL — mirrored Rise. Incoming page comes down from above.
+const fall: SlideTransition = {
+  duration: 200,
+  exit:  { duration: 140, easing: EASE_IN,
+           keyframes: [
+             { opacity: 1, transform: 'translateY(0)' },
+             { opacity: 0, transform: 'translateY(4px)' },
+           ] },
+  enter: { duration: 200, delay: 80, easing: EASE_OUT,
+           keyframes: [
+             { opacity: 0, transform: 'translateY(-6px)' },
+             { opacity: 1, transform: 'translateY(0)' },
+           ] },
+};
+
+// BREATH — section break. Exit fully, hold 120 ms, then enter.
+// Reserve for genuine chapter dividers; use at most 1–2× per deck.
+const breath: SlideTransition = {
+  duration: 460,
+  exit:  { duration: 180, easing: EASE_IN,
+           keyframes: [{ opacity: 1 }, { opacity: 0 }] },
+  enter: { duration: 240, delay: 300, easing: EASE_OUT,
+           keyframes: [
+             { opacity: 0, transform: 'translateY(8px)' },
+             { opacity: 1, transform: 'translateY(0)' },
+           ] },
+};
+```
+
+All six share the same DNA — they only differ in which property carries the small nudge. The reader perceives variety; the eye still reads one consistent hand.
+
+### Direction-aware keyframes (use sparingly)
+
+Most tasteful tools don't mirror on backward navigation. When you genuinely need to — e.g. a horizontal slide that should reverse — use `--osd-dir` inside `calc()`:
+
+```tsx
+{ transform: 'translateX(calc(var(--osd-dir, 1) * 8px))' },
+{ transform: 'translateX(0)' },
+```
+
+If you find yourself reaching for this on every transition, you're probably over-designing. Forward = backward is the more refined default.
+
+### Transition anti-patterns
+
+- ❌ Six different transitions across six pages — the single loudest "made in PowerPoint" tell.
+- ❌ `translateX(100%)` slide-from-side — iOS modal / PowerPoint Push; not a slide change.
+- ❌ Aggressive scale-pop (e.g. `0.85 → 1`) + blur — lightbox / photo-viewer vocabulary; implies zooming *into* something.
+- ❌ `clip-path: inset(…)` reveals — After Effects vocabulary; theatrical.
+- ❌ Parallel blur on both layers at once — visual mush; the eye can't fixate.
+- ❌ Duration > 350 ms for a standard slide change — drags.
+- ❌ Translate > 12 px or scale > 3% — reads as rupture, not continuity.
+- ❌ `linear` easing — feels like a slideshow, not a product.
+- ❌ Declaring a transition on every deck. **If you don't have a clear reason, omit it.** Snap-swap is fine.
+
 ## Repeated elements: component, not `map`
 
 When a page has visually repeated items — cards, logo rows, gallery tiles, list rows, step indicators — **define a small component and instantiate it once per item**. Do **not** render the group with `array.map` over a data array.
@@ -373,6 +541,7 @@ This applies whenever the *visual element* repeats, not whenever the *data* does
 - [ ] Visually repeated elements (cards, tiles, logo rows) are rendered as explicit `<Component />` instances, not via `array.map` over a data list.
 - [ ] All imported assets exist on disk — slide-local under `slides/<id>/assets/`, or global under `assets/` (imported via `@assets/...`).
 - [ ] Every `<ImagePlaceholder>` corresponds to a real image the user must supply — not decorative filler. If it could be replaced by typography or layout, it should be.
+- [ ] If a `SlideTransition` is declared, every page sits in one family — same duration band (140–280 ms), same easing pair, same out-then-in stagger, magnitude under 12 px / 3%. No six-different-vocabularies decks. When in doubt, omit transitions entirely.
 - [ ] Nothing outside `slides/<id>/` was edited.
 
 ## Anti-patterns

package/src/app/components/inspector/asset-picker-dialog.tsx

@@ -0,0 +1,196 @@
+import { ArrowDownToLine, Loader2, Upload } from 'lucide-react';
+import type React from 'react';
+import { useCallback, useId, useRef, useState } from 'react';
+import { toast } from 'sonner';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { type AssetEntry, uploadWithAutoRename, useAssets } from '@/lib/assets';
+import { format, useLocale } from '@/lib/use-locale';
+import { cn } from '@/lib/utils';
+
+export type PickerScope = 'slide' | 'global';
+const GLOBAL_PICKER_SLIDE_ID = '@global';
+
+export function AssetPickerDialog({
+  slideId,
+  onClose,
+  onPick,
+}: {
+  slideId: string;
+  onClose: () => void;
+  onPick: (asset: AssetEntry, scope: PickerScope) => void;
+}) {
+  const [scope, setScope] = useState<PickerScope>('slide');
+  const effectiveSlideId = scope === 'global' ? GLOBAL_PICKER_SLIDE_ID : slideId;
+  const { assets, loading, refresh } = useAssets(effectiveSlideId);
+  const images = assets.filter((a) => a.mime.startsWith('image/'));
+  const t = useLocale();
+  const path = scope === 'global' ? 'assets/' : `slides/${slideId}/assets/`;
+  const [descPrefix, descSuffix] = t.inspector.replaceImageDescription.split('{path}');
+  const [uploading, setUploading] = useState(false);
+  const [dragActive, setDragActive] = useState(false);
+  const dragDepth = useRef(0);
+  const inputId = useId();
+
+  const handleFile = useCallback(
+    async (file: File) => {
+      if (!file.type.startsWith('image/')) return;
+      setUploading(true);
+      try {
+        const { ok, status, entry } = await uploadWithAutoRename(effectiveSlideId, file);
+        if (!ok || !entry) {
+          toast.error(format(t.asset.toastUploadFailed, { status }));
+          return;
+        }
+        await refresh().catch(() => {});
+        onPick(entry, scope);
+      } finally {
+        setUploading(false);
+      }
+    },
+    [effectiveSlideId, scope, refresh, onPick, t],
+  );
+
+  return (
+    <Dialog open onOpenChange={(o) => !o && onClose()}>
+      <DialogContent className="sm:max-w-xl">
+        <DialogHeader>
+          <DialogTitle>{t.inspector.replaceImageDialogTitle}</DialogTitle>
+          <DialogDescription>
+            {descPrefix}
+            <span className="font-mono">{path}</span>
+            {descSuffix}
+          </DialogDescription>
+        </DialogHeader>
+        <Tabs value={scope} onValueChange={(next) => setScope(next as PickerScope)}>
+          <TabsList>
+            <TabsTrigger value="slide">{t.asset.scopeSlide}</TabsTrigger>
+            <TabsTrigger value="global">{t.asset.scopeGlobal}</TabsTrigger>
+          </TabsList>
+        </Tabs>
+        <label
+          htmlFor={inputId}
+          className={cn(
+            'absolute right-12 top-3.5 inline-flex h-7 cursor-pointer items-center gap-1.5 rounded-[5px] border border-border bg-card px-2 text-[12px] font-medium transition-colors',
+            'hover:bg-muted/60 hover:border-foreground/20 active:translate-y-px',
+            uploading && 'pointer-events-none opacity-60',
+          )}
+        >
+          {uploading ? (
+            <Loader2 className="size-3.5 animate-spin" />
+          ) : (
+            <Upload className="size-3.5" />
+          )}
+          <span>{t.asset.upload}</span>
+        </label>
+        <input
+          id={inputId}
+          type="file"
+          accept="image/*"
+          className="sr-only"
+          disabled={uploading}
+          onChange={(e) => {
+            const file = e.target.files?.[0];
+            e.target.value = '';
+            if (file) handleFile(file).catch(() => {});
+          }}
+        />
+        <section
+          aria-label={t.inspector.replaceImageDialogTitle}
+          className="relative max-h-[60vh] overflow-y-auto"
+          onDragEnter={(e) => {
+            if (uploading || !hasFiles(e)) return;
+            e.preventDefault();
+            dragDepth.current += 1;
+            setDragActive(true);
+          }}
+          onDragOver={(e) => {
+            if (uploading || !hasFiles(e)) return;
+            e.preventDefault();
+            e.dataTransfer.dropEffect = 'copy';
+          }}
+          onDragLeave={() => {
+            dragDepth.current = Math.max(0, dragDepth.current - 1);
+            if (dragDepth.current === 0) setDragActive(false);
+          }}
+          onDrop={(e) => {
+            if (uploading || !hasFiles(e)) return;
+            e.preventDefault();
+            dragDepth.current = 0;
+            setDragActive(false);
+            const file = e.dataTransfer.files?.[0];
+            if (file) handleFile(file).catch(() => {});
+          }}
+        >
+          {loading ? (
+            <p className="px-1 py-6 text-center text-xs text-muted-foreground">
+              {t.inspector.pickerLoading}
+            </p>
+          ) : images.length === 0 ? (
+            <p className="px-1 py-6 text-center text-xs text-muted-foreground">
+              {t.inspector.pickerEmpty}
+            </p>
+          ) : (
+            <div className="grid grid-cols-[repeat(auto-fill,minmax(120px,1fr))] gap-3">
+              {images.map((asset) => (
+                <button
+                  key={asset.name}
+                  type="button"
+                  onClick={() => onPick(asset, scope)}
+                  className={cn(
+                    'group flex flex-col overflow-hidden rounded-lg border bg-card text-left shadow-sm transition-all',
+                    'hover:-translate-y-0.5 hover:shadow-md focus-visible:ring-2 focus-visible:ring-ring/50 focus-visible:outline-none',
+                  )}
+                >
+                  <div className="flex aspect-square w-full items-center justify-center overflow-hidden bg-[repeating-conic-gradient(theme(colors.muted)_0_25%,transparent_0_50%)] bg-[length:12px_12px]">
+                    <img
+                      src={asset.url}
+                      alt=""
+                      className="size-full object-contain"
+                      draggable={false}
+                    />
+                  </div>
+                  <div className="border-t px-2 py-1.5">
+                    <div className="truncate text-[11px] font-medium" title={asset.name}>
+                      {asset.name}
+                    </div>
+                  </div>
+                </button>
+              ))}
+            </div>
+          )}
+          {dragActive && (
+            <div
+              className="pointer-events-none absolute inset-0 z-10 animate-in fade-in-0 duration-200"
+              aria-hidden
+            >
+              <div className="absolute inset-0 bg-brand/5" />
+              <div className="absolute inset-1 rounded-[8px] border border-dashed border-brand/40" />
+              <div className="absolute inset-x-0 bottom-4 flex justify-center">
+                <div className="flex items-center gap-2 rounded-[6px] border border-border bg-card px-3 py-1.5 text-[12px] font-medium shadow-floating">
+                  <ArrowDownToLine className="size-3.5 text-brand" />
+                  <span>{t.asset.dropToUpload}</span>
+                </div>
+              </div>
+            </div>
+          )}
+        </section>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function hasFiles(e: React.DragEvent): boolean {
+  const types = e.dataTransfer?.types;
+  if (!types) return false;
+  for (let i = 0; i < types.length; i++) {
+    if (types[i] === 'Files') return true;
+  }
+  return false;
+}

package/src/app/components/inspector/inspect-overlay.tsx

@@ -1,6 +1,10 @@
+import { Crop, ImageIcon } from 'lucide-react';
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { PANEL_TRANSITION_MS } from '@/components/panel/panel-shell';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
 import { findSlideSource, type SlideSourceHit } from '@/lib/inspector/fiber';
+import { useLocale } from '@/lib/use-locale';
+import { cn } from '@/lib/utils';
 import { useInspector } from './inspector-provider';
 
 type Highlight = { hit: SlideSourceHit };
@@ -31,6 +35,9 @@ export function InspectOverlay() {
     };
 
     const onMove = (e: PointerEvent) => {
+      if (e.target instanceof Element && e.target.closest('[data-inspector-ui]')) {
+        return setHover(null);
+      }
       const el = pickInspectorTarget(pickElement(e.clientX, e.clientY));
       if (!el) return setHover(null);
       const hit = findSlideSource(el, slideId, { hostOnly: true });
@@ -75,37 +82,48 @@ export function InspectOverlay() {
     };
   }, [active, slideId, setSelected, cancel, openCrop]);
 
+  const hoverAnchor = hover?.hit.anchor.isConnected ? hover.hit.anchor : null;
+  const selectedAnchor = selected?.anchor.isConnected ? selected.anchor : null;
+  const dedupedHover = hoverAnchor && hoverAnchor !== selectedAnchor ? hoverAnchor : null;
+
+  if (!active) return null;
   return (
-    <FrameOverlay
-      active={active}
-      overlayRef={overlayRef}
-      // Pin to the selection so the highlight tracks what the panel
-      // is editing even after the cursor moves away.
-      targetAnchor={selected?.anchor ?? hover?.hit.anchor ?? null}
-    />
+    <div ref={overlayRef} data-inspector-ui className="pointer-events-none absolute inset-0 z-30">
+      <Frame anchor={selectedAnchor} overlayRef={overlayRef} variant="selected" showImageActions />
+      <Frame anchor={dedupedHover} overlayRef={overlayRef} variant="hover" />
+    </div>
   );
 }
 
-function FrameOverlay({
-  active,
+type FrameVariant = 'selected' | 'hover';
+
+const FRAME_STYLES: Record<FrameVariant, React.CSSProperties> = {
+  selected: { outline: '2px solid #3b82f6', background: 'rgba(59,130,246,0.1)' },
+  hover: { outline: '1.5px dashed #3b82f6', background: 'rgba(59,130,246,0.05)' },
+};
+
+function Frame({
+  anchor,
   overlayRef,
-  targetAnchor,
+  variant,
+  showImageActions = false,
 }: {
-  active: boolean;
+  anchor: HTMLElement | null;
   overlayRef: React.RefObject<HTMLDivElement>;
-  targetAnchor: HTMLElement | null;
+  variant: FrameVariant;
+  showImageActions?: boolean;
 }) {
   const [rect, setRect] = useState<RelRect | null>(null);
   const [hasTarget, setHasTarget] = useState(false);
 
   const measure = useCallback(() => {
     const overlay = overlayRef.current;
-    if (!active || !targetAnchor?.isConnected || !overlay) {
+    if (!anchor?.isConnected || !overlay) {
       setHasTarget(false);
       return;
     }
 
-    const targetRect = targetAnchor.getBoundingClientRect();
+    const targetRect = anchor.getBoundingClientRect();
     const overlayRect = overlay.getBoundingClientRect();
     const next = {
       left: targetRect.left - overlayRect.left,
@@ -116,14 +134,14 @@ function FrameOverlay({
 
     setHasTarget(true);
     setRect((prev) => (sameRect(prev, next) ? prev : next));
-  }, [active, overlayRef, targetAnchor]);
+  }, [overlayRef, anchor]);
 
   useLayoutEffect(() => {
     measure();
   }, [measure]);
 
   useEffect(() => {
-    if (!active) {
+    if (!anchor) {
       setHasTarget(false);
       return;
     }
@@ -139,7 +157,7 @@ function FrameOverlay({
     const root = document.querySelector<HTMLElement>('[data-inspector-root]');
     if (root) resizeObserver.observe(root);
     if (overlayRef.current) resizeObserver.observe(overlayRef.current);
-    if (targetAnchor) resizeObserver.observe(targetAnchor);
+    resizeObserver.observe(anchor);
 
     const stopAt = performance.now() + LAYOUT_TRACK_MS;
     const trackPanelTransition = () => {
@@ -157,9 +175,9 @@ function FrameOverlay({
       window.removeEventListener('resize', scheduleMeasure, true);
       window.removeEventListener('scroll', scheduleMeasure, true);
     };
-  }, [active, measure, overlayRef, targetAnchor]);
+  }, [measure, overlayRef, anchor]);
 
-  const visible = !!(active && hasTarget && rect);
+  const visible = !!(hasTarget && rect);
 
   // First render after appearing: snap to the new rect (no transition).
   // Subsequent rect changes in the same visible session: animate.
@@ -173,31 +191,110 @@ function FrameOverlay({
     return () => clearTimeout(t);
   }, [visible]);
 
-  if (!active) return null;
+  if (!rect) return null;
   const transition = morph
     ? `left ${FRAME_MORPH_MS}ms ease-out, top ${FRAME_MORPH_MS}ms ease-out, ` +
       `width ${FRAME_MORPH_MS}ms ease-out, height ${FRAME_MORPH_MS}ms ease-out, ` +
       `opacity ${FRAME_FADE_MS}ms ease-out`
     : `opacity ${FRAME_FADE_MS}ms ease-out`;
 
+  const imageAnchor = anchor instanceof HTMLImageElement ? anchor : null;
+  const actionsVisible = showImageActions && visible && !!imageAnchor;
+
   return (
-    <div ref={overlayRef} data-inspector-ui className="pointer-events-none absolute inset-0 z-30">
-      {rect && (
-        <div
-          className="absolute"
-          style={{
-            left: rect.left,
-            top: rect.top,
-            width: rect.width,
-            height: rect.height,
-            opacity: visible ? 1 : 0,
-            transition,
-            outline: '2px solid #3b82f6',
-            background: 'rgba(59,130,246,0.1)',
-          }}
+    <>
+      <div
+        className="absolute"
+        style={{
+          left: rect.left,
+          top: rect.top,
+          width: rect.width,
+          height: rect.height,
+          opacity: visible ? 1 : 0,
+          transition,
+          ...FRAME_STYLES[variant],
+        }}
+      />
+      {showImageActions && imageAnchor && (
+        <ImageActionPanel
+          anchor={imageAnchor}
+          rect={rect}
+          visible={actionsVisible}
+          transition={transition}
         />
       )}
-    </div>
+    </>
+  );
+}
+
+const FLOATING_PANEL_GAP = 8;
+
+function ImageActionPanel({
+  anchor,
+  rect,
+  visible,
+  transition,
+}: {
+  anchor: HTMLElement;
+  rect: RelRect;
+  visible: boolean;
+  transition: string;
+}) {
+  const { openCrop, openReplace } = useInspector();
+  const t = useLocale();
+  return (
+    <TooltipProvider delayDuration={200}>
+      <div
+        className={cn(
+          'absolute flex items-center gap-0.5 rounded-[8px] border border-border bg-popover p-1 text-popover-foreground shadow-floating',
+          visible ? 'pointer-events-auto' : 'pointer-events-none',
+        )}
+        style={{
+          left: rect.left + rect.width / 2,
+          top: rect.top + rect.height + FLOATING_PANEL_GAP,
+          transform: 'translateX(-50%)',
+          opacity: visible ? 1 : 0,
+          transition,
+        }}
+      >
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              aria-label={t.inspector.replace}
+              onClick={(e) => {
+                e.stopPropagation();
+                openReplace(anchor);
+              }}
+              className="inline-flex size-7 items-center justify-center rounded-[5px] text-foreground/85 transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40"
+            >
+              <ImageIcon className="size-3.5" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom" data-inspector-ui>
+            {t.inspector.replace}
+          </TooltipContent>
+        </Tooltip>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              aria-label={t.inspector.crop}
+              onClick={(e) => {
+                e.stopPropagation();
+                openCrop(anchor as HTMLImageElement);
+              }}
+              className="inline-flex size-7 items-center justify-center rounded-[5px] text-foreground/85 transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40"
+            >
+              <Crop className="size-3.5" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom" data-inspector-ui>
+            {t.inspector.crop}
+          </TooltipContent>
+        </Tooltip>
+      </div>
+    </TooltipProvider>
   );
 }