From 546eebd73fcb423b29b572bfff571f22724be206 Mon Sep 17 00:00:00 2001
From: Ethanlita <lita@ethanlita.com>
Date: Fri, 26 Jun 2026 11:10:52 +0800
Subject: [PATCH 1/2] feat(editor): add Copilot in-editor code guides
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Instead of auto-applying patches or simply point to the editor area using a purple arrow, Copilot now guides the user to make the
edit themselves in the editor, so children practice writing code by hand.

A reply can render four guide elements(custom elements), each backed by an in-editor overlay:

- [NEW] code-drag-hint  — opens a drop target at a line and highlights the matching
                           API reference item, for inserting a new statement by drag
- [NEW] code-type-hint  — opens a pre-indented blank line with a "Type the code here"
                           chip and a green reference ghost, for typing a new statement
- [NEW] code-delete-hint — highlights a range in red, for deleting it
- [MODIFIED] code-change-hint     — shows the deletion (red) and addition (green) at once, for
                                     replacing existing code (inline or whole-line)

The CodeGuideController keeps a single active guide, navigates to it, and
auto-dismisses it once the suggested edit is done (whitespace-insensitive).
Completion for delete/change is region-local: an invisible Monaco decoration
tracks the target range so it stays correct even when the user edits elsewhere.
Shared logic lives in use-code-guide.ts (re-show on stream settle, reopen on
click, skip-if-already-done, blank-line scaffolding) so all elements behave
consistently.

Changes to be committed:
	new file:   node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json
	modified:   spx-gui/src/components/copilot/CopilotRound.vue
	modified:   spx-gui/src/components/copilot/context.ts
	modified:   spx-gui/src/components/copilot/copilot.ts
	modified:   spx-gui/src/components/editor/copilot/CodeChange.vue
	new file:   spx-gui/src/components/editor/copilot/CodeDeleteHint.vue
	new file:   spx-gui/src/components/editor/copilot/CodeDragHint.vue
	new file:   spx-gui/src/components/editor/copilot/CodeTypeHint.vue
	modified:   spx-gui/src/components/editor/copilot/index.ts
	new file:   spx-gui/src/components/editor/copilot/use-code-guide.ts
	modified:   spx-gui/src/components/xgo-code-editor/index.ts
	modified:   spx-gui/src/components/xgo-code-editor/ui/CodeEditorUI.vue
	modified:   spx-gui/src/components/xgo-code-editor/ui/api-reference/APIReferenceItem.vue
	modified:   spx-gui/src/components/xgo-code-editor/ui/api-reference/index.ts
	modified:   spx-gui/src/components/xgo-code-editor/ui/code-editor-ui.ts
	new file:   spx-gui/src/components/xgo-code-editor/ui/code-guide/CodeGuideUI.vue
	new file:   spx-gui/src/components/xgo-code-editor/ui/code-guide/index.test.ts
	new file:   spx-gui/src/components/xgo-code-editor/ui/code-guide/index.ts
	modified:   spx-gui/src/components/xgo-code-editor/ui/common.ts
---
 .../results.json                              |   1 +
 .../src/components/copilot/CopilotRound.vue   |   4 +
 spx-gui/src/components/copilot/context.ts     |  21 +-
 spx-gui/src/components/copilot/copilot.ts     |  11 +
 .../components/editor/copilot/CodeChange.vue  | 315 ++++++++++---
 .../editor/copilot/CodeDeleteHint.vue         | 111 +++++
 .../editor/copilot/CodeDragHint.vue           | 110 +++++
 .../editor/copilot/CodeTypeHint.vue           | 111 +++++
 .../src/components/editor/copilot/index.ts    |  42 +-
 .../editor/copilot/use-code-guide.ts          | 207 +++++++++
 .../src/components/xgo-code-editor/index.ts   |   2 +
 .../xgo-code-editor/ui/CodeEditorUI.vue       |   8 +
 .../ui/api-reference/APIReferenceItem.vue     |  29 +-
 .../xgo-code-editor/ui/api-reference/index.ts |  47 +-
 .../xgo-code-editor/ui/code-editor-ui.ts      |  26 ++
 .../ui/code-guide/CodeGuideUI.vue             | 428 ++++++++++++++++++
 .../ui/code-guide/index.test.ts               | 426 +++++++++++++++++
 .../xgo-code-editor/ui/code-guide/index.ts    | 291 ++++++++++++
 .../components/xgo-code-editor/ui/common.ts   |  45 ++
 19 files changed, 2159 insertions(+), 76 deletions(-)
 create mode 100644 node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json
 create mode 100644 spx-gui/src/components/editor/copilot/CodeDeleteHint.vue
 create mode 100644 spx-gui/src/components/editor/copilot/CodeDragHint.vue
 create mode 100644 spx-gui/src/components/editor/copilot/CodeTypeHint.vue
 create mode 100644 spx-gui/src/components/editor/copilot/use-code-guide.ts
 create mode 100644 spx-gui/src/components/xgo-code-editor/ui/code-guide/CodeGuideUI.vue
 create mode 100644 spx-gui/src/components/xgo-code-editor/ui/code-guide/index.test.ts
 create mode 100644 spx-gui/src/components/xgo-code-editor/ui/code-guide/index.ts

diff --git a/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json b/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json
new file mode 100644
index 0000000000..21c4bf8989
--- /dev/null
+++ b/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json
@@ -0,0 +1 @@
+{"version":"4.1.9","results":[[":spx-gui/src/components/xgo-code-editor/ui/code-guide/index.test.ts",{"duration":0,"failed":true}]]}
\ No newline at end of file
diff --git a/spx-gui/src/components/copilot/CopilotRound.vue b/spx-gui/src/components/copilot/CopilotRound.vue
index 58133e2f19..38bcc0cd17 100644
--- a/spx-gui/src/components/copilot/CopilotRound.vue
+++ b/spx-gui/src/components/copilot/CopilotRound.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import { RoundState, type Round } from './copilot'
+import { provideCopilotRound } from './context'
 import MarkdownView from './MarkdownView.vue'
 import BaseFailed from './feedback/BaseFailed.vue'
 import BaseCancelled from './feedback/BaseCancelled.vue'
@@ -13,6 +14,9 @@ const props = defineProps<{
   isLastRound: boolean
 }>()
 
