From f49390888881d16d948b48a59cb5c5e46522e893 Mon Sep 17 00:00:00 2001
From: KalPop <keypop3750@gmail.com>
Date: Thu, 2 Jul 2026 21:39:05 +0100
Subject: [PATCH 1/5] fix(scripts): Windows dev server port probing with cmd
 timeout fallback

Adds a Windows-specific retry loop using cmd /c timeout when the port
probing helper cannot identify the holding process. This avoids false
positives when a previous dev server is still shutting down.
---
 scripts/dev.ts          |  4 +++-
 scripts/lib/freePort.ts | 11 +++++++++--
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/scripts/dev.ts b/scripts/dev.ts
index a60564b3d..7387cbd42 100644
--- a/scripts/dev.ts
+++ b/scripts/dev.ts
@@ -265,7 +265,9 @@ function stopChildren(signal: NodeJS.Signals = 'SIGTERM'): void {
 }
 
 for (const cfg of processes) {
-  const child = Bun.spawn(cfg.command.split(' '), {
+  const args = cfg.command.split(' ')
+  if (args[0] === 'bun') args[0] = process.execPath
+  const child = Bun.spawn(args, {
     env: { ...process.env, ...cfg.env },
     stdin: 'inherit',
     stdout: 'inherit',
diff --git a/scripts/lib/freePort.ts b/scripts/lib/freePort.ts
index d7f51e3b7..6953e18e7 100644
--- a/scripts/lib/freePort.ts
+++ b/scripts/lib/freePort.ts
@@ -22,6 +22,7 @@ interface PortHolder {
  * holding process's `comm` name. Empty array when the port is free.
  */
 function findPortHolders(port: number): PortHolder[] {
+  if (process.platform === 'win32') return []
   const lsof = Bun.spawnSync(
     ['lsof', '-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'],
     { stdout: 'pipe', stderr: 'ignore' },
@@ -107,8 +108,14 @@ export async function ensurePortFree(
 
   const holders = findPortHolders(port)
   if (holders.length === 0) {
-    // Port is busy but we couldn't enumerate the holder (rare — usually
-    // a permissions issue on lsof). Fall through to the manual message.
+    if (process.platform === 'win32') {
+      // On Windows we can't enumerate holders easily; just wait a bit
+      // and re-probe in case a previous dev server is shutting down.
+      for (let i = 0; i < 30; i++) {
+        if (probePort(port) === 'free') return
+        Bun.spawnSync(['cmd', '/c', 'timeout', '/t', '1', '/nobreak', '>nul', '2>&1'])
+      }
+    }
     log(`Port ${port} (${name}) is in use, but the holding process could not be identified.`)
     log(`Run \`lsof -i :${port} -P -n\` to inspect it manually.`)
     process.exit(1)

From 029207a635bdd880423119ea0fbd5b1da1393830 Mon Sep 17 00:00:00 2001
From: KalPop <keypop3750@gmail.com>
Date: Thu, 2 Jul 2026 22:21:37 +0100
Subject: [PATCH 2/5] feat: clickable layer mention pills in AI chat composer
 and thread

---
 server/ai/tools/site/systemPrompt.ts          |   1 +
 src/__tests__/agent/agentSlice.test.ts        |  51 +++-
 .../dom-panel/layerNodeContextMenu.test.tsx   |  85 ++++++
 src/admin/pages/site/agent/agentSlice.ts      |  18 +-
 src/admin/pages/site/agent/agentSliceTypes.ts |  22 +-
 src/admin/pages/site/agent/index.ts           |   2 +-
 src/admin/pages/site/agent/types.ts           |  11 +
 .../canvas/BreakpointSelectionOverlay.tsx     |  19 ++
 .../site/panels/AgentPanel/AgentComposer.tsx  | 135 ++++++++++
 .../panels/AgentPanel/AgentPanel.module.css   |  56 ++++
 .../site/panels/AgentPanel/AgentPanel.tsx     |  92 +------
 .../site/panels/AgentPanel/RichTextBubble.tsx | 250 ++++++++++++++++++
 .../panels/DomPanel/LayerNodeContextMenu.tsx  |  13 +
 13 files changed, 671 insertions(+), 84 deletions(-)
 create mode 100644 src/admin/pages/site/panels/AgentPanel/AgentComposer.tsx
 create mode 100644 src/admin/pages/site/panels/AgentPanel/RichTextBubble.tsx

diff --git a/server/ai/tools/site/systemPrompt.ts b/server/ai/tools/site/systemPrompt.ts
index b8548fdd0..5fb8df003 100644
--- a/server/ai/tools/site/systemPrompt.ts
+++ b/server/ai/tools/site/systemPrompt.ts
@@ -68,6 +68,7 @@ Templates (CMS layouts):
 
 Notes:
 - Use real ids from the suffix or prior tool results — never invent ids. Class refs accept id OR name.
+- When the user references a specific layer by ID (e.g. "Layer abc123" or "Layers abc123, def456"), extract those nodeIds and use them directly in your tool calls — do not ask the user to describe the element again.
 - Browser write-tool success data uses explicit keys: cssRulesCreated/cssRulesUpdated for site_apply_css, pageId for site_add_page/site_duplicate_page, nodeId/nodeIds for site_duplicate_node, and nodeIds for HTML inserts.
 - On tool error: read the message and retry with corrected input.
 
diff --git a/src/__tests__/agent/agentSlice.test.ts b/src/__tests__/agent/agentSlice.test.ts
index cb91026e3..2e9499cf8 100644
--- a/src/__tests__/agent/agentSlice.test.ts
+++ b/src/__tests__/agent/agentSlice.test.ts
@@ -35,6 +35,7 @@ function freshAgentState() {
     agentActiveModelId: null,
     agentContextTokens: null,
     agentConversations: [],
+    agentDraftMentions: [],
     hasUnsavedChanges: false,
   })
 
@@ -507,8 +508,8 @@ describe('sendAgentMessage — request lifecycle', () => {
 })
 
 describe('conversation reset key-set', () => {
-  // All three reset paths must clear the SAME six keys — agentContextTokens and
-  // agentError have each silently drifted out of one copy in the past.
+  // All three reset paths must clear the SAME seven keys — agentContextTokens,
+  // agentError, and agentDraftMentions have each silently drifted out in the past.
   const RESET_SNAPSHOT = {
     agentMessages: [],
     agentError: null,
@@ -516,6 +517,7 @@ describe('conversation reset key-set', () => {
     agentActiveCredentialId: null,
     agentActiveModelId: null,
     agentContextTokens: null,
+    agentDraftMentions: [],
   }
 
   function seedDirtyConversation() {
@@ -527,6 +529,7 @@ describe('conversation reset key-set', () => {
       agentActiveCredentialId: 'cred-1',
       agentActiveModelId: 'model-1',
       agentContextTokens: 4096,
+      agentDraftMentions: [{ nodeId: 'abc123', label: 'Layer abc123' }],
     })
   }
 
@@ -539,10 +542,11 @@ describe('conversation reset key-set', () => {
       agentActiveCredentialId: s.agentActiveCredentialId,
       agentActiveModelId: s.agentActiveModelId,
       agentContextTokens: s.agentContextTokens,
+      agentDraftMentions: s.agentDraftMentions,
     }
   }
 
-  it('startNewAgentConversation resets the full six-key set (incl. agentContextTokens)', () => {
+  it('startNewAgentConversation resets the full seven-key set (incl. agentContextTokens)', () => {
     seedDirtyConversation()
     useEditorStore.getState().startNewAgentConversation()
     expect(pickResetKeys()).toEqual(RESET_SNAPSHOT)
@@ -781,3 +785,44 @@ describe('setAgentProvider', () => {
     expect(useEditorStore.getState().agentError).toBeNull()
   })
 })
+
+// ---------------------------------------------------------------------------
+// stageAgentMentions — "Add to AI Chat" staging
+// ---------------------------------------------------------------------------
+
+describe('stageAgentMentions', () => {
+  it('stages mentions and opens the agent panel', () => {
+    freshAgentState()
+    useEditorStore.setState({ isAgentOpen: false, agentDraftMentions: [] })
+
+    useEditorStore.getState().stageAgentMentions([{ nodeId: 'abc123', label: 'Layer abc123' }])
+
+    expect(useEditorStore.getState().agentDraftMentions).toEqual([{ nodeId: 'abc123', label: 'Layer abc123' }])
+    expect(useEditorStore.getState().isAgentOpen).toBe(true)
+  })
+
+  it('appends to existing mentions', () => {
+    freshAgentState()
+    useEditorStore.setState({ agentDraftMentions: [{ nodeId: 'old', label: 'Layer old' }] })
+
+    useEditorStore.getState().stageAgentMentions([
+      { nodeId: 'abc123', label: 'Layer abc123' },
+      { nodeId: 'def456', label: 'Layer def456' },
+    ])
+
+    expect(useEditorStore.getState().agentDraftMentions).toEqual([
+      { nodeId: 'old', label: 'Layer old' },
+      { nodeId: 'abc123', label: 'Layer abc123' },
+      { nodeId: 'def456', label: 'Layer def456' },
+    ])
+  })
+
+  it('clears mentions via clearAgentDraftMentions', () => {
+    freshAgentState()
+    useEditorStore.setState({ agentDraftMentions: [{ nodeId: 'abc123', label: 'Layer abc123' }] })
+
+    useEditorStore.getState().clearAgentDraftMentions()
+
+    expect(useEditorStore.getState().agentDraftMentions).toEqual([])
+  })
+})
diff --git a/src/__tests__/dom-panel/layerNodeContextMenu.test.tsx b/src/__tests__/dom-panel/layerNodeContextMenu.test.tsx
index 4330ab396..ce8f7c0c1 100644
--- a/src/__tests__/dom-panel/layerNodeContextMenu.test.tsx
+++ b/src/__tests__/dom-panel/layerNodeContextMenu.test.tsx
@@ -864,3 +864,88 @@ describe('LayerNodeContextMenu — multi-delete confirmation', () => {
     expect(pageAfterConfirm?.nodes.c).toBeDefined()
   })
 })
+
+describe('LayerNodeContextMenu — Add to AI chat', () => {
+  function setupAiChatPage() {
+    localStorage.clear()
+    const home = makePage({
+      id: 'page-ai',
+      title: 'Home',
+      slug: 'index',
+      rootNodeId: 'root',
+      nodes: {
+        root: makeNode({ id: 'root', moduleId: 'base.body', children: ['a', 'b'] }),
+        a: makeNode({ id: 'a', moduleId: 'base.text' }),
+        b: makeNode({ id: 'b', moduleId: 'base.button' }),
+      },
+    })
+    useEditorStore.setState({
+      site: makeSite({ pages: [home], files: [], visualComponents: [] }),
+      activePageId: 'page-ai',
+      selectedNodeId: 'a',
+      selectedNodeIds: ['a'],
+      hoveredNodeId: null,
+      activeDocument: null,
+      isAgentOpen: false,
+      agentDraftMentions: [],
+      _historyPast: [],
+      _historyFuture: [],
+      canUndo: false,
+      canRedo: false,
+      hasUnsavedChanges: false,
+    } as Parameters<typeof useEditorStore.setState>[0])
+  }
+
+  function renderAiChatMenu(nodeId = 'a') {
+    return render(
+      <LayerNodeContextMenu
+        x={100}
+        y={200}
+        nodeId={nodeId}
+        onClose={noop}
+        onDelete={noop}
+        onDuplicate={noop}
+        onRename={noop}
+        onWrapInContainer={noop}
+        onCopy={noop}
+        onCut={noop}
+        onPaste={noop}
+      />,
+    )
+  }
+
+  it('renders the "Add to AI chat" menu item', () => {
+    setupAiChatPage()
+    renderAiChatMenu()
+    expect(screen.getByRole('menuitem', { name: /add to ai chat/i })).toBeDefined()
+  })
+
+  it('stages a single node id as the agent draft and opens the panel', () => {
+    setupAiChatPage()
+    renderAiChatMenu('a')
+
+    fireEvent.click(screen.getByRole('menuitem', { name: /add to ai chat/i }))
+
+    expect(useEditorStore.getState().agentDraftMentions).toEqual([
+      { nodeId: 'a', label: 'Layer a' },
+    ])
+    expect(useEditorStore.getState().isAgentOpen).toBe(true)
+  })
+
+  it('stages multiple selected node ids when right-clicking a multi-selection', () => {
+    setupAiChatPage()
+    useEditorStore.setState({
+      selectedNodeId: 'b',
+      selectedNodeIds: ['a', 'b'],
+    } as Parameters<typeof useEditorStore.setState>[0])
+    renderAiChatMenu('b')
+
+    fireEvent.click(screen.getByRole('menuitem', { name: /add to ai chat/i }))
+
+    expect(useEditorStore.getState().agentDraftMentions).toEqual([
+      { nodeId: 'a', label: 'Layer a' },
+      { nodeId: 'b', label: 'Layer b' },
+    ])
+    expect(useEditorStore.getState().isAgentOpen).toBe(true)
+  })
+})
diff --git a/src/admin/pages/site/agent/agentSlice.ts b/src/admin/pages/site/agent/agentSlice.ts
index 3458b6939..887add329 100644
--- a/src/admin/pages/site/agent/agentSlice.ts
+++ b/src/admin/pages/site/agent/agentSlice.ts
@@ -42,6 +42,7 @@ export type { AgentSlice, AgentSliceConfig } from './agentSliceTypes'
 import type {
   AgentBridgeRuntime,
   AgentMessage,
+  AgentMessageMention,
   AgentRequestBody,
   AgentTextStreamSink,
 } from './types'
@@ -124,6 +125,7 @@ type ConversationResetKeys =
   | 'agentActiveCredentialId'
   | 'agentActiveModelId'
   | 'agentContextTokens'
+  | 'agentDraftMentions'
 
 function conversationResetState(): Pick<AgentSlice, ConversationResetKeys> {
   return {
@@ -133,6 +135,7 @@ function conversationResetState(): Pick<AgentSlice, ConversationResetKeys> {
     agentActiveCredentialId: null,
     agentActiveModelId: null,
     agentContextTokens: null,
+    agentDraftMentions: [],
   }
 }
 
@@ -242,6 +245,7 @@ export function createAgentSlice(
     agentActiveModelId: null,
     agentConversations: [],
     agentContextTokens: null,
+    agentDraftMentions: [],
 
     // ── UI actions ───────────────────────────────────────────────────────────
     openAgent() {
@@ -258,6 +262,17 @@ export function createAgentSlice(
       })
     },
 
+    stageAgentMentions(mentions) {
+      set((state) => {
+        state.agentDraftMentions.push(...mentions)
+        state.isAgentOpen = true
+      })
+    },
+
+    clearAgentDraftMentions() {
+      set({ agentDraftMentions: [] })
+    },
+
     abortAgent() {
       _abortController?.abort()
       _abortController = null
@@ -390,7 +405,7 @@ export function createAgentSlice(
     },
 
     // ── sendAgentMessage ─────────────────────────────────────────────────────
-    async sendAgentMessage(content) {
+    async sendAgentMessage(content, mentions?: AgentMessageMention[]) {
       if (get().isAgentStreaming) return // one request at a time
 
       const userMsg: AgentMessage = {
@@ -398,6 +413,7 @@ export function createAgentSlice(
         role: 'user',
         blocks: [{ kind: 'text', text: content }],
         timestamp: Date.now(),
+        mentions,
       }
 
       const assistantId = nanoid()
diff --git a/src/admin/pages/site/agent/agentSliceTypes.ts b/src/admin/pages/site/agent/agentSliceTypes.ts
index 91efa50ac..0593fec2d 100644
--- a/src/admin/pages/site/agent/agentSliceTypes.ts
+++ b/src/admin/pages/site/agent/agentSliceTypes.ts
@@ -28,6 +28,11 @@ export interface AgentSliceConfig {
   readonly noProviderMessage?: string
 }
 
+export interface AgentDraftMention {
+  nodeId: string
+  label: string
+}
+
 export interface AgentSlice {
   isAgentOpen: boolean
   isAgentStreaming: boolean
@@ -38,11 +43,17 @@ export interface AgentSlice {
   agentActiveModelId: string | null
   agentConversations: ConversationView[]
   agentContextTokens: number | null
+  /**
+   * Mention queue for the agent composer. Set by "Add to AI Chat" actions
+   * from the canvas / layers panel; consumed once by AgentComposer then
+   * cleared. Each entry carries the layer's nodeId and display label.
+   */
+  agentDraftMentions: AgentDraftMention[]
 
   openAgent(): void
   closeAgent(): void
   toggleAgent(): void
-  sendAgentMessage(content: string): Promise<void>
+  sendAgentMessage(content: string, mentions?: import('./types').AgentMessageMention[]): Promise<void>
   abortAgent(): void
   clearAgentMessages(): void
   loadAgentConversations(): Promise<void>
@@ -51,6 +62,15 @@ export interface AgentSlice {
   deleteAgentConversation(id: string): Promise<void>
   setAgentProvider(credentialId: string, modelId: string): Promise<void>
   loadScopeDefault(): Promise<void>
+  /**
+   * Queue layer mentions into the agent composer and open the panel so the
+   * user can finish their prompt. Used by "Add to AI Chat" flows.
+   */
+  stageAgentMentions(mentions: AgentDraftMention[]): void
+  /**
+   * Clear the mention queue after the composer has consumed it.
+   */
+  clearAgentDraftMentions(): void
 }
 
 export type EditorStoreSet = Parameters<EditorStoreSliceCreator<AgentSlice>>[0]
diff --git a/src/admin/pages/site/agent/index.ts b/src/admin/pages/site/agent/index.ts
index d62a98f97..199ddbb39 100644
--- a/src/admin/pages/site/agent/index.ts
+++ b/src/admin/pages/site/agent/index.ts
@@ -9,7 +9,7 @@
 
 // Slice factory + its public contract.
 export { createAgentSlice } from './agentSlice'
-export type { AgentSlice, AgentSliceConfig } from './agentSliceTypes'
+export type { AgentSlice, AgentSliceConfig, AgentDraftMention } from './agentSliceTypes'
 
 // Site-editor wiring (scope, snapshot, dispatcher) handed to the factory.
 export { siteAgentSliceConfig } from './agentSliceConfig.site'
diff --git a/src/admin/pages/site/agent/types.ts b/src/admin/pages/site/agent/types.ts
index 50a944f04..32af1717b 100644
--- a/src/admin/pages/site/agent/types.ts
+++ b/src/admin/pages/site/agent/types.ts
@@ -171,11 +171,22 @@ type AgentMessageBlock =
   | { kind: 'text'; text: string }
   | { kind: 'toolCall'; toolCall: AgentToolCall }
 
+export interface AgentMessageMention {
+  nodeId: string
+  label: string
+}
+
 export interface AgentMessage {
   id: string
   role: 'user' | 'assistant'
   blocks: AgentMessageBlock[]
   timestamp: number
+  /**
+   * Layer mentions embedded in this message, purely for client-side
+   * rendering. Not sent to the server — populated from the composer's
+   * DOM when the user sends a message, or extracted from assistant text.
+   */
+  mentions?: AgentMessageMention[]
 }
 
 // ---------------------------------------------------------------------------
diff --git a/src/admin/pages/site/canvas/BreakpointSelectionOverlay.tsx b/src/admin/pages/site/canvas/BreakpointSelectionOverlay.tsx
index fdb774065..3e297ebe7 100644
--- a/src/admin/pages/site/canvas/BreakpointSelectionOverlay.tsx
+++ b/src/admin/pages/site/canvas/BreakpointSelectionOverlay.tsx
@@ -80,6 +80,7 @@ import { cn } from '@ui/cn'
 import { CopyPlusSolidIcon } from 'pixel-art-icons/icons/copy-plus-solid'
 import { TrashSolidIcon } from 'pixel-art-icons/icons/trash-solid'
 import { HandGrabSolidIcon } from 'pixel-art-icons/icons/hand-grab-solid'
+import { SparklesSolidIcon } from 'pixel-art-icons/icons/sparkles-solid'
 import { CanvasViewportActionsContext } from './CanvasContexts'
 import { CanvasInsertModuleButton } from './CanvasInsertModuleButton'
 import { useCanvasReorderDrag } from './useCanvasReorderDrag'
@@ -139,6 +140,13 @@ function deleteSelectedLayers() {
   state.clearSelection()
 }
 
+function addSelectedLayersToAiChat() {
+  const ids = useEditorStore.getState().selectedNodeIds
+  if (ids.length === 0) return
+  const mentions = ids.map((id) => ({ nodeId: id, label: `Layer ${id}` }))
+  useEditorStore.getState().stageAgentMentions(mentions)
+}
+
 export function BreakpointSelectionOverlay({
   breakpointId,
   viewportRef,
@@ -389,6 +397,17 @@ export function BreakpointSelectionOverlay({
       </Button>
       <CanvasInsertModuleButton buttonClassName={styles.selectionToolbarButton} />
 
+      <Button
+        variant="secondary"
+        size="xs"
+        iconOnly
+        aria-label="Add selected layers to AI chat"
+        tooltip="Add selected layers to AI chat"
+        className={styles.selectionToolbarButton}
+        onClick={addSelectedLayersToAiChat}
+      >
+        <SparklesSolidIcon size={13} color="var(--text)" />
+      </Button>
       <Button
         variant="secondary"
         size="xs"
diff --git a/src/admin/pages/site/panels/AgentPanel/AgentComposer.tsx b/src/admin/pages/site/panels/AgentPanel/AgentComposer.tsx
new file mode 100644
index 000000000..4969db054
--- /dev/null
+++ b/src/admin/pages/site/panels/AgentPanel/AgentComposer.tsx
@@ -0,0 +1,135 @@
+/**
+ * AgentComposer — a contenteditable chat input that supports clickable
+ * layer-mention pills. Mentions are rendered as styled inline chips; the
+ * rest is plain text. On submit the editor's `innerText` is sent to the AI
+ * (mentions serialize as their label text, e.g. "Layer abc123").
+ */
+import { useRef, useEffect, useCallback } from 'react'
+import { useAgentStore } from '@admin/ai/useAgentStore'
+import { useEditorStore } from '@site/store/store'
+import { cn } from '@ui/cn'
+import styles from './AgentPanel.module.css'
+
+import type { AgentDraftMention } from '@site/agent'
+
+interface AgentComposerProps {
+  placeholder?: string
+  disabled?: boolean
+  onSubmit: (text: string, mentions: AgentDraftMention[]) => void
+}
+
+export function AgentComposer({ placeholder, disabled, onSubmit }: AgentComposerProps) {
+  const editorRef = useRef<HTMLDivElement>(null)
+  const draftMentions = useAgentStore((s) => s.agentDraftMentions)
+  const clearMentions = useAgentStore((s) => s.clearAgentDraftMentions)
+
+  // Consume queued mentions from the store and insert them into the editor.
+  useEffect(() => {
+    if (draftMentions.length === 0 || !editorRef.current) return
+    const el = editorRef.current
+    el.focus()
+
+    const sel = window.getSelection()
+    const hasSelection =
+      sel && sel.rangeCount > 0 && el.contains(sel.getRangeAt(0).commonAncestorContainer)
+
+    for (const mention of draftMentions) {
+      const pill = document.createElement('span')
+      pill.className = styles.mentionPill
+      pill.dataset.nodeId = mention.nodeId
+      pill.contentEditable = 'false'
+      pill.textContent = mention.label
+
+      const space = document.createTextNode('\u00A0')
+
+      if (hasSelection) {
+        const range = sel!.getRangeAt(0)
+        range.deleteContents()
+        range.insertNode(space)
+        range.collapse(false)
+        range.insertNode(pill)
+        range.collapse(false)
+      } else {
+        el.appendChild(pill)
+        el.appendChild(space)
+      }
+    }
+
+    // Move caret to end
+    const endRange = document.createRange()
+    endRange.selectNodeContents(el)
+    endRange.collapse(false)
+    sel?.removeAllRanges()
+    sel?.addRange(endRange)
+
+    // Update empty-state styling
+    const isEmpty = el.innerText.trim() === ''
+    el.classList.toggle(styles.composerEmpty, isEmpty)
+
+    clearMentions()
+  }, [draftMentions, clearMentions])
+
+  const handleInput = useCallback(() => {
+    const el = editorRef.current
+    if (!el) return
+    const isEmpty = el.innerText.trim() === ''
+    el.classList.toggle(styles.composerEmpty, isEmpty)
+  }, [])
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLDivElement>) => {
+      if (e.key === 'Enter' && !e.shiftKey) {
+        e.preventDefault()
+        const el = editorRef.current
+        if (!el) return
+        const text = el.innerText.trim()
+        if (text) {
+          // Collect mention pills before we wipe the DOM.
+          const mentions: AgentDraftMention[] = []
+          el.querySelectorAll('[data-node-id]').forEach((node) => {
+            const nodeId = node.getAttribute('data-node-id')
+            if (nodeId) {
+              mentions.push({ nodeId, label: node.textContent || `Layer ${nodeId}` })
+            }
+          })
+          onSubmit(text, mentions)
+          el.innerHTML = ''
+          el.classList.add(styles.composerEmpty)
+        }
+      }
+    },
+    [onSubmit],
+  )
+
+  const handlePaste = useCallback((e: React.ClipboardEvent<HTMLDivElement>) => {
+    e.preventDefault()
+    const plain = e.clipboardData.getData('text/plain')
+    document.execCommand('insertText', false, plain)
+  }, [])
+
+  const handleClick = useCallback((e: React.MouseEvent<HTMLDivElement>) => {
+    const target = e.target as HTMLElement
+    const nodeId = target.dataset.nodeId
+    if (nodeId) {
+      e.preventDefault()
+      e.stopPropagation()
+      useEditorStore.getState().selectNode(nodeId, 'replace')
+    }
+  }, [])
+
+  return (
+    <div
+      ref={editorRef}
+      className={cn(styles.composer, styles.composerEmpty, disabled && styles.composerDisabled)}
+      contentEditable={!disabled}
+      onInput={handleInput}
+      onKeyDown={handleKeyDown}
+      onPaste={handlePaste}
+      onClick={handleClick}
+      data-placeholder={placeholder}
+      suppressContentEditableWarning
+      aria-label={placeholder}
+      role="textbox"
+    />
+  )
+}
diff --git a/src/admin/pages/site/panels/AgentPanel/AgentPanel.module.css b/src/admin/pages/site/panels/AgentPanel/AgentPanel.module.css
index 38fda119f..fa8d58f09 100644
--- a/src/admin/pages/site/panels/AgentPanel/AgentPanel.module.css
+++ b/src/admin/pages/site/panels/AgentPanel/AgentPanel.module.css
@@ -123,6 +123,62 @@
   gap: var(--space-s);
 }
 
+/* ── Composer (contenteditable) ────────────────────────────────────────── */
+.composer {
+  width: 100%;
+  min-height: 44px;
+  max-height: 120px;
+  overflow-y: auto;
+  padding: var(--space-s) var(--space-m);
+  border: 1px solid var(--overlay-10);
+  border-radius: var(--radius);
+  background: var(--bg-surface);
+  color: var(--text);
+  font-size: var(--text-m);
+  line-height: 1.5;
+  outline: none;
+  cursor: text;
+  word-break: break-word;
+  white-space: pre-wrap;
+}
+
+.composer:focus {
+  border-color: var(--primary);
+}
+
+.composerEmpty::before {
+  content: attr(data-placeholder);
+  color: var(--text-disabled);
+  pointer-events: none;
+}
+
+.composerDisabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  background: var(--bg-surface-2);
+}
+
+/* ── Mention pill ────────────────────────────────────────────────────────── */
+.mentionPill {
+  display: inline-block;
+  padding: 1px 6px;
+  margin: 0 1px;
+  border-radius: var(--radius-sm);
+  background: var(--accent-2-10);
+  color: var(--accent-2);
+  font-size: var(--text-s);
+  font-weight: 600;
+  line-height: 1.4;
+  cursor: pointer;
+  user-select: none;
+  vertical-align: middle;
+  border: 1px solid color-mix(in srgb, var(--accent-2) 25%, transparent);
+}
+
+.mentionPill:hover {
+  background: color-mix(in srgb, var(--accent-2) 20%, transparent);
+}
+
 /* The picker takes the leftover width but never crowds out the button. */
 .inputControlsPicker {
   min-width: 0;
diff --git a/src/admin/pages/site/panels/AgentPanel/AgentPanel.tsx b/src/admin/pages/site/panels/AgentPanel/AgentPanel.tsx
index 670228137..586684207 100644
--- a/src/admin/pages/site/panels/AgentPanel/AgentPanel.tsx
+++ b/src/admin/pages/site/panels/AgentPanel/AgentPanel.tsx
@@ -21,13 +21,14 @@
  * @see Guideline #410 — 3 Self-Contained Independent Panels
  */
 
-import { useRef, useEffect, memo } from 'react'
+import { useRef, useEffect, useCallback } from 'react'
 import { useAgentStore } from '@admin/ai/useAgentStore'
 import { useAsyncResource } from '@admin/lib/useAsyncResource'
 import { useAdminNavigate } from '@admin/lib/useAdminNavigate'
 import { useAuthenticatedAdminUser } from '@admin/sessionContext'
 import { listCredentials, listModels } from '@admin/ai/api'
-import { renderMarkdownToHtml, type AgentMessage, type AgentToolCall } from '@site/agent'
+import { type AgentMessage, type AgentToolCall, type AgentMessageMention } from '@site/agent'
+import { RichTextBubble } from './RichTextBubble'
 import { SquareSolidIcon } from 'pixel-art-icons/icons/square-solid'
 import { SendSolidIcon } from 'pixel-art-icons/icons/send-solid'
 import { AiBoxSolidIcon } from 'pixel-art-icons/icons/ai-box-solid'
@@ -38,7 +39,7 @@ import { PanelHeader } from '@admin/shared/PanelHeader'
 import { UserAvatar } from '@admin/shared/UserAvatar'
 import { Button } from '@ui/components/Button'
 import { EmptyState } from '@ui/components/EmptyState'
-import { Textarea } from '@ui/components/Input'
+import { AgentComposer } from './AgentComposer'
 import { useDraggablePanel } from '@site/hooks/useDraggablePanel'
 import { cn } from '@ui/cn'
 import { ModelPicker } from './ModelPicker'
@@ -122,7 +123,6 @@ export function AgentPanel({ variant = 'floating' }: { variant?: PanelVariant })
     { swallowErrors: true },
   )
 
-  const inputRef = useRef<HTMLTextAreaElement>(null)
   const threadRef = useRef<HTMLDivElement>(null)
 
   // ── Draggable panel position ───────────────────────────────────────────────
@@ -143,16 +143,6 @@ export function AgentPanel({ variant = 'floating' }: { variant?: PanelVariant })
     if (el) el.scrollTop = el.scrollHeight
   }, [messages])
 
-  // Focus input when panel becomes active (isOpen transitions to true).
-  // The 50ms delay lets the panel's open transition settle before we steal
-  // focus; cleanup cancels the pending focus if the panel closes again
-  // (or the component unmounts) before the timer fires.
-  useEffect(() => {
-    if (!isOpen) return
-    const id = setTimeout(() => inputRef.current?.focus(), 50)
-    return () => clearTimeout(id)
-  }, [isOpen])
-
   // Preload the per-scope default credential + model when the panel opens, so
   // the picker shows the configured default immediately and the first send
   // uses it. The action no-ops if a conversation or explicit pick already
@@ -173,23 +163,10 @@ export function AgentPanel({ variant = 'floating' }: { variant?: PanelVariant })
     return () => document.removeEventListener('keydown', onKey)
   }, [isOpen, closeAgent])
 
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault()
-    const input = inputRef.current
-    if (!input) return
-    const content = input.value.trim()
+  const handleComposerSubmit = useCallback(async (content: string, mentions?: AgentMessageMention[]) => {
     if (!content || isStreaming) return
-    input.value = ''
-    input.style.height = 'auto'
-    await sendAgentMessage(content)
-  }
-
-  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
-    if (e.key === 'Enter' && !e.shiftKey) {
-      e.preventDefault()
-      handleSubmit(e as unknown as React.FormEvent)
-    }
-  }
+    await sendAgentMessage(content, mentions)
+  }, [isStreaming, sendAgentMessage])
 
   // Always-mounted: CSS display:none when closed (via .floatPanelClosed) preserves
   // Zustand state across open/close cycles without conditional rendering.
@@ -284,27 +261,18 @@ export function AgentPanel({ variant = 'floating' }: { variant?: PanelVariant })
         {/* Live context-window meter — renders once the active model's window
             is known (pre-turn shows 0 / window). */}
         <ContextMeter windowTokens={contextWindowResource.data} />
-        <form onSubmit={handleSubmit} className={styles.inputForm}>
-          {/* Textarea is hidden while streaming — the controls row collapses
+        <form onSubmit={(e) => e.preventDefault()} className={styles.inputForm}>
+          {/* Composer is hidden while streaming — the controls row collapses
               to just the model picker + Stop button. */}
           {!isStreaming && (
-            <Textarea
-              ref={inputRef}
+            <AgentComposer
               placeholder={lockReason === 'setup'
                 ? 'Add AI credentials to start chatting'
                 : lockReason === 'chooseModel'
                   ? 'Choose a model below to start'
                   : 'Tell me what to build… (Enter to send)'}
-              aria-label="Message to AI assistant"
-              rows={2}
-              resize="none"
               disabled={composerLocked}
-              onKeyDown={handleKeyDown}
-              onChange={(e) => {
-                // Auto-grow textarea
-                e.target.style.height = 'auto'
-                e.target.style.height = `${Math.min(e.target.scrollHeight, 120)}px`
-              }}
+              onSubmit={handleComposerSubmit}
             />
           )}
           {/* Controls row: model picker on the left (saves vertical space),
@@ -392,7 +360,7 @@ function MessageBubble({ group }: { group: ConversationGroup }) {
           DOMPurify-sanitised HTML pipeline. */}
       {groupRenderItems(group.messages).map((item) =>
         item.kind === 'text' ? (
-          <MarkdownTextBubble key={item.key} text={item.text} isUser={isUser} />
+          <RichTextBubble key={item.key} text={item.text} isUser={isUser} mentions={item.mentions} />
         ) : (
           // A run of consecutive tool calls shares one container so the rows
           // stack tightly; text blocks around them stay separate bubbles.
@@ -430,7 +398,7 @@ function groupConsecutiveMessages(messages: AgentMessage[]): ConversationGroup[]
 type MessageBlock = AgentMessage['blocks'][number]
 
 type MessageRenderItem =
-  | { kind: 'text'; key: string; text: string }
+  | { kind: 'text'; key: string; text: string; mentions?: AgentMessageMention[] }
   | { kind: 'tools'; key: string; toolCalls: AgentToolCall[] }
 
 function groupRenderItems(messages: AgentMessage[]): MessageRenderItem[] {
@@ -439,7 +407,7 @@ function groupRenderItems(messages: AgentMessage[]): MessageRenderItem[] {
     message.blocks.forEach((block: MessageBlock, index) => {
       if (block.kind === 'text') {
         // Position-based key, stable as streaming deltas append in place.
-        items.push({ kind: 'text', key: `text-${message.id}-${index}`, text: block.text })
+        items.push({ kind: 'text', key: `text-${message.id}-${index}`, text: block.text, mentions: message.mentions })
         return
       }
       const last = items.at(-1)
@@ -454,38 +422,6 @@ function groupRenderItems(messages: AgentMessage[]): MessageRenderItem[] {
 }
 
 // ---------------------------------------------------------------------------
-// MarkdownTextBubble — parses + sanitises the block text and injects it via
-// dangerouslySetInnerHTML. Memoised render so streaming deltas don't re-parse
-// markdown for unchanged blocks.
-// ---------------------------------------------------------------------------
-
-interface MarkdownTextBubbleProps {
-  text: string
-  isUser: boolean
-}
-
-// Exception #2: React.memo re-render bailout on a hot, list-rendered component
-// (one per text block, re-rendered on every streaming delta).
-const MarkdownTextBubble = memo(function MarkdownTextBubble({
-  text,
-  isUser,
-}: MarkdownTextBubbleProps) {
-  const html = renderMarkdownToHtml(text)
-  // Empty/whitespace-only blocks don't render at all (avoids stray bubbles
-  // around stripped-out tool blocks during streaming).
-  if (!html) return null
-  return (
-    <div
-      className={cn(
-        styles.messageText,
-        isUser ? styles.messageTextUser : styles.messageTextAssistant,
-        styles.markdownText,
-      )}
-      // Safe: sanitised by DOMPurify (via sanitizeRichtext) before reaching here.
-      dangerouslySetInnerHTML={{ __html: html }}
-    />
-  )
-})
 
 // ---------------------------------------------------------------------------
 // Empty state
diff --git a/src/admin/pages/site/panels/AgentPanel/RichTextBubble.tsx b/src/admin/pages/site/panels/AgentPanel/RichTextBubble.tsx
new file mode 100644
index 000000000..80e9ba6c2
--- /dev/null
+++ b/src/admin/pages/site/panels/AgentPanel/RichTextBubble.tsx
@@ -0,0 +1,250 @@
+/**
+ * RichTextBubble — renders a message text block with inline clickable
+ * layer-mention pills. User messages use stored mentions; assistant messages
+ * are scanned for mention patterns and validated against the current page.
+ * Text without mentions falls back to markdown rendering (bold, lists, code).
+ */
+import { memo, useCallback } from 'react'
+import { useEditorStore } from '@site/store/store'
+import { renderMarkdownToHtml } from '@site/agent'
+import { cn } from '@ui/cn'
+import type { AgentMessageMention } from '@site/agent'
+import styles from './AgentPanel.module.css'
+
+interface RichTextBubbleProps {
+  text: string
+  isUser: boolean
+  mentions?: AgentMessageMention[]
+}
+
+const MENTION_RE = /\bLayer(s?)\s+([A-Za-z0-9_-]+(?:,\s*[A-Za-z0-9_-]+)*)\b/g
+
+function useNodeSelector() {
+  const selectNode = useCallback(
+    (nodeId: string) => {
+      try {
+        useEditorStore.getState().selectNode(nodeId, 'replace')
+      } catch {
+        // Content workspace or missing store — silently ignore.
+      }
+    },
+    [],
+  )
+  return selectNode
+}
+
+function MentionPill({ label, nodeId }: { label: string; nodeId: string }) {
+  const selectNode = useNodeSelector()
+  return (
+    <span
+      className={styles.mentionPill}
+      data-node-id={nodeId}
+      onClick={(e) => {
+        e.stopPropagation()
+        selectNode(nodeId)
+      }}
+      role="button"
+      tabIndex={0}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault()
+          selectNode(nodeId)
+        }
+      }}
+    >
+      {label}
+    </span>
+  )
+}
+
+/**
+ * Split text by a set of known mention labels and render each mention as a
+ * clickable pill. Unmatched text is rendered as a plain <span>.
+ */
+function renderWithStoredMentions(
+  text: string,
+  mentions: AgentMessageMention[],
+): React.ReactNode[] {
+  const segments: React.ReactNode[] = []
+  let remaining = text
+
+  for (const mention of mentions) {
+    const idx = remaining.indexOf(mention.label)
+    if (idx === -1) continue
+    if (idx > 0) {
+      segments.push(
+        <span key={`t-${segments.length}`}>{remaining.slice(0, idx)}</span>,
+      )
+    }
+    segments.push(
+      <MentionPill
+        key={`m-${mention.nodeId}-${segments.length}`}
+        nodeId={mention.nodeId}
+        label={mention.label}
+      />,
+    )
+    remaining = remaining.slice(idx + mention.label.length)
+  }
+
+  if (remaining) {
+    segments.push(<span key={`t-${segments.length}`}>{remaining}</span>)
+  }
+
+  return segments.length > 0 ? segments : [text]
+}
+
+/**
+ * Scan assistant text for "Layer abc123" or "Layers abc123, def456" patterns
+ * and render matching nodeIds as pills. All other text stays plain.
+ */
+function renderWithScannedMentions(text: string): React.ReactNode[] {
+  const segments: React.ReactNode[] = []
+  let lastIndex = 0
+
+  // Get current page node ids for validation
+  let validNodeIds: Set<string> | null = null
+  try {
+    const site = useEditorStore.getState().site
+    const activePageId = useEditorStore.getState().activePageId
+    const page = site?.pages.find((p) => p.id === activePageId)
+    if (page?.nodes) {
+      validNodeIds = new Set(Object.keys(page.nodes))
+    }
+  } catch {
+    // No editor store available (content workspace)
+  }
+
+  let match: RegExpExecArray | null
+  MENTION_RE.lastIndex = 0
+  while ((match = MENTION_RE.exec(text)) !== null) {
+    const [fullMatch, plural, idsStr] = match
+    const start = match.index
+    const ids = idsStr.split(',').map((s) => s.trim())
+
+    // Push plain text before the match
+    if (start > lastIndex) {
+      segments.push(
+        <span key={`t-${segments.length}`}>{text.slice(lastIndex, start)}</span>,
+      )
+    }
+
+    // Render each id as a pill if it looks valid
+    const pills: React.ReactNode[] = []
+    ids.forEach((id, i) => {
+      const isValid = !validNodeIds || validNodeIds.has(id)
+      if (isValid) {
+        pills.push(
+          <MentionPill
+            key={`m-${id}-${segments.length}-${i}`}
+            nodeId={id}
+            label={`Layer ${id}`}
+          />,
+        )
+      } else {
+        pills.push(
+          <span key={`m-${id}-${segments.length}-${i}`}>Layer {id}</span>,
+        )
+      }
+      if (i < ids.length - 1) {
+        pills.push(<span key={`sep-${segments.length}-${i}`}>, </span>)
+      }
+    })
+
+    // Wrap the group with the "Layers" prefix if plural
+    if (plural && ids.length > 1) {
+      segments.push(
+        <span key={`g-${segments.length}`}>
+          Layers {pills}
+        </span>,
+      )
+    } else if (plural && ids.length === 1) {
+      segments.push(
+        <span key={`g-${segments.length}`}>
+          Layers {pills}
+        </span>,
+      )
+    } else {
+      segments.push(
+        <span key={`g-${segments.length}`}>
+          Layer {pills}
+        </span>,
+      )
+    }
+
+    lastIndex = start + fullMatch.length
+  }
+
+  // Remaining plain text
+  if (lastIndex < text.length) {
+    segments.push(<span key={`t-${segments.length}`}>{text.slice(lastIndex)}</span>)
+  }
+
+  return segments.length > 0 ? segments : [text]
+}
+
+// Exception: React.memo re-render bailout on a hot, list-rendered component.
+const RichTextBubble = memo(function RichTextBubble({
+  text,
+  isUser,
+  mentions,
+}: RichTextBubbleProps) {
+  const hasStoredMentions = mentions && mentions.length > 0
+
+  if (hasStoredMentions) {
+    return (
+      <div
+        className={cn(
+          styles.messageText,
+          isUser ? styles.messageTextUser : styles.messageTextAssistant,
+        )}
+      >
+        {renderWithStoredMentions(text, mentions!)}
+      </div>
+    )
+  }
+
+  // Assistant text — scan for mention patterns
+  if (!isUser && MENTION_RE.test(text)) {
+    // Reset regex state after test
+    MENTION_RE.lastIndex = 0
+    return (
+      <div
+        className={cn(
+          styles.messageText,
+          styles.messageTextAssistant,
+        )}
+      >
+        {renderWithScannedMentions(text)}
+      </div>
+    )
+  }
+  MENTION_RE.lastIndex = 0
+
+  // No mentions — render markdown for assistants, plain text for users
+  const html = !isUser ? renderMarkdownToHtml(text) : null
+  if (html) {
+    return (
+      <div
+        className={cn(
+          styles.messageText,
+          styles.messageTextAssistant,
+          styles.markdownText,
+        )}
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    )
+  }
+
+  return (
+    <div
+      className={cn(
+        styles.messageText,
+        isUser ? styles.messageTextUser : styles.messageTextAssistant,
+      )}
+    >
+      {text}
+    </div>
+  )
+})
+
+export { RichTextBubble }
diff --git a/src/admin/pages/site/panels/DomPanel/LayerNodeContextMenu.tsx b/src/admin/pages/site/panels/DomPanel/LayerNodeContextMenu.tsx
index c7d745f27..6a7f86fff 100644
--- a/src/admin/pages/site/panels/DomPanel/LayerNodeContextMenu.tsx
+++ b/src/admin/pages/site/panels/DomPanel/LayerNodeContextMenu.tsx
@@ -64,6 +64,7 @@ import { CodeIcon } from 'pixel-art-icons/icons/code'
 import { BoxSolidIcon } from 'pixel-art-icons/icons/box-solid'
 import { LayoutSolidIcon } from 'pixel-art-icons/icons/layout-solid'
 import { EyeSolidIcon } from 'pixel-art-icons/icons/eye-solid'
+import { SparklesSolidIcon } from 'pixel-art-icons/icons/sparkles-solid'
 import { isNarrowEditorChromeViewport } from '@site/layout/responsiveChrome'
 import styles from './LayerNodeContextMenu.module.css'
 
@@ -318,6 +319,13 @@ export function LayerNodeContextMenu({
     onClose()
   }
 
+  const dispatchAddToAiChat = () => {
+    if (targetIds.length === 0) return
+    const mentions = targetIds.map((id) => ({ nodeId: id, label: `Layer ${id}` }))
+    useEditorStore.getState().stageAgentMentions(mentions)
+    onClose()
+  }
+
   // Selection-count chip in the menu header (multi only). Lives as a
   // disabled menuitem-equivalent label so screen readers can read "3 layers
   // selected" before announcing the action items.
@@ -387,6 +395,11 @@ export function LayerNodeContextMenu({
             </ContextMenuItem>
           )}
 
+          <ContextMenuItem onClick={dispatchAddToAiChat}>
+            <span aria-hidden="true"><SparklesSolidIcon size={13} /></span>
+            Add to AI chat
+          </ContextMenuItem>
+
           <ContextMenuSeparator />
 
           <ContextMenuItem onClick={dispatchCopy}>

From 73ef1edd95d53744e6cef9ee9f80d77422924d25 Mon Sep 17 00:00:00 2001
From: KalPop <keypop3750@gmail.com>
Date: Fri, 3 Jul 2026 17:13:27 +0100
Subject: [PATCH 3/5] feat: human-readable layer mention labels with
 tag-derived colors

- New mentionLabel.ts helper resolves .classSelector, <tag>, or
  displayName from a nodeId, plus a tag-derived colorKey.
- Mention pills are now bold colored inline text (no badge box) so
  they don't push line height out of alignment.
- Underline uses currentColor so hover matches the pill color.
- AgentComposer uses getMentionLabelForNode for inserted pills.
- LayerNodeContextMenu generates human labels when staging mentions.
---
 src/admin/pages/site/agent/mentionLabel.ts    | 46 +++++++++++++++++++
 .../site/panels/AgentPanel/AgentComposer.tsx  | 14 ++++--
 .../panels/AgentPanel/AgentPanel.module.css   | 18 +++-----
 .../panels/DomPanel/LayerNodeContextMenu.tsx  |  6 ++-
 4 files changed, 67 insertions(+), 17 deletions(-)
 create mode 100644 src/admin/pages/site/agent/mentionLabel.ts

diff --git a/src/admin/pages/site/agent/mentionLabel.ts b/src/admin/pages/site/agent/mentionLabel.ts
new file mode 100644
index 000000000..526427cf8
--- /dev/null
+++ b/src/admin/pages/site/agent/mentionLabel.ts
@@ -0,0 +1,46 @@
+/**
+ * MentionLabel — compute a human-readable label and a tag-derived color key
+ * for a layer mention pill.
+ *
+ * The label is what the user sees; the colorKey is what drives the pill
+ * accent so it matches the DOM tree's `<tag>` badge colour.
+ */
+import { registry } from '@core/module-engine'
+import {
+  getNodeDisplayName,
+  getNodeHtmlTag,
+  getNodeClassNames,
+} from '@core/page-tree'
+import { useEditorStore } from '@site/store/store'
+
+export interface MentionLabelResult {
+  label: string
+  colorKey: string
+}
+
+export function getMentionLabelForNode(nodeId: string): MentionLabelResult {
+  const state = useEditorStore.getState()
+  const site = state.site
+  const activePageId = state.activePageId
+  const page = site?.pages.find((p) => p.id === activePageId)
+  const node = page?.nodes[nodeId]
+
+  if (!node) {
+    return { label: nodeId, colorKey: nodeId }
+  }
+
+  const def = registry.get(node.moduleId)
+  const classNames = getNodeClassNames(node, site?.styleRules)
+  const htmlTag = getNodeHtmlTag(node, def)
+
+  // Priority: class selector chip → html tag badge → module display name
+  if (classNames.length > 0) {
+    return { label: `.${classNames.join('.')}`, colorKey: htmlTag ?? classNames[0] }
+  }
+  if (htmlTag) {
+    return { label: `<${htmlTag}>`, colorKey: htmlTag }
+  }
+
+  const displayName = getNodeDisplayName(node, def, site?.visualComponents)
+  return { label: displayName, colorKey: displayName }
+}
diff --git a/src/admin/pages/site/panels/AgentPanel/AgentComposer.tsx b/src/admin/pages/site/panels/AgentPanel/AgentComposer.tsx
index 4969db054..8eb26c3e7 100644
--- a/src/admin/pages/site/panels/AgentPanel/AgentComposer.tsx
+++ b/src/admin/pages/site/panels/AgentPanel/AgentComposer.tsx
@@ -1,13 +1,17 @@
 /**
  * AgentComposer — a contenteditable chat input that supports clickable
- * layer-mention pills. Mentions are rendered as styled inline chips; the
- * rest is plain text. On submit the editor's `innerText` is sent to the AI
- * (mentions serialize as their label text, e.g. "Layer abc123").
+ * layer-mention pills. Mentions render as bold coloured inline text (e.g.
+ * ".icon" or "<header>"). On submit the human text is stored for UI
+ * display, but `sendAgentMessage` replaces each mention label with
+ * "Layer <nodeId>" in the prompt sent to the AI so the model understands
+ * these are layer references and can respond with machine-readable ids.
  */
 import { useRef, useEffect, useCallback } from 'react'
 import { useAgentStore } from '@admin/ai/useAgentStore'
 import { useEditorStore } from '@site/store/store'
 import { cn } from '@ui/cn'
+import { pillAccent, pillAccentVar } from '@ui/pillAccent'
+import { getMentionLabelForNode } from '@site/agent/mentionLabel'
 import styles from './AgentPanel.module.css'
 
 import type { AgentDraftMention } from '@site/agent'
@@ -34,11 +38,13 @@ export function AgentComposer({ placeholder, disabled, onSubmit }: AgentComposer
       sel && sel.rangeCount > 0 && el.contains(sel.getRangeAt(0).commonAncestorContainer)
 
     for (const mention of draftMentions) {
+      const { label, colorKey } = getMentionLabelForNode(mention.nodeId)
       const pill = document.createElement('span')
       pill.className = styles.mentionPill
       pill.dataset.nodeId = mention.nodeId
       pill.contentEditable = 'false'
-      pill.textContent = mention.label
+      pill.textContent = label
+      pill.style.color = pillAccentVar(pillAccent(colorKey))
 
       const space = document.createTextNode('\u00A0')
 
diff --git a/src/admin/pages/site/panels/AgentPanel/AgentPanel.module.css b/src/admin/pages/site/panels/AgentPanel/AgentPanel.module.css
index fa8d58f09..baec27bdd 100644
--- a/src/admin/pages/site/panels/AgentPanel/AgentPanel.module.css
+++ b/src/admin/pages/site/panels/AgentPanel/AgentPanel.module.css
@@ -160,23 +160,17 @@
 
 /* ── Mention pill ────────────────────────────────────────────────────────── */
 .mentionPill {
-  display: inline-block;
-  padding: 1px 6px;
-  margin: 0 1px;
-  border-radius: var(--radius-sm);
-  background: var(--accent-2-10);
   color: var(--accent-2);
-  font-size: var(--text-s);
-  font-weight: 600;
-  line-height: 1.4;
+  font-weight: 700;
   cursor: pointer;
-  user-select: none;
-  vertical-align: middle;
-  border: 1px solid color-mix(in srgb, var(--accent-2) 25%, transparent);
+  text-decoration: underline;
+  text-decoration-color: color-mix(in srgb, currentColor 35%, transparent);
+  text-underline-offset: 2px;
+  text-decoration-thickness: 1.5px;
 }
 
 .mentionPill:hover {
-  background: color-mix(in srgb, var(--accent-2) 20%, transparent);
+  text-decoration-color: currentColor;
 }
 
 /* The picker takes the leftover width but never crowds out the button. */
diff --git a/src/admin/pages/site/panels/DomPanel/LayerNodeContextMenu.tsx b/src/admin/pages/site/panels/DomPanel/LayerNodeContextMenu.tsx
index 6a7f86fff..4f133c6f6 100644
--- a/src/admin/pages/site/panels/DomPanel/LayerNodeContextMenu.tsx
+++ b/src/admin/pages/site/panels/DomPanel/LayerNodeContextMenu.tsx
@@ -48,6 +48,7 @@ import { useInsertModule } from '@site/hooks/useInsertModule'
 import { resolveInsertLocation } from '@site/store/insertLocation'
 import { ModulePicker } from '@site/module-picker'
 import { canComponentizeNode } from '@site/componentization'
+import { getMentionLabelForNode } from '@site/agent/mentionLabel'
 import { useConfirmDelete } from '@admin/shared/dialogs/ConfirmDeleteDialog'
 import type { AnyModuleDefinition } from '@core/module-engine'
 import { PenSquareSolidIcon } from 'pixel-art-icons/icons/pen-square-solid'
@@ -321,7 +322,10 @@ export function LayerNodeContextMenu({
 
   const dispatchAddToAiChat = () => {
     if (targetIds.length === 0) return
-    const mentions = targetIds.map((id) => ({ nodeId: id, label: `Layer ${id}` }))
+    const mentions = targetIds.map((id) => {
+      const { label } = getMentionLabelForNode(id)
+      return { nodeId: id, label }
+    })
     useEditorStore.getState().stageAgentMentions(mentions)
     onClose()
   }

From d7d568f09f4bce5886d209a0414fdc98836f363c Mon Sep 17 00:00:00 2001
From: KalPop <keypop3750@gmail.com>
Date: Fri, 3 Jul 2026 17:13:41 +0100
Subject: [PATCH 4/5] feat: AI response mention scanning with machine-readable
 prompts

- RichTextBubble scanner now matches Layer/Module/Element/Node/Section/
  Component prefixes with optional brackets or backticks.
- Preserves the original prefix word in rendered output.
- Falls back to agentMentionLabels registry for deleted nodes.
- sendAgentMessage replaces human mention labels with 'Layer nodeId'
  in the AI prompt, and appends a concise instruction telling the AI
  to use the same format in its responses.
---
 src/admin/pages/site/agent/agentSlice.ts      | 26 +++++-
 .../site/panels/AgentPanel/RichTextBubble.tsx | 83 ++++++++++++-------
 2 files changed, 78 insertions(+), 31 deletions(-)

diff --git a/src/admin/pages/site/agent/agentSlice.ts b/src/admin/pages/site/agent/agentSlice.ts
index 887add329..e0276bc98 100644
--- a/src/admin/pages/site/agent/agentSlice.ts
+++ b/src/admin/pages/site/agent/agentSlice.ts
@@ -126,6 +126,7 @@ type ConversationResetKeys =
   | 'agentActiveModelId'
   | 'agentContextTokens'
   | 'agentDraftMentions'
+  | 'agentMentionLabels'
 
 function conversationResetState(): Pick<AgentSlice, ConversationResetKeys> {
   return {
@@ -136,6 +137,7 @@ function conversationResetState(): Pick<AgentSlice, ConversationResetKeys> {
     agentActiveModelId: null,
     agentContextTokens: null,
     agentDraftMentions: [],
+    agentMentionLabels: {},
   }
 }
 
@@ -246,6 +248,7 @@ export function createAgentSlice(
     agentConversations: [],
     agentContextTokens: null,
     agentDraftMentions: [],
+    agentMentionLabels: {},
 
     // ── UI actions ───────────────────────────────────────────────────────────
     openAgent() {
@@ -265,6 +268,9 @@ export function createAgentSlice(
     stageAgentMentions(mentions) {
       set((state) => {
         state.agentDraftMentions.push(...mentions)
+        for (const m of mentions) {
+          state.agentMentionLabels[m.nodeId] = m.label
+        }
         state.isAgentOpen = true
       })
     },
@@ -429,6 +435,10 @@ export function createAgentSlice(
         state.agentMessages.push(assistantMsg)
         state.agentError = null
         state.isAgentStreaming = true
+        // Register mention labels so they survive node deletion
+        for (const m of mentions ?? []) {
+          state.agentMentionLabels[m.nodeId] = m.label
+        }
       })
 
       _abortController = new AbortController()
@@ -451,7 +461,21 @@ export function createAgentSlice(
           return
         }
 
-        const body: AgentRequestBody = { conversationId, prompt: content, snapshot }
+        // Build machine-readable prompt: replace human mention labels with
+        // Layer <nodeId> so the AI knows these are layer references.
+        let machinePrompt = content
+        for (const mention of mentions ?? []) {
+          machinePrompt = machinePrompt.replace(mention.label, `Layer ${mention.nodeId}`)
+        }
+
+        // Instruct the AI to respond with the same Layer <nodeId> format
+        // so the UI can render them as clickable mention pills.
+        const hasMentions = (mentions ?? []).length > 0
+        const instruction = hasMentions
+          ? `Write layer references exactly as: the word Layer, a space, then the raw id with no extra characters. Example: Layer b3zJlOcL1. Never wrap ids in angle brackets or backticks.\n\n`
+          : ''
+
+        const body: AgentRequestBody = { conversationId, prompt: instruction + machinePrompt, snapshot }
         const res = await fetch(`/admin/api/ai/chat/${config.scope}`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
diff --git a/src/admin/pages/site/panels/AgentPanel/RichTextBubble.tsx b/src/admin/pages/site/panels/AgentPanel/RichTextBubble.tsx
index 80e9ba6c2..f8008d885 100644
--- a/src/admin/pages/site/panels/AgentPanel/RichTextBubble.tsx
+++ b/src/admin/pages/site/panels/AgentPanel/RichTextBubble.tsx
@@ -8,6 +8,8 @@ import { memo, useCallback } from 'react'
 import { useEditorStore } from '@site/store/store'
 import { renderMarkdownToHtml } from '@site/agent'
 import { cn } from '@ui/cn'
+import { pillAccent, pillAccentVar } from '@ui/pillAccent'
+import { getMentionLabelForNode } from '@site/agent/mentionLabel'
 import type { AgentMessageMention } from '@site/agent'
 import styles from './AgentPanel.module.css'
 
@@ -17,7 +19,13 @@ interface RichTextBubbleProps {
   mentions?: AgentMessageMention[]
 }
 
-const MENTION_RE = /\bLayer(s?)\s+([A-Za-z0-9_-]+(?:,\s*[A-Za-z0-9_-]+)*)\b/g
+/**
+ * Matches layer references like "Layer abc123", "Module <abc123>",
+ * "Elements \`def456\`, \`ghi789\`", etc. Accepts multiple prefix words
+ * (Layer, Module, Element, Node, Section, Component) with optional plural
+ * 's' and optional angle-brackets or backticks around each id.
+ */
+const MENTION_RE = /\b(?:Layer|Module|Element|Node|Section|Component)s?\s+((?:<|`|`)?[A-Za-z0-9_-]+(?:>|`|\`)?(?:,\s*(?:<|`|\`)?[A-Za-z0-9_-]+(?:>|`|\`)?)*)/gi
 
 function useNodeSelector() {
   const selectNode = useCallback(
@@ -35,10 +43,17 @@ function useNodeSelector() {
 
 function MentionPill({ label, nodeId }: { label: string; nodeId: string }) {
   const selectNode = useNodeSelector()
+  let colorKey = nodeId
+  try {
+    colorKey = getMentionLabelForNode(nodeId).colorKey
+  } catch {
+    // Node deleted — fall back to nodeId for color generation
+  }
   return (
     <span
       className={styles.mentionPill}
       data-node-id={nodeId}
+      style={{ color: pillAccentVar(pillAccent(colorKey)) }}
       onClick={(e) => {
         e.stopPropagation()
         selectNode(nodeId)
@@ -101,15 +116,18 @@ function renderWithScannedMentions(text: string): React.ReactNode[] {
   const segments: React.ReactNode[] = []
   let lastIndex = 0
 
-  // Get current page node ids for validation
+  // Get current page node ids for validation + mention label registry
   let validNodeIds: Set<string> | null = null
+  let mentionLabels: Record<string, string> = {}
   try {
-    const site = useEditorStore.getState().site
-    const activePageId = useEditorStore.getState().activePageId
+    const state = useEditorStore.getState()
+    const site = state.site
+    const activePageId = state.activePageId
     const page = site?.pages.find((p) => p.id === activePageId)
     if (page?.nodes) {
       validNodeIds = new Set(Object.keys(page.nodes))
     }
+    mentionLabels = state.agentMentionLabels ?? {}
   } catch {
     // No editor store available (content workspace)
   }
@@ -117,9 +135,15 @@ function renderWithScannedMentions(text: string): React.ReactNode[] {
   let match: RegExpExecArray | null
   MENTION_RE.lastIndex = 0
   while ((match = MENTION_RE.exec(text)) !== null) {
-    const [fullMatch, plural, idsStr] = match
+    const [fullMatch, idsStr] = match
     const start = match.index
-    const ids = idsStr.split(',').map((s) => s.trim())
+    const ids = idsStr
+      .split(',')
+      .map((s) => s.trim().replace(/^[<`\`]+|[>`\`]+$/g, ''))
+
+    // Preserve the original prefix word (Layer, Module, Node, etc.)
+    const prefixMatch = fullMatch.match(/^\S+/)
+    const prefix = prefixMatch ? prefixMatch[0] : 'Layer'
 
     // Push plain text before the match
     if (start > lastIndex) {
@@ -128,21 +152,34 @@ function renderWithScannedMentions(text: string): React.ReactNode[] {
       )
     }
 
-    // Render each id as a pill if it looks valid
+    // Render each id as a pill with a human-readable label if it looks valid
     const pills: React.ReactNode[] = []
     ids.forEach((id, i) => {
+      const cachedLabel = mentionLabels[id]
       const isValid = !validNodeIds || validNodeIds.has(id)
-      if (isValid) {
+      if (cachedLabel) {
+        // Known from registry (may be deleted) — render as pill
         pills.push(
           <MentionPill
             key={`m-${id}-${segments.length}-${i}`}
             nodeId={id}
-            label={`Layer ${id}`}
+            label={cachedLabel}
+          />,
+        )
+      } else if (isValid) {
+        // Still exists in page — resolve fresh
+        const { label } = getMentionLabelForNode(id)
+        pills.push(
+          <MentionPill
+            key={`m-${id}-${segments.length}-${i}`}
+            nodeId={id}
+            label={label}
           />,
         )
       } else {
+        // Unknown deleted node — plain text fallback
         pills.push(
-          <span key={`m-${id}-${segments.length}-${i}`}>Layer {id}</span>,
+          <span key={`m-${id}-${segments.length}-${i}`}>{prefix} {id}</span>,
         )
       }
       if (i < ids.length - 1) {
@@ -150,26 +187,12 @@ function renderWithScannedMentions(text: string): React.ReactNode[] {
       }
     })
 
-    // Wrap the group with the "Layers" prefix if plural
-    if (plural && ids.length > 1) {
-      segments.push(
-        <span key={`g-${segments.length}`}>
-          Layers {pills}
-        </span>,
-      )
-    } else if (plural && ids.length === 1) {
-      segments.push(
-        <span key={`g-${segments.length}`}>
-          Layers {pills}
-        </span>,
-      )
-    } else {
-      segments.push(
-        <span key={`g-${segments.length}`}>
-          Layer {pills}
-        </span>,
-      )
-    }
+    // Preserve the original prefix word in the rendered output
+    segments.push(
+      <span key={`g-${segments.length}`}>
+        {prefix} {pills}
+      </span>,
+    )
 
     lastIndex = start + fullMatch.length
   }

From f0f31ac0201b24db00eec737a4da53732173488f Mon Sep 17 00:00:00 2001
From: KalPop <keypop3750@gmail.com>
Date: Fri, 3 Jul 2026 17:13:48 +0100
Subject: [PATCH 5/5] feat: cached tool-call labels + conversation mention
 registry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- AgentToolCall gains displayLabel (resolved at creation time via
  getMentionLabelForNode) so tool rows show human names after deletion.
- ToolCallRow and toolCallDisplay.ts thread displayLabel through
  all node-detail helpers.
- AgentSlice gains agentMentionLabels: Record<string, string> to
  accumulate nodeId→label mappings across the conversation.
- Labels are registered when drafting mentions, sending user messages,
  and creating tool calls — surviving node deletion for AI response
  scanning.
- streamEvents.ts resolves and caches displayLabel on toolCall creation.
---
 src/admin/pages/site/agent/agentSliceTypes.ts |  6 ++
 src/admin/pages/site/agent/streamEvents.ts    | 20 ++++++
 src/admin/pages/site/agent/types.ts           |  6 ++
 .../site/panels/AgentPanel/ToolCallRow.tsx    |  2 +-
 .../site/panels/AgentPanel/toolCallDisplay.ts | 68 +++++++++++++------
 5 files changed, 81 insertions(+), 21 deletions(-)

diff --git a/src/admin/pages/site/agent/agentSliceTypes.ts b/src/admin/pages/site/agent/agentSliceTypes.ts
index 0593fec2d..b8c8bb1e2 100644
--- a/src/admin/pages/site/agent/agentSliceTypes.ts
+++ b/src/admin/pages/site/agent/agentSliceTypes.ts
@@ -49,6 +49,12 @@ export interface AgentSlice {
    * cleared. Each entry carries the layer's nodeId and display label.
    */
   agentDraftMentions: AgentDraftMention[]
+  /**
+   * Accumulated nodeId → human label registry across the conversation.
+   * Survives node deletion so scanned assistant mentions can still be
+   * rendered as clickable pills with friendly names after a node is gone.
+   */
+  agentMentionLabels: Record<string, string>
 
   openAgent(): void
   closeAgent(): void
diff --git a/src/admin/pages/site/agent/streamEvents.ts b/src/admin/pages/site/agent/streamEvents.ts
index 002ebd6e5..8b9a947fb 100644
--- a/src/admin/pages/site/agent/streamEvents.ts
+++ b/src/admin/pages/site/agent/streamEvents.ts
@@ -34,6 +34,7 @@ import type {
   ServerStreamEvent,
 } from './types'
 import { getErrorMessage } from '@core/utils/errorMessage'
+import { getMentionLabelForNode } from './mentionLabel'
 
 // ---------------------------------------------------------------------------
 // Stream-event schema
@@ -182,6 +183,20 @@ export async function processStreamEvent(
           if (inputAsRecord) existing.toolCall.params = inputAsRecord
           return
         }
+        // Resolve a friendly display label now, while the node still exists.
+        const nodeId =
+          typeof inputAsRecord?.nodeId === 'string'
+            ? (inputAsRecord.nodeId as string)
+            : undefined
+        let displayLabel: string | undefined
+        if (nodeId) {
+          try {
+            displayLabel = getMentionLabelForNode(nodeId).label
+          } catch {
+            /* ignore */
+          }
+        }
+
         msg.blocks.push({
           kind: 'toolCall',
           toolCall: {
@@ -191,8 +206,13 @@ export async function processStreamEvent(
             params: inputAsRecord ?? {},
             result: null,
             status: 'pending',
+            displayLabel,
           },
         })
+        // Register label so AI response scanning can resolve it after deletion
+        if (nodeId && displayLabel) {
+          state.agentMentionLabels[nodeId] = displayLabel
+        }
       })
       break
     }
diff --git a/src/admin/pages/site/agent/types.ts b/src/admin/pages/site/agent/types.ts
index 32af1717b..463261443 100644
--- a/src/admin/pages/site/agent/types.ts
+++ b/src/admin/pages/site/agent/types.ts
@@ -159,6 +159,12 @@ export interface AgentToolCall {
    * agent looked at; never persisted — it rehydrates empty after a reload.
    */
   screenshotDataUrl?: string
+  /**
+   * Human-readable label resolved at creation time (e.g. ".icon").
+   * Cached so tool-call rows still show a friendly name after the node
+   * has been deleted. Populated for node-related tools only.
+   */
+  displayLabel?: string
 }
 
 /**
diff --git a/src/admin/pages/site/panels/AgentPanel/ToolCallRow.tsx b/src/admin/pages/site/panels/AgentPanel/ToolCallRow.tsx
index e4b64528e..82a2a4f74 100644
--- a/src/admin/pages/site/panels/AgentPanel/ToolCallRow.tsx
+++ b/src/admin/pages/site/panels/AgentPanel/ToolCallRow.tsx
@@ -37,7 +37,7 @@ export function ToolCallRow({ toolCall }: { toolCall: AgentToolCall }) {
   const isSuccess = toolCall.status === 'success'
   const isError = toolCall.status === 'error'
 
-  const display = getToolCallDisplay(toolCall.actionType, toolCall.params)
+  const display = getToolCallDisplay(toolCall.actionType, toolCall.params, toolCall.displayLabel)
   const swatches = extractColorSwatches(toolCall.actionType, toolCall.params)
   const accessibleStatus = isPending ? 'Running' : isSuccess ? 'Completed' : 'Failed'
   const statusLabel = `${accessibleStatus} ${display.title}${display.detail ? ` — ${display.detail}` : ''}`
diff --git a/src/admin/pages/site/panels/AgentPanel/toolCallDisplay.ts b/src/admin/pages/site/panels/AgentPanel/toolCallDisplay.ts
index 7e140cfb5..d569f05c1 100644
--- a/src/admin/pages/site/panels/AgentPanel/toolCallDisplay.ts
+++ b/src/admin/pages/site/panels/AgentPanel/toolCallDisplay.ts
@@ -1,3 +1,5 @@
+import { getMentionLabelForNode } from '@site/agent/mentionLabel'
+
 export type ToolCallIcon =
   | 'add'
   | 'class'
@@ -39,7 +41,11 @@ export interface ToolCallDisplay {
  * and the current provider names (`site_set_color_tokens`, `site_insert_html`,
  * `content_create_document`) resolve to the same canonical key.
  */
-export function getToolCallDisplay(actionType: string, params: unknown): ToolCallDisplay {
+export function getToolCallDisplay(
+  actionType: string,
+  params: unknown,
+  displayLabel?: string,
+): ToolCallDisplay {
   const toolName = normalizeToolName(actionType)
   const p = asRecord(params)
 
@@ -60,30 +66,30 @@ export function getToolCallDisplay(actionType: string, params: unknown): ToolCal
     case 'insert_html':
       return display('Inserting HTML', targetDetail('inside', p.parentId), 'code', 'write')
     case 'get_node_html':
-      return display('Reading node HTML', nodeDetail(p.nodeId), 'node', 'read')
+      return display('Reading node HTML', nodeDetail(p.nodeId, displayLabel), 'node', 'read')
     case 'read_document':
       return display('Reading document', documentDetail(p.document), 'document', 'read')
     case 'open_document':
       return display('Opening document', documentDetail(p.document), 'open', 'read')
     case 'replace_node_html':
-      return display('Replacing node HTML', nodeDetail(p.nodeId), 'code', 'write')
+      return display('Replacing node HTML', nodeDetail(p.nodeId, displayLabel), 'code', 'write')
     case 'delete_node':
-      return display('Deleting node', nodeDetail(p.nodeId), 'delete', 'danger')
+      return display('Deleting node', nodeDetail(p.nodeId, displayLabel), 'delete', 'danger')
     case 'update_node_props':
-      return display('Updating node props', nodeBreakpointDetail(p.nodeId, p.breakpointId), 'edit', 'write')
+      return display('Updating node props', nodeBreakpointDetail(p.nodeId, p.breakpointId, displayLabel), 'edit', 'write')
     case 'move_node':
       return display('Moving node', targetDetail('to', p.newParentId), 'move', 'write')
     case 'rename_node':
       return display('Renaming node', optionalString(p.label), 'edit', 'write')
     case 'duplicate_node':
-      return display('Duplicating node', duplicateNodeDetail(p.nodeId, p.count), 'copy', 'write')
+      return display('Duplicating node', duplicateNodeDetail(p.nodeId, p.count, displayLabel), 'copy', 'write')
 
     case 'apply_css':
       return display('Updating CSS', summarizeCss(optionalString(p.css)), 'style', 'style')
     case 'assign_class':
-      return display('Assigning class', classDetail(p.classId, p.nodeId), 'class', 'style')
+      return display('Assigning class', classDetail(p.classId, p.nodeId, displayLabel), 'class', 'style')
     case 'remove_class':
-      return display('Removing class', classDetail(p.classId, p.nodeId), 'class', 'danger')
+      return display('Removing class', classDetail(p.classId, p.nodeId, displayLabel), 'class', 'danger')
 
     case 'list_code_assets':
       return display('Listing code assets', titleCase(optionalString(p.type)), 'code', 'read')
@@ -118,7 +124,7 @@ export function getToolCallDisplay(actionType: string, params: unknown): ToolCal
     case 'set_spacing_scale':
       return display('Updating spacing scale', scaleDetail(p.groupId, p.namingConvention), 'tokens', 'style')
     case 'render_snapshot':
-      return display('Capturing preview', previewDetail(p), 'preview', 'read')
+      return display('Capturing preview', previewDetail(p, displayLabel), 'preview', 'read')
 
     case 'list_collections':
       return display('Listing collections', '', 'collection', 'read')
@@ -208,9 +214,16 @@ function shortId(value: unknown): string {
   return text.length > 12 ? `${text.slice(0, 12)}...` : text
 }
 
-function nodeDetail(nodeId: unknown): string {
-  const id = shortId(nodeId)
-  return id ? `node ${id}` : ''
+function nodeDetail(nodeId: unknown, cachedLabel?: string): string {
+  if (cachedLabel) return cachedLabel
+  const id = optionalString(nodeId)
+  if (!id) return ''
+  try {
+    const { label } = getMentionLabelForNode(id)
+    return label
+  } catch {
+    return shortId(nodeId)
+  }
 }
 
 function pageDetail(pageId: unknown): string {
@@ -223,23 +236,35 @@ function targetDetail(prefix: string, idValue: unknown): string {
   return id ? `${prefix} ${id}` : ''
 }
 
-function nodeBreakpointDetail(nodeId: unknown, breakpointId: unknown): string {
-  const node = nodeDetail(nodeId)
+function nodeBreakpointDetail(
+  nodeId: unknown,
+  breakpointId: unknown,
+  cachedLabel?: string,
+): string {
+  const node = nodeDetail(nodeId, cachedLabel)
   const breakpoint = optionalString(breakpointId)
   if (!node) return breakpoint
   return breakpoint ? `${node} at ${breakpoint}` : node
 }
 
-function duplicateNodeDetail(nodeId: unknown, count: unknown): string {
-  const node = nodeDetail(nodeId)
+function duplicateNodeDetail(
+  nodeId: unknown,
+  count: unknown,
+  cachedLabel?: string,
+): string {
+  const node = nodeDetail(nodeId, cachedLabel)
   const copies = typeof count === 'number' && count > 1 ? `${count} copies` : ''
   if (!node) return copies
   return copies ? `${node}, ${copies}` : node
 }
 
-function classDetail(classId: unknown, nodeId: unknown): string {
+function classDetail(
+  classId: unknown,
+  nodeId: unknown,
+  cachedLabel?: string,
+): string {
   const className = optionalString(classId)
-  const node = nodeDetail(nodeId)
+  const node = nodeDetail(nodeId, cachedLabel)
   if (!className) return node
   return node ? `${className} on ${node}` : className
 }
@@ -307,8 +332,11 @@ function scaleDetail(groupId: unknown, namingConvention: unknown): string {
   return optionalString(groupId) || optionalString(namingConvention)
 }
 
-function previewDetail(params: Record<string, unknown>): string {
-  const node = nodeDetail(params.nodeId)
+function previewDetail(
+  params: Record<string, unknown>,
+  cachedLabel?: string,
+): string {
+  const node = nodeDetail(params.nodeId, cachedLabel)
   const breakpoint = optionalString(params.breakpointId)
   if (!node) return breakpoint
   return breakpoint ? `${node} at ${breakpoint}` : node