From c7b41c8847c5ff0946870abfcc8817cc54472aa5 Mon Sep 17 00:00:00 2001
From: Seungpyo1007 <rush94434@gmail.com>
Date: Thu, 6 Aug 2026 11:52:08 +0900
Subject: [PATCH] =?UTF-8?q?=ED=99=95=EC=9E=A5=EC=9D=98=20=EB=8D=B0?=
 =?UTF-8?q?=EC=BD=94=EB=A0=88=EC=9D=B4=EC=85=98=EC=9D=84=20=EC=8B=A4?=
 =?UTF-8?q?=EC=A0=9C=EB=A1=9C=20=EA=B7=B8=EB=A6=AC=EA=B3=A0,=20=ED=99=9C?=
 =?UTF-8?q?=EC=84=B1=20=ED=8E=B8=EC=A7=91=EA=B8=B0=20=EC=82=AC=EA=B1=B4?=
 =?UTF-8?q?=EC=9D=84=20=EC=A0=9C=EB=95=8C=20=EC=8F=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

createTextEditorDecorationType 은 멀쩡해 보이는 핸들을 돌려주고 setDecorations 는
범위를 받아 놓고, 아무것도 그리지 않았다. 0.2.0 이 한 판을 통째로 들여 없앤
"조용히 성공하는 답" 이 마지막으로 남아 있던 자리다.

두 API 의 모양이 다르다. VS Code 는 CSS 를 그대로 받고 Monaco 는 클래스 이름만
받는다. 그래서 타입 하나당 규칙을 만들어 스타일시트에 넣고 Monaco 에는 그 이름을
준다. 변환은 decorations.ts 에 순수 함수로 두어 그대로 시험한다 — 확장이 준
contentText 의 따옴표·역슬래시를 막는 것도 여기다(안 막으면 규칙 밖으로 새어
스타일시트 전체가 깨진다). 스타일시트는 한 장을 공유한다. 타입마다 <style> 을
만들면 줄마다 색이 다른 흔한 확장에서 head 가 수천 개로 불어난다.

빈 배열은 "그 타입으로 그린 것을 전부 지운다" 로 동작하고, 확장이 내려가면
그려 둔 것까지 걷는다. 빈 옵션으로 타입을 만들면 경고한다 — 조용히 성공을
답하는 것이 여기서 없애려던 그 모양이다.

그리고 고치다 더 큰 것을 찾았다. onDidChangeActiveTextEditor 가 잘못된 편집기를
주고 있었다. openFile 이 setState 전에 사건을 쏘는데 그 시점엔 페인도 모델도
없어서 shimDocFor 가 빈손으로 돌아오고, 거기서 사건이 함께 끊겼다. 결과적으로
새 파일을 열면 확장은 사건을 아예 못 받고, 받은 한 번은 이전 파일의 편집기였다.
데코레이션을 쓰는 확장은 거의 다 이 사건에 매달려 그리므로 실사용에서는
아무것도 안 그려졌을 것이다. 이제 페인이 실제로 뜰 때까지 최대 1초 기다렸다
쏘고, 같은 파일로 두 번 쏘지 않는다.

임시 확장을 실제로 깔아 CDP 로 몰아 7/7. 계산된 배경색이
rgba(143,168,147,0.35) 이고 ::after 가 실제로 그려지며, 탭을 바꾸면 다시
그려지는 것까지(사건 2회) 확인했다. 단위 28개 추가(1009개 통과).
---
 README.md                       |  17 ++--
 ide/src/editor/MonacoPane.tsx   |  15 +++-
 ide/src/ext/decoStore.ts        |  91 +++++++++++++++++++
 ide/src/ext/decorations.test.ts | 151 ++++++++++++++++++++++++++++++++
 ide/src/ext/decorations.ts      | 136 ++++++++++++++++++++++++++++
 ide/src/ext/extHost.ts          |  42 ++++++++-
 ide/src/ext/shimDoc.ts          |   9 +-
 ide/src/ext/vscodeShim.ts       |  23 ++++-
 ide/vitest.config.ts            |   2 +-
 9 files changed, 475 insertions(+), 11 deletions(-)
 create mode 100644 ide/src/ext/decoStore.ts
 create mode 100644 ide/src/ext/decorations.test.ts
 create mode 100644 ide/src/ext/decorations.ts

diff --git a/README.md b/README.md
index 0e86b0a..e2e28f7 100644
--- a/README.md
+++ b/README.md
@@ -137,12 +137,17 @@ files, and the shim has no custom editors and no debug adapter API. Those three
 `WorkspaceEdit` throws, and the other two are absent from the API object, so calling one is a
 `TypeError` rather than a quiet nothing.
 
