feat: emit per-Placement subsection in components/<slug>.md

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.

Author: trmquang93

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: {

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
 

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);
 

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");
+  });
 });