From de09bcc66d4be9567a5c5a9003ef80cf95e2ac0e Mon Sep 17 00:00:00 2001
From: Quang Tran <16215255+trmquang93@users.noreply.github.com>
Date: Mon, 27 Apr 2026 23:19:35 +0700
Subject: [PATCH 1/3] feat: enable hotspot/connection editing on component
 instances

Drop "hotspots" from VISUAL_FIELDS in resolveInstanceVisuals: instance
screens no longer inherit canonical hotspots at render time. Image and
dimensions still inherit. screen.hotspots[] on an instance now holds the
placement's own additive local hotspots, rendered as-is.

Remove every isInstanceVisual gate in ScreenNode (the + Link button,
rubber-band draw, hotspot mouse/double-click, the hotspot connect-drag
handle, and resize handles). Drop the prop pass-through from CanvasArea
and the unused isResolvedInstance import.

Tests:
- resolveInstanceVisuals: invert the merged-hotspots assertion; add
  cases for non-empty locals returning verbatim, empty locals returning
  empty (canonical's NOT copied), and image fields still inheriting.

This is a pure semantic shift on instance.hotspots[]; no schema or file
format change.
---
 src/components/CanvasArea.jsx            |  4 +-
 src/components/ScreenNode.jsx            | 16 ++----
 src/utils/resolveInstanceVisuals.js      | 20 ++++---
 src/utils/resolveInstanceVisuals.test.js | 72 +++++++++++++++++++++++-
 4 files changed, 88 insertions(+), 24 deletions(-)

diff --git a/src/components/CanvasArea.jsx b/src/components/CanvasArea.jsx
index b88d933..d3b0de5 100644
--- a/src/components/CanvasArea.jsx
+++ b/src/components/CanvasArea.jsx
@@ -3,7 +3,7 @@ import { DEFAULT_SCREEN_WIDTH, DEFAULT_SCREEN_HEIGHT } from "../constants";
 import { copyScreenForFigma, copyScreensForFigma, copyScreensForFigmaEditable, downloadScreenSvg } from "../utils/copyToFigma";
 import { copyScreensAsImage } from "../utils/copyAsImage";
 import { ScreenNode } from "./ScreenNode";
-import { resolveInstanceVisuals, isResolvedInstance } from "../utils/resolveInstanceVisuals";
+import { resolveInstanceVisuals } from "../utils/resolveInstanceVisuals";
 import { ConnectionLines } from "./ConnectionLines";
 import { ConditionalPrompt } from "./ConditionalPrompt";
 import { ConnectionTypePrompt } from "./ConnectionTypePrompt";
@@ -163,12 +163,10 @@ export function CanvasArea({
         ))}
         {screens.map((screen) => {
           const visualScreen = resolveInstanceVisuals(screen, screens);
-          const instanceVisual = isResolvedInstance(screen) && visualScreen !== screen;
           return (
           <ScreenNode
             key={screen.id}
             screen={visualScreen}
-            isInstanceVisual={instanceVisual}
             selected={selectedScreen === screen.id}
             onSelect={(id) => { clearSelection(); setSelectedScreen(id); setSelectedStickyNote(null); }}
             onDragStart={onDragStart}
diff --git a/src/components/ScreenNode.jsx b/src/components/ScreenNode.jsx
index 941a9ee..4d5aac2 100644
--- a/src/components/ScreenNode.jsx
+++ b/src/components/ScreenNode.jsx
@@ -21,10 +21,6 @@ export function ScreenNode({
   selectedCommentId,
   onCommentPinClick,
   onDeselectComment,
-  // True when this is an instance whose image/hotspots are inherited from
-  // its canonical at render time. Hotspot edits are read-only here — users
-  // must edit the canonical instead.
-  isInstanceVisual,
 }) {
   const [imgLoaded, setImgLoaded] = useState(false);
   const [isEditingDesc, setIsEditingDesc] = useState(false);
@@ -370,7 +366,7 @@ export function ScreenNode({
           >
             S+
           </button>
-          {!isInstanceVisual && <button
+          <button
             className="screen-btn"
             onClick={(e) => { e.stopPropagation(); onAddHotspot(screen.id); }}
             title="Add tap area / button link"
@@ -386,7 +382,7 @@ export function ScreenNode({
             }}
           >
             + Link
-          </button>}
+          </button>
           <button
             className="screen-btn"
             onClick={(e) => { e.stopPropagation(); onRemoveScreen(screen.id); }}
@@ -434,7 +430,7 @@ export function ScreenNode({
             }
           }
           onSelect(screen.id);
-          if (screen.imageData && !isInstanceVisual && onImageAreaMouseDown) {
+          if (screen.imageData && onImageAreaMouseDown) {
             onImageAreaMouseDown(e, screen.id);
           }
         }}
@@ -463,12 +459,10 @@ export function ScreenNode({
                   className="hotspot-area"
                   onMouseDown={(e) => {
                     e.stopPropagation();
-                    if (isInstanceVisual) return;
                     if (onHotspotMouseDown) onHotspotMouseDown(e, screen.id, hs.id);
                   }}
                   onDoubleClick={(e) => {
                     e.stopPropagation();
-                    if (isInstanceVisual) return;
                     if (onHotspotDoubleClick) onHotspotDoubleClick(e, screen.id, hs.id);
                   }}
                   style={{
@@ -505,7 +499,7 @@ export function ScreenNode({
                 >
                   {hs.label || "TAP"}
                   {/* Drag handle for hotspot-to-screen connect */}
-                  {isSelected && !isInstanceVisual && (
+                  {isSelected && (
                     <div
                       className="hotspot-drag-handle"
                       onMouseDown={(e) => {
@@ -532,7 +526,7 @@ export function ScreenNode({
                     />
                   )}
                   {/* Resize handles */}
-                  {isSelected && !isInstanceVisual && ["nw","n","ne","e","se","s","sw","w"].map((handle) => {
+                  {isSelected && ["nw","n","ne","e","se","s","sw","w"].map((handle) => {
                     const pos = {
                       nw: { left: -4, top: -4, cursor: "nwse-resize" },
                       n:  { left: "50%", top: -4, cursor: "ns-resize", transform: "translateX(-50%)" },
diff --git a/src/utils/resolveInstanceVisuals.js b/src/utils/resolveInstanceVisuals.js
index d0dfdd7..99b55f7 100644
--- a/src/utils/resolveInstanceVisuals.js
+++ b/src/utils/resolveInstanceVisuals.js
@@ -1,15 +1,20 @@
 // resolveInstanceVisuals
 //
-// When a screen is marked as a component instance, on the canvas it should
-// look identical to its canonical (same image, same hotspot positions, same
-// dimensions). The canonical is the single source of truth for the visual
-// spec — instances are placements.
+// When a screen is marked as a component instance, on the canvas it inherits
+// IMAGE and DIMENSIONS from its canonical so every placement renders the same
+// underlying screenshot at the same size. The canonical remains the single
+// source of truth for those visuals.
+//
+// `hotspots[]` is NOT inherited — on an instance, `screen.hotspots[]` holds
+// the placement's own *additive local* hotspots. They are rendered as-is on
+// the canvas and merged with the canonical's hotspots at export time
+// (see generateInstructionFiles.js), not at render time.
 //
 // This helper is the render-time bridge: pass any screen and the full screens
 // array, get back either the screen unchanged (canonical / unlinked / orphan
-// instance) or a shallow-merged screen whose visual fields come from the
-// canonical while identity fields (id, x, y, name, status, comments, etc.)
-// stay from the instance.
+// instance) or a shallow-merged screen whose IMAGE/DIMENSIONS come from the
+// canonical while identity fields (id, x, y, name, status, comments, hotspots,
+// etc.) stay from the instance.
 //
 // We intentionally do NOT copy data into instances on save — keeping this at
 // render time means edits to the canonical propagate to every instance
@@ -20,7 +25,6 @@ const VISUAL_FIELDS = [
   "imageWidth",
   "imageHeight",
   "width",
-  "hotspots",
 ];
 
 export function resolveInstanceVisuals(screen, screens) {
diff --git a/src/utils/resolveInstanceVisuals.test.js b/src/utils/resolveInstanceVisuals.test.js
index 9da4347..ef6c7ee 100644
--- a/src/utils/resolveInstanceVisuals.test.js
+++ b/src/utils/resolveInstanceVisuals.test.js
@@ -33,7 +33,7 @@ describe("resolveInstanceVisuals", () => {
     expect(result).toBe(orphan);
   });
 
-  it("merges canonical's image + dimensions + hotspots into instance", () => {
+  it("merges canonical's image + dimensions into instance but NOT hotspots", () => {
     const canonical = baseScreen({
       id: "s1",
       name: "Card",
@@ -60,7 +60,75 @@ describe("resolveInstanceVisuals", () => {
     expect(result.imageWidth).toBe(800);
     expect(result.imageHeight).toBe(600);
     expect(result.width).toBe(800);
-    expect(result.hotspots).toEqual(canonical.hotspots);
+    // Hotspots are NOT inherited from the canonical — instances keep their own.
+    expect(result.hotspots).toEqual([]);
+  });
+
+  it("instance with non-empty local hotspots returns them verbatim regardless of canonical's hotspots", () => {
+    const canonical = baseScreen({
+      id: "s1",
+      componentId: "c1",
+      componentRole: "canonical",
+      hotspots: [
+        { id: "hC1", label: "Canonical Tap", x: 0, y: 0, w: 10, h: 10 },
+        { id: "hC2", label: "Canonical Other", x: 10, y: 10, w: 10, h: 10 },
+      ],
+    });
+    const localHotspots = [
+      { id: "hI1", label: "Local Skip", x: 50, y: 50, w: 30, h: 30 },
+    ];
+    const instance = baseScreen({
+      id: "s2",
+      componentId: "c1",
+      componentRole: "instance",
+      hotspots: localHotspots,
+    });
+    const result = resolveInstanceVisuals(instance, [canonical, instance]);
+    expect(result.hotspots).toBe(localHotspots);
+    expect(result.hotspots).toEqual(localHotspots);
+  });
+
+  it("instance with empty hotspots returns empty (canonical's are NOT copied)", () => {
+    const canonical = baseScreen({
+      id: "s1",
+      componentId: "c1",
+      componentRole: "canonical",
+      hotspots: [{ id: "hC1", label: "Canonical Tap", x: 0, y: 0, w: 10, h: 10 }],
+    });
+    const instance = baseScreen({
+      id: "s2",
+      componentId: "c1",
+      componentRole: "instance",
+      hotspots: [],
+    });
+    const result = resolveInstanceVisuals(instance, [canonical, instance]);
+    expect(result.hotspots).toEqual([]);
+  });
+
+  it("image fields (imageData, imageWidth, imageHeight, width) still inherit from canonical", () => {
+    const canonical = baseScreen({
+      id: "s1",
+      componentId: "c1",
+      componentRole: "canonical",
+      imageData: "data:image/png;base64,CANONICAL",
+      imageWidth: 1024,
+      imageHeight: 768,
+      width: 1024,
+    });
+    const instance = baseScreen({
+      id: "s2",
+      componentId: "c1",
+      componentRole: "instance",
+      imageData: null,
+      imageWidth: 100,
+      imageHeight: 100,
+      width: 200,
+    });
+    const result = resolveInstanceVisuals(instance, [canonical, instance]);
+    expect(result.imageData).toBe("data:image/png;base64,CANONICAL");
+    expect(result.imageWidth).toBe(1024);
+    expect(result.imageHeight).toBe(768);
+    expect(result.width).toBe(1024);
   });
 
   it("preserves identity fields (id, name, position) from the instance", () => {

From f9fcef86af2c23b2c9824cc7fb5ff6efda606b9b Mon Sep 17 00:00:00 2001
From: Quang Tran <16215255+trmquang93@users.noreply.github.com>
Date: Mon, 27 Apr 2026 23:19:46 +0700
Subject: [PATCH 2/3] feat: merge hotspots and re-point connections on
 canonical promotion
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When a canonical component screen is removed (single delete, batch
delete) or unlinked while instances remain, the auto-promoted instance
must inherit the canonical's hotspots so the spec is not lost and any
existing hotspot-driven connections stay live.

Add a mergeOnPromotion helper that unions the canonical's hotspots with
the promoted instance's locals, deduped by id (canonical wins on
collision). Wire it into the three call sites in useScreenManager:
removeScreen, removeScreens, and the setScreenComponent unlink branch.
In each, capture firstInstance.id and canonicalHotspotIds BEFORE the
setters so neither closure reads stale state, then re-point connections
that originated from the removed canonical and referenced one of the
canonical-owned hotspot ids onto the promoted instance — BEFORE the
existing orphan-filter drops connections still touching the removed id.

setScreenComponent's unlink branch previously did not touch
connections; add a paired setConnections call scoped to the
unlink-canonical-with-instances case only.

Tests cover: single delete promotion + re-point, multi-delete via
removeScreens, manual unlink, and id-collision dedup with canonical
winning.
---
 src/hooks/useScreenManager.js      | 260 +++++++++++++++++++++++------
 src/hooks/useScreenManager.test.js | 195 ++++++++++++++++++++++
 2 files changed, 407 insertions(+), 48 deletions(-)

diff --git a/src/hooks/useScreenManager.js b/src/hooks/useScreenManager.js
index abfdf37..1ad0218 100644
--- a/src/hooks/useScreenManager.js
+++ b/src/hooks/useScreenManager.js
@@ -20,6 +20,37 @@ import {
   HEADER_HEIGHT,
 } from "../constants";
 
+// When a canonical component screen is removed (or unlinked) and we auto-promote
+// its first remaining instance, the promoted screen must inherit the canonical's
+// hotspots so existing connections keyed off those hotspot ids stay live.
+//
+// Returns:
+//   canonicalHotspotIds — Set<string> of hotspot ids that lived on the canonical;
+//                         used by callers to re-point connections from the
+//                         deleted canonical onto the promoted instance.
+//   mergedHotspots      — union of canonical's hotspots and the instance's own
+//                         locals, deduped by id (canonical wins on collision).
+function mergeOnPromotion({ removedCanonical, firstInstance }) {
+  const canonicalHotspots = (removedCanonical && removedCanonical.hotspots) || [];
+  const instanceHotspots = (firstInstance && firstInstance.hotspots) || [];
+  const canonicalHotspotIds = new Set(canonicalHotspots.map((h) => h.id));
+  const seen = new Set();
+  const mergedHotspots = [];
+  for (const h of canonicalHotspots) {
+    if (!seen.has(h.id)) {
+      seen.add(h.id);
+      mergedHotspots.push(h);
+    }
+  }
+  for (const h of instanceHotspots) {
+    if (!seen.has(h.id)) {
+      seen.add(h.id);
+      mergedHotspots.push(h);
+    }
+  }
+  return { canonicalHotspotIds, mergedHotspots };
+}
+
 function makeScreen(overrides = {}) {
   return {
     id: generateId(),
@@ -193,6 +224,36 @@ export function useScreenManager(pan, zoom, canvasRef, commentCallbacks = {}) {
     commentCallbacksRef.current.onDeleteCommentsForScreen?.(id);
     pushHistory(screens, connections, documents);
     const removedScreen = screens.find((s) => s.id === id);
+
+    // Pre-compute promotion metadata BEFORE the setters so neither closure
+    // reads stale state. firstInstance is found from the current `screens`
+    // snapshot — auto-save broadcasts and other state-mutators only affect
+    // membership, not which instance is "first."
+    let promotion = null;
+    if (
+      removedScreen &&
+      removedScreen.componentRole === "canonical" &&
+      removedScreen.componentId
+    ) {
+      const firstInstance = screens.find(
+        (s) =>
+          s.id !== id &&
+          s.componentId === removedScreen.componentId &&
+          s.componentRole === "instance"
+      );
+      if (firstInstance) {
+        const { canonicalHotspotIds, mergedHotspots } = mergeOnPromotion({
+          removedCanonical: removedScreen,
+          firstInstance,
+        });
+        promotion = {
+          firstInstanceId: firstInstance.id,
+          canonicalHotspotIds,
+          mergedHotspots,
+        };
+      }
+    }
+
     setScreens((prev) => {
       let remaining = prev.filter((s) => s.id !== id);
       // Auto-cleanup: if only one screen left in the stateGroup, clear it
@@ -206,22 +267,34 @@ export function useScreenManager(pan, zoom, canvasRef, commentCallbacks = {}) {
           );
         }
       }
-      // Auto-promote: if the removed screen was a canonical component, promote the first instance.
-      if (removedScreen?.componentRole === "canonical" && removedScreen.componentId) {
-        const firstInstance = remaining.find(
-          (s) => s.componentId === removedScreen.componentId && s.componentRole === "instance"
+      // Auto-promote: if the removed screen was a canonical component, promote
+      // the first instance and merge canonical's hotspots into its locals.
+      if (promotion) {
+        remaining = remaining.map((s) =>
+          s.id === promotion.firstInstanceId
+            ? { ...s, componentRole: "canonical", hotspots: promotion.mergedHotspots }
+            : s
         );
-        if (firstInstance) {
-          remaining = remaining.map((s) =>
-            s.id === firstInstance.id ? { ...s, componentRole: "canonical" } : s
-          );
-        }
       }
       return remaining;
     });
-    setConnections((prev) =>
-      prev.filter((c) => c.fromScreenId !== id && c.toScreenId !== id)
-    );
+    setConnections((prev) => {
+      let next = prev;
+      if (promotion) {
+        // Re-point connections that originated from the removed canonical and
+        // referenced one of the canonical's hotspot ids to the promoted
+        // instance, BEFORE the orphan-filter drops connections that still
+        // reference the deleted id.
+        next = next.map((c) =>
+          c.fromScreenId === id &&
+          c.hotspotId &&
+          promotion.canonicalHotspotIds.has(c.hotspotId)
+            ? { ...c, fromScreenId: promotion.firstInstanceId }
+            : c
+        );
+      }
+      return next.filter((c) => c.fromScreenId !== id && c.toScreenId !== id);
+    });
     if (selectedScreen === id) setSelectedScreen(null);
   }, [selectedScreen, screens, connections, documents, pushHistory]);
 
@@ -269,6 +342,35 @@ export function useScreenManager(pan, zoom, canvasRef, commentCallbacks = {}) {
   //                  the first instance to canonical so the group survives.
   const setScreenComponent = useCallback((id, mode, opts = {}) => {
     pushHistory(screens, connections, documents);
+
+    // Pre-compute promotion metadata for the unlink-canonical branch BEFORE
+    // any setter so the connection re-pointer uses pre-state, matching the
+    // pattern in removeScreen / removeScreens.
+    let unlinkPromotion = null;
+    if (mode === "unlink") {
+      const target = screens.find((s) => s.id === id);
+      if (target && target.componentRole === "canonical" && target.componentId) {
+        const firstInstance = screens.find(
+          (s) =>
+            s.id !== id &&
+            s.componentId === target.componentId &&
+            s.componentRole === "instance"
+        );
+        if (firstInstance) {
+          const { canonicalHotspotIds, mergedHotspots } = mergeOnPromotion({
+            removedCanonical: target,
+            firstInstance,
+          });
+          unlinkPromotion = {
+            unlinkedCanonicalId: id,
+            firstInstanceId: firstInstance.id,
+            canonicalHotspotIds,
+            mergedHotspots,
+          };
+        }
+      }
+    }
+
     setScreens((prev) => {
       const target = prev.find((s) => s.id === id);
       if (!target) return prev;
@@ -303,20 +405,20 @@ export function useScreenManager(pan, zoom, canvasRef, commentCallbacks = {}) {
       }
 
       if (mode === "unlink") {
-        const wasCanonical = target.componentRole === "canonical";
-        const groupId = target.componentId;
-        if (wasCanonical && groupId) {
-          // Auto-promote: find first instance and make it canonical
-          const firstInstance = prev.find(
-            (s) => s.id !== id && s.componentId === groupId && s.componentRole === "instance"
-          );
-          if (firstInstance) {
-            return prev.map((s) => {
-              if (s.id === id) return { ...s, componentId: null, componentRole: null };
-              if (s.id === firstInstance.id) return { ...s, componentRole: "canonical" };
-              return s;
-            });
-          }
+        if (unlinkPromotion) {
+          // Auto-promote: clear role on the unlinked canonical and merge its
+          // hotspots into the promoted instance.
+          return prev.map((s) => {
+            if (s.id === id) return { ...s, componentId: null, componentRole: null };
+            if (s.id === unlinkPromotion.firstInstanceId) {
+              return {
+                ...s,
+                componentRole: "canonical",
+                hotspots: unlinkPromotion.mergedHotspots,
+              };
+            }
+            return s;
+          });
         }
         return prev.map((s) =>
           s.id === id ? { ...s, componentId: null, componentRole: null } : s
@@ -325,6 +427,22 @@ export function useScreenManager(pan, zoom, canvasRef, commentCallbacks = {}) {
 
       return prev;
     });
+
+    // Re-point connections in the unlink-canonical-with-instances branch only:
+    // hotspot-driven connections originating from the unlinked canonical that
+    // referenced a canonical-owned hotspot id should now flow from the
+    // promoted instance, since the merged hotspots live on it.
+    if (unlinkPromotion) {
+      setConnections((prev) =>
+        prev.map((c) =>
+          c.fromScreenId === unlinkPromotion.unlinkedCanonicalId &&
+          c.hotspotId &&
+          unlinkPromotion.canonicalHotspotIds.has(c.hotspotId)
+            ? { ...c, fromScreenId: unlinkPromotion.firstInstanceId }
+            : c
+        )
+      );
+    }
   }, [screens, connections, documents, pushHistory]);
 
   const markAllExisting = useCallback(() => {
@@ -366,6 +484,43 @@ export function useScreenManager(pan, zoom, canvasRef, commentCallbacks = {}) {
     commentCallbacksRef.current.onDeleteCommentsForScreens?.(ids);
     pushHistory(screens, connections, documents);
     const idSet = new Set(ids);
+
+    // Pre-compute per-group promotion metadata BEFORE both setters so neither
+    // closure reads stale state. We resolve `firstInstance` against the
+    // pre-removal screen list (skipping screens being removed).
+    const removedScreensSnapshot = screens.filter((s) => idSet.has(s.id));
+    const removedCanonicalsSnapshot = removedScreensSnapshot.filter(
+      (s) => s.componentRole === "canonical" && s.componentId
+    );
+    // Map of removedCanonicalId -> { firstInstanceId, canonicalHotspotIds, mergedHotspots }
+    const promotions = new Map();
+    for (const removedCanonical of removedCanonicalsSnapshot) {
+      // Skip if another canonical for the same group somehow remains (shouldn't happen normally).
+      const stillCanonical = screens.some(
+        (s) =>
+          !idSet.has(s.id) &&
+          s.componentId === removedCanonical.componentId &&
+          s.componentRole === "canonical"
+      );
+      if (stillCanonical) continue;
+      const firstInstance = screens.find(
+        (s) =>
+          !idSet.has(s.id) &&
+          s.componentId === removedCanonical.componentId &&
+          s.componentRole === "instance"
+      );
+      if (!firstInstance) continue;
+      const { canonicalHotspotIds, mergedHotspots } = mergeOnPromotion({
+        removedCanonical,
+        firstInstance,
+      });
+      promotions.set(removedCanonical.id, {
+        firstInstanceId: firstInstance.id,
+        canonicalHotspotIds,
+        mergedHotspots,
+      });
+    }
+
     setScreens((prev) => {
       const removedScreens = prev.filter((s) => idSet.has(s.id));
       let remaining = prev.filter((s) => !idSet.has(s.id));
@@ -380,32 +535,41 @@ export function useScreenManager(pan, zoom, canvasRef, commentCallbacks = {}) {
           );
         }
       });
-      // Auto-promote any orphaned component groups: if a canonical was removed and instances remain,
-      // promote the first remaining instance to canonical.
-      const removedCanonicalGroups = new Set(
-        removedScreens
-          .filter((s) => s.componentRole === "canonical" && s.componentId)
-          .map((s) => s.componentId)
-      );
-      removedCanonicalGroups.forEach((groupId) => {
-        const stillCanonical = remaining.some(
-          (s) => s.componentId === groupId && s.componentRole === "canonical"
-        );
-        if (stillCanonical) return;
-        const firstInstance = remaining.find(
-          (s) => s.componentId === groupId && s.componentRole === "instance"
+      // Auto-promote any orphaned component groups: if a canonical was removed
+      // and instances remain, promote the first remaining instance, merging
+      // the canonical's hotspots into its locals.
+      promotions.forEach((promo) => {
+        remaining = remaining.map((s) =>
+          s.id === promo.firstInstanceId
+            ? { ...s, componentRole: "canonical", hotspots: promo.mergedHotspots }
+            : s
         );
-        if (firstInstance) {
-          remaining = remaining.map((s) =>
-            s.id === firstInstance.id ? { ...s, componentRole: "canonical" } : s
-          );
-        }
       });
       return remaining;
     });
-    setConnections((prev) =>
-      prev.filter((c) => !idSet.has(c.fromScreenId) && !idSet.has(c.toScreenId))
-    );
+    setConnections((prev) => {
+      let next = prev;
+      if (promotions.size > 0) {
+        // Re-point connections originating from a removed canonical that
+        // referenced one of that canonical's hotspot ids onto the promoted
+        // instance — BEFORE the orphan-filter drops connections that still
+        // touch a removed id.
+        next = next.map((c) => {
+          const promo = promotions.get(c.fromScreenId);
+          if (
+            promo &&
+            c.hotspotId &&
+            promo.canonicalHotspotIds.has(c.hotspotId)
+          ) {
+            return { ...c, fromScreenId: promo.firstInstanceId };
+          }
+          return c;
+        });
+      }
+      return next.filter(
+        (c) => !idSet.has(c.fromScreenId) && !idSet.has(c.toScreenId)
+      );
+    });
     if (idSet.has(selectedScreen)) setSelectedScreen(null);
   }, [selectedScreen, screens, connections, documents, pushHistory]);
 
diff --git a/src/hooks/useScreenManager.test.js b/src/hooks/useScreenManager.test.js
index 24624d8..a70a881 100644
--- a/src/hooks/useScreenManager.test.js
+++ b/src/hooks/useScreenManager.test.js
@@ -1258,3 +1258,198 @@ describe("addScreensBatch", () => {
     expect(result.current.canUndo).toBe(false);
   });
 });
+
+describe("useScreenManager component promotion", () => {
+  it("removeScreen on canonical with two instances promotes first instance, merges hotspots, re-points connections", () => {
+    // Build: canonical with hotspot hC1 (navigate -> targetScreen).
+    // Instance 1 has its own local hI1.
+    const { result } = setup();
+    act(() => result.current.addScreen(null, "Target"));
+    const targetId = result.current.screens[0].id;
+
+    act(() => result.current.addScreen(null, "Canonical"));
+    const canonicalId = result.current.screens[1].id;
+    const canonicalHotspot = {
+      id: "hC1",
+      label: "CanTap",
+      x: 0, y: 0, w: 10, h: 10,
+      action: "navigate",
+      targetScreenId: targetId,
+    };
+    act(() => result.current.saveHotspot(canonicalId, canonicalHotspot));
+    act(() => result.current.setScreenComponent(canonicalId, "canonical"));
+    const componentId = result.current.screens.find((s) => s.id === canonicalId).componentId;
+
+    act(() => result.current.addScreen(null, "Instance 1"));
+    const inst1Id = result.current.screens[result.current.screens.length - 1].id;
+    act(() => result.current.setScreenComponent(inst1Id, "instance", { componentId }));
+    const localHotspot = {
+      id: "hI1",
+      label: "LocalTap",
+      x: 50, y: 50, w: 10, h: 10,
+      action: "navigate",
+      targetScreenId: null,
+    };
+    act(() => result.current.saveHotspot(inst1Id, localHotspot));
+
+    act(() => result.current.addScreen(null, "Instance 2"));
+    const inst2Id = result.current.screens[result.current.screens.length - 1].id;
+    act(() => result.current.setScreenComponent(inst2Id, "instance", { componentId }));
+
+    // Sanity: connection from canonical exists, keyed off hC1.
+    const connBefore = result.current.connections.find(
+      (c) => c.fromScreenId === canonicalId && c.hotspotId === "hC1"
+    );
+    expect(connBefore).toBeTruthy();
+
+    // Delete canonical.
+    act(() => result.current.removeScreen(canonicalId));
+
+    // Canonical gone.
+    expect(result.current.screens.find((s) => s.id === canonicalId)).toBeUndefined();
+    // Instance 1 promoted.
+    const promoted = result.current.screens.find((s) => s.id === inst1Id);
+    expect(promoted.componentRole).toBe("canonical");
+    // Hotspots merged: canonical's hC1 first, then instance's hI1.
+    const ids = promoted.hotspots.map((h) => h.id);
+    expect(ids).toContain("hC1");
+    expect(ids).toContain("hI1");
+    expect(promoted.hotspots).toHaveLength(2);
+    // Instance 2 still an instance.
+    const stillInstance = result.current.screens.find((s) => s.id === inst2Id);
+    expect(stillInstance.componentRole).toBe("instance");
+
+    // Connection re-pointed: now flows from promoted (inst1) instead of removed canonical.
+    const connAfter = result.current.connections.find((c) => c.hotspotId === "hC1");
+    expect(connAfter).toBeTruthy();
+    expect(connAfter.fromScreenId).toBe(inst1Id);
+    expect(connAfter.toScreenId).toBe(targetId);
+  });
+
+  it("removeScreens batch-deletes canonical with instances; promotes & re-points", () => {
+    const { result } = setup();
+    act(() => result.current.addScreen(null, "Target"));
+    const targetId = result.current.screens[0].id;
+
+    act(() => result.current.addScreen(null, "Canonical"));
+    const canonicalId = result.current.screens[1].id;
+    act(() =>
+      result.current.saveHotspot(canonicalId, {
+        id: "hC1", label: "CanTap", x: 0, y: 0, w: 10, h: 10,
+        action: "navigate", targetScreenId: targetId,
+      })
+    );
+    act(() => result.current.setScreenComponent(canonicalId, "canonical"));
+    const componentId = result.current.screens.find((s) => s.id === canonicalId).componentId;
+
+    act(() => result.current.addScreen(null, "Instance 1"));
+    const inst1Id = result.current.screens[result.current.screens.length - 1].id;
+    act(() => result.current.setScreenComponent(inst1Id, "instance", { componentId }));
+    act(() =>
+      result.current.saveHotspot(inst1Id, {
+        id: "hI1", label: "LocalTap", x: 50, y: 50, w: 10, h: 10,
+        action: "navigate", targetScreenId: null,
+      })
+    );
+
+    // Add an unrelated screen alongside the canonical in the batch removal.
+    act(() => result.current.addScreen(null, "Other"));
+    const otherId = result.current.screens[result.current.screens.length - 1].id;
+
+    act(() => result.current.removeScreens([canonicalId, otherId]));
+
+    expect(result.current.screens.find((s) => s.id === canonicalId)).toBeUndefined();
+    expect(result.current.screens.find((s) => s.id === otherId)).toBeUndefined();
+    const promoted = result.current.screens.find((s) => s.id === inst1Id);
+    expect(promoted.componentRole).toBe("canonical");
+    const ids = promoted.hotspots.map((h) => h.id);
+    expect(ids).toContain("hC1");
+    expect(ids).toContain("hI1");
+
+    const connAfter = result.current.connections.find((c) => c.hotspotId === "hC1");
+    expect(connAfter).toBeTruthy();
+    expect(connAfter.fromScreenId).toBe(inst1Id);
+  });
+
+  it("setScreenComponent unlink on canonical with instances promotes first instance, merges hotspots, re-points", () => {
+    const { result } = setup();
+    act(() => result.current.addScreen(null, "Target"));
+    const targetId = result.current.screens[0].id;
+
+    act(() => result.current.addScreen(null, "Canonical"));
+    const canonicalId = result.current.screens[1].id;
+    act(() =>
+      result.current.saveHotspot(canonicalId, {
+        id: "hC1", label: "CanTap", x: 0, y: 0, w: 10, h: 10,
+        action: "navigate", targetScreenId: targetId,
+      })
+    );
+    act(() => result.current.setScreenComponent(canonicalId, "canonical"));
+    const componentId = result.current.screens.find((s) => s.id === canonicalId).componentId;
+
+    act(() => result.current.addScreen(null, "Instance 1"));
+    const inst1Id = result.current.screens[result.current.screens.length - 1].id;
+    act(() => result.current.setScreenComponent(inst1Id, "instance", { componentId }));
+    act(() =>
+      result.current.saveHotspot(inst1Id, {
+        id: "hI1", label: "LocalTap", x: 50, y: 50, w: 10, h: 10,
+        action: "navigate", targetScreenId: null,
+      })
+    );
+
+    act(() => result.current.setScreenComponent(canonicalId, "unlink"));
+
+    const unlinked = result.current.screens.find((s) => s.id === canonicalId);
+    expect(unlinked.componentRole).toBeNull();
+    expect(unlinked.componentId).toBeNull();
+
+    const promoted = result.current.screens.find((s) => s.id === inst1Id);
+    expect(promoted.componentRole).toBe("canonical");
+    const ids = promoted.hotspots.map((h) => h.id);
+    expect(ids).toContain("hC1");
+    expect(ids).toContain("hI1");
+
+    // Re-point: connection from the (now-unlinked) canonical that referenced
+    // hC1 should now flow from the promoted instance.
+    const connRePointed = result.current.connections.find(
+      (c) => c.hotspotId === "hC1" && c.fromScreenId === inst1Id
+    );
+    expect(connRePointed).toBeTruthy();
+  });
+
+  it("promotion dedupes by hotspot id (canonical wins on collision)", () => {
+    const { result } = setup();
+    act(() => result.current.addScreen(null, "Target"));
+    const targetId = result.current.screens[0].id;
+
+    act(() => result.current.addScreen(null, "Canonical"));
+    const canonicalId = result.current.screens[1].id;
+    const sharedId = "hSHARED";
+    act(() =>
+      result.current.saveHotspot(canonicalId, {
+        id: sharedId, label: "Canonical version", x: 0, y: 0, w: 10, h: 10,
+        action: "navigate", targetScreenId: targetId,
+      })
+    );
+    act(() => result.current.setScreenComponent(canonicalId, "canonical"));
+    const componentId = result.current.screens.find((s) => s.id === canonicalId).componentId;
+
+    act(() => result.current.addScreen(null, "Instance 1"));
+    const inst1Id = result.current.screens[result.current.screens.length - 1].id;
+    act(() => result.current.setScreenComponent(inst1Id, "instance", { componentId }));
+    act(() =>
+      result.current.saveHotspot(inst1Id, {
+        id: sharedId, label: "Instance version", x: 50, y: 50, w: 10, h: 10,
+        action: "navigate", targetScreenId: null,
+      })
+    );
+
+    act(() => result.current.removeScreen(canonicalId));
+
+    const promoted = result.current.screens.find((s) => s.id === inst1Id);
+    expect(promoted.hotspots).toHaveLength(1);
+    // Canonical wins on collision — its label is preserved.
+    expect(promoted.hotspots[0].id).toBe(sharedId);
+    expect(promoted.hotspots[0].label).toBe("Canonical version");
+  });
+});

From 4e4c4e844bed1d882d3899fe95cca0989b8f3f08 Mon Sep 17 00:00:00 2001
From: Quang Tran <16215255+trmquang93@users.noreply.github.com>
Date: Mon, 27 Apr 2026 23:19:58 +0700
Subject: [PATCH 3/3] feat: emit per-Placement subsection in
 components/<slug>.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In generateComponentFiles, after the Placements table and before the
Spec block, iterate non-canonical placements and emit a "### Placement:
<name>" subsection for each instance with non-empty content. The block
includes:

- Per-hotspot detail via the shared renderHotspotDetailBlock renderer,
  so canonical and placement hotspot details look identical to the AI
  agent.
- Screen-level outgoing connections (no hotspotId) listed as
  "- → <target.name> (<action>)".

Skip the canonical placement — its spec is already emitted by the Spec
block. Skip instances with no local hotspots and no screen-level
outgoing connections.

Tests cover: emission of the Placement section for an instance with a
local hotspot, omission for the canonical itself, omission when the
instance has no local content, and regression that screens.md keeps
its one-line instance stub.

Update userGuide.md (and therefore the #/docs page, which imports the
markdown raw) with a new "Instance-specific hotspots" subsection
explaining the additive semantics and the auto-promotion merge. Soften
the prior TIP that called instance hotspots read-only.

Update MCP create_hotspot and list_hotspots tool descriptions to
clarify canonical-vs-instance hotspot semantics. No logic change.
---
 mcp-server/src/tools/hotspot-tools.js      |  4 +-
 src/pages/docs/userGuide.md                | 16 +++-
 src/utils/generateInstructionFiles.js      | 40 ++++++++++
 src/utils/generateInstructionFiles.test.js | 92 ++++++++++++++++++++++
 4 files changed, 148 insertions(+), 4 deletions(-)

diff --git a/mcp-server/src/tools/hotspot-tools.js b/mcp-server/src/tools/hotspot-tools.js
index 4269be1..e37b08b 100644
--- a/mcp-server/src/tools/hotspot-tools.js
+++ b/mcp-server/src/tools/hotspot-tools.js
@@ -23,7 +23,7 @@ const accessibilitySchema = {
 export const hotspotTools = [
   {
     name: "create_hotspot",
-    description: "Add a hotspot (tap area) to a screen. Coordinates are percentages (0-100) of the screen image dimensions. If action is 'navigate' or 'modal' and targetScreenId is provided, a connection is automatically created.",
+    description: "Add a hotspot (tap area) to a screen. Coordinates are percentages (0-100) of the screen image dimensions. If action is 'navigate' or 'modal' and targetScreenId is provided, a connection is automatically created. Hotspots on a canonical component apply to every placement; hotspots on an instance are placement-specific additive interactions that do not modify or hide the canonical's hotspots.",
     inputSchema: {
       type: "object",
       properties: {
@@ -120,7 +120,7 @@ export const hotspotTools = [
   },
   {
     name: "list_hotspots",
-    description: "List all hotspots on a specific screen.",
+    description: "List all hotspots on a specific screen. On a canonical component, this returns the hotspots that apply to every placement. On an instance, this returns only the placement-specific (additive) hotspots — to see the canonical's hotspots, call this against the canonical screen.",
     inputSchema: {
       type: "object",
       properties: {
diff --git a/src/pages/docs/userGuide.md b/src/pages/docs/userGuide.md
index 5f32b0c..1b4df43 100644
--- a/src/pages/docs/userGuide.md
+++ b/src/pages/docs/userGuide.md
@@ -300,10 +300,22 @@ You can also right-click the screen and choose **Mark as reusable component** fr
 1. Select a different screen that should be the same component.
 2. In the **Reusable Component** section, use the **Instance of…** dropdown to pick the canonical component you just created.
 3. The screen's spec fields (description, code reference, acceptance criteria, roles) collapse — the spec lives on the canonical screen. The screen gets a `↗ Instance` badge.
-4. The instance's image and hotspots on the canvas mirror the canonical's automatically. Edit the canonical and every instance updates.
+4. The instance's image and dimensions on the canvas mirror the canonical's automatically. Edit the canonical and every instance updates.
 
 > [!TIP]
-> Hotspot positions, dimensions, and the `+ Link` button are read-only on instances — the canonical owns the visual spec. To edit a hotspot or replace the image, jump to the canonical via the **Open canonical →** link in the sidebar.
+> The image is owned by the canonical — to replace it, jump to the canonical via the **Open canonical →** link in the sidebar. Hotspots and connections are different: see *Instance-specific hotspots* below.
+
+### Instance-specific hotspots
+
+Hotspots and connections on a canonical component apply to every placement where it appears. Sometimes a single placement also needs an extra tap area or navigation link that doesn't belong on the component itself.
+
+You can draw hotspots and create connections directly on an instance. These are **additive** — they do not modify or hide the canonical's hotspots. At export time, instance-local hotspots appear in the component file under "Placement: <screen name>" alongside the canonical spec.
+
+> [!NOTE]
+> Hotspots drawn on the canvas of an instance live only on that placement. If you need a hotspot to apply to every instance, edit the canonical instead.
+
+> [!TIP]
+> If you delete a canonical that has instances, the first instance becomes the new canonical. Its existing local hotspots are merged with the deleted canonical's, so nothing is lost. Connections that referenced the canonical's hotspots are re-pointed to the promoted instance automatically.
 
 ### Unlinking and conversions
 
diff --git a/src/utils/generateInstructionFiles.js b/src/utils/generateInstructionFiles.js
index 3e7ac84..021ccef 100644
--- a/src/utils/generateInstructionFiles.js
+++ b/src/utils/generateInstructionFiles.js
@@ -710,6 +710,46 @@ function generateComponentFiles(screens, connections, images, documents, compone
     }
     md += `\n`;
 
+    // Per-placement subsection: emit only for non-canonical placements that
+    // carry placement-specific content (local hotspots and/or screen-level
+    // outgoing connections). Hotspots on an instance are additive locals;
+    // canonical hotspots are NOT inherited at storage time and are already
+    // covered by the Spec block below.
+    for (const placement of instances) {
+      const localHotspots = placement.hotspots || [];
+      const localHotspotIds = new Set(localHotspots.map((h) => h.id));
+      const hotspotConns = connections.filter(
+        (c) =>
+          c.fromScreenId === placement.id &&
+          c.hotspotId &&
+          localHotspotIds.has(c.hotspotId)
+      );
+      const screenLevelConns = connections.filter(
+        (c) => c.fromScreenId === placement.id && !c.hotspotId
+      );
+      if (
+        localHotspots.length === 0 &&
+        hotspotConns.length === 0 &&
+        screenLevelConns.length === 0
+      ) {
+        continue;
+      }
+      md += `### Placement: ${placement.name}\n\n`;
+      md += `*Placement-specific interactions (in addition to the canonical spec below).*\n\n`;
+      for (const h of localHotspots) {
+        md += `#### ${h.label || "Hotspot"}\n\n`;
+        const detail = renderHotspotDetailBlock(h, screens, documents);
+        if (detail) md += detail;
+      }
+      for (const c of screenLevelConns) {
+        const target = screens.find((s) => s.id === c.toScreenId);
+        const targetName = target?.name ?? "(unknown)";
+        const action = c.action || "navigate";
+        md += `- → ${targetName} (${action})\n`;
+      }
+      md += `\n`;
+    }
+
     md += `## Spec\n\n`;
     md += generateScreenDetailMd(canonical, screens, connections, images, documents);
 
diff --git a/src/utils/generateInstructionFiles.test.js b/src/utils/generateInstructionFiles.test.js
index 3e22299..79ff57d 100644
--- a/src/utils/generateInstructionFiles.test.js
+++ b/src/utils/generateInstructionFiles.test.js
@@ -401,4 +401,96 @@ describe("generateInstructionFiles - reusable components", () => {
     expect(componentFile.content).toContain("instance");
     expect(componentFile.content).toContain("Home");
   });
+
+  it("emits a 'Placement: <name>' subsection in components/<slug>.md for an instance with a local hotspot", () => {
+    const localHotspot = {
+      id: "hI1",
+      label: "Skip",
+      elementType: "button",
+      interactionType: "tap",
+      action: "navigate",
+      x: 10, y: 10, w: 30, h: 10,
+    };
+    const screens = [
+      { ...minimalScreen, id: "s1", name: "Card", componentId: "c1", componentRole: "canonical" },
+      {
+        ...minimalScreen,
+        id: "s2",
+        name: "Card on Onboarding",
+        x: 400,
+        componentId: "c1",
+        componentRole: "instance",
+        hotspots: [localHotspot],
+      },
+    ];
+    const result = generateInstructionFiles(screens, [], opts);
+    const componentFile = result.files.find((f) => f.name === "components/card.md");
+    expect(componentFile.content).toContain("### Placement: Card on Onboarding");
+    expect(componentFile.content).toContain(
+      "*Placement-specific interactions (in addition to the canonical spec below).*"
+    );
+    expect(componentFile.content).toContain("#### Skip");
+  });
+
+  it("does not emit a 'Placement:' subsection for the canonical itself (its spec is the Spec block)", () => {
+    const screens = [
+      {
+        ...minimalScreen,
+        id: "s1",
+        name: "Card",
+        hotspots: [{
+          id: "hC1",
+          label: "Tap",
+          elementType: "button",
+          interactionType: "tap",
+          action: "navigate",
+          x: 10, y: 10, w: 80, h: 15,
+        }],
+        componentId: "c1",
+        componentRole: "canonical",
+      },
+      { ...minimalScreen, id: "s2", name: "Home", x: 400, componentId: "c1", componentRole: "instance" },
+    ];
+    const result = generateInstructionFiles(screens, [], opts);
+    const componentFile = result.files.find((f) => f.name === "components/card.md");
+    expect(componentFile.content).not.toContain("### Placement: Card\n");
+  });
+
+  it("does not emit a Placement subsection for an instance with no local content (regression)", () => {
+    const screens = [
+      { ...minimalScreen, id: "s1", name: "Card", componentId: "c1", componentRole: "canonical" },
+      { ...minimalScreen, id: "s2", name: "Home", x: 400, componentId: "c1", componentRole: "instance", hotspots: [] },
+    ];
+    const result = generateInstructionFiles(screens, [], opts);
+    const componentFile = result.files.find((f) => f.name === "components/card.md");
+    expect(componentFile.content).not.toContain("### Placement:");
+  });
+
+  it("screens.md instance entry remains a one-line stub (regression)", () => {
+    const screens = [
+      { ...minimalScreen, id: "s1", name: "Card", componentId: "c1", componentRole: "canonical" },
+      {
+        ...minimalScreen,
+        id: "s2",
+        name: "Card on Home",
+        x: 400,
+        componentId: "c1",
+        componentRole: "instance",
+        hotspots: [{
+          id: "hI1",
+          label: "Skip",
+          elementType: "button",
+          interactionType: "tap",
+          action: "navigate",
+          x: 10, y: 10, w: 30, h: 10,
+        }],
+      },
+    ];
+    const result = generateInstructionFiles(screens, [], opts);
+    const screensFile = result.files.find((f) => f.name === "screens.md");
+    expect(screensFile.content).toContain("Instance of [Card](components/card.md)");
+    // The instance stub must not duplicate the placement-specific hotspot detail
+    // — that lives in components/card.md only.
+    expect(screensFile.content).not.toContain("### Placement: Card on Home");
+  });
 });