-One gap does not behave that way, and saying otherwise here was worse than the gap itself:
-**`createTextEditorDecorationType` returns a working-looking handle and `setDecorations`
-accepts ranges, and nothing is ever drawn.** An extension doing inline blame or coverage
-highlighting gets a successful answer and no pixels. It is the one place left with the shape
-this project spent a release removing; it is named here until it is built rather than
-described as something it is not.
+Decorations used to sit in that list as the one gap that answered successfully and drew
+nothing. They now draw: `createTextEditorDecorationType` compiles the requested styling into
+a real rule, `setDecorations` puts it on the Monaco editor, and passing an empty array clears
+what that type drew. Inline blame and coverage highlighting work, `before`/`after` content
+included.
+
+Fixing it surfaced the reason such an extension would have appeared broken anyway:
+`onDidChangeActiveTextEditor` fired before the editor existed, and the notification was
+dropped on the way out, so opening a file delivered either nothing or the *previous* file's
+editor. Extensions that draw on editor changes — which is most of them — were being handed
+the wrong editor. The event now waits for the pane and fires once per file.
 
 ## Contributing
 
diff --git a/ide/src/editor/MonacoPane.tsx b/ide/src/editor/MonacoPane.tsx
index ff3df98..949758d 100644
--- a/ide/src/editor/MonacoPane.tsx
+++ b/ide/src/editor/MonacoPane.tsx
@@ -60,7 +60,19 @@ export interface PaneApi {
   editor: monaco.editor.IStandaloneCodeEditor;
   save: () => Promise<void>;
 }