+// Let markdown elements rendered in this round (e.g. code guides) know which round they belong to.
+provideCopilotRound({ round: props.round, isLastRound: () => props.isLastRound })
+
 const feedbackProps = computed(() => ({
   round: props.round,
   isLastRound: props.isLastRound
diff --git a/spx-gui/src/components/copilot/context.ts b/spx-gui/src/components/copilot/context.ts
index 525f325ed7..c1010c7d20 100644
--- a/spx-gui/src/components/copilot/context.ts
+++ b/spx-gui/src/components/copilot/context.ts
@@ -1,5 +1,5 @@
 import { inject, provide, type InjectionKey } from 'vue'
-import type { Copilot } from './copilot'
+import type { Copilot, Round } from './copilot'
 
 const copilotInjectionKey: InjectionKey<Copilot> = Symbol('copilot')
 
@@ -12,3 +12,22 @@ export function useCopilot(): Copilot {
 export function provideCopilot(copilot: Copilot) {
   return provide(copilotInjectionKey, copilot)
 }
+
+/** Context describing the copilot round a markdown element is rendered within. */
+export interface CopilotRoundContext {
+  /** The round this content belongs to. */
+  round: Round
+  /** Whether this is the latest round in the session. */
+  isLastRound: () => boolean
+}
+
+const copilotRoundInjectionKey: InjectionKey<CopilotRoundContext> = Symbol('copilot-round')
+
+/** Read the round a markdown element belongs to, or `null` when not rendered inside a copilot round. */
+export function useCopilotRound(): CopilotRoundContext | null {
+  return inject(copilotRoundInjectionKey, null)
+}
+
+export function provideCopilotRound(ctx: CopilotRoundContext) {
+  return provide(copilotRoundInjectionKey, ctx)
+}
diff --git a/spx-gui/src/components/copilot/copilot.ts b/spx-gui/src/components/copilot/copilot.ts
index 4e0adb434a..e256ce5653 100644
--- a/spx-gui/src/components/copilot/copilot.ts
+++ b/spx-gui/src/components/copilot/copilot.ts
@@ -176,6 +176,16 @@ export class Round {
   get state() {
     return this.stateRef.value
   }
+
+  /**
+   * Whether this round was produced live in the current session (vs. loaded from history). Set when the
+   * round is started; rounds restored via `load` stay `false`. Used by features (e.g. in-editor code
+   * guides) to decide whether to auto-drive the editor — so a restored suggestion doesn't re-pop guides.
+   */
+  private liveRef = ref(false)
+  get isLive() {
+    return this.liveRef.value
+  }
   private setState(state: RoundState) {
     this.stateRef.value = state
     this.updatedAt = dayjs().valueOf()
@@ -355,6 +365,7 @@ export class Round {
     this.errorRef.value = null
     this.apiExceptionCode = null
     this.apiExceptionMeta = null
+    this.liveRef.value = true
     this.setState(RoundState.Loading)
     this.ctrl = new AbortController()
     this.generateCopilotMessage()
diff --git a/spx-gui/src/components/editor/copilot/CodeChange.vue b/spx-gui/src/components/editor/copilot/CodeChange.vue
index fb382f1db6..d79701e680 100644
--- a/spx-gui/src/components/editor/copilot/CodeChange.vue
+++ b/spx-gui/src/components/editor/copilot/CodeChange.vue
@@ -2,122 +2,303 @@
 import { z } from 'zod'
 import { codeFilePathSchema } from '@/components/copilot/common'
 
-export const tagName = 'code-change'
+export const tagName = 'code-change-hint'
 
 export const isRaw = true
 
 export const description = 'Display a modification based on the existing code.'
 
-export const detailedDescription = `Display a modification based on the existing code. For example,
+export const detailedDescription = `Display a modification based on the existing code and guide the user to make it \
+themselves in the editor (there is no "Apply" button). The removed text is highlighted in red and the new code is shown \
+as a green addition at the same time, so the user can see exactly what to change. In the editor the highlight is \
+automatically narrowed to the part that actually differs, so unchanged text around the edit is not marked. The guide \
+disappears once the user has made the change.
 
-<code-change file="NiuXiaoQi.spx" line="10" remove-line-count="2">
+To change something on a single line, use the \`old\` attribute with the exact existing text that contains the change:
+
+<code-change-hint file="NiuXiaoQi.spx" line="10" old="step 5">step 10</code-change-hint>
+
+(only \`5\` → \`10\` will be highlighted in the editor). To replace whole lines, use \`remove-line-count\`:
+
+<code-change-hint file="NiuXiaoQi.spx" line="10" remove-line-count="2">
 onClick => {
 	say "Hello!"
 }
-</code-change>
+</code-change-hint>
 
-will display a code change that removes line 10 & 11, then adds the new code content. The user can then apply the change by clicking the "Apply" button.`
+(replaces line 10 & 11 with the new code). Omit both \`old\` and \`remove-line-count\` for a pure insertion \
+(only a green addition to type). Leave the content empty for a pure deletion (only a red highlight to remove).
+
+IMPORTANT: when you want to MODIFY existing code (not add a brand-new line), you must express it as a change of the \
+existing code — set \`old\` to the existing text (or \`remove-line-count\` to the lines) being modified, and put the new \
+version in the content. Do NOT describe a modification by only supplying the new line as if inserting it; that would \
+look like adding a duplicate line instead of changing the existing one. For example, to change \`step 150\` into \
+\`step 180\`, write <code-change-hint file="..." line="3" old="step 150">step 180</code-change-hint>, not \
+<code-change-hint file="..." line="3">step 180</code-change-hint>.`
 
 export const attributes = z.object({
   file: codeFilePathSchema,
-  line: z.string().describe('Position (line number) to do change, 1-based'),
-  'remove-line-count': z.string().optional().describe('Line count to remove. No line will be removed if not provided')
+  line: z.string().describe('Line number of the change, 1-based'),
+  old: z
+    .string()
+    .optional()
+    .describe('Exact existing text on the line that contains the change (for a single-line edit)'),
+  'remove-line-count': z.string().optional().describe('Number of whole lines to replace/remove, starting at line')
 })
 </script>
 
 <script setup lang="ts">
 import { computed } from 'vue'
 import { useSlotText } from '@/utils/vnode'
-import { useMessageHandle, ActionException } from '@/utils/exception'
 import CodeView from '@/components/common/CodeView.vue'
-import { useEditorCtxRef } from '@/components/editor/EditorContextProvider.vue'
-import { CodeLink, getTextDocumentId, type Range, useCodeEditorRef } from '@/components/editor/spx-code-editor'
+import {
+  CodeLink,
+  diffEdges,
+  getTextDocumentId,
+  isContiguousDiff,
+  leadingIdentifier,
+  trimCommonLines,
+  useCodeEditorRef,
+  type CodeGuide,
+  type Range
+} from '@/components/editor/spx-code-editor'
 import BlockWrapper from '@/components/copilot/markdown-elements/common/BlockWrapper.vue'
-import BlockFooter from '@/components/copilot/markdown-elements/common/BlockFooter.vue'
-import BlockActionBtn from '@/components/copilot/markdown-elements/common/BlockActionBtn.vue'
+import { useEditorCtxRef } from '@/components/editor/EditorContextProvider.vue'
+import { useCodeGuide, useInsertionBlankLine } from './use-code-guide'
 
 const props = defineProps<{
   /** Code file path, e.g., `NiuXiaoQi.spx` */
   file: string
-  /** Position (line number) to do change */
+  /** Line number of the change */
   line: string
-  /** Line count to remove. No line will be removed if not provided */
+  /** Exact existing text on the line that contains the change (single-line edit) */
+  old?: string
+  /** Number of whole lines to replace/remove */
   removeLineCount?: string
 }>()
 
-const editorCtxRef = useEditorCtxRef()
 const codeEditorRef = useCodeEditorRef()
-
+const editorCtxRef = useEditorCtxRef()
 const childrenText = useSlotText()
-const codeToAdd = computed(() => {
-  // strip leading line break to keep consistent with markdown code block
-  let code = childrenText.value.replace(/^\n/, '')
-  // add trailing line break, as the code is always inserted as lines
-  if (!code.endsWith('\n')) code = code + '\n'
-  return code
+
+const textDocumentId = computed(() => getTextDocumentId(props.file))
+const startLine = computed(() => parseInt(props.line, 10))
+const removeLineCount = computed(() => (props.removeLineCount == null ? 0 : parseInt(props.removeLineCount, 10)))
+
+// New code (replacement / insertion). Leading line break stripped to match the markdown code block.
+const fullCode = computed(() => childrenText.value.replace(/^\n/, ''))
+const hasAddition = computed(() => fullCode.value.trim() !== '')
+
+const valid = computed(() => {
+  const codeEditor = codeEditorRef.value
+  if (codeEditor == null) return false
+  if (codeEditor.getTextDocument(textDocumentId.value) == null) return false
+  return !isNaN(startLine.value) && !isNaN(removeLineCount.value)
 })
 
-const target = computed(() => {
+// The full range being replaced and its original text (used for the complete diff shown in chat).
+// Returns null for a pure insertion (handled by the `type` guide).
+const changeBase = computed<{ range: Range; oldText: string } | null>(() => {
   const codeEditor = codeEditorRef.value
-  if (codeEditor == null) return null
-  const textDocument = codeEditor.getTextDocument(getTextDocumentId(props.file))
+  if (codeEditor == null || isNaN(startLine.value) || isNaN(removeLineCount.value)) return null
+  const textDocument = codeEditor.getTextDocument(textDocumentId.value)
   if (textDocument == null) return null
-  const startLine = parseInt(props.line, 10)
-  const removeLineCount = props.removeLineCount == null ? 0 : parseInt(props.removeLineCount, 10)
-  if (isNaN(startLine) || isNaN(removeLineCount)) return null
-  const endLine = startLine + removeLineCount
-  const range: Range = {
-    start: { line: startLine, column: 1 },
-    end: { line: endLine, column: 1 }
+  // Guard against an out-of-range target line, so `getLineContent` below never throws.
+  const lineCount = textDocument.getValue().split(/\r?\n/).length
+  if (startLine.value < 1 || startLine.value > lineCount) return null
+
+  let range: Range | null = null
+  if (props.old != null && props.old !== '') {
+    const lineContent = textDocument.getLineContent(startLine.value)
+    const index = lineContent.indexOf(props.old)
+    if (index >= 0) {
+      range = {
+        start: { line: startLine.value, column: index + 1 },
+        end: { line: startLine.value, column: index + 1 + props.old.length }
+      }
+    }
+  }
+  if (range == null && removeLineCount.value === 1) {
+    const lineContent = textDocument.getLineContent(startLine.value)
+    range = {
+      start: { line: startLine.value, column: 1 },
+      end: { line: startLine.value, column: lineContent.length + 1 }
+    }
+  }
+  if (range == null && removeLineCount.value > 1) {
+    range = {
+      start: { line: startLine.value, column: 1 },
+      end: { line: startLine.value + removeLineCount.value, column: 1 }
+    }
+  }
+  // Heuristic: when neither `old` nor `remove-line-count` is given, but the target line already holds a
+  // statement with the same function name as the new code (e.g. `step 150` → `step 180`), treat it as
+  // replacing that line so it becomes a precise inline edit rather than inserting a whole new line.
+  if (range == null && removeLineCount.value === 0) {
+    const newText = fullCode.value.replace(/\n+$/, '')
+    const lineContent = textDocument.getLineContent(startLine.value)
+    const fnName = leadingIdentifier(newText)
+    if (fnName !== '' && !newText.includes('\n') && leadingIdentifier(lineContent) === fnName) {
+      range = {
+        start: { line: startLine.value, column: 1 },
+        end: { line: startLine.value, column: lineContent.length + 1 }
+      }
+    }
+  }
+  if (range == null) return null
+  return { range, oldText: textDocument.getValueInRange(range) }
+})
+
+type ChangeTarget = { range: Range; code: string; lineInsertion: boolean }
+
+/**
+ * Narrow a single-line range by trimming the common prefix/suffix characters (incl. leading whitespace).
+ * This is always an in-place edit (`lineInsertion: false`), even when it collapses to an empty range —
+ * e.g. prepending text at the start of a line is an inline edit, NOT a new line.
+ */
+function charTrim(range: Range, oldText: string, newText: string): ChangeTarget {
+  const { prefix, suffix } = diffEdges(oldText, newText)
+  return {
+    range: {
+      start: { line: range.start.line, column: range.start.column + prefix },
+      end: { line: range.end.line, column: range.end.column - suffix }
+    },
+    code: newText.slice(prefix, newText.length - suffix),
+    lineInsertion: false
+  }
+}
+
+/** A whole-line replacement: replace all of `line` with `code`, rendered as a whole-line (not inline) change. */
+function wholeLineTarget(line: number, code: string): ChangeTarget {
+  return { range: { start: { line, column: 1 }, end: { line: line + 1, column: 1 } }, code, lineInsertion: false }
+}
+
+/** Whether `range` spans a whole line's content (so it can be treated as a whole-line replacement). */
+function isWholeLineRange(range: Range): boolean {
+  const textDocument = codeEditorRef.value?.getTextDocument(textDocumentId.value)
+  if (textDocument == null || range.start.line !== range.end.line) return false
+  return range.start.column === 1 && range.end.column === textDocument.getLineContent(range.start.line).length + 1
+}
+
+// The narrowed range + code shown in the editor:
+// - single-line: trim common prefix/suffix characters (incl. leading whitespace);
+// - multi-line: drop identical leading/trailing lines (incl. shared indentation lines), then char-trim if a single line remains.
+// `lineInsertion` marks the case where the change collapsed to inserting whole new line(s) (from line-level
+// trimming), which is rendered as a new line — distinct from an inline edit that merely has an empty range.
+const changeTarget = computed<ChangeTarget | null>(() => {
+  const base = changeBase.value
+  if (base == null) return null
+  const newText = fullCode.value.replace(/\n+$/, '')
+  const oldText = base.oldText.replace(/\n+$/, '')
+
+  if (base.range.start.line === base.range.end.line && !oldText.includes('\n') && !newText.includes('\n')) {
+    // A whole-line replacement whose old & new only share scattered characters would render as a noisy,
+    // fragmented inline diff — show it as a clean whole-line replacement instead.
+    if (isWholeLineRange(base.range) && !isContiguousDiff(oldText, newText)) {
+      return wholeLineTarget(base.range.start.line, newText)
+    }
+    return charTrim(base.range, oldText, newText)
+  }
+
+  const oldLines = oldText.split('\n')
+  const newLines = newText.split('\n')
+  const { prefixLines, suffixLines } = trimCommonLines(oldText, newText)
+  const oldMid = oldLines.slice(prefixLines, oldLines.length - suffixLines)
+  const newMid = newLines.slice(prefixLines, newLines.length - suffixLines)
+  const startLine = base.range.start.line + prefixLines
+
+  // All removed lines were common → inserting whole new line(s) before `startLine`.
+  if (oldMid.length === 0) {
+    return {
+      range: { start: { line: startLine, column: 1 }, end: { line: startLine, column: 1 } },
+      code: newMid.join('\n'),
+      lineInsertion: true
+    }
+  }
+  if (oldMid.length === 1 && newMid.length === 1 && isContiguousDiff(oldMid[0], newMid[0])) {
+    const lineRange = { start: { line: startLine, column: 1 }, end: { line: startLine, column: oldMid[0].length + 1 } }
+    return charTrim(lineRange, oldMid[0], newMid[0])
+  }
+  return {
+    range: { start: { line: startLine, column: 1 }, end: { line: startLine + oldMid.length, column: 1 } },
+    code: newMid.join('\n'),
+    lineInsertion: false
   }
-  return { textDocument, range }
 })
 
-// We don't want `codeToDelete` to change when text-document edited.
-// So we are not using `computed` here.
-const codeToDelete = (() => {
-  if (target.value == null) return ''
-  const { textDocument, range } = target.value
-  return textDocument.getValueInRange(range)
-})()
-
-const handleApply = useMessageHandle(
-  async () => {
-    if (target.value == null) throw new Error('Target is not available')
-    const editorCtx = editorCtxRef.value
-    if (editorCtx == null) throw new Error('Editor context is not available')
-    const { textDocument, range } = target.value
-    if (textDocument.getValueInRange(range) !== codeToDelete)
-      throw new ActionException(null, {
-        en: 'The original code has changed',
-        zh: '原代码已被更改'
-      })
-    await editorCtx.state.history.doAction({ name: { en: 'Apply code change', zh: '应用代码更改' } }, () =>
-      textDocument.pushEdits([{ range, newText: codeToAdd.value }])
-    )
+// The line a new statement is inserted at (after trimming), or the raw target line for a pure insertion.
+const insertionLine = computed(() => {
+  const target = changeTarget.value
+  return target != null ? target.range.start.line : startLine.value
+})
+
+// Whether this guide inserts a brand-new line (→ open a blank line); otherwise it edits existing code in place.
+const isInsertion = computed(() => {
+  if (!valid.value) return false
+  const target = changeTarget.value
+  return target == null ? hasAddition.value : target.lineInsertion
+})
+
+// Open a blank line to type into, only for an insertion.
+const blankLine = useInsertionBlankLine({
+  codeEditor: codeEditorRef,
+  editorCtx: editorCtxRef,
+  textDocumentId: () => textDocumentId.value,
+  line: () => insertionLine.value
+})
+
+const guide = computed<CodeGuide | null>(() => {
+  if (!valid.value) return null
+  const target = changeTarget.value
+  // Replacement / deletion / inline insertion (anything that isn't a whole new line) → `change` guide.
+  if (target != null && !target.lineInsertion) {
+    return { kind: 'change', textDocument: textDocumentId.value, range: target.range, code: target.code }
+  }
+  // New-line insertion → `type` guide (opens a blank line, chip on the new line, green reference below).
+  const code = target != null ? target.code : fullCode.value
+  if (code.trim() === '') return null
+  // Place the insertion point after the indentation that the opened line will receive.
+  const column = blankLine.indent.value.length + 1
+  return {
+    kind: 'type',
+    textDocument: textDocumentId.value,
+    range: { start: { line: insertionLine.value, column }, end: { line: insertionLine.value, column } },
+    code
+  }
+})
+
+const { activate } = useCodeGuide({
+  codeEditor: codeEditorRef,
+  guide: () => guide.value,
+  signature: () => {
+    const g = guide.value
+    if (g == null) return ''
+    const code = 'code' in g ? g.code : ''
+    return `${g.kind}:${JSON.stringify(g.range)}:${code}`
   },
-  { en: 'Failed to apply code change', zh: '应用代码更改失败' }
-).fn
+  onBeforeShow: () => {
+    if (isInsertion.value) blankLine.open()
+  },
+  onCleanup: () => blankLine.remove()
+})
 </script>
 
 <template>
   <BlockWrapper>
-    <template v-if="target != null">
+    <template v-if="valid">
       <div class="p-2">
-        <CodeLink :file="target.textDocument.id" :range="target.range" />
+        <CodeLink :file="textDocumentId" :position="{ line: startLine, column: 1 }" @click="activate">
+          {{ $t({ en: 'Make this change in the editor', zh: '在编辑器中完成这处修改' }) }}
+        </CodeLink>
       </div>
       <div class="min-w-0 overflow-x-auto pb-2 pl-2">
         <div class="min-w-fit">
-          <!-- TODO: Consider using [transformerNotationDiff](https://shiki.style/packages/transformers#transformernotationdiff) instead -->
-          <CodeView class="pr-2" mode="block" deletion>{{ codeToDelete }}</CodeView>
-          <CodeView class="pr-2" mode="block" addition>{{ codeToAdd }}</CodeView>
+          <CodeView v-if="changeBase != null && changeBase.oldText !== ''" class="pr-2" mode="block" deletion>{{
+            changeBase.oldText
+          }}</CodeView>
+          <CodeView v-if="hasAddition" class="pr-2" mode="block" addition>{{ fullCode }}</CodeView>
         </div>
       </div>
-      <BlockFooter>
-        <BlockActionBtn icon="apply" @click="handleApply">
-          {{ $t({ en: 'Apply', zh: '应用' }) }}
-        </BlockActionBtn>
-      </BlockFooter>
     </template>
     <div v-else class="p-2 text-center text-hint-2">
       <p>{{ $t({ en: 'Invalid code change', zh: '无效的代码变更' }) }}</p>
diff --git a/spx-gui/src/components/editor/copilot/CodeDeleteHint.vue b/spx-gui/src/components/editor/copilot/CodeDeleteHint.vue
new file mode 100644
index 0000000000..8f3682964c
--- /dev/null
+++ b/spx-gui/src/components/editor/copilot/CodeDeleteHint.vue
@@ -0,0 +1,111 @@
+<script lang="ts">
+import { z } from 'zod'
+import { codeFilePathSchema } from '@/components/copilot/common'
+
+export const tagName = 'code-delete-hint'
+
+export const isRaw = false
+
+export const description = 'Guide the user to delete a piece of existing code.'
+
+export const detailedDescription = `Guide the user to delete a piece of existing code by highlighting it in red in the editor. \
+Like the other hint elements, this does NOT modify the code itself — it only marks which lines the user should remove, \
+and the user deletes them. (To replace code, use <code-change-hint>, which shows the deletion and the new code together \
+and guides the user to make the edit themselves.) \
+To guide the user to change code, combine this with <code-type-hint>: mark the old code to delete here, then show the \
+new code to type. For example,
+
+<code-delete-hint file="NiuXiaoQi.spx" line="10" remove-line-count="2" />
+
+highlights line 10 & 11 of "NiuXiaoQi.spx" in red, indicating the user should delete them. \
+The hint disappears once the user has deleted the highlighted code.`
+
+export const attributes = z.object({
+  file: codeFilePathSchema,
+  line: z.string().describe('Position (line number) to delete from, 1-based'),
+  'remove-line-count': z.string().describe('Number of lines to delete')
+})
+</script>
+
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import CodeView from '@/components/common/CodeView.vue'
+import {
+  CodeLink,
+  getTextDocumentId,
+  useCodeEditorRef,
+  type CodeGuide,
+  type Range
+} from '@/components/editor/spx-code-editor'
+import BlockWrapper from '@/components/copilot/markdown-elements/common/BlockWrapper.vue'
+import { useCodeGuide } from './use-code-guide'
+
+const props = defineProps<{
+  /** Code file path, e.g., `NiuXiaoQi.spx` */
+  file: string
+  /** Position (line number) to delete from */
+  line: string
+  /** Number of lines to delete */
+  removeLineCount: string
+}>()
+
+const codeEditorRef = useCodeEditorRef()
+const textDocumentId = computed(() => getTextDocumentId(props.file))
+
+const range = computed<Range | null>(() => {
+  const startLine = parseInt(props.line, 10)
+  const removeLineCount = parseInt(props.removeLineCount, 10)
+  if (isNaN(startLine) || isNaN(removeLineCount) || removeLineCount <= 0) return null
+  return {
+    start: { line: startLine, column: 1 },
+    end: { line: startLine + removeLineCount, column: 1 }
+  }
+})
+
+const guide = computed<CodeGuide | null>(() => {
+  const codeEditor = codeEditorRef.value
+  if (codeEditor == null || range.value == null) return null
+  if (codeEditor.getTextDocument(textDocumentId.value) == null) return null
+  return { kind: 'delete', textDocument: textDocumentId.value, range: range.value }
+})
+
+// Snapshot the code to delete as soon as the document is available, then freeze it (stop watching) so the
+// red preview doesn't change as the user edits. Capturing during setup can be too early — the editor ref
+// may still be null at that point, which would leave the preview permanently blank.
+const codeToDelete = ref('')
+const stopCapture = watch(
+  () => codeEditorRef.value?.getTextDocument(textDocumentId.value),
+  (textDocument) => {
+    if (textDocument == null || range.value == null) return
+    codeToDelete.value = textDocument.getValueInRange(range.value)
+    stopCapture()
+  },
+  { immediate: true }
+)
+
+const { activate } = useCodeGuide({
+  codeEditor: codeEditorRef,
+  guide: () => guide.value,
+  signature: () => `delete:${JSON.stringify(range.value)}`
+})
+</script>
+
+<template>
+  <BlockWrapper>
+    <template v-if="guide != null">
+      <div class="p-2">
+        <CodeLink :file="textDocumentId" :range="guide.range" @click="activate">
+          {{ $t({ en: 'Delete the highlighted code', zh: '删除编辑器中标红的代码' }) }}
+        </CodeLink>
+      </div>
+      <div v-if="codeToDelete !== ''" class="min-w-0 overflow-x-auto pb-2 pl-2">
+        <div class="min-w-fit">
+          <CodeView class="pr-2" mode="block" deletion>{{ codeToDelete }}</CodeView>
+        </div>
+      </div>
+    </template>
+    <div v-else class="p-2 text-center text-hint-2">
+      <p>{{ $t({ en: 'Invalid code hint', zh: '无效的代码提示' }) }}</p>
+    </div>
+  </BlockWrapper>
+</template>
diff --git a/spx-gui/src/components/editor/copilot/CodeDragHint.vue b/spx-gui/src/components/editor/copilot/CodeDragHint.vue
new file mode 100644
index 0000000000..859aa37f32
--- /dev/null
+++ b/spx-gui/src/components/editor/copilot/CodeDragHint.vue
@@ -0,0 +1,110 @@
+<script lang="ts">
+import { z } from 'zod'
+import { codeFilePathSchema } from '@/components/copilot/common'
+
+export const tagName = 'code-drag-hint'
+
+export const isRaw = true
+
+export const description = 'Guide the user to drag an API reference item into a specific location in the editor.'
+
+export const detailedDescription = `Guide the user to drag a draggable API reference item (from the API reference panel) \
+into a specific location in the editor. It opens a gap at the target line and draws a translucent orange indicator \
+showing where to drop, and also highlights the matching item in the API reference panel automatically. This element \
+does NOT modify the code; the user performs the drag themselves.
+
+IMPORTANT: dragging an item from the API reference panel only INSERTS a new line — it CANNOT replace or overwrite \
+existing code. So use <code-drag-hint> only to ADD a brand-new statement. Never instruct the user to drag an item to \
+"replace" / "overwrite" existing code. To change or replace existing code, use <code-change-hint> instead (the user edits it \
+by hand). Prefer <code-drag-hint> over <code-type-hint> when adding a new statement that exists as a draggable item, \
+since dragging is the easiest way for the user to insert code. The slot content should be the expected code. For example,
+
+<code-drag-hint file="NiuXiaoQi.spx" line="10">
+say "Hello!"
+</code-drag-hint>
+
+opens a drop target at line 10 of "NiuXiaoQi.spx". The hint disappears once the user has dropped the block.`
+
+export const attributes = z.object({
+  file: codeFilePathSchema,
+  line: z.string().describe('Line number where the block should be dropped, 1-based')
+})
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useSlotText } from '@/utils/vnode'
+import CodeView from '@/components/common/CodeView.vue'
+import { CodeLink, getTextDocumentId, useCodeEditorRef, type CodeGuide } from '@/components/editor/spx-code-editor'
+import BlockWrapper from '@/components/copilot/markdown-elements/common/BlockWrapper.vue'
+import { useEditorCtxRef } from '@/components/editor/EditorContextProvider.vue'
+import { useCodeGuide, useInsertionBlankLine } from './use-code-guide'
+
+const props = defineProps<{
+  /** Code file path, e.g., `NiuXiaoQi.spx` */
+  file: string
+  /** Line number where the block should be dropped */
+  line: string
+}>()
+
+const codeEditorRef = useCodeEditorRef()
+const editorCtxRef = useEditorCtxRef()
+const childrenText = useSlotText()
+
+const code = computed(() => childrenText.value.replace(/^\n/, '').replace(/\n+$/, ''))
+
+const textDocumentId = computed(() => getTextDocumentId(props.file))
+
+const startLine = computed(() => parseInt(props.line, 10))
+
+// Open a pre-indented blank line at the target so the dropped block lands on a real line with the right
+// indentation — the same line the hint marks. The line is removed again if the user drops nothing into it.
+const blankLine = useInsertionBlankLine({
+  codeEditor: codeEditorRef,
+  editorCtx: editorCtxRef,
+  textDocumentId: () => textDocumentId.value,
+  line: () => startLine.value
+})
+
+const guide = computed<CodeGuide | null>(() => {
+  const codeEditor = codeEditorRef.value
+  if (codeEditor == null || isNaN(startLine.value)) return null
+  if (codeEditor.getTextDocument(textDocumentId.value) == null) return null
+  // Anchor after the indentation the opened line receives, matching where the dropped code will land.
+  const column = blankLine.indent.value.length + 1
+  return {
+    kind: 'drag',
+    textDocument: textDocumentId.value,
+    range: { start: { line: startLine.value, column }, end: { line: startLine.value, column } },
+    code: code.value
+  }
+})
+
+const { activate } = useCodeGuide({
+  codeEditor: codeEditorRef,
+  guide: () => guide.value,
+  signature: () => `drag:${startLine.value}:${code.value}`,
+  onBeforeShow: blankLine.open,
+  onCleanup: blankLine.remove
+})
+</script>
+
+<template>
+  <BlockWrapper>
+    <template v-if="guide != null">
+      <div class="p-2">
+        <CodeLink :file="textDocumentId" :position="{ line: startLine, column: 1 }" @click="activate">
+          {{ $t({ en: 'Drag the block to this location', zh: '把积木拖到这个位置' }) }}
+        </CodeLink>
+      </div>
+      <div v-if="code !== ''" class="min-w-0 overflow-x-auto pb-2 pl-2">
+        <div class="min-w-fit">
+          <CodeView class="pr-2" mode="block" addition>{{ code }}</CodeView>
+        </div>
+      </div>
+    </template>
+    <div v-else class="p-2 text-center text-hint-2">
+      <p>{{ $t({ en: 'Invalid code hint', zh: '无效的代码提示' }) }}</p>
+    </div>
+  </BlockWrapper>
+</template>
diff --git a/spx-gui/src/components/editor/copilot/CodeTypeHint.vue b/spx-gui/src/components/editor/copilot/CodeTypeHint.vue
new file mode 100644
index 0000000000..1e37352cbe
--- /dev/null
+++ b/spx-gui/src/components/editor/copilot/CodeTypeHint.vue
@@ -0,0 +1,111 @@
+<script lang="ts">
+import { z } from 'zod'
+import { codeFilePathSchema } from '@/components/copilot/common'
+
+export const tagName = 'code-type-hint'
+
+export const isRaw = true
+
+export const description = 'Guide the user to manually type a piece of code at a specific location.'
+
+export const detailedDescription = `Guide the user to manually type a piece of code at a specific location in the editor. \
+An empty line is opened at the target with a "Type the code here" chip, and the given code is shown as a green \
+reference below; the user types it themselves. This element does NOT write the code for the user — it only prepares an \
+empty line and shows what to type. (That empty line is a temporary scaffold: it is undoable and is removed \
+automatically if the user does not type anything into it.) Use this when teaching the user to write a brand-new line \
+of code by hand. For example,
+
+<code-type-hint file="NiuXiaoQi.spx" line="10">
+onClick => {
+	say "Hello!"
+}
+</code-type-hint>
+
+guides the user to type the code at line 10 of "NiuXiaoQi.spx". The hint disappears once the user has typed the code. \
+NOTE: to MODIFY existing code, use <code-change-hint> instead; this element is only for typing brand-new code.`
+
+export const attributes = z.object({
+  file: codeFilePathSchema,
+  line: z.string().describe('Line number where the user should type the code, 1-based')
+})
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useSlotText } from '@/utils/vnode'
+import CodeView from '@/components/common/CodeView.vue'
+import { CodeLink, getTextDocumentId, useCodeEditorRef, type CodeGuide } from '@/components/editor/spx-code-editor'
+import BlockWrapper from '@/components/copilot/markdown-elements/common/BlockWrapper.vue'
+import { useEditorCtxRef } from '@/components/editor/EditorContextProvider.vue'
+import { useCodeGuide, useInsertionBlankLine } from './use-code-guide'
+
+const props = defineProps<{
+  /** Code file path, e.g., `NiuXiaoQi.spx` */
+  file: string
+  /** Line number where the user should type the code */
+  line: string
+}>()
+
+const codeEditorRef = useCodeEditorRef()
+const editorCtxRef = useEditorCtxRef()
+const childrenText = useSlotText()
+
+const code = computed(() => {
+  // strip leading line break to keep consistent with markdown code block
+  let c = childrenText.value.replace(/^\n/, '')
+  if (!c.endsWith('\n')) c = c + '\n'
+  return c
+})
+
+const textDocumentId = computed(() => getTextDocumentId(props.file))
+const startLine = computed(() => parseInt(props.line, 10))
+
+const blankLine = useInsertionBlankLine({
+  codeEditor: codeEditorRef,
+  editorCtx: editorCtxRef,
+  textDocumentId: () => textDocumentId.value,
+  line: () => startLine.value
+})
+
+const guide = computed<CodeGuide | null>(() => {
+  const codeEditor = codeEditorRef.value
+  if (codeEditor == null || isNaN(startLine.value)) return null
+  if (codeEditor.getTextDocument(textDocumentId.value) == null) return null
+  // Place the insertion point after the indentation that the opened line will receive.
+  const column = blankLine.indent.value.length + 1
+  return {
+    kind: 'type',
+    textDocument: textDocumentId.value,
+    range: { start: { line: startLine.value, column }, end: { line: startLine.value, column } },
+    code: code.value
+  }
+})
+
+const { activate } = useCodeGuide({
+  codeEditor: codeEditorRef,
+  guide: () => guide.value,
+  signature: () => `type:${startLine.value}:${code.value}`,
+  onBeforeShow: blankLine.open,
+  onCleanup: blankLine.remove
+})
+</script>
+
+<template>
+  <BlockWrapper>
+    <template v-if="guide != null">
+      <div class="p-2">
+        <CodeLink :file="textDocumentId" :position="{ line: startLine, column: 1 }" @click="activate">
+          {{ $t({ en: 'Type this code in the editor', zh: '在编辑器中手动输入这段代码' }) }}
+        </CodeLink>
+      </div>
+      <div class="min-w-0 overflow-x-auto pb-2 pl-2">
+        <div class="min-w-fit">
+          <CodeView class="pr-2" mode="block" addition>{{ code }}</CodeView>
+        </div>
+      </div>
+    </template>
+    <div v-else class="p-2 text-center text-hint-2">
+      <p>{{ $t({ en: 'Invalid code hint', zh: '无效的代码提示' }) }}</p>
+    </div>
+  </BlockWrapper>
+</template>
diff --git a/spx-gui/src/components/editor/copilot/index.ts b/spx-gui/src/components/editor/copilot/index.ts
index 3960c2b43b..d8a0dc9180 100644
--- a/spx-gui/src/components/editor/copilot/index.ts
+++ b/spx-gui/src/components/editor/copilot/index.ts
@@ -19,7 +19,10 @@ import {
   type TextDocument
 } from '../spx-code-editor'
 import * as codeLink from './CodeLink'
-import * as codeChange from './CodeChange.vue'
+import * as codeChangeHint from './CodeChange.vue'
+import * as codeDragHint from './CodeDragHint.vue'
+import * as codeTypeHint from './CodeTypeHint.vue'
+import * as codeDeleteHint from './CodeDeleteHint.vue'
 import CodeBlock from './CodeBlock.vue'
 
 class Retriever {
@@ -297,11 +300,38 @@ export function useSpxEditorCopilot(): void {
   )
   d.addDisposer(
     copilot.registerCustomElement({
-      tagName: codeChange.tagName,
-      description: codeChange.detailedDescription,
-      attributes: codeChange.attributes,
-      isRaw: codeChange.isRaw,
-      component: codeChange.default
+      tagName: codeChangeHint.tagName,
+      description: codeChangeHint.detailedDescription,
+      attributes: codeChangeHint.attributes,
+      isRaw: codeChangeHint.isRaw,
+      component: codeChangeHint.default
+    })
+  )
+  d.addDisposer(
+    copilot.registerCustomElement({
+      tagName: codeDragHint.tagName,
+      description: codeDragHint.detailedDescription,
+      attributes: codeDragHint.attributes,
+      isRaw: codeDragHint.isRaw,
+      component: codeDragHint.default
+    })
+  )
+  d.addDisposer(
+    copilot.registerCustomElement({
+      tagName: codeTypeHint.tagName,
+      description: codeTypeHint.detailedDescription,
+      attributes: codeTypeHint.attributes,
+      isRaw: codeTypeHint.isRaw,
+      component: codeTypeHint.default
+    })
+  )
+  d.addDisposer(
+    copilot.registerCustomElement({
+      tagName: codeDeleteHint.tagName,
+      description: codeDeleteHint.detailedDescription,
+      attributes: codeDeleteHint.attributes,
+      isRaw: codeDeleteHint.isRaw,
+      component: codeDeleteHint.default
     })
   )
   d.addDisposer(copilot.registerContextProvider(new ProjectContextProvider(editorCtx)))
diff --git a/spx-gui/src/components/editor/copilot/use-code-guide.ts b/spx-gui/src/components/editor/copilot/use-code-guide.ts
new file mode 100644
index 0000000000..24bf7e7d60
--- /dev/null
+++ b/spx-gui/src/components/editor/copilot/use-code-guide.ts
@@ -0,0 +1,207 @@
+/**
+ * @desc Shared logic for the copilot code-guide elements (code-change-hint / code-type-hint /
+ * code-delete-hint / code-drag-hint), so they all behave consistently:
+ * - re-show the guide as the streamed message settles (deduped by a signature),
+ * - reopen it on demand (the returned `activate`, used as the chat link's click handler),
+ * - only auto-drive the editor for a live suggestion (not restored history), and clean up on unmount;
+ * - optionally open a real blank line to type a new statement into.
+ *
+ * Note: "is the suggested edit already done?" is intentionally NOT decided here. The editor owns guide
+ * completion (the controller's completion detection is baseline-relative, so showing a guide is harmless
+ * even when similar code already exists). What this composable adds is the feature-level decision of
+ * *when* to auto-drive the editor — only for the current, live round — so a restored chat doesn't re-pop
+ * guides for edits the user already made.
+ */
+
+import { computed, onUnmounted, watch, type ComputedRef } from 'vue'
+import { tabSize, insertSpaces } from '@/utils/xgo/highlighter'
+import { useCopilotRound } from '@/components/copilot/context'
+import type { CodeEditor, CodeGuide, TextDocument, TextDocumentIdentifier } from '@/components/editor/spx-code-editor'
+import type { EditorCtx } from '@/components/editor/EditorContextProvider.vue'
+
+export interface UseCodeGuideOptions {
+  codeEditor: ComputedRef<CodeEditor | null>
+  /** The guide to show, or null when not applicable. */
+  guide: () => CodeGuide | null
+  /** Signature of the guide; when it changes the guide is re-shown (keeps it correct as a message streams in). */
+  signature: () => string
+  /** Run right before showing the guide (e.g. open a blank line). Should be idempotent. */
+  onBeforeShow?: () => void
+  /** Run on cleanup (e.g. remove an opened blank line). */
+  onCleanup?: () => void
+}
+
+export function useCodeGuide(options: UseCodeGuideOptions): { activate: () => void } {
+  let currentId: string | null = null
+  let shownKey = ''
+  const round = useCopilotRound()
+
+  function getUI() {
+    return options.codeEditor.value?.getAttachedUI() ?? null
+  }
+
+  function activate() {
+    const ui = getUI()
+    const guide = options.guide()
+    if (ui == null || guide == null) return
+    const key = options.signature()
+    if (key === shownKey && currentId != null) return
+    shownKey = key
+    options.onBeforeShow?.()
+    currentId = ui.showGuide(guide)
+  }
+
+  // Auto-activation is gated to the current, live round so a restored/historical suggestion doesn't
+  // re-pop its guide. Manual activation (the returned `activate`, used as the chat link's click handler)
+  // stays ungated — clicking an old suggestion should still show it.
+  function autoActivate() {
+    if (round != null && !(round.round.isLive && round.isLastRound())) return
+    activate()
+  }
+
+  function deactivate() {
+    const ui = getUI()
+    if (ui != null && currentId != null) ui.clearGuide(currentId)
+    currentId = null
+    shownKey = ''
+    options.onCleanup?.()
+  }
+
+  // When the controller clears OUR guide (e.g. another guide in the same reply displaced it, or it
+  // completed), run cleanup so a blank line opened for typing isn't orphaned, and reset so a click can
+  // reopen it. (The controller allows only one active guide, so guides in one reply displace each other.)
+  watch(
+    getUI,
+    (ui, _, onWatchCleanup) => {
+      if (ui == null) return
+      onWatchCleanup(
+        ui.onGuideCleared((id) => {
+          if (id !== currentId) return
+          currentId = null
+          shownKey = ''
+          options.onCleanup?.()
+        })
+      )
+    },
+    { immediate: true }
+  )
+
+  // Re-activate as inputs settle (the message streams in), so the editor matches the final suggestion.
+  watch(
+    () => [options.guide(), getUI(), options.signature(), round?.round.isLive, round?.isLastRound()] as const,
+    () => autoActivate(),
+    { immediate: true }
+  )
+  onUnmounted(deactivate)
+
+  return { activate }
+}
+
+export interface UseInsertionBlankLineOptions {
+  codeEditor: ComputedRef<CodeEditor | null>
+  editorCtx: { value: EditorCtx | null | undefined }
+  textDocumentId: () => TextDocumentIdentifier
+  /** 1-based line where the new statement should go. */
+  line: () => number
+}
+
+/** One indent level, matching the editor's tab settings. */
+function indentUnit(): string {
+  return insertSpaces ? ' '.repeat(tabSize) : '\t'
+}
+
+/** Indentation for a new statement line inserted at `line`: match the previous line, one level deeper if it opens a block. */
+function computeIndent(textDocument: TextDocument, line: number): string {
+  const lineCount = textDocument.getValue().split(/\r?\n/).length
+  const prevLine = Math.min(line - 1, lineCount) // clamp for append-past-end
+  const prevContent = prevLine >= 1 ? textDocument.getLineContent(prevLine) : ''
+  const prevIndent = prevContent.match(/^[\t ]*/)?.[0] ?? ''
+  return /\{\s*$/.test(prevContent) ? prevIndent + indentUnit() : prevIndent
+}
+
+export interface InsertionBlankLine {
+  open: () => void
+  remove: () => void
+  /** The indentation that the opened line will (or did) receive; empty when no blank line is opened. */
+  indent: ComputedRef<string>
+}
+
+/**
+ * Manage a blank line opened at `line`, so the user has a real, editable line to type a new statement
+ * into (and the "Type the code here" chip can sit on it). The new line is pre-indented to match the
+ * surrounding code, and removed again if left empty.
+ */
+export function useInsertionBlankLine(options: UseInsertionBlankLineOptions): InsertionBlankLine {
+  let openedLine: number | null = null
+
+  // True when a new line should be opened: appending past the end, or the target line already holds content.
+  // (When the target line is an existing empty line, the user types into it directly.)
+  const willOpen = computed(() => {
+    const textDocument = options.codeEditor.value?.getTextDocument(options.textDocumentId())
+    const line = options.line()
+    if (textDocument == null || isNaN(line) || line < 1) return false
+    const lineCount = textDocument.getValue().split(/\r?\n/).length
+    if (line > lineCount) return true // append past the end
+    return textDocument.getLineContent(line).trim() !== ''
+  })
+
+  const indent = computed(() => {
+    if (!willOpen.value) return ''
+    const textDocument = options.codeEditor.value?.getTextDocument(options.textDocumentId())
+    if (textDocument == null) return ''
+    return computeIndent(textDocument, options.line())
+  })
+
+  function open() {
+    if (openedLine != null || !willOpen.value) return
+    const codeEditor = options.codeEditor.value
+    const editorCtx = options.editorCtx.value
+    const line = options.line()
+    if (codeEditor == null || editorCtx == null) return
+    const textDocument = codeEditor.getTextDocument(options.textDocumentId())
+    if (textDocument == null) return
+    const lineCount = textDocument.getValue().split(/\r?\n/).length
+    editorCtx.state.history.doAction({ name: { en: 'Open a line to type', zh: '插入空行以便输入' } }, () => {
+      if (line > lineCount) {
+        // Append a new indented line after the last line.
+        const at = { line: lineCount, column: textDocument.getLineContent(lineCount).length + 1 }
+        textDocument.pushEdits([{ range: { start: at, end: at }, newText: '\n' + indent.value }])
+        openedLine = lineCount + 1
+      } else {
+        // Insert a new indented line above the (content-holding) target line.
+        const at = { line, column: 1 }
+        textDocument.pushEdits([{ range: { start: at, end: at }, newText: indent.value + '\n' }])
+        openedLine = line
+      }
+    })
+  }
+
+  function remove() {
+    if (openedLine == null) return
+    const line = openedLine
+    openedLine = null
+    const codeEditor = options.codeEditor.value
+    const editorCtx = options.editorCtx.value
+    const textDocument = codeEditor?.getTextDocument(options.textDocumentId())
+    if (textDocument == null || editorCtx == null) return
+    if (textDocument.getLineContent(line).trim() !== '') return // user typed into it; keep it
+    const lineCount = textDocument.getValue().split(/\r?\n/).length
+    // For a trailing line, remove the preceding newline too; otherwise remove the line and its trailing newline.
+    // When it's the only line there is no newline to remove — just clear its content (line numbers are
+    // 1-based, so the `line - 1` branch would produce an invalid line 0).
+    const range =
+      lineCount <= 1
+        ? { start: { line: 1, column: 1 }, end: { line: 1, column: textDocument.getLineContent(1).length + 1 } }
+        : line >= lineCount
+          ? {
+              start: { line: line - 1, column: textDocument.getLineContent(line - 1).length + 1 },
+              end: { line, column: textDocument.getLineContent(line).length + 1 }
+            }
+          : { start: { line, column: 1 }, end: { line: line + 1, column: 1 } }
+    editorCtx.state.history.doAction({ name: { en: 'Remove the empty line', zh: '移除空行' } }, () =>
+      textDocument.pushEdits([{ range, newText: '' }])
+    )
+  }
+
+  return { open, remove, indent }
+}
diff --git a/spx-gui/src/components/xgo-code-editor/index.ts b/spx-gui/src/components/xgo-code-editor/index.ts
index 4f9320f79f..aae831a15c 100644
--- a/spx-gui/src/components/xgo-code-editor/index.ts
+++ b/spx-gui/src/components/xgo-code-editor/index.ts
@@ -30,3 +30,5 @@ export { default as ResourceInput } from './ui/input-helper/ResourceInput.vue'
 
 export type { ICopilot, CopilotTopic } from './copilot'
 export type { CodeEditorUIController } from './ui/code-editor-ui'
+export type { CodeGuide } from './ui/code-guide'
+export { normalizeCode, diffEdges, trimCommonLines, leadingIdentifier, isContiguousDiff } from './ui/code-guide'
diff --git a/spx-gui/src/components/xgo-code-editor/ui/CodeEditorUI.vue b/spx-gui/src/components/xgo-code-editor/ui/CodeEditorUI.vue
index e0426072fd..0b552d7c6e 100644
--- a/spx-gui/src/components/xgo-code-editor/ui/CodeEditorUI.vue
+++ b/spx-gui/src/components/xgo-code-editor/ui/CodeEditorUI.vue
@@ -34,6 +34,7 @@ import ContextMenuUI from './context-menu/ContextMenuUI.vue'
 import InputHelperUI from './input-helper/InputHelperUI.vue'
 import InlayHintUI from './inlay-hint/InlayHintUI.vue'
 import DropIndicatorUI from './drop-indicator/DropIndicatorUI.vue'
+import CodeGuideUI from './code-guide/CodeGuideUI.vue'
 import DocumentTabs from './document-tab/DocumentTabs.vue'
 import ZoomControl from './ZoomControl.vue'
 import { userLocalStorageRef } from '@/utils/user-storage'
@@ -126,6 +127,12 @@ async function handleMonacoEditorDrop(e: DragEvent) {
   const target = ui.editor.getTargetAtClientPoint(e.clientX, e.clientY)
   if (target == null || target.position == null) return
   const position = fromMonacoPosition(target.position)
+  // When dropping onto a blank but indented line (e.g. the line opened for a drag hint), land after the
+  // existing indentation so the inserted code keeps that indent instead of jumping to the line start.
+  const targetLineContent = ui.activeTextDocument?.getLineContent(position.line) ?? ''
+  if (targetLineContent !== '' && targetLineContent.trim() === '') {
+    position.column = targetLineContent.length + 1
+  }
   const range = { start: position, end: position }
   const ddi = getDdiDragData(e.dataTransfer)
   if (ddi != null) {
@@ -273,6 +280,7 @@ providePopupContainer(codeEditorEl)
     <InputHelperUI :controller="uiRef.inputHelperController" />
     <InlayHintUI :controller="uiRef.inlayHintController" />
     <DropIndicatorUI :controller="uiRef.dropIndicatorController" />
+    <CodeGuideUI :controller="uiRef.codeGuideController" />
     <aside class="flex min-h-0 min-w-0 flex-none flex-col justify-between gap-10 px-2 py-3">
       <DocumentTabs class="min-h-0 flex-[0_1_auto]" />
       <ZoomControl class="flex-none" @in="zoomIn" @out="zoomOut" @reset="zoomReset" />
diff --git a/spx-gui/src/components/xgo-code-editor/ui/api-reference/APIReferenceItem.vue b/spx-gui/src/components/xgo-code-editor/ui/api-reference/APIReferenceItem.vue
index e01d2254e0..4370a2b285 100644
--- a/spx-gui/src/components/xgo-code-editor/ui/api-reference/APIReferenceItem.vue
+++ b/spx-gui/src/components/xgo-code-editor/ui/api-reference/APIReferenceItem.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, ref } from 'vue'
+import { computed, ref, watch } from 'vue'
 import * as lsp from 'vscode-languageserver-protocol'
 import { useMessageHandle } from '@/utils/exception'
 import { UIDropdown } from '@/components/ui'
@@ -22,6 +22,13 @@ const props = defineProps<{
 const codeEditor = useCodeEditor()
 const codeEditorUICtx = useCodeEditorUICtx()
 
+const itemEl = ref<HTMLElement | null>(null)
+// Highlighted while a copilot drag guide points the user at this API item.
+const isHighlighted = computed(() => codeEditorUICtx.ui.apiReferenceController.highlightedItem === props.item)
+watch(isHighlighted, (highlighted) => {
+  if (highlighted) itemEl.value?.scrollIntoView({ block: 'nearest', behavior: 'smooth' })
+})
+
 const handleInsert = useMessageHandle(
   () =>
     codeEditor.history.doAction({ name: { en: 'Insert code', zh: '插入代码' } }, () =>
@@ -102,11 +109,13 @@ function handleMouseUp(e: MouseEvent) {
   <UIDropdown ref="hoverDropdown" placement="bottom-start" :offset="{ x: 0, y: 4 }" :disabled="interactionDisabled">
     <template #trigger>
       <li
+        ref="itemEl"
         v-radar="{
           name: parsed.overview,
           desc: ''
         }"
         class="api-reference-item"
+        :class="{ 'api-reference-item-highlighted': isHighlighted }"
         draggable="true"
         @dragstart="handleDragStart"
         @mousedown.passive="handleMouseDown"
@@ -152,6 +161,24 @@ function handleMouseUp(e: MouseEvent) {
   background: var(--ui-color-grey-300);
 }
 
+/* Highlighted while a copilot drag guide points the user at this item. */
+.api-reference-item-highlighted {
+  outline: 2px solid rgba(249, 115, 22, 0.9);
+  outline-offset: 1px;
+  background: rgba(249, 115, 22, 0.12);
+  animation: api-reference-item-pulse 1.2s ease-in-out infinite;
+}
+
+@keyframes api-reference-item-pulse {
+  0%,
+  100% {
+    outline-color: rgba(249, 115, 22, 0.9);
+  }
+  50% {
+    outline-color: rgba(249, 115, 22, 0.35);
+  }
+}
+
 .api-reference-item.before-dragging {
   /* Adjust transparency for dragging to avoid visual obstruction */
   background-color: rgba(from var(--ui-color-grey-300) r g b / 0.6);
diff --git a/spx-gui/src/components/xgo-code-editor/ui/api-reference/index.ts b/spx-gui/src/components/xgo-code-editor/ui/api-reference/index.ts
index 6d891c8c7f..6eb017048c 100644
--- a/spx-gui/src/components/xgo-code-editor/ui/api-reference/index.ts
+++ b/spx-gui/src/components/xgo-code-editor/ui/api-reference/index.ts
@@ -1,4 +1,4 @@
-import { watch } from 'vue'
+import { shallowRef, watch } from 'vue'
 import { Disposable } from '@/utils/disposable'
 import { TaskManager } from '@/utils/task'
 import type {
@@ -8,6 +8,7 @@ import type {
   IAPIReferenceProvider
 } from '../../api-reference'
 import type { CodeEditorUIController } from '../code-editor-ui'
+import { leadingIdentifier, normalizeCode } from '../code-guide'
 
 export type { APIReferenceItem, APIReferenceContext, IAPIReferenceProvider, APICategoryViewInfo }
 
@@ -16,6 +17,43 @@ export class APIReferenceController extends Disposable {
     super()
   }
 
+  /** Code whose corresponding API item should be highlighted, or null. */
+  private highlightCodeRef = shallowRef<string | null>(null)
+  private highlightedItemRef = shallowRef<APIReferenceItem | null>(null)
+
+  /** The API item currently highlighted (e.g. while a drag guide points the user at it), or null. */
+  get highlightedItem() {
+    return this.highlightedItemRef.value
+  }
+
+  /** Highlight the API item whose function name matches the leading identifier of `code`. */
+  highlightForCode(code: string) {
+    this.highlightCodeRef.value = code
+    this.applyHighlight()
+  }
+
+  clearHighlight() {
+    this.highlightCodeRef.value = null
+    this.highlightedItemRef.value = null
+  }
+
+  private applyHighlight() {
+    const code = this.highlightCodeRef.value
+    if (code == null || code === '') {
+      this.highlightedItemRef.value = null
+      return
+    }
+    const items = this.items ?? []
+    // Prefer the item whose resolved snippet matches the expected code exactly — this disambiguates
+    // same-name variants (e.g. several `turn ...` overloads). Fall back to matching by function name.
+    const target = normalizeCode(code)
+    const name = leadingIdentifier(code)
+    this.highlightedItemRef.value =
+      items.find((item) => normalizeCode(this.ui.parseSnippet(item.insertSnippet).toString()) === target) ??
+      (name !== '' ? items.find((item) => leadingIdentifier(item.insertSnippet) === name) : undefined) ??
+      null
+  }
+
   private itemsMgr = new TaskManager(async (signal) => {
     const provider = this.ui.codeEditor.apiReferenceProvider
     const { activeTextDocument: textDocument } = this.ui
@@ -46,5 +84,12 @@ export class APIReferenceController extends Disposable {
         { immediate: true }
       )
     )
+    // Re-resolve the highlighted item when the item list (re)loads.
+    this.addDisposer(
+      watch(
+        () => this.items,
+        () => this.applyHighlight()
+      )
+    )
   }
 }
diff --git a/spx-gui/src/components/xgo-code-editor/ui/code-editor-ui.ts b/spx-gui/src/components/xgo-code-editor/ui/code-editor-ui.ts
index c223833340..1728aa90f7 100644
--- a/spx-gui/src/components/xgo-code-editor/ui/code-editor-ui.ts
+++ b/spx-gui/src/components/xgo-code-editor/ui/code-editor-ui.ts
@@ -33,6 +33,7 @@ import { fromMonacoPosition, toMonacoRange, fromMonacoSelection, toMonacoPositio
 import { InputHelperController, type InternalInputSlot } from './input-helper'
 import { InlayHintController } from './inlay-hint'
 import { DropIndicatorController } from './drop-indicator'
+import { CodeGuideController, type CodeGuide } from './code-guide'
 import { SnippetParser } from './snippet'
 import {
   CopilotExplainKind,
@@ -55,6 +56,7 @@ export * from './input-helper'
 export * from './inlay-hint'
 export * from '../copilot'
 export * from './drop-indicator'
+export * from './code-guide'
 export type { ISnippetVariablesProvider } from './snippet'
 
 export interface ICodeEditorUIController {
@@ -78,6 +80,15 @@ export interface ICodeEditorUIController {
 
   insertBlockText(text: string, range?: Range): Promise<void>
 
+  /** Show an in-editor copilot guide (drag target / type-along ghost / deletion highlight). Returns the guide ID. */
+  showGuide(guide: CodeGuide): string
+  /** Clear the active guide. When `id` is given, only clears if it matches the active guide. */
+  clearGuide(id?: string): void
+  /** Subscribe to guide completion. Returns an unsubscribe function. */
+  onGuideCompleted(cb: (id: string) => void): () => void
+  /** Subscribe to a guide being cleared/displaced. Returns an unsubscribe function. */
+  onGuideCleared(cb: (id: string) => void): () => void
+
   dispose(): void
 }
 
@@ -175,8 +186,22 @@ export class CodeEditorUIController extends Disposable implements ICodeEditorUIC
   inputHelperController = new InputHelperController(this)
   inlayHintController = new InlayHintController(this)
   dropIndicatorController = new DropIndicatorController(this)
+  codeGuideController = new CodeGuideController(this)
   snippetParser = new SnippetParser(this)
 
+  showGuide(guide: CodeGuide): string {
+    return this.codeGuideController.setGuide(guide)
+  }
+  clearGuide(id?: string): void {
+    this.codeGuideController.clearGuide(id)
+  }
+  onGuideCompleted(cb: (id: string) => void): () => void {
+    return this.codeGuideController.on('completed', ({ id }) => cb(id))
+  }
+  onGuideCleared(cb: (id: string) => void): () => void {
+    return this.codeGuideController.on('cleared', ({ id }) => cb(id))
+  }
+
   /** Temporary text document IDs */
   private tempTextDocumentIds = shallowReactive<TextDocumentIdentifier[]>([])
 
@@ -718,6 +743,7 @@ export class CodeEditorUIController extends Disposable implements ICodeEditorUIC
 
   dispose() {
     this.snippetParser.dispose()
+    this.codeGuideController.dispose()
     this.dropIndicatorController.dispose()
     this.inlayHintController.dispose()
     this.inputHelperController.dispose()
diff --git a/spx-gui/src/components/xgo-code-editor/ui/code-guide/CodeGuideUI.vue b/spx-gui/src/components/xgo-code-editor/ui/code-guide/CodeGuideUI.vue
new file mode 100644
index 0000000000..f79b9682a2
--- /dev/null
+++ b/spx-gui/src/components/xgo-code-editor/ui/code-guide/CodeGuideUI.vue
@@ -0,0 +1,428 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import type * as monaco from 'monaco-editor'
+import { tabSize } from '@/utils/xgo/highlighter'
+import { textDocumentIdEq, type Range } from '../../common'
+import { useDecorations, useViewZone, toMonacoRange, type ViewZoneSpec } from '../common'
+import { useCodeEditorUICtx } from '../CodeEditorUI.vue'
+import { diffRemovedSpans, type CodeGuide, type CodeGuideController } from '.'
+
+const props = defineProps<{
+  controller: CodeGuideController
+}>()
+
+const { ui } = useCodeEditorUICtx()
+
+// Bumped whenever the active document content changes, so type-ghost rendering re-runs as the user types.
+const docVersion = ref(0)
+watch(
+  () => ui.activeTextDocument,
+  (doc, _, onCleanup) => {
+    if (doc == null) return
+    onCleanup(doc.on('didChangeContent', () => docVersion.value++))
+  },
+  { immediate: true }
+)
+
+// Line count of the active document, recomputed once per content change (shared by the rendering helpers
+// below so each keystroke doesn't re-split the whole document several times).
+const lineCount = computed(() => {
+  void docVersion.value
+  return ui.activeTextDocument?.getValue().split(/\r?\n/).length ?? 0
+})
+
+// Only render the guide when its target document is the one currently shown in the editor.
+const activeGuide = computed(() => {
+  const active = props.controller.active
+  if (active == null) return null
+  if (!textDocumentIdEq(ui.activeTextDocument?.id ?? null, active.guide.textDocument)) return null
+  return active.guide
+})
+
+useDecorations(() => {
+  const guide = activeGuide.value
+  if (guide == null) return []
+  switch (guide.kind) {
+    case 'delete':
+      return deleteDecorations(guide.range)
+    case 'change':
+      return changeDecorations(guide)
+    case 'type':
+      return typeChipDecorations(guide)
+    case 'drag':
+      return dragInlineDecorations(guide)
+  }
+})
+
+useViewZone(() => {
+  const guide = activeGuide.value
+  if (guide == null) return null
+  if (guide.kind === 'type' || guide.kind === 'change') return additionZone(guide)
+  if (guide.kind === 'drag') return dragNewLineZone(guide)
+  return null
+})
+
+/** A range that stays within a single line is rendered inline; otherwise it spans whole lines. */
+function isInlineRange(range: Range): boolean {
+  return range.start.line === range.end.line
+}
+
+/** Red highlight for the text to delete: inline for a sub-line range, whole-line otherwise. */
+function deleteDecorations(range: Range): monaco.editor.IModelDeltaDecoration[] {
+  if (isInlineRange(range)) {
+    if (range.start.column === range.end.column) return [] // nothing to delete (pure insertion)
+    // `inlineClassName` styles the actual characters, so the strike-through renders reliably.
+    return [{ range: toMonacoRange(range), options: { inlineClassName: 'code-editor-guide-delete-inline' } }]
+  }
+  // The range ends at column 1 of the line *after* the last removed line, so exclude that trailing line.
+  const endLine = range.end.column === 1 && range.end.line > range.start.line ? range.end.line - 1 : range.end.line
+  return [
+    {
+      range: { startLineNumber: range.start.line, startColumn: 1, endLineNumber: endLine, endColumn: 1 },
+      options: {
+        isWholeLine: true,
+        className: 'code-editor-guide-delete-line',
+        inlineClassName: 'code-editor-guide-delete-line-text',
+        linesDecorationsClassName: 'code-editor-guide-delete-line-header'
+      }
+    }
+  ]
+}
+
+/**
+ * Red strike-through for a single-line change, computed by diffing the live edit region against the target
+ * code so it marks only the characters that are still old (to remove). Recomputed on every edit, it stays
+ * correct regardless of edit order — typing new code next to or inside the old text is classified as "new"
+ * (not struck), and only the leftover old characters are red.
+ */
+function inlineChangeRedDecorations(guide: CodeGuide & { kind: 'change' }): monaco.editor.IModelDeltaDecoration[] {
+  void docVersion.value
+  const doc = ui.activeTextDocument
+  if (doc == null) return []
+  const region = props.controller.getActiveEditRange()
+  if (region == null) return deleteDecorations(guide.range) // no live region yet → static strike-through
+  const current = doc.getValueInRange(region)
+  const startOffset = doc.getOffsetAt(region.start)
+  return diffRemovedSpans(current, guide.code).map((span) => ({
+    range: toMonacoRange({
+      start: doc.getPositionAt(startOffset + span.start),
+      end: doc.getPositionAt(startOffset + span.end)
+    }),
+    options: { inlineClassName: 'code-editor-guide-delete-inline' }
+  }))
+}
+
+/**
+ * Red for a whole-line replacement (a wholesale change of unrelated code): strike through the old line
+ * content once, with NeverGrows stickiness so text the user types at either edge is NOT swallowed into the
+ * red — their input is assumed to be the new code. Monaco tracks the decoration, shrinking it as the old
+ * content is deleted. (Text inserted in the middle of the old content is still covered — an accepted edge.)
+ */
+function wholeLineChangeRedDecorations(guide: CodeGuide & { kind: 'change' }): monaco.editor.IModelDeltaDecoration[] {
+  const doc = ui.activeTextDocument
+  if (doc == null) return []
+  const line = guide.range.start.line
+  const contentLength = doc.getLineContent(line).length
+  if (contentLength === 0) return []
+  return [
+    {
+      range: { startLineNumber: line, startColumn: 1, endLineNumber: line, endColumn: contentLength + 1 },
+      options: {
+        inlineClassName: 'code-editor-guide-delete-inline',
+        stickiness: ui.monaco.editor.TrackedRangeStickiness.NeverGrowsWhenTypingAtEdges
+      }
+    }
+  ]
+}
+
+/**
+ * Decorations for a change: red strike-through for the removed text, plus — for a pure inline insertion
+ * (empty range) — a "Type the code here" chip at the insertion point that marks where the new code goes.
+ * The green code itself is shown below (additionZone), with an arrow pointing back at the chip. Single-line
+ * (inline) changes use a per-keystroke char diff; whole-line replacements strike the old content once and
+ * let the user's typed input stay un-red (see `wholeLineChangeRedDecorations`).
+ */
+function changeDecorations(guide: CodeGuide & { kind: 'change' }): monaco.editor.IModelDeltaDecoration[] {
+  const { start, end } = guide.range
+  const decorations = isInlineRange(guide.range)
+    ? inlineChangeRedDecorations(guide)
+    : wholeLineChangeRedDecorations(guide)
+  const isPureInlineInsertion = start.line === end.line && start.column === end.column
+  if (isPureInlineInsertion && guide.code !== '') {
+    decorations.push({
+      range: {
+        startLineNumber: start.line,
+        startColumn: start.column,
+        endLineNumber: start.line,
+        endColumn: start.column
+      },
+      options: {
+        showIfCollapsed: true,
+        after: {
+          content: ui.i18n.t({ en: 'Type the code here', zh: '在这里输入代码' }),
+          inlineClassName: 'code-editor-guide-chip',
+          cursorStops: ui.monaco.editor.InjectedTextCursorStops.Left
+        }
+      }
+    })
+  }
+  return decorations
+}
+
+/**
+ * Where the green addition aligns to (priority): the insertion chip, else the inline red, else the
+ * whole-line red. `afterLineNumber` is the line the green sits below. When the anchor is not found at
+ * render time (e.g. the chip is hidden after the user starts typing), the green falls back to no
+ * indentation (see `alignAdditionNode`).
+ */
+function resolveAdditionAnchor(guide: CodeGuide & { kind: 'type' | 'change' }): {
+  anchorSelector: string
+  afterLineNumber: number
+} {
+  const { start, end } = guide.range
+  if (guide.kind === 'type') {
+    return { anchorSelector: '.code-editor-guide-chip', afterLineNumber: start.line }
+  }
+  if (isInlineRange(guide.range)) {
+    const isPureInsertion = start.column === end.column
+    return {
+      anchorSelector: isPureInsertion ? '.code-editor-guide-chip' : '.code-editor-guide-delete-inline',
+      afterLineNumber: start.line
+    }
+  }
+  const endLine = end.column === 1 && end.line > start.line ? end.line - 1 : end.line
+  return { anchorSelector: '.code-editor-guide-delete-line-text', afterLineNumber: endLine }
+}
+
+/**
+ * The unified green addition (type & change, single/inline/multi-line): the code shown as a view zone
+ * below, aligned to its anchor with a `↳` connector. Only the anchor & line differ per case.
+ */
+function additionZone(guide: CodeGuide & { kind: 'type' | 'change' }): ViewZoneSpec | null {
+  const codeLines = guide.code.replace(/\n+$/, '').split('\n')
+  if (codeLines.length === 1 && codeLines[0] === '') return null // pure deletion → no green
+  const { anchorSelector, afterLineNumber } = resolveAdditionAnchor(guide)
+  const { node, dispose } = createAdditionNode(codeLines.join('\n'), '↳', anchorSelector)
+  return { afterLineNumber, heightInLines: codeLines.length, domNode: node, onRemove: dispose }
+}
+
+/** Inline drop-target hint: an orange chip rendered after the line content (for typing into an empty line). */
+function dragInlineDecorations(guide: CodeGuide & { kind: 'drag' }): monaco.editor.IModelDeltaDecoration[] {
+  void docVersion.value
+  const line = guide.range.start.line
+  // New-line insertion: the chip is shown as a block above the line instead of appended inline.
+  if (isNewLineInsertion(line)) return []
+  const doc = ui.activeTextDocument
+  let column = 1
+  if (doc != null && line <= lineCount.value) column = doc.getLineContent(line).length + 1
+  return [
+    {
+      range: { startLineNumber: line, startColumn: column, endLineNumber: line, endColumn: column },
+      options: {
+        showIfCollapsed: true,
+        after: {
+          content: ui.i18n.t({ en: 'Drag the block here', zh: '把积木拖到这里' }),
+          inlineClassName: 'code-editor-guide-chip'
+        }
+      }
+    }
+  ]
+}
+
+/** When dragging inserts a new line (target line has content), show the drop indicator as a block above it. */
+function dragNewLineZone(guide: CodeGuide & { kind: 'drag' }): ViewZoneSpec | null {
+  void docVersion.value
+  if (!isNewLineInsertion(guide.range.start.line)) return null
+  return { afterLineNumber: Math.max(guide.range.start.line - 1, 0), heightInLines: 1, domNode: createDragNode() }
+}
+
+/**
+ * Whether the insertion creates a brand-new line, as opposed to typing into an already-empty line.
+ * True when appending past the end of the document, or when the target line already holds content.
+ */
+function isNewLineInsertion(startLine: number): boolean {
+  const doc = ui.activeTextDocument
+  if (doc == null) return false
+  if (startLine > lineCount.value) return true // appending past the end → a new line
+  return doc.getLineContent(startLine).trim() !== ''
+}
+
+/** "Type the code here" chip rendered inline on the (blank) target line — where the user will actually type. */
+function typeChipDecorations(guide: CodeGuide & { kind: 'type' }): monaco.editor.IModelDeltaDecoration[] {
+  void docVersion.value
+  const doc = ui.activeTextDocument
+  if (doc == null) return []
+  const line = guide.range.start.line
+  if (line > lineCount.value) return []
+  if (doc.getLineContent(line).trim() !== '') return [] // user started typing → hide the chip
+  // Anchor the chip after the line content (i.e. after any indentation) and keep the caret on its left,
+  // so typing pushes characters in before the chip instead of making the caret jump past it.
+  const column = doc.getLineContent(line).length + 1
+  return [
+    {
+      range: { startLineNumber: line, startColumn: column, endLineNumber: line, endColumn: column },
+      options: {
+        showIfCollapsed: true,
+        after: {
+          content: ui.i18n.t({ en: 'Type the code here', zh: '在这里输入代码' }),
+          inlineClassName: 'code-editor-guide-chip',
+          cursorStops: ui.monaco.editor.InjectedTextCursorStops.Left
+        }
+      }
+    }
+  ]
+}
+
+/** Match a green-ghost code element to the editor's own font and tab width, so it reads like real code. */
+function applyEditorCodeFont(el: HTMLElement) {
+  const fontInfo = ui.editor.getOption(ui.monaco.editor.EditorOption.fontInfo)
+  el.style.fontFamily = fontInfo.fontFamily
+  el.style.fontSize = `${fontInfo.fontSize}px`
+  el.style.lineHeight = `${fontInfo.lineHeight}px`
+  el.style.tabSize = `${tabSize}`
+}
+
+function createDragNode(): HTMLElement {
+  const node = document.createElement('div')
+  node.className = 'code-editor-guide-drag-block'
+  const chip = document.createElement('span')
+  chip.className = 'code-editor-guide-chip'
+  chip.textContent = ui.i18n.t({ en: 'Drag the block here', zh: '把积木拖到这里' })
+  node.appendChild(chip)
+  return node
+}
+
+/** Green addition (one or more lines) aligned under its anchor element with a connector. */
+function createAdditionNode(
+  code: string,
+  connector: string,
+  anchorSelector: string
+): { node: HTMLElement; dispose: () => void } {
+  const node = document.createElement('div')
+  node.className = 'code-editor-guide-addition'
+  const connectorEl = document.createElement('span')
+  connectorEl.className = 'code-editor-guide-addition-connector'
+  connectorEl.textContent = connector
+  const text = document.createElement('span')
+  text.className = 'code-editor-guide-addition-text'
+  text.textContent = code.replace(/\n+$/, '')
+  applyEditorCodeFont(text)
+  node.appendChild(connectorEl)
+  node.appendChild(text)
+  const dispose = alignAdditionNode(node, anchorSelector)
+  return { node, dispose }
+}
+
+/**
+ * Align the addition under its anchor (the red strike-through for a replacement, or the insertion chip)
+ * by measuring the actual rendered element. Robust against inlay hints (injected `before` text), which
+ * column→pixel APIs misreport. Returns a disposer that cancels any pending frame (called when the view
+ * zone is removed, so alignment doesn't keep running against a stale/disposed editor).
+ */
+function alignAdditionNode(node: HTMLElement, anchorSelector: string): () => void {
+  let attempts = 0
+  let rafId: number | null = null
+  const tryAlign = () => {
+    rafId = null
+    if (!node.isConnected) {
+      // Not inserted into the DOM yet — wait a few frames; give up if it never connects (zone removed).
+      if (attempts++ < 10) rafId = requestAnimationFrame(tryAlign)
+      return
+    }
+    const anchorEl = ui.editor.getDomNode()?.querySelector(anchorSelector)
+    if (anchorEl != null) {
+      // Shift via margin (not padding): the node's padding-left is the connector gutter, and we want
+      // the connector — at the node's left edge — to line up with the anchor.
+      const delta = anchorEl.getBoundingClientRect().left - node.getBoundingClientRect().left
+      if (delta > 0) node.style.marginLeft = `${delta}px`
+      return
+    }
+    if (attempts++ < 10) rafId = requestAnimationFrame(tryAlign)
+  }
+  rafId = requestAnimationFrame(tryAlign)
+  return () => {
+    if (rafId != null) cancelAnimationFrame(rafId)
+    rafId = null
+  }
+}
+</script>
+
+<template>
+  <div></div>
+</template>
+
+<style>
+.code-editor-guide-delete-line,
+.code-editor-guide-delete-line-header {
+  background-color: rgba(244, 63, 94, 0.18);
+}
+
+.code-editor-guide-delete-line-header {
+  width: 100% !important;
+  left: 0 !important;
+}
+
+/* Inline red highlight for a sub-line deletion/replacement. */
+.code-editor-guide-delete-inline {
+  background-color: rgba(244, 63, 94, 0.22);
+  text-decoration: line-through;
+  text-decoration-color: rgba(244, 63, 94, 0.9);
+}
+
+/* Strike-through for the text of whole-line deletions. */
+.code-editor-guide-delete-line-text {
+  text-decoration: line-through;
+  text-decoration-color: rgba(244, 63, 94, 0.9);
+}
+
+/* Green addition shown below the removed text / insertion chip. The connector sits in a left gutter
+   (absolutely positioned), so every code line — including line 2+ — aligns to the same left edge.
+   The code's font, size and tab width are set in JS to exactly match the editor (see applyEditorCodeFont). */
+.code-editor-guide-addition {
+  box-sizing: border-box;
+  position: relative;
+  height: 100%;
+  padding-left: 1.3em;
+  white-space: pre;
+}
+
+.code-editor-guide-addition-connector {
+  position: absolute;
+  left: 0;
+  top: 0;
+  color: var(--ui-color-hint-2, #999);
+  opacity: 0.7;
+}
+
+.code-editor-guide-addition-text {
+  padding: 0 2px;
+  border-radius: 2px;
+  color: rgb(22, 163, 74);
+  background-color: rgba(34, 197, 94, 0.2);
+}
+
+/* Shared amber signpost chip for guide hints — reused by the type & drag hints, and available to other hints. */
+.code-editor-guide-chip {
+  display: inline-flex;
+  align-items: center;
+  margin-left: 4px;
+  padding: 1px 8px;
+  border: 1px dashed rgba(249, 115, 22, 0.7);
+  border-radius: 6px;
+  font-size: 12px;
+  line-height: 1.5;
+  white-space: nowrap;
+  /* When rendered as Monaco injected text the span also gets a token color class (`mtk1`, near-black);
+     `!important` keeps the chip amber regardless of cascade order. */
+  color: rgb(234, 88, 12) !important;
+  background-color: rgba(249, 115, 22, 0.16);
+}
+
+/* View-zone container that vertically centers the drag chip when dragging inserts a new line. */
+.code-editor-guide-drag-block {
+  display: flex;
+  align-items: center;
+  height: 100%;
+  padding: 0 16px;
+}
+</style>
diff --git a/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.test.ts b/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.test.ts
new file mode 100644
index 0000000000..8ebdf4eddc
--- /dev/null
+++ b/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.test.ts
@@ -0,0 +1,426 @@
+import { describe, it, expect, vi } from 'vitest'
+import Emitter from '@/utils/emitter'
+import type { Range, TextDocumentIdentifier } from '../../common'
+import type { CodeEditorUIController } from '../code-editor-ui'
+import { CodeGuideController, diffEdges, diffRemovedSpans, isContiguousDiff, trimCommonLines } from '.'
+
+const textDocumentId: TextDocumentIdentifier = { uri: 'file:///Test.spx' }
+
+type MonacoRange = { startLineNumber: number; startColumn: number; endLineNumber: number; endColumn: number }
+
+/** Subset of Monaco's TrackedRangeStickiness used by the controller. */
+const TrackedRangeStickiness = { AlwaysGrowsWhenTypingAtEdges: 0, NeverGrowsWhenTypingAtEdges: 1 }
+
+/**
+ * Minimal TextDocument stub: an emitter with mutable content plus a Monaco-like text model that supports
+ * decoration tracking. Each `setContent` is treated as a single contiguous edit (derived via `diffEdges`)
+ * and tracked decoration ranges are adjusted accordingly — mirroring how Monaco keeps a decoration in sync
+ * with edits, so completion detection can be exercised end-to-end (including edits made elsewhere).
+ */
+class FakeTextDocument extends Emitter<{ didChangeContent: string }> {
+  id = textDocumentId
+  constructor(private content: string) {
+    super()
+  }
+  getValue() {
+    return this.content
+  }
+
+  // --- offset <-> position helpers (offsets count '\n' as one char) ---
+  private offsetAt(line: number, column: number) {
+    const lines = this.content.split('\n')
+    let offset = 0
+    for (let i = 0; i < line - 1; i++) offset += (lines[i] ?? '').length + 1
+    return offset + (column - 1)
+  }
+  private positionAt(offset: number) {
+    const before = this.content.slice(0, offset).split('\n')
+    return { line: before.length, column: before[before.length - 1].length + 1 }
+  }
+
+  // --- mock decoration store (ranges kept as char offsets) ---
+  private decorations = new Map<string, { start: number; end: number; grows: boolean }>()
+  private decorationSeq = 0
+  monacoTextModel = {
+    deltaDecorations: (
+      oldIds: string[],
+      newDecs: { range: MonacoRange; options?: { stickiness?: number } }[]
+    ): string[] => {
+      for (const id of oldIds) this.decorations.delete(id)
+      return newDecs.map((d) => {
+        const id = `dec-${this.decorationSeq++}`
+        this.decorations.set(id, {
+          start: this.offsetAt(d.range.startLineNumber, d.range.startColumn),
+          end: this.offsetAt(d.range.endLineNumber, d.range.endColumn),
+          grows: d.options?.stickiness === TrackedRangeStickiness.AlwaysGrowsWhenTypingAtEdges
+        })
+        return id
+      })
+    },
+    getDecorationRange: (id: string): MonacoRange | null => {
+      const d = this.decorations.get(id)
+      if (d == null) return null
+      const start = this.positionAt(d.start)
+      const end = this.positionAt(d.end)
+      return { startLineNumber: start.line, startColumn: start.column, endLineNumber: end.line, endColumn: end.column }
+    },
+    getValueInRange: (range: MonacoRange): string =>
+      this.content.slice(
+        this.offsetAt(range.startLineNumber, range.startColumn),
+        this.offsetAt(range.endLineNumber, range.endColumn)
+      )
+  }
+
+  setContent(content: string) {
+    // Derive the single contiguous edit that turns the old content into the new one (delete [es, ee),
+    // then insert `insertLen` chars at es), then adjust each tracked decoration the way Monaco would.
+    const old = this.content
+    const { prefix, suffix } = diffEdges(old, content)
+    const es = prefix
+    const ee = old.length - suffix
+    const dl = ee - es
+    const insertLen = content.length - prefix - suffix
+    for (const d of this.decorations.values()) {
+      // Deletion of [es, ee): clamp endpoints inside the deleted span, shift those after it left.
+      const adjustForDeletion = (p: number) => (p <= es ? p : p >= ee ? p - dl : es)
+      let start = adjustForDeletion(d.start)
+      let end = adjustForDeletion(d.end)
+      // Insertion of `insertLen` at es.
+      if (es < start) {
+        start += insertLen
+        end += insertLen // strictly before the region: shift it
+      } else if (es > end) {
+        // strictly after the region: unchanged
+      } else if (es > start && es < end) {
+        end += insertLen // strictly inside: always grow
+      } else if (d.grows) {
+        end += insertLen // at an edge, AlwaysGrows: include the inserted text
+      } else if (es === start) {
+        start += insertLen
+        end += insertLen // at the start edge, NeverGrows: push the region after the insertion
+      } // at the end edge, NeverGrows: unchanged
+      d.start = start
+      d.end = end
+    }
+    this.content = content
+    this.emit('didChangeContent', content)
+  }
+}
+
+function createController(initialContent: string) {
+  const doc = new FakeTextDocument(initialContent)
+  const open = vi.fn()
+  const apiReferenceController = { highlightForCode: vi.fn(), clearHighlight: vi.fn() }
+  const ui = {
+    open,
+    monaco: { editor: { TrackedRangeStickiness } },
+    codeEditor: {
+      getTextDocument: () => doc
+    },
+    apiReferenceController
+  } as unknown as CodeEditorUIController
+  return { controller: new CodeGuideController(ui), doc, open, apiReferenceController }
+}
+
+function lineRange(line: number, count = 0): Range {
+  return { start: { line, column: 1 }, end: { line: line + count, column: 1 } }
+}
+
+describe('CodeGuideController', () => {
+  it('sets an active guide and navigates to it', () => {
+    const { controller, open } = createController('')
+    const id = controller.setGuide({
+      kind: 'type',
+      textDocument: textDocumentId,
+      range: lineRange(1),
+      code: 'say "hi"'
+    })
+    expect(controller.active?.id).toBe(id)
+    expect(controller.active?.guide.kind).toBe('type')
+    expect(open).toHaveBeenCalledWith(textDocumentId, { line: 1, column: 1 })
+  })
+
+  it('keeps only one active guide at a time', () => {
+    const { controller } = createController('')
+    controller.setGuide({ kind: 'type', textDocument: textDocumentId, range: lineRange(1), code: 'a' })
+    const second = controller.setGuide({ kind: 'delete', textDocument: textDocumentId, range: lineRange(1, 1) })
+    expect(controller.active?.id).toBe(second)
+    expect(controller.active?.guide.kind).toBe('delete')
+  })
+
+  it('clearGuide only clears the matching guide when an id is given', () => {
+    const { controller } = createController('')
+    const id = controller.setGuide({ kind: 'drag', textDocument: textDocumentId, range: lineRange(1) })
+    controller.clearGuide('other-id')
+    expect(controller.active?.id).toBe(id)
+    controller.clearGuide(id)
+    expect(controller.active).toBeNull()
+  })
+
+  it('completes a type guide when the code is typed (ignoring whitespace)', () => {
+    const { controller, doc } = createController('')
+    const completed = vi.fn()
+    controller.on('completed', completed)
+    const id = controller.setGuide({
+      kind: 'type',
+      textDocument: textDocumentId,
+      range: lineRange(1),
+      code: 'say "hi"'
+    })
+
+    doc.setContent('say ') // partial, should not complete
+    expect(controller.active?.id).toBe(id)
+
+    doc.setContent('say   "hi"') // extra whitespace, still matches
+    expect(completed).toHaveBeenCalledWith({ id })
+    expect(controller.active).toBeNull()
+  })
+
+  it('completes a type guide only when the code is typed at the target line, not on edits elsewhere', () => {
+    const { controller, doc } = createController('move 10\n') // type target is the empty line 2
+    const completed = vi.fn()
+    controller.on('completed', completed)
+    controller.setGuide({ kind: 'type', textDocument: textDocumentId, range: lineRange(2), code: 'say "hi"' })
+
+    doc.setContent('move 10 fast\n') // edit line 1 (elsewhere) → target region untouched
+    expect(completed).not.toHaveBeenCalled()
+    expect(controller.active).not.toBeNull()
+
+    doc.setContent('move 10 fast\nsay "hi"') // typed at the target line
+    expect(completed).toHaveBeenCalledTimes(1)
+    expect(controller.active).toBeNull()
+  })
+
+  it('completes a type guide after the user removes an earlier identical line, then types at the target', () => {
+    const { controller, doc } = createController('say "hi"\n') // an identical statement already exists on line 1
+    const completed = vi.fn()
+    controller.on('completed', completed)
+    // Target is the empty line 2. Region tracking follows the location, so the pre-existing copy and the
+    // delete-then-retype sequence (which a count-based check would miss) both work.
+    controller.setGuide({ kind: 'type', textDocument: textDocumentId, range: lineRange(2), code: 'say "hi"' })
+
+    doc.setContent('\n') // user deletes the earlier copy first
+    expect(completed).not.toHaveBeenCalled()
+
+    doc.setContent('\nsay "hi"') // then types the code at the target
+    expect(completed).toHaveBeenCalledTimes(1)
+    expect(controller.active).toBeNull()
+  })
+
+  it('completes a delete guide once the highlighted lines are removed, even after editing elsewhere', () => {
+    const { controller, doc } = createController('a\nb\nc\nd')
+    const completed = vi.fn()
+    controller.on('completed', completed)
+    // delete lines 2 & 3 ("b" and "c")
+    controller.setGuide({ kind: 'delete', textDocument: textDocumentId, range: lineRange(2, 2) })
+
+    doc.setContent('x\na\nb\nc\nd') // inserted a line above: the tracked lines shift down but remain
+    expect(completed).not.toHaveBeenCalled()
+
+    doc.setContent('x\na\nd') // the (shifted) highlighted lines removed
+    expect(completed).toHaveBeenCalledTimes(1)
+    expect(controller.active).toBeNull()
+  })
+
+  it('does not complete a delete guide until the lines are fully removed', () => {
+    const { controller, doc } = createController('a\nbb\nc\nd')
+    const completed = vi.fn()
+    controller.on('completed', completed)
+    // delete lines 2 & 3 ("bb" and "c")
+    controller.setGuide({ kind: 'delete', textDocument: textDocumentId, range: lineRange(2, 2) })
+
+    doc.setContent('a\nb\nc\nd') // only one character removed, not fully deleted
+    expect(completed).not.toHaveBeenCalled()
+    expect(controller.active).not.toBeNull()
+
+    doc.setContent('a\nd') // fully removed → reaches the post-deletion state
+    expect(completed).toHaveBeenCalledTimes(1)
+    expect(controller.active).toBeNull()
+  })
+
+  it('completes a whole-line change when the lines reach the replaced state', () => {
+    const { controller, doc } = createController('turnTo Radish\nstep 5')
+    const completed = vi.fn()
+    controller.on('completed', completed)
+    // replace line 1 with "turnTo Stone3"
+    controller.setGuide({
+      kind: 'change',
+      textDocument: textDocumentId,
+      range: lineRange(1, 1),
+      code: 'turnTo Stone3\n'
+    })
+
+    doc.setContent('turnTo Stone33\nstep 5') // close but not exact
+    expect(completed).not.toHaveBeenCalled()
+
+    doc.setContent('turnTo Stone3\nstep 5')
+    expect(completed).toHaveBeenCalledTimes(1)
+    expect(controller.active).toBeNull()
+  })
+
+  it('completes an inline (partial-line) change', () => {
+    const { controller, doc } = createController('step step:90')
+    const completed = vi.fn()
+    controller.on('completed', completed)
+    // replace "90" (columns 11-13) with "180"
+    const range = { start: { line: 1, column: 11 }, end: { line: 1, column: 13 } }
+    controller.setGuide({ kind: 'change', textDocument: textDocumentId, range, code: '180' })
+
+    doc.setContent('step step:9') // partially edited
+    expect(completed).not.toHaveBeenCalled()
+
+    doc.setContent('step step:180')
+    expect(completed).toHaveBeenCalledTimes(1)
+    expect(controller.active).toBeNull()
+  })
+
+  it('completes a change guide after the user has edited elsewhere first', () => {
+    const { controller, doc } = createController('turnTo Radish\nstep 5')
+    const completed = vi.fn()
+    controller.on('completed', completed)
+    // replace line 1 with "turnTo Stone3"
+    controller.setGuide({
+      kind: 'change',
+      textDocument: textDocumentId,
+      range: lineRange(1, 1),
+      code: 'turnTo Stone3\n'
+    })
+
+    doc.setContent('turnTo Radish\nstep 5\nsay "hi"') // appended a line below the target
+    expect(completed).not.toHaveBeenCalled()
+
+    doc.setContent('turnTo Stone3\nstep 5\nsay "hi"') // now apply the suggested change
+    expect(completed).toHaveBeenCalledTimes(1)
+    expect(controller.active).toBeNull()
+  })
+
+  it('highlights the matching API reference item for a drag guide and clears it afterwards', () => {
+    const { controller, doc, apiReferenceController } = createController('')
+    const id = controller.setGuide({
+      kind: 'drag',
+      textDocument: textDocumentId,
+      range: lineRange(1),
+      code: 'turn Left'
+    })
+    expect(apiReferenceController.highlightForCode).toHaveBeenCalledWith('turn Left')
+
+    doc.setContent('turn Left') // completing the drag clears the guide
+    expect(apiReferenceController.clearHighlight).toHaveBeenCalled()
+    expect(controller.active).toBeNull()
+    void id
+  })
+
+  it('completes a drag guide on any content change when it has no expected code', () => {
+    const { controller, doc } = createController('')
+    const completed = vi.fn()
+    controller.on('completed', completed)
+    controller.setGuide({ kind: 'drag', textDocument: textDocumentId, range: lineRange(1) })
+
+    doc.setContent('move 10')
+    expect(completed).toHaveBeenCalledTimes(1)
+    expect(controller.active).toBeNull()
+  })
+
+  it('completes a drag guide only when a new statement of the expected kind appears', () => {
+    const { controller, doc } = createController('turn Right') // already contains a `turn`
+    const completed = vi.fn()
+    controller.on('completed', completed)
+    controller.setGuide({ kind: 'drag', textDocument: textDocumentId, range: lineRange(2), code: 'turn Left' })
+
+    doc.setContent('turn Right\nsomething else') // edited elsewhere, no new `turn`
+    expect(completed).not.toHaveBeenCalled()
+    expect(controller.active).not.toBeNull()
+
+    doc.setContent('turn Right\nturn Left') // a new `turn` statement appeared
+    expect(completed).toHaveBeenCalledTimes(1)
+    expect(controller.active).toBeNull()
+  })
+
+  it('emits "cleared" with the displaced guide id when another guide takes over', () => {
+    const { controller } = createController('')
+    const cleared = vi.fn()
+    controller.on('cleared', cleared)
+    const first = controller.setGuide({ kind: 'type', textDocument: textDocumentId, range: lineRange(1), code: 'a' })
+    controller.setGuide({ kind: 'delete', textDocument: textDocumentId, range: lineRange(1, 1) })
+    expect(cleared).toHaveBeenCalledWith({ id: first })
+  })
+})
+
+describe('diffEdges', () => {
+  it('finds the common prefix/suffix so only the real diff remains', () => {
+    // shared prefix "step " and shared suffix "0" → only "16" vs "20" differ
+    expect(diffEdges('step 160', 'step 200')).toEqual({ prefix: 5, suffix: 1 })
+    // shared prefix "step:" and shared suffix "0" → only "9" vs "18" differ
+    expect(diffEdges('step:90', 'step:180')).toEqual({ prefix: 5, suffix: 1 })
+    expect(diffEdges('turnTo Radish', 'turnTo Stone3')).toEqual({ prefix: 7, suffix: 0 })
+  })
+
+  it('keeps a shared suffix out of the diff', () => {
+    // "100px" -> "200px": only the leading digit differs
+    expect(diffEdges('100px', '200px')).toEqual({ prefix: 0, suffix: 4 })
+  })
+
+  it('handles pure insertion and pure deletion', () => {
+    expect(diffEdges('step', 'steps')).toEqual({ prefix: 4, suffix: 0 }) // insert "s" at end
+    expect(diffEdges('steps', 'step')).toEqual({ prefix: 4, suffix: 0 }) // delete trailing "s"
+    expect(diffEdges('abc', 'abc')).toEqual({ prefix: 3, suffix: 0 }) // identical
+  })
+})
+
+describe('trimCommonLines', () => {
+  it('drops identical leading and trailing lines', () => {
+    // shared first line "\tturn -60"; only the second line differs
+    expect(trimCommonLines('\tturn -60\n\tstep 50', '\tturn -60\n\tstep 100')).toEqual({
+      prefixLines: 1,
+      suffixLines: 0
+    })
+    // shared trailing line
+    expect(trimCommonLines('\ta\n\tkeep', '\tb\n\tkeep')).toEqual({ prefixLines: 0, suffixLines: 1 })
+  })
+
+  it('does not over-trim when whole blocks differ', () => {
+    expect(trimCommonLines('\tstepTo Radish\n\tsetXpos x:0', '\tturn -60\n\tstep 100')).toEqual({
+      prefixLines: 0,
+      suffixLines: 0
+    })
+  })
+
+  it('counts prefix and suffix without overlap for identical blocks', () => {
+    expect(trimCommonLines('a\nb', 'a\nb')).toEqual({ prefixLines: 2, suffixLines: 0 })
+  })
+})
+
+describe('diffRemovedSpans', () => {
+  it('marks the old text still present, regardless of where the new code was typed', () => {
+    // new code typed to the right of the old → only the old "old" is removed
+    expect(diffRemovedSpans('oldnew', 'new')).toEqual([{ start: 0, end: 3 }])
+    // new code typed to the left of the old → only the trailing old is removed
+    expect(diffRemovedSpans('newold', 'new')).toEqual([{ start: 3, end: 6 }])
+  })
+
+  it('handles old text on both sides of the new code (typed into the middle)', () => {
+    // "x" + kept "new" + "y": both leftover chunks are removed, the new code in the middle is kept
+    expect(diffRemovedSpans('xnewy', 'new')).toEqual([
+      { start: 0, end: 1 },
+      { start: 4, end: 5 }
+    ])
+  })
+
+  it('returns no spans once the content matches the target, or for a pure insertion', () => {
+    expect(diffRemovedSpans('new', 'new')).toEqual([])
+    expect(diffRemovedSpans('', 'new')).toEqual([]) // nothing old to remove yet
+  })
+})
+
+describe('isContiguousDiff', () => {
+  it('is true for a single contiguous replacement (with shared prefix/suffix)', () => {
+    expect(isContiguousDiff('AoldB', 'AnewB')).toBe(true)
+    expect(isContiguousDiff('step 90', 'step 180')).toBe(true)
+    expect(isContiguousDiff('', 'say "hi"')).toBe(true) // pure insertion
+  })
+
+  it('is false when the edits are scattered across unrelated text', () => {
+    expect(isContiguousDiff('xAxBx', 'AB')).toBe(false) // "x" removed in three separate places
+    expect(isContiguousDiff('setYpos y:0', 'stepTo Radish')).toBe(false)
+  })
+})
diff --git a/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.ts b/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.ts
new file mode 100644
index 0000000000..675ca5dc94
--- /dev/null
+++ b/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.ts
@@ -0,0 +1,291 @@
+/**
+ * @file Code Guide Controller
+ * @desc Manages copilot-driven, in-editor guidance: drag targets, type-along ghosts,
+ * and deletion highlights. Unlike a code change, a guide never modifies the document;
+ * it only renders hints and clears itself once the user has completed the suggested action.
+ */
+
+import { shallowRef } from 'vue'
+import { uniqueId } from 'lodash'
+import { diffChars } from 'diff'
+import Emitter from '@/utils/emitter'
+import { type Range, type TextDocumentIdentifier } from '../../common'
+import type { CodeEditorUIController } from '../code-editor-ui'
+
+export type CodeGuide = { textDocument: TextDocumentIdentifier; range: Range } & (
+  | {
+      /** Guide the user to drag a block (e.g. an API reference item) into the editor. */
+      kind: 'drag'
+      /** Expected code, used to also highlight the matching item in the API reference panel. */
+      code?: string
+    }
+  | {
+      /** Guide the user to manually type the given code at the target location. */
+      kind: 'type'
+      code: string
+    }
+  | {
+      /** Guide the user to delete the highlighted range. */
+      kind: 'delete'
+    }
+  | {
+      /**
+       * Guide the user to replace `range` with `code`, showing the deletion (red) and the
+       * addition (green) at the same time. `range` may be a sub-line range (inline change) or
+       * span whole lines. `code` may be empty (then it behaves like a deletion).
+       */
+      kind: 'change'
+      code: string
+    }
+)
+
+export type ActiveCodeGuide = {
+  id: string
+  guide: CodeGuide
+}
+
+/** Normalize code for whitespace-insensitive comparison. */
+export function normalizeCode(code: string): string {
+  return code.replace(/\s+/g, '')
+}
+
+/** Leading identifier (function name) of a snippet or code line, e.g. `turn ${1}` / `turn Left` → `turn`. */
+export function leadingIdentifier(code: string): string {
+  return code.trimStart().match(/^[A-Za-z_$][\w$]*/)?.[0] ?? ''
+}
+
+/**
+ * Length of the common prefix and (non-overlapping) common suffix between two strings.
+ * Used to narrow a replacement down to the part that actually differs, so a change like
+ * `step 160` → `step 200` highlights only `160` → `200`.
+ */
+export function diffEdges(oldText: string, newText: string): { prefix: number; suffix: number } {
+  const maxPrefix = Math.min(oldText.length, newText.length)
+  let prefix = 0
+  while (prefix < maxPrefix && oldText[prefix] === newText[prefix]) prefix++
+  let suffix = 0
+  while (
+    suffix < oldText.length - prefix &&
+    suffix < newText.length - prefix &&
+    oldText[oldText.length - 1 - suffix] === newText[newText.length - 1 - suffix]
+  ) {
+    suffix++
+  }
+  return { prefix, suffix }
+}
+
+/**
+ * Number of identical leading and (non-overlapping) trailing lines shared by `oldText` and `newText`.
+ * Lets a multi-line change drop unchanged lines (including shared indentation lines) and narrow to the
+ * lines that actually differ.
+ */
+export function trimCommonLines(oldText: string, newText: string): { prefixLines: number; suffixLines: number } {
+  const oldLines = oldText.split('\n')
+  const newLines = newText.split('\n')
+  let prefixLines = 0
+  while (
+    prefixLines < oldLines.length &&
+    prefixLines < newLines.length &&
+    oldLines[prefixLines] === newLines[prefixLines]
+  ) {
+    prefixLines++
+  }
+  let suffixLines = 0
+  while (
+    suffixLines < oldLines.length - prefixLines &&
+    suffixLines < newLines.length - prefixLines &&
+    oldLines[oldLines.length - 1 - suffixLines] === newLines[newLines.length - 1 - suffixLines]
+  ) {
+    suffixLines++
+  }
+  return { prefixLines, suffixLines }
+}
+
+/** Escape a string for literal use inside a `RegExp`. */
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Character-level diff of `current` against `target`: the spans of `current` that are NOT part of `target`
+ * (old text still to be removed). Offsets are char indices into `current`. Recomputed on each edit, this
+ * marks exactly the leftover-old characters — robust to any edit order, including inserting new code into
+ * the middle of the old text, since every keystroke re-classifies old vs. new.
+ */
+export function diffRemovedSpans(current: string, target: string): Array<{ start: number; end: number }> {
+  const spans: Array<{ start: number; end: number }> = []
+  let offset = 0
+  for (const part of diffChars(current, target)) {
+    if (part.added) continue // present only in target → doesn't consume `current`
+    if (part.removed) spans.push({ start: offset, end: offset + part.value.length })
+    offset += part.value.length
+  }
+  return spans
+}
+
+/**
+ * Whether changing `oldText` into `newText` is a single contiguous replacement — one changed region,
+ * possibly with a shared prefix/suffix — rather than several scattered edits. Used to decide whether a
+ * change is worth showing as a precise inline diff, or should be shown as a whole-line replacement (a
+ * scattered char diff between unrelated snippets reads as noise, e.g. `setYpos y:0` → `stepTo Radish`).
+ */
+export function isContiguousDiff(oldText: string, newText: string): boolean {
+  let changeGroups = 0
+  let inChange = false
+  for (const part of diffChars(oldText, newText)) {
+    const changed = part.added === true || part.removed === true
+    if (changed && !inChange) changeGroups++
+    inChange = changed
+  }
+  return changeGroups <= 1
+}
+
+export class CodeGuideController extends Emitter<{ completed: { id: string }; cleared: { id: string } }> {
+  constructor(private ui: CodeEditorUIController) {
+    super()
+  }
+
+  private activeRef = shallowRef<ActiveCodeGuide | null>(null)
+  get active(): ActiveCodeGuide | null {
+    return this.activeRef.value
+  }
+
+  private completionWatcher: (() => void) | null = null
+
+  // Accessor for the active guide's live tracked region (delete/change/type), or null. Lets the renderer
+  // read where the edit region currently is — e.g. to diff its content against the target for the red hint.
+  private activeRegionRange: (() => Range | null) | null = null
+
+  /** The active guide's tracked edit region in its current (post-edit) position, or null. */
+  getActiveEditRange(): Range | null {
+    return this.activeRegionRange?.() ?? null
+  }
+
+  /**
+   * Show a guide. Only one guide can be active at a time; the previous one (if any)
+   * is cleared first. Returns the new guide's ID.
+   */
+  setGuide(guide: CodeGuide): string {
+    this.clearGuide()
+    const id = uniqueId('code-guide-')
+    this.activeRef.value = { id, guide }
+    // Navigate to the target so the guide is visible & its document active.
+    this.ui.open(guide.textDocument, guide.range.start)
+    // For a drag guide, also highlight the matching item in the API reference panel.
+    if (guide.kind === 'drag' && guide.code != null && guide.code !== '') {
+      this.ui.apiReferenceController.highlightForCode(guide.code)
+    }
+    this.watchCompletion(id, guide)
+    return id
+  }
+
+  /** Clear the active guide. When `id` is given, only clears if it matches the active guide. */
+  clearGuide(id?: string): void {
+    const active = this.activeRef.value
+    if (active == null) return
+    if (id != null && active.id !== id) return
+    this.activeRef.value = null
+    this.completionWatcher?.()
+    this.completionWatcher = null
+    this.ui.apiReferenceController.clearHighlight()
+    // Notify the guide's owner (e.g. a chat element) so it can clean up its own side effects, such as a
+    // blank line opened for typing — needed because one reply may have several guides that displace each other.
+    this.emit('cleared', { id: active.id })
+  }
+
+  private watchCompletion(id: string, guide: CodeGuide) {
+    const textDocument = this.ui.codeEditor.getTextDocument(guide.textDocument)
+    if (textDocument == null) return
+    const model = textDocument.monacoTextModel
+
+    // Drag: completion means a new statement of the expected kind appeared (e.g. a new `turn`), rather
+    // than any content change — so editing elsewhere doesn't dismiss the hint. Compile the word matcher
+    // once: it is evaluated on every content change while the guide is active.
+    const dragName = guide.kind === 'drag' && guide.code != null ? leadingIdentifier(guide.code) : ''
+    const dragMatcher = dragName !== '' ? new RegExp(`(^|[^\\w$])${escapeRegExp(dragName)}(?![\\w$])`, 'g') : null
+    const dragBaseline = guide.kind === 'drag' ? textDocument.getValue() : ''
+    const dragBaselineCount = dragMatcher != null ? (textDocument.getValue().match(dragMatcher) ?? []).length : 0
+
+    // Delete / change / type: track the target region with an (invisible) Monaco decoration. Monaco keeps
+    // the decoration's range in sync as the document is edited, so completion looks only at the region's own
+    // current content. This makes it robust to edits elsewhere (line shifts), duplicate snippets, and the
+    // delete-then-retype case. Completion is when the region reaches its target text: empty for a deletion,
+    // the new code for a change, the typed code for a type hint.
+    const trackedTarget = guide.kind === 'change' || guide.kind === 'type' ? normalizeCode(guide.code) : ''
+    let trackId: string | null = null
+    if (guide.kind === 'delete' || guide.kind === 'change' || guide.kind === 'type') {
+      const stickiness =
+        guide.kind === 'delete'
+          ? // Don't grow at edges: an insert right before the highlighted lines should push them down,
+            // not be swallowed into the region we're checking for emptiness.
+            this.ui.monaco.editor.TrackedRangeStickiness.NeverGrowsWhenTypingAtEdges
+          : // Grow at both edges so the region keeps covering the code the user types / the replacement.
+            this.ui.monaco.editor.TrackedRangeStickiness.AlwaysGrowsWhenTypingAtEdges
+      trackId =
+        model.deltaDecorations(
+          [],
+          [
+            {
+              range: {
+                startLineNumber: guide.range.start.line,
+                startColumn: guide.range.start.column,
+                endLineNumber: guide.range.end.line,
+                endColumn: guide.range.end.column
+              },
+              options: { stickiness }
+            }
+          ]
+        )[0] ?? null
+    }
+    const trackedRegion = (): string => {
+      if (trackId == null) return ''
+      const range = model.getDecorationRange(trackId)
+      return range == null ? '' : model.getValueInRange(range)
+    }
+    // Expose the live region so the renderer can diff its content against the target for the red hint.
+    this.activeRegionRange =
+      trackId == null
+        ? null
+        : () => {
+            const r = model.getDecorationRange(trackId)
+            return r == null
+              ? null
+              : {
+                  start: { line: r.startLineNumber, column: r.startColumn },
+                  end: { line: r.endLineNumber, column: r.endColumn }
+                }
+          }
+
+    const isCompleted = (): boolean => {
+      switch (guide.kind) {
+        case 'delete':
+        case 'change':
+        case 'type':
+          // The tracked region reached its target: empty for a deletion, the new/typed code otherwise.
+          return normalizeCode(trackedRegion()) === trackedTarget
+        case 'drag':
+          // A new statement of the expected kind appeared (the block was dropped / typed).
+          if (dragMatcher != null) return (textDocument.getValue().match(dragMatcher) ?? []).length > dragBaselineCount
+          // No expected code to match against: fall back to "any content change".
+          return textDocument.getValue() !== dragBaseline
+      }
+    }
+
+    const off = textDocument.on('didChangeContent', () => {
+      if (this.activeRef.value?.id !== id) return
+      if (!isCompleted()) return
+      this.emit('completed', { id })
+      this.clearGuide(id)
+    })
+    this.completionWatcher = () => {
+      off()
+      if (trackId != null) model.deltaDecorations([trackId], [])
+      this.activeRegionRange = null
+    }
+  }
+
+  dispose() {
+    this.clearGuide()
+    super.dispose()
+  }
+}
diff --git a/spx-gui/src/components/xgo-code-editor/ui/common.ts b/spx-gui/src/components/xgo-code-editor/ui/common.ts
index 0b8cd6e0ca..f2d43c401d 100644
--- a/spx-gui/src/components/xgo-code-editor/ui/common.ts
+++ b/spx-gui/src/components/xgo-code-editor/ui/common.ts
@@ -112,3 +112,48 @@ export function useDecorations(
   })
   onUnmounted(() => collection?.clear())
 }
+
+export type ViewZoneSpec = {
+  /** The view zone is placed after this line number. Use `0` to place it at the very top. */
+  afterLineNumber: number
+  /** Height of the view zone, measured in editor lines. */
+  heightInLines: number
+  /** DOM node rendered inside the view zone. */
+  domNode: HTMLElement
+  /** Optional cleanup run when this zone is removed (e.g. cancel work tied to `domNode`). */
+  onRemove?: () => void
+}
+
+/**
+ * Reactively manage a single Monaco view zone (extra vertical space between lines).
+ * `getZone` is re-evaluated reactively; returning `null` removes the zone.
+ */
+export function useViewZone(getZone: () => ViewZoneSpec | null) {
+  const codeEditorUICtx = useCodeEditorUICtx()
+  let zoneId: string | null = null
+  let zoneCleanup: (() => void) | null = null
+
+  function removeZone() {
+    if (zoneId == null) return
+    const id = zoneId
+    codeEditorUICtx.ui.editor.changeViewZones((accessor) => accessor.removeZone(id))
+    zoneId = null
+    zoneCleanup?.()
+    zoneCleanup = null
+  }
+
+  watchEffect(() => {
+    const zone = getZone()
+    removeZone()
+    if (zone == null) return
+    zoneCleanup = zone.onRemove ?? null
+    codeEditorUICtx.ui.editor.changeViewZones((accessor) => {
+      zoneId = accessor.addZone({
+        afterLineNumber: zone.afterLineNumber,
+        heightInLines: zone.heightInLines,
+        domNode: zone.domNode
+      })
+    })
+  })
+  onUnmounted(removeZone)
+}

From 23a9d0f37d2d23b007088a0a2df0da63e650bc67 Mon Sep 17 00:00:00 2001
From: Ethanlita <lita@ethanlita.com>
Date: Thu, 2 Jul 2026 10:03:56 +0800
Subject: [PATCH 2/2] feat(editor): use token-level diff for code-guide change
 highlight

Comparison variant of the copilot code-guide: the inline change red
highlight (and its inline-vs-whole-line classification) diffs the edit
region against the target at token/word level instead of per character.

Coarser than the character-level diff (a partly-typed token doesn't match
until complete), but avoids character-level noise on unrelated snippets.
Kept on a separate branch so the two behaviors can be compared side by side
in their PR preview environments.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../components/editor/copilot/CodeChange.vue  | 10 ++--
 .../src/components/xgo-code-editor/index.ts   |  9 ++-
 .../ui/code-guide/index.test.ts               | 58 ++++++++++++-------
 .../xgo-code-editor/ui/code-guide/index.ts    | 39 ++++++++++---
 4 files changed, 81 insertions(+), 35 deletions(-)

diff --git a/spx-gui/src/components/editor/copilot/CodeChange.vue b/spx-gui/src/components/editor/copilot/CodeChange.vue
index d79701e680..695d35ddaa 100644
--- a/spx-gui/src/components/editor/copilot/CodeChange.vue
+++ b/spx-gui/src/components/editor/copilot/CodeChange.vue
@@ -53,10 +53,10 @@ import { useSlotText } from '@/utils/vnode'
 import CodeView from '@/components/common/CodeView.vue'
 import {
   CodeLink,
-  diffEdges,
   getTextDocumentId,
   isContiguousDiff,
   leadingIdentifier,
+  tokenDiffEdges,
   trimCommonLines,
   useCodeEditorRef,
   type CodeGuide,
@@ -152,12 +152,12 @@ const changeBase = computed<{ range: Range; oldText: string } | null>(() => {
 type ChangeTarget = { range: Range; code: string; lineInsertion: boolean }
 
 /**
- * Narrow a single-line range by trimming the common prefix/suffix characters (incl. leading whitespace).
- * This is always an in-place edit (`lineInsertion: false`), even when it collapses to an empty range —
- * e.g. prepending text at the start of a line is an inline edit, NOT a new line.
+ * Narrow a single-line range by trimming the common leading/trailing tokens (this token-level variant
+ * keeps whole changed tokens, e.g. `Rawish` → `Radish`, rather than single characters). Always an in-place
+ * edit (`lineInsertion: false`), even when it collapses to an empty range.
  */
 function charTrim(range: Range, oldText: string, newText: string): ChangeTarget {
-  const { prefix, suffix } = diffEdges(oldText, newText)
+  const { prefix, suffix } = tokenDiffEdges(oldText, newText)
   return {
     range: {
       start: { line: range.start.line, column: range.start.column + prefix },
diff --git a/spx-gui/src/components/xgo-code-editor/index.ts b/spx-gui/src/components/xgo-code-editor/index.ts
index aae831a15c..5efe7dbd4e 100644
--- a/spx-gui/src/components/xgo-code-editor/index.ts
+++ b/spx-gui/src/components/xgo-code-editor/index.ts
@@ -31,4 +31,11 @@ export { default as ResourceInput } from './ui/input-helper/ResourceInput.vue'
 export type { ICopilot, CopilotTopic } from './copilot'
 export type { CodeEditorUIController } from './ui/code-editor-ui'
 export type { CodeGuide } from './ui/code-guide'
-export { normalizeCode, diffEdges, trimCommonLines, leadingIdentifier, isContiguousDiff } from './ui/code-guide'
+export {
+  normalizeCode,
+  diffEdges,
+  tokenDiffEdges,
+  trimCommonLines,
+  leadingIdentifier,
+  isContiguousDiff
+} from './ui/code-guide'
diff --git a/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.test.ts b/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.test.ts
index 8ebdf4eddc..9a4bf8bf22 100644
--- a/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.test.ts
+++ b/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, vi } from 'vitest'
 import Emitter from '@/utils/emitter'
 import type { Range, TextDocumentIdentifier } from '../../common'
 import type { CodeEditorUIController } from '../code-editor-ui'
-import { CodeGuideController, diffEdges, diffRemovedSpans, isContiguousDiff, trimCommonLines } from '.'
+import { CodeGuideController, diffEdges, diffRemovedSpans, isContiguousDiff, tokenDiffEdges, trimCommonLines } from '.'
 
 const textDocumentId: TextDocumentIdentifier = { uri: 'file:///Test.spx' }
 
@@ -367,6 +367,20 @@ describe('diffEdges', () => {
   })
 })
 
+describe('tokenDiffEdges', () => {
+  it('trims to whole changed tokens, not individual characters', () => {
+    // a whole word is replaced → nothing shared (character-level would keep "Ra"/"ish")
+    expect(tokenDiffEdges('Rawish', 'Radish')).toEqual({ prefix: 0, suffix: 0 })
+    // common leading token(s) kept; the changed word is the middle
+    expect(tokenDiffEdges('stepTo Rawish', 'stepTo Radish')).toEqual({ prefix: 7, suffix: 0 })
+    expect(tokenDiffEdges('step 90', 'step 180')).toEqual({ prefix: 5, suffix: 0 })
+  })
+
+  it('keeps common leading and trailing tokens around a middle change', () => {
+    expect(tokenDiffEdges('a b c', 'a X c')).toEqual({ prefix: 2, suffix: 2 })
+  })
+})
+
 describe('trimCommonLines', () => {
   it('drops identical leading and trailing lines', () => {
     // shared first line "\tturn -60"; only the second line differs
@@ -390,37 +404,39 @@ describe('trimCommonLines', () => {
   })
 })
 
-describe('diffRemovedSpans', () => {
-  it('marks the old text still present, regardless of where the new code was typed', () => {
-    // new code typed to the right of the old → only the old "old" is removed
-    expect(diffRemovedSpans('oldnew', 'new')).toEqual([{ start: 0, end: 3 }])
-    // new code typed to the left of the old → only the trailing old is removed
-    expect(diffRemovedSpans('newold', 'new')).toEqual([{ start: 3, end: 6 }])
-  })
+describe('diffRemovedSpans (token level)', () => {
+  // The chars of `current` that survive (are NOT marked for removal).
+  const keptText = (current: string, target: string) => {
+    let out = ''
+    let last = 0
+    for (const span of diffRemovedSpans(current, target)) {
+      out += current.slice(last, span.start)
+      last = span.end
+    }
+    return out + current.slice(last)
+  }
 
-  it('handles old text on both sides of the new code (typed into the middle)', () => {
-    // "x" + kept "new" + "y": both leftover chunks are removed, the new code in the middle is kept
-    expect(diffRemovedSpans('xnewy', 'new')).toEqual([
-      { start: 0, end: 1 },
-      { start: 4, end: 5 }
-    ])
+  it('keeps a matching word wherever it appears and marks the surrounding old words for removal', () => {
+    expect(keptText('setYpos step', 'step')).toBe('step') // typed at the end
+    expect(keptText('step setYpos', 'step')).toBe('step') // typed at the start
+    expect(keptText('a step b', 'step')).toBe('step') // typed in the middle
   })
 
   it('returns no spans once the content matches the target, or for a pure insertion', () => {
-    expect(diffRemovedSpans('new', 'new')).toEqual([])
-    expect(diffRemovedSpans('', 'new')).toEqual([]) // nothing old to remove yet
+    expect(diffRemovedSpans('step', 'step')).toEqual([])
+    expect(diffRemovedSpans('', 'step')).toEqual([]) // nothing old to remove yet
   })
 })
 
-describe('isContiguousDiff', () => {
-  it('is true for a single contiguous replacement (with shared prefix/suffix)', () => {
-    expect(isContiguousDiff('AoldB', 'AnewB')).toBe(true)
+describe('isContiguousDiff (token level)', () => {
+  it('is true for a single contiguous replacement', () => {
     expect(isContiguousDiff('step 90', 'step 180')).toBe(true)
+    expect(isContiguousDiff('turnTo Radish', 'turnTo Stone3')).toBe(true)
     expect(isContiguousDiff('', 'say "hi"')).toBe(true) // pure insertion
   })
 
-  it('is false when the edits are scattered across unrelated text', () => {
-    expect(isContiguousDiff('xAxBx', 'AB')).toBe(false) // "x" removed in three separate places
+  it('is false when unrelated tokens change across the text', () => {
+    expect(isContiguousDiff('foo bar', 'baz qux')).toBe(false) // both words differ
     expect(isContiguousDiff('setYpos y:0', 'stepTo Radish')).toBe(false)
   })
 })
diff --git a/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.ts b/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.ts
index 675ca5dc94..da477040fa 100644
--- a/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.ts
+++ b/spx-gui/src/components/xgo-code-editor/ui/code-guide/index.ts
@@ -7,7 +7,7 @@
 
 import { shallowRef } from 'vue'
 import { uniqueId } from 'lodash'
-import { diffChars } from 'diff'
+import { diffWordsWithSpace } from 'diff'
 import Emitter from '@/utils/emitter'
 import { type Range, type TextDocumentIdentifier } from '../../common'
 import type { CodeEditorUIController } from '../code-editor-ui'
@@ -74,6 +74,28 @@ export function diffEdges(oldText: string, newText: string): { prefix: number; s
   return { prefix, suffix }
 }
 
+/**
+ * Like `diffEdges`, but aligned to whole tokens: the char length of the common leading and (non-overlapping)
+ * trailing tokens shared by `oldText` and `newText`. Narrows a change to the tokens that differ (e.g.
+ * `Rawish` → `Radish` as a whole word), rather than to individual characters.
+ */
+export function tokenDiffEdges(oldText: string, newText: string): { prefix: number; suffix: number } {
+  const parts = diffWordsWithSpace(oldText, newText)
+  let prefix = 0
+  let i = 0
+  while (i < parts.length && parts[i].added !== true && parts[i].removed !== true) {
+    prefix += parts[i].value.length
+    i++
+  }
+  let suffix = 0
+  let j = parts.length - 1
+  while (j >= i && parts[j].added !== true && parts[j].removed !== true) {
+    suffix += parts[j].value.length
+    j--
+  }
+  return { prefix, suffix }
+}
+
 /**
  * Number of identical leading and (non-overlapping) trailing lines shared by `oldText` and `newText`.
  * Lets a multi-line change drop unchanged lines (including shared indentation lines) and narrow to the
@@ -107,15 +129,16 @@ function escapeRegExp(s: string): string {
 }
 
 /**
- * Character-level diff of `current` against `target`: the spans of `current` that are NOT part of `target`
- * (old text still to be removed). Offsets are char indices into `current`. Recomputed on each edit, this
- * marks exactly the leftover-old characters — robust to any edit order, including inserting new code into
- * the middle of the old text, since every keystroke re-classifies old vs. new.
+ * Token-level diff of `current` against `target`: the spans of `current` that are NOT part of `target`
+ * (old tokens still to be removed). Offsets are char indices into `current`. Recomputed on each edit, this
+ * marks the leftover-old tokens — whole words the user has already typed are matched against the target and
+ * left un-marked, wherever they appear. Coarser than a per-character diff (a partly-typed token does not
+ * match yet), but avoids character-level noise on unrelated snippets.
  */
 export function diffRemovedSpans(current: string, target: string): Array<{ start: number; end: number }> {
   const spans: Array<{ start: number; end: number }> = []
   let offset = 0
-  for (const part of diffChars(current, target)) {
+  for (const part of diffWordsWithSpace(current, target)) {
     if (part.added) continue // present only in target → doesn't consume `current`
     if (part.removed) spans.push({ start: offset, end: offset + part.value.length })
     offset += part.value.length
@@ -127,12 +150,12 @@ export function diffRemovedSpans(current: string, target: string): Array<{ start
  * Whether changing `oldText` into `newText` is a single contiguous replacement — one changed region,
  * possibly with a shared prefix/suffix — rather than several scattered edits. Used to decide whether a
  * change is worth showing as a precise inline diff, or should be shown as a whole-line replacement (a
- * scattered char diff between unrelated snippets reads as noise, e.g. `setYpos y:0` → `stepTo Radish`).
+ * scattered diff between unrelated snippets reads as noise, e.g. `setYpos y:0` → `stepTo Radish`).
  */
 export function isContiguousDiff(oldText: string, newText: string): boolean {
   let changeGroups = 0
   let inChange = false
-  for (const part of diffChars(oldText, newText)) {
+  for (const part of diffWordsWithSpace(oldText, newText)) {
     const changed = part.added === true || part.removed === true
     if (changed && !inChange) changeGroups++
     inChange = changed