@leviosa-ai/detail-page-editor 0.1.0

package/components/detail-page/annotation-dialog.tsx

@@ -0,0 +1,397 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { ImagePlus, Loader2, X } from "lucide-react";
+import { useTranslation } from "react-i18next";
+
+import { Button } from "../ui/button";
+import {
+  AnnotationCanvas,
+  type AnnotationCanvasHandle,
+} from "./annotation-canvas";
+import {
+  DESIGN_REFERENCE_ASPECTS,
+  MAX_DESIGN_REFERENCES,
+  REFERENCE_ACCEPT_ATTR,
+  finalizeReferenceDataUri,
+  readReferenceFile,
+  referenceOrdinal,
+  type DesignReference,
+  type DesignReferenceAspect,
+} from "../../lib/detail-page/design-reference";
+
+/**
+ * 그림으로 가리켜 고치는 모달 — 밑그림 위에 표시하고, 무엇을 바꿀지 적는다.
+ *
+ * 이미지 편집(선택 이미지)과 화면 재저작(섹션 하나)이 같은 모달을 쓴다. 유저가 하는
+ * 일이 같기 때문이다: **어디를** 그림으로, **무엇을** 글로.
+ *
+ * 밑그림은 반드시 **오염되지 않는 출처**로 받는다(``imageUrl`` 이 data URI 이거나
+ * 동일 출처). 교차 출처 이미지를 캔버스에 그리면 합성이 SecurityError 로 터지는데,
+ * 그 실패는 유저가 다 그리고 제출을 누른 **다음에야** 드러난다.
+ *
+ * ``maxReferences`` 를 주면 "이렇게 생기게" 참고 사진을 붙일 수 있다. 마킹본과는 **다른
+ * 역할**이라 화면에서도 갈라 놓는다: 마킹본은 캔버스(고칠 화면 자체)이고 레퍼런스는 그
+ * 아래 줄(남의 화면)이다. 같은 자리에 두면 유저도 모델도 헷갈린다.
+ *
+ * 참고 사진에는 **번호와 축**이 붙는다. 유저가 실제로 쓰는 문장이 "1번 이미지의 색감과
+ * 폰트를 참고하고 2번 이미지의 레이아웃을 참고해 줘"이기 때문이다. 번호를 화면에 적어
+ * 두지 않으면 그 문장을 쓸 근거가 없고, 축을 못 고르면 모델이 한 장을 통째로 따라가
+ * 남의 상세페이지가 된다.
+ */
+
+export type AnnotationSubmit = {
+  /** 프롬프트(비어 있을 수 있다 — 손글씨로만 지시하는 경우). */
+  instruction: string;
+  /** 원본+마킹 합성 PNG data URI. 그린 것이 없으면 null. */
+  annotatedImage: string | null;
+  /** "이렇게 생기게" 참고 사진. 붙이지 않았으면 빈 배열. 순서가 곧 번호다. */
+  references: DesignReference[];
+};
+
+let referenceSeq = 0;
+
+/** 썸네일 열쇠. 같은 파일을 두 번 붙여도 갈라 잡아야 한다. */
+function nextReferenceId(): string {
+  referenceSeq += 1;
+  return `ref-${referenceSeq}`;
+}
+
+export function AnnotationDialog({
+  open,
+  imageUrl,
+  title,
+  description,
+  placeholder,
+  submitLabel,
+  maxReferences = 0,
+  busy = false,
+  error,
+  onSubmit,
+  onClose,
+}: {
+  open: boolean;
+  /** 밑그림. data URI 또는 동일 출처 URL. 없으면 모달을 열지 않는다. */
+  imageUrl: string | null;
+  title: string;
+  description?: string;
+  placeholder?: string;
+  submitLabel: string;
+  /** 0 이면 레퍼런스 줄을 아예 띄우지 않는다 — 이미지 편집 쪽은 쓰지 않는 기능이다. */
+  maxReferences?: number;
+  busy?: boolean;
+  error?: string | null;
+  onSubmit: (input: AnnotationSubmit) => void;
+  onClose: () => void;
+}) {
+  const { t } = useTranslation("branding");
+  const canvasRef = useRef<AnnotationCanvasHandle>(null);
+  const [instruction, setInstruction] = useState("");
+  const [hasMarks, setHasMarks] = useState(false);
+  const [flattenError, setFlattenError] = useState<string | null>(null);
+  // 같은 항목을 나중에 갈아 끼워야 해서 자리(index)가 아니라 열쇠로 잡는다 — 그 사이에
+  // 유저가 앞의 것을 빼면 자리는 밀린다.
+  const [references, setReferences] = useState<
+    Array<{ id: string; uri: string; aspects: DesignReferenceAspect[] }>
+  >([]);
+  const [attachError, setAttachError] = useState<string | null>(null);
+  const fileRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    if (!open) {
+      setInstruction("");
+      setHasMarks(false);
+      setFlattenError(null);
+      setReferences([]);
+      setAttachError(null);
+    }
+  }, [open]);
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape" && !busy) onClose();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open, busy, onClose]);
+
+  const submit = useCallback(async () => {
+    if (busy) return;
+    setFlattenError(null);
+    let annotatedImage: string | null = null;
+    try {
+      annotatedImage = (await canvasRef.current?.flatten()) ?? null;
+    } catch {
+      // 합성이 실패하면 마킹 없이 보내지 않는다 — 유저가 가리킨 자리가 통째로 사라진
+      // 채로 편집이 돌면 "엉뚱한 데를 고쳤다"가 된다. 차라리 멈추고 말한다.
+      setFlattenError(
+        t("detailPage.annotate.flattenFailed", {
+          defaultValue: "표시한 그림을 합치지 못했어요. 다시 시도해 주세요.",
+        }),
+      );
+      return;
+    }
+    onSubmit({
+      instruction: instruction.trim(),
+      annotatedImage,
+      references: references.map((ref) => ({ url: ref.uri, aspects: ref.aspects })),
+    });
+  }, [busy, instruction, onSubmit, references, t]);
+
+  const attach = useCallback(
+    async (files: FileList | null) => {
+      if (!files?.length || maxReferences <= 0) return;
+      setAttachError(null);
+      const room = maxReferences - references.length;
+      if (room <= 0) return;
+      const picked = Array.from(files).slice(0, room);
+      // 같은 파일을 지웠다가 다시 고를 수 있어야 한다 — 값이 남아 있으면 change 가 안 뜬다.
+      if (fileRef.current) fileRef.current.value = "";
+
+      const added: Array<{ id: string; uri: string; aspects: DesignReferenceAspect[] }> =
+        [];
+      for (const file of picked) {
+        try {
+          added.push({
+            id: nextReferenceId(),
+            uri: await readReferenceFile(file),
+            aspects: [],
+          });
+        } catch (err) {
+          // 형식·원본 크기는 **읽기 전에** 걸러 이 자리에서 말한다. 제출 뒤에 422 로
+          // 돌아오면 유저는 그림을 고르고 축을 고르고 지시를 다 적은 다음에야 안다.
+          setAttachError(
+            err instanceof Error ? err.message : "참고 사진을 붙이지 못했어요.",
+          );
+        }
+      }
+      if (!added.length) return;
+      // 원본으로 **먼저** 띄운다. 줄이기는 디코드를 기다려야 하는데, 그 사이 아무것도
+      // 안 뜨면 유저는 첨부가 먹히지 않은 줄 안다.
+      setReferences((prev) => [...prev, ...added].slice(0, maxReferences));
+
+      for (const item of added) {
+        void finalizeReferenceDataUri(item.uri).then((result) => {
+          if ("error" in result) {
+            // 줄이기로도 상한 아래로 못 내려간 그림은 붙여 둘 수 없다 — 그대로 두면
+            // 제출이 서버에서 막힌다.
+            setReferences((prev) => prev.filter((ref) => ref.id !== item.id));
+            setAttachError(result.error);
+            return;
+          }
+          if (result.uri === item.uri) return;
+          setReferences((prev) =>
+            prev.map((ref) => (ref.id === item.id ? { ...ref, uri: result.uri } : ref)),
+          );
+        });
+      }
+    },
+    [maxReferences, references.length],
+  );
+
+  const toggleAspect = useCallback((id: string, aspect: DesignReferenceAspect) => {
+    setReferences((prev) =>
+      prev.map((ref) =>
+        ref.id === id
+          ? {
+              ...ref,
+              aspects: ref.aspects.includes(aspect)
+                ? ref.aspects.filter((a) => a !== aspect)
+                : [...ref.aspects, aspect],
+            }
+          : ref,
+      ),
+    );
+  }, []);
+
+  if (!open || !imageUrl) return null;
+
+  const canSubmit = !busy && (hasMarks || instruction.trim().length > 0);
+
+  return (
+    <div className="fixed inset-0 z-[100] flex items-center justify-center bg-neutral-900/60 p-4">
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label={title}
+        className="flex h-full max-h-[92vh] w-full max-w-5xl flex-col overflow-hidden rounded-2xl bg-white shadow-2xl"
+      >
+        <div className="flex items-start justify-between gap-4 border-b border-neutral-200 px-5 py-3">
+          <div className="min-w-0">
+            <h2 className="text-sm font-semibold text-neutral-900">{title}</h2>
+            {description ? (
+              <p className="mt-0.5 text-xs text-neutral-500">{description}</p>
+            ) : null}
+          </div>
+          <button
+            type="button"
+            aria-label={t("detailPage.annotate.close", { defaultValue: "닫기" })}
+            onClick={onClose}
+            disabled={busy}
+            className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg text-neutral-400 transition-colors hover:bg-neutral-100 hover:text-neutral-900 disabled:opacity-40"
+          >
+            <X size={16} />
+          </button>
+        </div>
+
+        <div className="min-h-0 flex-1">
+          <AnnotationCanvas
+            ref={canvasRef}
+            imageUrl={imageUrl}
+            onChange={setHasMarks}
+            labels={{
+              pen: t("detailPage.annotate.tools.pen", { defaultValue: "그리기" }),
+              rect: t("detailPage.annotate.tools.rect", { defaultValue: "박스" }),
+              arrow: t("detailPage.annotate.tools.arrow", { defaultValue: "화살표" }),
+              text: t("detailPage.annotate.tools.text", { defaultValue: "메모" }),
+              eraser: t("detailPage.annotate.tools.eraser", { defaultValue: "지우개" }),
+              select: t("detailPage.annotate.tools.select", { defaultValue: "이동" }),
+              color: t("detailPage.annotate.tools.color", { defaultValue: "색상" }),
+              undo: t("detailPage.annotate.tools.undo", { defaultValue: "실행 취소" }),
+              redo: t("detailPage.annotate.tools.redo", { defaultValue: "다시 실행" }),
+              note: t("detailPage.annotate.tools.note", { defaultValue: "메모 입력" }),
+            }}
+          />
+        </div>
+
+        <div className="border-t border-neutral-200 px-5 py-3">
+          <textarea
+            value={instruction}
+            onChange={(e) => setInstruction(e.target.value)}
+            rows={2}
+            disabled={busy}
+            placeholder={
+              placeholder ??
+              t("detailPage.annotate.placeholder", {
+                defaultValue:
+                  "표시한 곳을 어떻게 바꿀지 적어주세요. 그림 위에 손글씨로 적어도 돼요.",
+              })
+            }
+            className="w-full resize-none rounded-lg border border-neutral-200 px-3 py-2 text-sm text-neutral-900 outline-none placeholder:text-neutral-400 focus:border-neutral-400 disabled:bg-neutral-50"
+          />
+          {maxReferences > 0 ? (
+            <div className="mt-2 flex flex-wrap items-start gap-2">
+              {references.map((ref, index) => (
+                <div
+                  key={ref.id}
+                  className="flex items-start gap-2 rounded-lg border border-neutral-200 p-1.5"
+                >
+                  <div className="relative h-14 w-14 shrink-0 overflow-hidden rounded-md bg-neutral-100">
+                    {/* 붙인 사진은 data URI라 next/image 로 최적화할 것이 없다. */}
+                    {/* eslint-disable-next-line @next/next/no-img-element */}
+                    <img
+                      src={ref.uri}
+                      alt={t("detailPage.reauthor.referenceAlt", {
+                        defaultValue: "참고 사진",
+                      })}
+                      className="h-full w-full object-cover"
+                    />
+                    {/* 번호는 프롬프트에 쓰는 이름이다 — 화면에 없으면 "2번 이미지"라고
+                        적을 근거가 없다. */}
+                    <span className="absolute left-0.5 top-0.5 rounded bg-neutral-900/75 px-1 text-[10px] font-semibold leading-4 text-white">
+                      {referenceOrdinal(index)}
+                    </span>
+                    <button
+                      type="button"
+                      disabled={busy}
+                      onClick={() =>
+                        setReferences((prev) => prev.filter((_, i) => i !== index))
+                      }
+                      aria-label={t("detailPage.reauthor.referenceRemove", {
+                        defaultValue: "참고 사진 빼기",
+                      })}
+                      className="absolute right-0.5 top-0.5 flex h-4 w-4 items-center justify-center rounded-full bg-neutral-900/70 text-white disabled:opacity-40"
+                    >
+                      <X size={10} />
+                    </button>
+                  </div>
+                  <div className="flex max-w-[15rem] flex-wrap gap-1">
+                    {DESIGN_REFERENCE_ASPECTS.map((aspect) => {
+                      const on = ref.aspects.includes(aspect.key);
+                      return (
+                        <button
+                          key={aspect.key}
+                          type="button"
+                          disabled={busy}
+                          aria-pressed={on}
+                          // 축 이름만으로는 "내용 구성"이 문구까지인지 알 수 없다.
+                          title={aspect.hint}
+                          onClick={() => toggleAspect(ref.id, aspect.key)}
+                          className={`rounded-full border px-2 py-0.5 text-[11px] transition-colors disabled:opacity-40 ${
+                            on
+                              ? "border-neutral-900 bg-neutral-900 text-white"
+                              : "border-neutral-200 text-neutral-500 hover:border-neutral-400 hover:text-neutral-700"
+                          }`}
+                        >
+                          {aspect.label}
+                        </button>
+                      );
+                    })}
+                  </div>
+                </div>
+              ))}
+              {references.length < maxReferences ? (
+                <button
+                  type="button"
+                  disabled={busy}
+                  onClick={() => fileRef.current?.click()}
+                  className="flex h-[4.75rem] items-center gap-1.5 rounded-lg border border-dashed border-neutral-300 px-3 text-xs text-neutral-500 transition-colors hover:border-neutral-400 hover:text-neutral-700 disabled:opacity-40"
+                >
+                  <ImagePlus size={14} />
+                  {t("detailPage.reauthor.referenceAdd", {
+                    defaultValue: "이렇게 생기게 (참고 사진)",
+                  })}
+                </button>
+              ) : null}
+              <input
+                ref={fileRef}
+                type="file"
+                accept={REFERENCE_ACCEPT_ATTR}
+                multiple
+                hidden
+                onChange={(e) => void attach(e.target.files)}
+              />
+              {references.length ? (
+                <p className="w-full text-[11px] text-neutral-400">
+                  {t("detailPage.reauthor.referenceHint", {
+                    defaultValue:
+                      "축을 고르면 그 장에서는 고른 것만 따라가요(안 고르면 배치와 구성만). " +
+                      '지시에 "1번 이미지의 색감처럼"이라고 적어도 돼요. 참고 사진 자체는 ' +
+                      "페이지에 들어가지 않아요.",
+                  })}
+                </p>
+              ) : null}
+            </div>
+          ) : null}
+          {error || flattenError || attachError ? (
+            <p className="mt-2 text-xs text-red-600">
+              {error ?? flattenError ?? attachError}
+            </p>
+          ) : null}
+          <div className="mt-3 flex items-center justify-between gap-3">
+            <p className="text-xs text-neutral-400">
+              {hasMarks
+                ? t("detailPage.annotate.marked", {
+                    defaultValue: "표시한 자리를 기준으로 고쳐요.",
+                  })
+                : t("detailPage.annotate.unmarked", {
+                    defaultValue: "고칠 자리를 그림으로 표시하면 더 정확해요.",
+                  })}
+            </p>
+            <Button type="button" onClick={submit} disabled={!canSubmit}>
+              {busy ? (
+                <>
+                  <Loader2 size={14} className="mr-1.5 animate-spin" />
+                  {t("detailPage.annotate.working", { defaultValue: "고치는 중…" })}
+                </>
+              ) : (
+                submitLabel
+              )}
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/components/detail-page/bubble-tail-overlay.tsx

@@ -0,0 +1,209 @@
+"use client";
+
+import { useEffect, useRef, useState, type PointerEvent as ReactPointerEvent, type RefObject } from "react";
+import { observer } from "./canvas-observer";
+import { useTranslation } from "react-i18next";
+
+import {
+  selectedElementsDeep,
+  type SelectableElement,
+} from "./detail-page-selection";
+import { elementClientRect, type RectElement } from "./element-rects";
+import {
+  bubbleSvgDataUrl,
+  readBubbleParams,
+  type BubbleParams,
+  type Pt,
+} from "../../lib/detail-page-canvas/bubble-path";
+
+/**
+ * 말풍선 꼬리 끝점을 드래그하는 핸들 — Canva/미리캔버스식.
+ *
+ * 말풍선은 몸통+꼬리가 이어진 하나의 닫힌 path이고(``bubble-path.ts``), 그 생성
+ * 파라미터가 ``custom.bubble``에 실려 온다(디컴포저가 ``data-bubble``에서 옮겨 담는다).
+ * 그래서 편집기는 말풍선을 굳은 그림이 아니라 **다시 구울 수 있는 도형**으로 다룬다:
+ * 끝점을 옮기고 path를 재생성해 ``src``에 다시 넣으면 된다.
+ *
+ * 꼬리는 각도가 아니라 끝점으로 잡히므로 360도 어디로 끌어도 몸통에 붙어 있고,
+ * 모서리에 걸치면 두 변에 걸친 부리가 된다. 끝점을 몸통 안으로 끌면 꼬리가 사라진다.
+ *
+ * ``NestedSelectionOverlay``와 같은 좌표계 규약을 쓴다 — Konva 노드에서 잰 rect를
+ * 컨테이너 기준으로 옮기므로 줌·스크롤·스택 워크스페이스가 그대로 동작한다.
+ */
+
+const HANDLE = 12;
+const ACCENT = "#2F6FEB";
+
+// SelectableElement(선택 모델)과 RectElement(측정 모델)의 교집합 — 두 헬퍼를 다 쓴다.
+type ElementLike = SelectableElement & RectElement;
+
+type StoreLike = {
+  selectedElements?: SelectableElement[];
+  selectedElementsIds?: string[];
+  getElementById?: (id: string) => SelectableElement | undefined;
+  scale?: number;
+  history?: { startTransaction?: () => void; endTransaction?: () => void };
+};
+
+/** 몸통 로컬 좌표 → SVG 박스 안의 0..1 비율. 리사이즈돼도 비율은 그대로다. */
+function tipFraction(p: BubbleParams, tip: Pt): { fx: number; fy: number } {
+  return { fx: (tip[0] + p.pad) / (p.w + 2 * p.pad), fy: (tip[1] + p.pad) / (p.h + 2 * p.pad) };
+}
+
+/** 0..1 비율 → 몸통 로컬 좌표. 꼬리가 잘리지 않도록 pad 안으로 가둔다. */
+function fractionToTip(p: BubbleParams, fx: number, fy: number): Pt {
+  const bw = p.w + 2 * p.pad;
+  const bh = p.h + 2 * p.pad;
+  const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));
+  return [
+    clamp(fx * bw - p.pad, -p.pad, p.w + p.pad),
+    clamp(fy * bh - p.pad, -p.pad, p.h + p.pad),
+  ];
+}
+
+/** 파라미터를 갱신하고 path를 다시 구워 요소에 반영한다. */
+export function applyBubble(el: ElementLike, next: BubbleParams): void {
+  const custom = (el.custom && typeof el.custom === "object" ? el.custom : {}) as Record<string, unknown>;
+  el.set({ src: bubbleSvgDataUrl(next), custom: { ...custom, bubble: next } });
+}
+
+/**
+ * 말풍선을 리사이즈하면 몸통 크기를 파라미터에 되먹인다.
+ *
+ * 이게 없으면 스톡 편집기가 svg를 통째로 스케일해 모서리 라운드와 테두리 굵기까지 늘어난다
+ * (가로로만 늘리면 라운드가 타원이 된다). w/h를 다시 못박고 path를 재생성하면
+ * 라운드·스트로크는 원래 굵기를 유지한 채 몸통만 커진다.
+ */
+export function syncBubbleToBox(el: ElementLike): boolean {
+  const p = readBubbleParams(el.custom);
+  if (!p) return false;
+  const boxW = Number(el.width);
+  const boxH = Number(el.height);
+  if (!Number.isFinite(boxW) || !Number.isFinite(boxH)) return false;
+  const w = boxW - 2 * p.pad;
+  const h = boxH - 2 * p.pad;
+  if (w <= 0 || h <= 0) return false;
+  if (Math.abs(w - p.w) < 0.5 && Math.abs(h - p.h) < 0.5) return false;
+
+  // 꼬리 끝점은 몸통에 대한 비율을 유지한다 — 늘려도 꼬리가 제자리에 남는다.
+  const tip: Pt | null = p.tip ? [(p.tip[0] / p.w) * w, (p.tip[1] / p.h) * h] : null;
+  applyBubble(el, { ...p, w, h, tip });
+  return true;
+}
+
+export const BubbleTailOverlay = observer(function BubbleTailOverlay({
+  store,
+  containerRef,
+}: {
+  store: unknown;
+  containerRef: RefObject<HTMLElement | null>;
+}) {
+  const { t } = useTranslation("branding");
+  const s = store as StoreLike;
+  const [handles, setHandles] = useState<Array<{ id: string; left: number; top: number }>>([]);
+  const drag = useRef<{ pointerId: number; el: ElementLike; p: BubbleParams } | null>(null);
+
+  const selected = selectedElementsDeep(s) as ElementLike[];
+  // mobx가 위치/크기 변화를 감지하도록 렌더 중에 읽는다.
+  const stamp = selected.map((e) => `${e.id}:${e.x},${e.y},${e.width},${e.height}`).join("|");
+  const scale = s.scale ?? 1;
+
+  // selectedElementsDeep은 매 렌더 '새 배열'을 만든다. 그 배열을 의존성에 두면 이펙트가
+  // 매 렌더 돌고, setHandles가 또 새 배열을 넣어 리렌더를 부른다 — 무한 루프
+  // ("Maximum update depth exceeded"). 그래서 의존성은 내용을 요약한 stamp로만 걸고,
+  // 배열 자체는 ref로 읽는다.
+  const selectedRef = useRef<ElementLike[]>(selected);
+  selectedRef.current = selected;
+  // 계산 결과가 같으면 상태를 아예 건드리지 않는다 — 두 번째 안전장치.
+  const keyRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    const host = containerRef.current;
+    const next: Array<{ id: string; left: number; top: number }> = [];
+    if (host) {
+      const box = host.getBoundingClientRect();
+      for (const el of selectedRef.current) {
+        // 리사이즈는 선택된 상태에서만 일어나므로 여기서 되먹이면 충분하다.
+        // 멱등하다(크기가 그대로면 no-op) → 루프를 돌지 않는다.
+        syncBubbleToBox(el);
+        const p = readBubbleParams(el.custom);
+        if (!p?.tip) continue;
+        const r = elementClientRect(el);
+        if (!r) continue;
+        const { fx, fy } = tipFraction(p, p.tip);
+        next.push({
+          id: el.id,
+          left: r.left - box.left + fx * (r.right - r.left),
+          top: r.top - box.top + fy * (r.bottom - r.top),
+        });
+      }
+    }
+    const key = next.map((h) => `${h.id}:${h.left.toFixed(2)},${h.top.toFixed(2)}`).join("|");
+    if (key === keyRef.current) return;
+    keyRef.current = key;
+    setHandles(next);
+  }, [stamp, scale, containerRef]);
+
+  const begin = (e: ReactPointerEvent<HTMLElement>, id: string) => {
+    const el = s.getElementById?.(id) as ElementLike | undefined;
+    const p = el && readBubbleParams(el.custom);
+    if (!el || !p) return;
+    e.preventDefault();
+    e.stopPropagation();
+    (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+    drag.current = { pointerId: e.pointerId, el, p };
+    s.history?.startTransaction?.();
+  };
+
+  const move = (e: ReactPointerEvent<HTMLElement>) => {
+    const d = drag.current;
+    if (!d || e.pointerId !== d.pointerId) return;
+    const r = elementClientRect(d.el);
+    if (!r) return;
+    const w = r.right - r.left;
+    const h = r.bottom - r.top;
+    if (!w || !h) return;
+    const fx = (e.clientX - r.left) / w;
+    const fy = (e.clientY - r.top) / h;
+    applyBubble(d.el, { ...d.p, tip: fractionToTip(d.p, fx, fy) });
+  };
+
+  const end = (e: ReactPointerEvent<HTMLElement>) => {
+    const d = drag.current;
+    if (!d || e.pointerId !== d.pointerId) return;
+    drag.current = null;
+    s.history?.endTransaction?.();
+  };
+
+  if (!handles.length) return null;
+
+  return (
+    <div style={{ position: "absolute", inset: 0, pointerEvents: "none", zIndex: 21 }}>
+      {handles.map((h) => (
+        <span
+          key={h.id}
+          title={t("detailPage.bubbleTail.handle")}
+          onPointerDown={(e) => begin(e, h.id)}
+          onPointerMove={move}
+          onPointerUp={end}
+          onPointerCancel={end}
+          style={{
+            position: "absolute",
+            left: h.left - HANDLE / 2,
+            top: h.top - HANDLE / 2,
+            width: HANDLE,
+            height: HANDLE,
+            borderRadius: "50%",
+            background: "#fff",
+            border: `2px solid ${ACCENT}`,
+            boxSizing: "border-box",
+            pointerEvents: "auto",
+            cursor: "grab",
+            touchAction: "none",
+          }}
+        />
+      ))}
+    </div>
+  );
+});
+BubbleTailOverlay.displayName = "BubbleTailOverlay";