-export const paneRegistry: { panes: Map<string, PaneApi>; focused: PaneApi | null } = {
+/** 페인 하나가 실제로 뜬 뒤에 부른다.
+ *
+ *  확장에게 "이 편집기가 활성이다" 를 알리는 시점이 여기여야 한다. 예전엔 openFile 이
+ *  setState 전에 알려서, 그 사건을 받은 확장이 곧장 setDecorations 를 불러도 붙일
+ *  편집기가 아직 없었다 — 조용히 아무 일도 안 일어났다. 데코레이션을 쓰는 확장은
+ *  거의 다 이 사건에 매달려 그린다.
+ *
+ *  훅 필드로 두는 이유는 순환 임포트를 피하기 위해서다(extHost 가 여기를 읽는다). */
+export const paneRegistry: {
+  panes: Map<string, PaneApi>;
+  focused: PaneApi | null;
+  onReady?: (rel: string) => void;
+} = {
   panes: new Map(),
   focused: null,
 };
@@ -193,6 +205,7 @@ function MonacoPaneImpl({ root, rel, onDirtyChange, onSaved, onConfirm, onStatus
 
       const api: PaneApi = { rel, editor, save };
       paneRegistry.panes.set(rel, api);
+      try { paneRegistry.onReady?.(rel); } catch { /* 확장이 던져도 페인은 살아 있어야 한다 */ }
       editor.onDidFocusEditorWidget(() => {
         paneRegistry.focused = api;
         const p = editor!.getPosition();
diff --git a/ide/src/ext/decoStore.ts b/ide/src/ext/decoStore.ts
new file mode 100644
index 0000000..a92cf56
--- /dev/null
+++ b/ide/src/ext/decoStore.ts
@@ -0,0 +1,91 @@
+// 데코레이션 타입을 실제로 화면에 붙이는 쪽. 변환 규칙은 decorations.ts 에 있고,
+// 여기는 스타일시트 한 장과 편집기별 적용분을 들고 있는 살림꾼이다.
+//
+// 스타일시트가 한 장인 이유: 타입마다 <style> 을 만들면 확장이 데코레이션 타입을
+// 자주 만들고 버리는 흔한 꼴(줄마다 다른 색)에서 head 가 수천 개로 불어난다.
+
+import type monacoNS from "monaco-editor";
+import { styleSheetFor, monacoOptions, normalizeDecos, drawsNothing } from "./decorations";
+
+let sheet: HTMLStyleElement | null = null;
+const rules = new Map<string, string>();   // 타입 id → 규칙 전문
+let seq = 0;
+
+function flush(): void {
+  if (typeof document === "undefined") return;
+  if (!sheet) {
+    sheet = document.createElement("style");
+    sheet.setAttribute("data-schutz", "ext-decorations");
+    document.head.appendChild(sheet);
+  }
+  sheet.textContent = [...rules.values()].filter(Boolean).join("\n");
+}
+
+type Collection = monacoNS.editor.IEditorDecorationsCollection;
+
+export interface DecoTypeHandle {
+  /** Monaco 에 넘길 옵션 — setDecorations 가 읽는다. */
+  readonly _szDeco: ReturnType<typeof monacoOptions>;
+  readonly key: string;
+  /** 이 타입이 아무것도 안 그리는가(확장이 빈 옵션을 준 경우). */
+  readonly _szEmpty: boolean;
+  /** 편집기별로 지금 그려 둔 것. 같은 타입으로 다시 설정하면 갈아끼워야 한다(누적이 아니다). */
+  readonly _szByEditor: WeakMap<object, Collection>;
+  /** 폐기할 때 걷어야 하므로 따로 모아 둔다 — WeakMap 은 훑을 수 없다. */
+  readonly _szCols: Set<Collection>;
+  dispose(): void;
+}
+
+/** vscode.window.createTextEditorDecorationType */
+export function createDecoType(opts: any): DecoTypeHandle {
+  const id = String(++seq);
+  const css = styleSheetFor(id, opts);
+  if (css) { rules.set(id, css); flush(); }
+  const options = monacoOptions(id, opts);
+  const empty = drawsNothing(opts);
+  const cols = new Set<Collection>();
+  return {
+    _szDeco: options,
+    _szEmpty: empty,
+    _szByEditor: new WeakMap<object, Collection>(),
+    _szCols: cols,
+    key: "szdeco-" + id,
+    dispose() {
+      rules.delete(id);
+      flush();
+      // 이 타입으로 그려 둔 것도 함께 걷는다 — 규칙만 지우면 클래스 없는
+      // 데코레이션이 남아 다음 편집에서 엉뚱한 자리를 잡는다.
+      for (const c of cols) { try { c.clear(); } catch { /* 이미 폐기된 편집기 */ } }
+      cols.clear();
+    },
+  };
+}
+
+/** vscode.TextEditor.setDecorations */
+export function applyDecos(editor: any, type: any, list: any): void {
+  const h = type as DecoTypeHandle | undefined;
+  if (!editor || !h?._szDeco || !h._szByEditor) return;
+
+  const decos = normalizeDecos(list).map(d => ({
+    range: d.range,
+    options: d.hover ? { ...h._szDeco, hoverMessage: { value: d.hover } } : h._szDeco,
+  }));
+
+  const existing = h._szByEditor.get(editor);
+  if (existing) {
+    // set([]) 이 곧 "이 타입으로 그린 것을 전부 지운다" 이다. 확장이 그렇게 지운다.
+    try { existing.set(decos as any); } catch { /* 폐기된 편집기 */ }
+    return;
+  }
+  if (!decos.length) return;   // 지울 것도 그릴 것도 없다
+  try {
+    const c = editor.createDecorationsCollection(decos) as Collection;
+    h._szByEditor.set(editor, c);
+    h._szCols.add(c);
+  } catch { /* 폐기된 편집기 */ }
+}
+
+/** 확장 하나가 내려갈 때 그 확장이 만든 타입을 전부 정리한다. */
+export function disposeAllDecos(handles: Iterable<DecoTypeHandle>): void {
+  for (const h of handles) { try { h.dispose(); } catch { /* */ } }
+}
diff --git a/ide/src/ext/decorations.test.ts b/ide/src/ext/decorations.test.ts
new file mode 100644
index 0000000..d75f3f8
--- /dev/null
+++ b/ide/src/ext/decorations.test.ts
@@ -0,0 +1,151 @@
+import { describe, it, expect } from "vitest";
+import {
+  cssColor, cssDecls, pseudoDecls, classNames, styleSheetFor,
+  monacoOptions, drawsNothing, normalizeDecos, hoverText,
+} from "./decorations";
+
+describe("cssColor", () => {
+  it("문자열 색은 그대로 쓴다", () => {
+    expect(cssColor("#8FA893")).toBe("#8FA893");
+    expect(cssColor("  rgba(0,0,0,.2) ")).toBe("rgba(0,0,0,.2)");
+  });
+  it("ThemeColor 는 우리 토큰과 대응이 없어 버린다", () => {
+    expect(cssColor({ id: "editor.background" })).toBeNull();
+  });
+  it("빈 값은 색이 아니다", () => {
+    expect(cssColor("")).toBeNull();
+    expect(cssColor(undefined)).toBeNull();
+    expect(cssColor(null)).toBeNull();
+  });
+});
+
+describe("cssDecls", () => {
+  it("알아듣는 속성을 CSS 선언으로 옮긴다", () => {
+    const d = cssDecls({ backgroundColor: "#222", color: "red", fontWeight: "bold" });
+    expect(d).toContain("background:#222");
+    expect(d).toContain("color:red");
+    expect(d).toContain("font-weight:bold");
+  });
+  it("모르는 속성은 조용히 넘긴다", () => {
+    expect(cssDecls({ someFutureThing: "x" })).toEqual([]);
+  });
+  it("ThemeColor 로 온 색은 그 속성만 빠지고 나머지는 남는다", () => {
+    const d = cssDecls({ backgroundColor: { id: "editor.bg" }, color: "red" });
+    expect(d).toEqual(["color:red"]);
+  });
+  it("빈 옵션에도 터지지 않는다", () => {
+    expect(cssDecls(undefined)).toEqual([]);
+    expect(cssDecls(null)).toEqual([]);
+  });
+});
+
+describe("pseudoDecls", () => {
+  it("contentText 가 있어야 만든다", () => {
+    expect(pseudoDecls({ color: "red" })).toBeNull();
+    expect(pseudoDecls({ contentText: "" })).toBeNull();
+    expect(pseudoDecls(undefined)).toBeNull();
+  });
+  it("글자와 스타일을 함께 낸다", () => {
+    const d = pseudoDecls({ contentText: " 3 refs", color: "#888", margin: "0 0 0 1em" });
+    expect(d).toContain('content:" 3 refs"');
+    expect(d).toContain("color:#888");
+    expect(d).toContain("margin:0 0 0 1em");
+  });
+  // 확장이 준 문자열이 규칙 밖으로 새어 나가면 스타일시트 전체가 깨진다.
+  it("따옴표와 역슬래시를 막는다", () => {
+    const d = pseudoDecls({ contentText: 'a"b\\c' });
+    expect(d![0]).toBe('content:"a\\"b\\\\c"');
+  });
+  it("줄바꿈은 한 줄로 눕힌다", () => {
+    expect(pseudoDecls({ contentText: "a\nb" })![0]).toBe('content:"a b"');
+  });
+});
+
+describe("styleSheetFor", () => {
+  it("본문과 앞뒤를 각각 규칙으로 낸다", () => {
+    const css = styleSheetFor("7", { backgroundColor: "#111", after: { contentText: "x" } });
+    expect(css).toContain(".szdeco-7{background:#111}");
+    expect(css).toContain('.szdeco-7-a::after{content:"x"}');
+  });
+  it("그릴 것이 없으면 빈 문자열", () => {
+    expect(styleSheetFor("7", {})).toBe("");
+    expect(styleSheetFor("7", { isWholeLine: true })).toBe("");
+  });
+  it("클래스 이름은 id 로 갈린다", () => {
+    expect(classNames("1").base).not.toBe(classNames("2").base);
+  });
+});
+
+describe("monacoOptions", () => {
+  it("글자 범위는 inlineClassName 으로 간다", () => {
+    const o = monacoOptions("1", { backgroundColor: "#111" });
+    expect(o.inlineClassName).toBe("szdeco-1");
+    expect(o.className).toBeUndefined();
+  });
+  it("줄 전체는 className 과 isWholeLine 으로 간다", () => {
+    const o = monacoOptions("1", { backgroundColor: "#111", isWholeLine: true });
+    expect(o.className).toBe("szdeco-1");
+    expect(o.inlineClassName).toBeUndefined();
+    expect(o.isWholeLine).toBe(true);
+  });
+  it("스타일이 없어도 앞뒤 글자만으로 그린다", () => {
+    const o = monacoOptions("1", { after: { contentText: "→" } });
+    expect(o.afterContentClassName).toBe("szdeco-1-a");
+    expect(o.inlineClassName).toBeUndefined();
+  });
+  it("개요 눈금 색을 옮긴다", () => {
+    expect(monacoOptions("1", { overviewRulerColor: "#C97B7B" }).overviewRuler).toEqual({ color: "#C97B7B", position: 1 });
+  });
+  it("ThemeColor 눈금은 대응이 없어 빠진다", () => {
+    expect(monacoOptions("1", { overviewRulerColor: { id: "x" } }).overviewRuler).toBeUndefined();
+  });
+});
+
+describe("drawsNothing", () => {
+  it("빈 옵션은 아무것도 안 그린다", () => {
+    expect(drawsNothing({})).toBe(true);
+    expect(drawsNothing({ isWholeLine: true })).toBe(true);
+  });
+  it("무엇이든 하나 있으면 그린다", () => {
+    expect(drawsNothing({ backgroundColor: "#111" })).toBe(false);
+    expect(drawsNothing({ before: { contentText: "•" } })).toBe(false);
+    expect(drawsNothing({ overviewRulerColor: "red" })).toBe(false);
+  });
+});
+
+describe("normalizeDecos", () => {
+  const R = (l: number, c: number, l2: number, c2: number) => ({ start: { line: l, character: c }, end: { line: l2, character: c2 } });
+
+  it("Range 배열을 받는다", () => {
+    expect(normalizeDecos([R(0, 0, 0, 4)])).toEqual([{ range: { startLineNumber: 1, startColumn: 1, endLineNumber: 1, endColumn: 5 } }]);
+  });
+  it("DecorationOptions 배열도 받는다", () => {
+    const out = normalizeDecos([{ range: R(2, 1, 2, 3), hoverMessage: "왜" }]);
+    expect(out).toEqual([{ range: { startLineNumber: 3, startColumn: 2, endLineNumber: 3, endColumn: 4 }, hover: "왜" }]);
+  });
+  it("배열이 아니면 빈 목록", () => {
+    expect(normalizeDecos(undefined)).toEqual([]);
+    expect(normalizeDecos(null)).toEqual([]);
+    expect(normalizeDecos("nope")).toEqual([]);
+  });
+  it("빈 칸은 건너뛴다", () => {
+    expect(normalizeDecos([null, undefined, {}])).toEqual([]);
+  });
+  it("빈 배열은 '전부 지우기' 다 — 빈 목록으로 그대로 전한다", () => {
+    expect(normalizeDecos([])).toEqual([]);
+  });
+});
+
+describe("hoverText", () => {
+  it("문자열·MarkdownString·배열을 모두 받는다", () => {
+    expect(hoverText("a")).toBe("a");
+    expect(hoverText({ value: "**b**" })).toBe("**b**");
+    expect(hoverText(["a", { value: "b" }])).toBe("a\n\nb");
+  });
+  it("비어 있으면 없는 것으로 친다", () => {
+    expect(hoverText("")).toBeUndefined();
+    expect(hoverText({ value: "" })).toBeUndefined();
+    expect(hoverText([])).toBeUndefined();
+    expect(hoverText(undefined)).toBeUndefined();
+  });
+});
diff --git a/ide/src/ext/decorations.ts b/ide/src/ext/decorations.ts
new file mode 100644
index 0000000..89ac244
--- /dev/null
+++ b/ide/src/ext/decorations.ts
@@ -0,0 +1,136 @@
+// 확장이 요구한 데코레이션을 Monaco 가 그릴 수 있는 모양으로 옮긴다.
+//
+// 여기가 0.2.0 이 한 판을 통째로 들여 없앤 그 모양이 마지막으로 남아 있던 자리다.
+// `createTextEditorDecorationType` 은 멀쩡해 보이는 핸들을 돌려주고 `setDecorations` 는
+// 범위를 받아 놓고, 아무것도 그리지 않았다. 인라인 blame 이나 커버리지 표시를 하는
+// 확장은 성공을 답으로 받고 화면에는 아무것도 못 얻었다.
+//
+// 두 API 의 모양이 다르다. VS Code 는 CSS 를 그대로 받는다(backgroundColor, border,
+// textDecoration…). Monaco 는 클래스 이름만 받고 그 클래스가 어딘가 정의돼 있기를
+// 기대한다. 그래서 타입 하나당 규칙을 만들어 스타일시트에 넣고, Monaco 에는 그 이름을
+// 준다. 이 파일은 그 변환만 한다 — DOM 도 monaco 도 건드리지 않아 그대로 시험할 수 있다.
+
+import { toMonacoRange, type MonacoRange } from "./shimLang";
+
+/** CSS 값으로 쓸 수 있는 색인가. ThemeColor({id}) 는 우리 토큰과 이름이 달라 못 쓴다. */
+export function cssColor(v: unknown): string | null {
+  if (typeof v === "string") return v.trim() || null;
+  // vscode.ThemeColor — VS Code 의 색 이름 체계라 우리 테마에 대응이 없다.
+  // 억지로 매핑하면 엉뚱한 색이 나오므로 그 속성만 뺀다(그린다는 사실은 유지된다).
+  return null;
+}
+
+/** VS Code 데코레이션 옵션 → CSS 선언 목록. 알아듣는 것만 옮긴다. */
+export function cssDecls(opts: any): string[] {
+  const out: string[] = [];
+  const put = (prop: string, v: unknown) => { const c = typeof v === "string" ? v.trim() : cssColor(v); if (c) out.push(`${prop}:${c}`); };
+  put("background", opts?.backgroundColor);
+  put("color", opts?.color);
+  put("border", opts?.border);
+  put("border-color", opts?.borderColor);
+  put("border-style", opts?.borderStyle);
+  put("border-width", opts?.borderWidth);
+  put("border-radius", opts?.borderRadius);
+  put("outline", opts?.outline);
+  put("text-decoration", opts?.textDecoration);
+  put("font-style", opts?.fontStyle);
+  put("font-weight", opts?.fontWeight);
+  put("letter-spacing", opts?.letterSpacing);
+  put("opacity", opts?.opacity);
+  return out;
+}
+
+/** before/after 는 가짜 요소로 그린다. contentText 가 없으면 만들 이유가 없다. */
+export function pseudoDecls(side: any): string[] | null {
+  if (!side || typeof side !== "object") return null;
+  const text = side.contentText;
+  if (typeof text !== "string" || text === "") return null;
+  // 따옴표와 역슬래시를 막지 않으면 확장이 준 문자열이 CSS 규칙을 깨고 나온다.
+  const safe = text.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, " ");
+  return [`content:"${safe}"`, ...cssDecls(side), ...(side.margin ? [`margin:${String(side.margin)}`] : [])];
+}
+
+/** 타입 하나가 쓸 클래스 이름들. id 는 부르는 쪽이 붙인 일련번호다. */
+export function classNames(id: string) {
+  return { base: `szdeco-${id}`, before: `szdeco-${id}-b`, after: `szdeco-${id}-a` };
+}
+
+/** 스타일시트에 넣을 규칙 전문. 넣을 것이 없으면 빈 문자열. */
+export function styleSheetFor(id: string, opts: any): string {
+  const n = classNames(id);
+  const rules: string[] = [];
+  const main = cssDecls(opts);
+  if (main.length) rules.push(`.${n.base}{${main.join(";")}}`);
+  const before = pseudoDecls(opts?.before);
+  if (before) rules.push(`.${n.before}::before{${before.join(";")}}`);
+  const after = pseudoDecls(opts?.after);
+  if (after) rules.push(`.${n.after}::after{${after.join(";")}}`);
+  return rules.join("\n");
+}
+
+export interface MonacoDecoOptions {
+  className?: string;
+  inlineClassName?: string;
+  beforeContentClassName?: string;
+  afterContentClassName?: string;
+  isWholeLine?: boolean;
+  stickiness?: number;
+  overviewRuler?: { color: string; position: number };
+  minimap?: { color: string; position: number };
+}
+
+/** Monaco 가 받는 옵션. 클래스가 하나도 안 붙으면 그릴 것이 없다는 뜻이다. */
+export function monacoOptions(id: string, opts: any): MonacoDecoOptions {
+  const n = classNames(id);
+  const o: MonacoDecoOptions = {};
+  const whole = opts?.isWholeLine === true;
+  if (cssDecls(opts).length) {
+    // 줄 전체는 className(줄 배경), 글자 범위는 inlineClassName 이 맞는 자리다.
+    if (whole) o.className = n.base; else o.inlineClassName = n.base;
+  }
+  if (whole) o.isWholeLine = true;
+  if (pseudoDecls(opts?.before)) o.beforeContentClassName = n.before;
+  if (pseudoDecls(opts?.after)) o.afterContentClassName = n.after;
+  const ruler = cssColor(opts?.overviewRulerColor);
+  // 1 = Left. VS Code 의 overviewRulerLane 과 숫자가 다르지만, 레인 선택까지 옮기면
+  // 대응이 없는 값에서 아무것도 안 그리게 된다 — 보이는 쪽을 택한다.
+  if (ruler) o.overviewRuler = { color: ruler, position: 1 };
+  // 어느 줄이 늘어날 때 데코레이션이 따라 늘지 — VS Code 기본과 같은 쪽으로.
+  o.stickiness = 1;
+  return o;
+}
+
+/** 그릴 것이 하나도 없는 타입인가. 있으면 확장에게 알려 줄 수 있다. */
+export function drawsNothing(opts: any): boolean {
+  const o = monacoOptions("x", opts);
+  return !o.className && !o.inlineClassName && !o.beforeContentClassName && !o.afterContentClassName && !o.overviewRuler;
+}
+
+export interface NormDeco { range: MonacoRange; hover?: string }
+
+/** setDecorations 는 Range[] 도 DecorationOptions[] 도 받는다. 둘 다 받아 준다. */
+export function normalizeDecos(list: any): NormDeco[] {
+  if (!Array.isArray(list)) return [];
+  const out: NormDeco[] = [];
+  for (const it of list) {
+    if (!it) continue;
+    // DecorationOptions 면 range 를 품고 있고, 아니면 그 자체가 Range 다.
+    const r = it.range ?? it;
+    if (!r || (r.start === undefined && !Array.isArray(r))) continue;
+    const hover = hoverText(it.hoverMessage);
+    out.push(hover ? { range: toMonacoRange(r), hover } : { range: toMonacoRange(r) });
+  }
+  return out;
+}
+
+/** hoverMessage 는 문자열·MarkdownString·그 배열 중 아무거나로 온다. */
+export function hoverText(v: any): string | undefined {
+  if (v == null) return undefined;
+  if (typeof v === "string") return v || undefined;
+  if (Array.isArray(v)) {
+    const parts = v.map(hoverText).filter(Boolean);
+    return parts.length ? parts.join("\n\n") : undefined;
+  }
+  const s = typeof v.value === "string" ? v.value : "";
+  return s || undefined;
+}
diff --git a/ide/src/ext/extHost.ts b/ide/src/ext/extHost.ts
index 11a2206..a08c281 100644
--- a/ide/src/ext/extHost.ts
+++ b/ide/src/ext/extHost.ts
@@ -4,6 +4,7 @@
 import { makeVscodeApi, disposeShimRegistrations, deliverFsDelta, listExtViews, onExtViewsChanged } from "./vscodeShim";
 import { onHook, clearHooks, emitHook, HOOK_EVENTS, type HookEvent } from "./hooks";
 import { editorEvents } from "./vscodeShim";
+import { paneRegistry } from "../editor/MonacoPane";
 import { t } from "../i18n";
 
 export interface ExtCommand { id: string; title: string; run: (...args: any[]) => any; source: string; }
@@ -56,12 +57,51 @@ export function notifyExtensions(ev: HookEvent, payload: Record<string, unknown>
   // 빈 EventEmitter 였다 — onDidSaveTextDocument 를 구독한 확장은 영원히 안 불렸다.
   const rel = typeof payload.rel === "string" ? payload.rel : null;
   if (!rel) return;
+  // 활성 편집기 통지는 문서가 아직 없어도 걸어 둔다 — 새로 여는 파일은 이 시점에
+  // 모델도 페인도 없어서 shimDocFor 가 빈손으로 돌아온다. 예전엔 그 자리에서 함께
+  // 끊겨, 탭을 바꿔도 확장은 영영 못 듣고 데코레이션이 다시 그려지지 않았다.
+  if (ev === "file.open") notifyActiveEditor(rel);
   const doc = shimDocFor(rel);
   if (!doc) return;
-  if (ev === "file.open") { editorEvents.docOpened.fire(doc); editorEvents.activeChanged.fire(shimEditorFor(rel)); }
+  if (ev === "file.open") editorEvents.docOpened.fire(doc);
   else if (ev === "file.save") editorEvents.docSaved.fire(doc);
 }
 
+/** "이 편집기가 활성이다" 를 확장에게 알린다.
+ *
+ *  **페인이 실제로 떠 있을 때만 쏜다.** 아직 없으면 이 사건을 받은 확장이 곧장
+ *  setDecorations 를 불러도 붙일 자리가 없어 조용히 사라진다 — 데코레이션을 쓰는
+ *  확장은 거의 다 이 사건에 매달려 그리므로, 이르게 쏘면 안 쏜 것과 같다.
+ *
+ *  openFile 은 setState 전에 부르고, 탭을 바꿀 때 페인이 다시 마운트되지 않는
+ *  경우도 있다(모델만 갈아끼운다). 그래서 "있으면 쏘고 없으면 잠깐 기다린다".
+ *  기다림은 유한하다 — 못 뜨면 조용히 접는다. */
+let activeWait: ReturnType<typeof setTimeout> | null = null;
+let lastActiveRel: string | null = null;
+
+export function notifyActiveEditor(rel: string): void {
+  if (activeWait) { clearTimeout(activeWait); activeWait = null; }
+  if (!rel) return;
+  let tries = 0;
+  const attempt = () => {
+    activeWait = null;
+    const pane = paneRegistry.panes.get(rel);
+    if (!pane) {
+      // 페인이 아직 없다. 40ms 씩 최대 25번(1초) 기다린다 — 그 안에 안 뜨면
+      // 그 탭은 편집기가 아니거나(이미지·미리보기) 사용자가 다시 옮긴 것이다.
+      if (++tries <= 25) activeWait = setTimeout(attempt, 40);
+      return;
+    }
+    if (lastActiveRel === rel) return;   // 같은 파일로 두 번 쏘지 않는다
+    lastActiveRel = rel;
+    const ed = shimEditorFor(rel);
+    if (ed) editorEvents.activeChanged.fire(ed);
+  };
+  attempt();
+}
+
+paneRegistry.onReady = (rel: string) => notifyActiveEditor(rel);
+
 /** 사건을 쏠 때 쓸 문서 통로. makeVscodeApi 가 확장마다 인덱스를 만들지만,
  *  사건에는 확장과 무관한 문서 하나면 된다. */
 let shimDocFor: (rel: string) => any = () => null;
diff --git a/ide/src/ext/shimDoc.ts b/ide/src/ext/shimDoc.ts
index 4412526..8fa2c3d 100644
--- a/ide/src/ext/shimDoc.ts
+++ b/ide/src/ext/shimDoc.ts
@@ -1,6 +1,7 @@
 import monaco from "../editor/monacoSetup";
 import * as projectModels from "../editor/projectModels";
 import { paneRegistry } from "../editor/MonacoPane";
+import { applyDecos } from "./decoStore";
 
 /**
  * vscode 셰임의 문서·편집기 — **실제 Monaco 모델에 연결한다.**
@@ -122,7 +123,13 @@ export function makeEditor(doc: any, rel: string, Position: any, Selection: any,
     revealRange(r: any) {
       try { api()?.editor.revealRangeInCenter({ startLineNumber: r.start.line + 1, startColumn: 1, endLineNumber: r.end.line + 1, endColumn: 1 }); } catch { /* */ }
     },
-    setDecorations() { /* 데코레이션 타입이 no-op 이라 여기도 no-op */ },
+    /** 이 파일을 띄운 팬이 없으면 그릴 자리가 없다 — 조용히 넘긴다(닫힌 탭에
+     *  그려 달라는 요청은 오류가 아니다). 열려 있으면 그 편집기에 실제로 붙는다. */
+    setDecorations(type: any, ranges: any) {
+      const e = api()?.editor;
+      if (!e) return;
+      applyDecos(e, type, ranges);
+    },
   };
 }
 
diff --git a/ide/src/ext/vscodeShim.ts b/ide/src/ext/vscodeShim.ts
index 4297d61..0fb6460 100644
--- a/ide/src/ext/vscodeShim.ts
+++ b/ide/src/ext/vscodeShim.ts
@@ -12,6 +12,7 @@ import { cleanText, ALIGN_LEFT, ALIGN_RIGHT, type StatusItem } from "./statusBar
 import { globToRegExp, dispatch as fsDispatch, type WatcherSpec, type FsDelta } from "./fsWatch";
 import { parseViews, containerTitle, normalizeTreeItem, type ViewDecl, type TreeRow } from "./views";
 import { collectEdits, groupByFile, sortForApply, hasOverlap, normalizeAction } from "./workspaceEdit";
+import { createDecoType, applyDecos, disposeAllDecos, type DecoTypeHandle } from "./decoStore";
 import { setShimDocSource } from "./extHost";
 
 /** 지금 살아 있는 파일 감시자들. 확장을 다시 읽으면 disposeShimRegistrations 가 비운다. */
@@ -85,8 +86,13 @@ export interface ShimDeps {
 
 const disposables: monaco.IDisposable[] = [];
 /** 이전 로드에서 등록한 Monaco 프로바이더 정리 (재로드 시 중복 방지) */
+/** 확장별로 만들어 둔 데코레이션 타입 — 정리 때 그려 둔 것까지 걷기 위해 들고 있다. */
+const decoTypesByExt = new Map<string, DecoTypeHandle[]>();
+
 export function disposeShimRegistrations() {
   for (const d of disposables.splice(0)) { try { d.dispose(); } catch { /* */ } }
+  for (const list of decoTypesByExt.values()) disposeAllDecos(list);
+  decoTypesByExt.clear();
 }
 
 // ── 기본 타입 ──────────────────────────────────────────────────
@@ -212,6 +218,10 @@ function relOfWith(root: string | null, arg: any): string | null {
 }
 
 export function makeVscodeApi(deps: ShimDeps, ext: { id: string; name: string; contributes?: any }) {
+  // 이 확장이 만든 데코레이션 타입. 확장이 내려갈 때 그려 둔 것까지 함께 걷는다 —
+  // 규칙만 남기고 가면 다음 확장이 만든 타입과 클래스가 섞인다.
+  const extDecoTypes: DecoTypeHandle[] = [];
+  decoTypesByExt.set(ext.id, extDecoTypes);
   const docs = makeDocIndex(
     { root: deps.workspaceRoot, activeRel: deps.getActiveFile, openRels: deps.openFiles, save: deps.saveFile },
     { Position, Range, Selection },
@@ -554,7 +564,18 @@ export function makeVscodeApi(deps: ShimDeps, ext: { id: string; name: string; c
       });
       return got == null ? undefined : String(got);
     },
-    createTextEditorDecorationType: () => ({ dispose() {}, key: "sz-deco" }),
+    // 예전엔 `() => ({ dispose() {}, key: "sz-deco" })` 였다. 확장은 성공을 받고
+    // 화면에는 아무것도 없었다 — 인라인 blame·커버리지 표시가 전부 여기 걸려 있었다.
+    createTextEditorDecorationType: (options: any) => {
+      const h = createDecoType(options);
+      if (h._szEmpty) {
+        // 옵션에서 알아들은 것이 하나도 없으면 그려도 보이는 것이 없다. 조용히
+        // 성공을 답하는 대신 말해 준다 — 그게 이 자리에서 없애려던 바로 그 모양이다.
+        console.warn(`[ext:${ext.id}] createTextEditorDecorationType: 그릴 수 있는 속성이 없습니다.`);
+      }
+      extDecoTypes.push(h);
+      return h;
+    },
     registerTreeDataProvider: (viewId: string, provider: any) => {
       const id = String(viewId);
       extViews.set(id, {
diff --git a/ide/vitest.config.ts b/ide/vitest.config.ts
index 09e8d7a..4a64080 100644
--- a/ide/vitest.config.ts
+++ b/ide/vitest.config.ts
@@ -22,7 +22,7 @@ export default defineConfig({
       "src/ai/retry.test.ts",
       "src/keymap.test.ts",
       "src/overlays.test.ts",
-      "src/ext/hooks.test.ts", "src/ext/prompt.test.ts", "src/ext/shimLang.test.ts", "src/ext/config.test.ts", "src/ext/statusBar.test.ts", "src/ext/fsWatch.test.ts", "src/ext/views.test.ts", "src/ext/workspaceEdit.test.ts", "src/mcp/mcpExtras.test.ts",
+      "src/ext/hooks.test.ts", "src/ext/prompt.test.ts", "src/ext/shimLang.test.ts", "src/ext/config.test.ts", "src/ext/statusBar.test.ts", "src/ext/fsWatch.test.ts", "src/ext/views.test.ts", "src/ext/workspaceEdit.test.ts", "src/ext/decorations.test.ts", "src/mcp/mcpExtras.test.ts",
       "src/theme.test.ts",
       "src/editor/monacoColors.test.ts",
       "src/opening/**/*.test.ts",