@iyulab/chat-components 0.11.8 → 0.11.9

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.11.9] - 2026-09-08
+
+### Fixed
+
+- **Inline citation badges rendered as the literal placeholder text instead of a
+  `u-ref-tag`.** Any `u-marked-block` given a non-empty `refs` array was affected,
+  with no special content required, from `0.11.7` onward. The XSS hardening added
+  in that release escapes every raw HTML token, and the placeholder the component
+  splices into the markdown source was an HTML comment — which the markdown
+  parser classifies as exactly that. Escaping turned it into text that the restore
+  pass no longer recognised, so the marker survived into the DOM and appeared
+  mid-sentence.
+
+  The placeholder is now a private-use sentinel that markdown gives no meaning to,
+  so it tokenises as plain text and escaping is a no-op on it. This removes the
+  coupling between the sanitizer and the placeholder format rather than adding an
+  exemption to it: a future sanitizing hook cannot break the round trip again.
+  Exempting the comment form in the renderer would also have let author text
+  matching the internal format through unescaped.
+
+  **The hardening is unchanged.** Raw HTML written by an author is still escaped,
+  and a regression covers that alongside the round trip.
+
+### Changed
+
+- **A `<!--ref:N-->` written by an author inside a code block is no longer
+  stripped.** It used to collide with the component's internal placeholder format
+  and was removed with it; now it is ordinary content, and a code block shows what
+  was written.
+
 ## [0.11.8] - 2026-09-07
 
 ### Fixed

package/dist/components/blocks/UMarkedBlock.d.ts

@@ -64,11 +64,16 @@ export declare class UMarkedBlock extends UElement {
     private renderImage;
     /**
      * 인용/출처 참조객체가 있을때 ref 태그 HTML을 this.placeholder에 보관하고
-     * 마크다운 문자열의 해당 위치에 주석 플레이스홀더를 삽입합니다.
+     * 마크다운 문자열의 해당 위치에 플레이스홀더 센티널을 삽입합니다.
      */
     private insertRefs;
     /**
-     * 코드블록 내부의 <!--ref:idx--> 플레이스홀더와 그 외 refs 태그를 모두 제거하여 HTML이 코드로 렌더링되도록 합니다.
+     * 코드블록 내부의 플레이스홀더 센티널과 그 외 refs 태그를 모두 제거하여 HTML이 코드로
+     * 렌더링되도록 합니다.
+     *
+     * ⚠**작성자가 쓴 `<!--ref:N-->` 는 더 이상 지우지 않는다.** 종전에는 그것이 우리 내부
+     * 플레이스홀더의 형태와 같아 함께 지워졌지만, 이제 그 문자열은 **작성자의 콘텐츠일 뿐**
+     * 이므로 코드블록 안에서 적힌 그대로 보이는 것이 옳다.
      */
     private removeRefs;
 }

package/dist/components/blocks/UMarkedBlock.js

@@ -8,7 +8,7 @@ import "../references/URefTag.js";
 import { URefCard } from "../references/URefCard.js";
 import "../references/URefCardGroup.js";
 import { UTableBlock } from "./UTableBlock.js";
-import { HtmlPlaceholder } from "../../utilities/HtmlPlaceholder.js";
+import { HtmlPlaceholder, stripRefPlaceholders } from "../../utilities/HtmlPlaceholder.js";
 import { styles } from "./UMarkedBlock.styles.js";
 import { nothing } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
@@ -135,7 +135,7 @@ var UMarkedBlock = class UMarkedBlock extends UElement {
 	}
 	/**
 	* 인용/출처 참조객체가 있을때 ref 태그 HTML을 this.placeholder에 보관하고
-	* 마크다운 문자열의 해당 위치에 주석 플레이스홀더를 삽입합니다.
+	* 마크다운 문자열의 해당 위치에 플레이스홀더 센티널을 삽입합니다.
 	*/
 	insertRefs(value, refs) {
 		const sorted = [...refs].sort((a, b) => b.endIndex - a.endIndex);
@@ -155,11 +155,16 @@ var UMarkedBlock = class UMarkedBlock extends UElement {
 		return value;
 	}
 	/**
-	* 코드블록 내부의 <!--ref:idx--> 플레이스홀더와 그 외 refs 태그를 모두 제거하여 HTML이 코드로 렌더링되도록 합니다.   
+	* 코드블록 내부의 플레이스홀더 센티널과 그 외 refs 태그를 모두 제거하여 HTML이 코드로
+	* 렌더링되도록 합니다.
+	*
+	* ⚠**작성자가 쓴 `<!--ref:N-->` 는 더 이상 지우지 않는다.** 종전에는 그것이 우리 내부
+	* 플레이스홀더의 형태와 같아 함께 지워졌지만, 이제 그 문자열은 **작성자의 콘텐츠일 뿐**
+	* 이므로 코드블록 안에서 적힌 그대로 보이는 것이 옳다.
 	*/
 	removeRefs(value) {
 		value = value.replace(/<u-ref-tag\b[^>]*>[\s\S]*?<\/u-ref-tag>/gi, "");
-		value = value.replace(/<!--ref:\d+-->/g, "");
+		value = stripRefPlaceholders(value);
 		return value;
 	}
 };

package/dist/react/UCodeBlock.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { UCodeBlock as UCodeBlockElement } from '../components/blocks/UCodeBlock';
+import { UCodeBlock as UCodeBlockElement } from '@iyulab/chat-components/dist/components/blocks/UCodeBlock.js';
 
 export declare const UCodeBlock: React.ForwardRefExoticComponent<
   Omit<Partial<UCodeBlockElement>, keyof React.HTMLAttributes<UCodeBlockElement>>

package/dist/react/UCodeBlock.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { UCodeBlock as UCodeBlockElement } from '../components/blocks/UCodeBlock.js';
+import { UCodeBlock as UCodeBlockElement } from '@iyulab/chat-components/dist/components/blocks/UCodeBlock.js';
 
 export const UCodeBlock = createComponent({
   react: React,

package/dist/react/UElementBlock.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { UElementBlock as UElementBlockElement } from '../components/blocks/UElementBlock';
+import { UElementBlock as UElementBlockElement } from '@iyulab/chat-components/dist/components/blocks/UElementBlock.js';
 
 export declare const UElementBlock: React.ForwardRefExoticComponent<
   Omit<Partial<UElementBlockElement>, keyof React.HTMLAttributes<UElementBlockElement>>

package/dist/react/UElementBlock.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { UElementBlock as UElementBlockElement } from '../components/blocks/UElementBlock.js';
+import { UElementBlock as UElementBlockElement } from '@iyulab/chat-components/dist/components/blocks/UElementBlock.js';
 
 export const UElementBlock = createComponent({
   react: React,

package/dist/react/UFileBlock.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { UFileBlock as UFileBlockElement } from '../components/blocks/UFileBlock';
+import { UFileBlock as UFileBlockElement } from '@iyulab/chat-components/dist/components/blocks/UFileBlock.js';
 
 export declare const UFileBlock: React.ForwardRefExoticComponent<
   Omit<Partial<UFileBlockElement>, keyof React.HTMLAttributes<UFileBlockElement>>

package/dist/react/UFileBlock.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { UFileBlock as UFileBlockElement } from '../components/blocks/UFileBlock.js';
+import { UFileBlock as UFileBlockElement } from '@iyulab/chat-components/dist/components/blocks/UFileBlock.js';
 
 export const UFileBlock = createComponent({
   react: React,

package/dist/react/UImagesBlock.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { UImagesBlock as UImagesBlockElement } from '../components-extra/UImagesBlock';
+import { UImagesBlock as UImagesBlockElement } from '@iyulab/chat-components/dist/components-extra/UImagesBlock.js';
 
 export declare const UImagesBlock: React.ForwardRefExoticComponent<
   Omit<Partial<UImagesBlockElement>, keyof React.HTMLAttributes<UImagesBlockElement>>

package/dist/react/UImagesBlock.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { UImagesBlock as UImagesBlockElement } from '../components-extra/UImagesBlock.js';
+import { UImagesBlock as UImagesBlockElement } from '@iyulab/chat-components/dist/components-extra/UImagesBlock.js';
 
 export const UImagesBlock = createComponent({
   react: React,

package/dist/react/UMapBlock.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { UMapBlock as UMapBlockElement } from '../components-extra/UMapBlock';
+import { UMapBlock as UMapBlockElement } from '@iyulab/chat-components/dist/components-extra/UMapBlock.js';
 
 export declare const UMapBlock: React.ForwardRefExoticComponent<
   Omit<Partial<UMapBlockElement>, keyof React.HTMLAttributes<UMapBlockElement>>

package/dist/react/UMapBlock.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { UMapBlock as UMapBlockElement } from '../components-extra/UMapBlock.js';
+import { UMapBlock as UMapBlockElement } from '@iyulab/chat-components/dist/components-extra/UMapBlock.js';
 
 export const UMapBlock = createComponent({
   react: React,

package/dist/react/UMarkedBlock.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { UMarkedBlock as UMarkedBlockElement } from '../components/blocks/UMarkedBlock';
+import { UMarkedBlock as UMarkedBlockElement } from '@iyulab/chat-components/dist/components/blocks/UMarkedBlock.js';
 
 export declare const UMarkedBlock: React.ForwardRefExoticComponent<
   Omit<Partial<UMarkedBlockElement>, keyof React.HTMLAttributes<UMarkedBlockElement>>

package/dist/react/UMarkedBlock.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { UMarkedBlock as UMarkedBlockElement } from '../components/blocks/UMarkedBlock.js';
+import { UMarkedBlock as UMarkedBlockElement } from '@iyulab/chat-components/dist/components/blocks/UMarkedBlock.js';
 
 export const UMarkedBlock = createComponent({
   react: React,

package/dist/react/UMessage.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { UMessage as UMessageElement } from '../components/message/UMessage';
+import { UMessage as UMessageElement } from '@iyulab/chat-components/dist/components/message/UMessage.js';
 
 export declare const UMessage: React.ForwardRefExoticComponent<
   Omit<Partial<UMessageElement>, keyof React.HTMLAttributes<UMessageElement>>

package/dist/react/UMessage.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { UMessage as UMessageElement } from '../components/message/UMessage.js';
+import { UMessage as UMessageElement } from '@iyulab/chat-components/dist/components/message/UMessage.js';
 
 export const UMessage = createComponent({
   react: React,

package/dist/react/UPrompt.d.ts

@@ -1,7 +1,7 @@
 import React from 'react';
-import { UPrompt as UPromptElement } from '../components/prompt/UPrompt';
-import { type StopEventDetail } from '../events/StopEvent';
-import { type SendEventDetail } from '../events/SendEvent';
+import { UPrompt as UPromptElement } from '@iyulab/chat-components/dist/components/prompt/UPrompt.js';
+import { type StopEventDetail } from '@iyulab/chat-components/dist/events/StopEvent.js';
+import { type SendEventDetail } from '@iyulab/chat-components/dist/events/SendEvent.js';
 
 export declare const UPrompt: React.ForwardRefExoticComponent<
   Omit<Partial<UPromptElement>, keyof React.HTMLAttributes<UPromptElement>>

package/dist/react/UPrompt.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { UPrompt as UPromptElement } from '../components/prompt/UPrompt.js';
+import { UPrompt as UPromptElement } from '@iyulab/chat-components/dist/components/prompt/UPrompt.js';
 
 export const UPrompt = createComponent({
   react: React,

package/dist/react/URefBlock.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { URefBlock as URefBlockElement } from '../components/blocks/URefBlock';
+import { URefBlock as URefBlockElement } from '@iyulab/chat-components/dist/components/blocks/URefBlock.js';
 
 export declare const URefBlock: React.ForwardRefExoticComponent<
   Omit<Partial<URefBlockElement>, keyof React.HTMLAttributes<URefBlockElement>>

package/dist/react/URefBlock.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { URefBlock as URefBlockElement } from '../components/blocks/URefBlock.js';
+import { URefBlock as URefBlockElement } from '@iyulab/chat-components/dist/components/blocks/URefBlock.js';
 
 export const URefBlock = createComponent({
   react: React,

package/dist/react/URefCard.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { URefCard as URefCardElement } from '../components/references/URefCard';
+import { URefCard as URefCardElement } from '@iyulab/chat-components/dist/components/references/URefCard.js';
 
 export declare const URefCard: React.ForwardRefExoticComponent<
   Omit<Partial<URefCardElement>, keyof React.HTMLAttributes<URefCardElement>>

package/dist/react/URefCard.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { URefCard as URefCardElement } from '../components/references/URefCard.js';
+import { URefCard as URefCardElement } from '@iyulab/chat-components/dist/components/references/URefCard.js';
 
 export const URefCard = createComponent({
   react: React,

package/dist/react/URefCardGroup.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { URefCardGroup as URefCardGroupElement } from '../components/references/URefCardGroup';
+import { URefCardGroup as URefCardGroupElement } from '@iyulab/chat-components/dist/components/references/URefCardGroup.js';
 
 export declare const URefCardGroup: React.ForwardRefExoticComponent<
   Omit<Partial<URefCardGroupElement>, keyof React.HTMLAttributes<URefCardGroupElement>>

package/dist/react/URefCardGroup.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { URefCardGroup as URefCardGroupElement } from '../components/references/URefCardGroup.js';
+import { URefCardGroup as URefCardGroupElement } from '@iyulab/chat-components/dist/components/references/URefCardGroup.js';
 
 export const URefCardGroup = createComponent({
   react: React,

package/dist/react/URefTag.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { URefTag as URefTagElement } from '../components/references/URefTag';
+import { URefTag as URefTagElement } from '@iyulab/chat-components/dist/components/references/URefTag.js';
 
 export declare const URefTag: React.ForwardRefExoticComponent<
   Omit<Partial<URefTagElement>, keyof React.HTMLAttributes<URefTagElement>>

package/dist/react/URefTag.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { URefTag as URefTagElement } from '../components/references/URefTag.js';
+import { URefTag as URefTagElement } from '@iyulab/chat-components/dist/components/references/URefTag.js';
 
 export const URefTag = createComponent({
   react: React,

package/dist/react/UTableBlock.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { UTableBlock as UTableBlockElement } from '../components/blocks/UTableBlock';
+import { UTableBlock as UTableBlockElement } from '@iyulab/chat-components/dist/components/blocks/UTableBlock.js';
 
 export declare const UTableBlock: React.ForwardRefExoticComponent<
   Omit<Partial<UTableBlockElement>, keyof React.HTMLAttributes<UTableBlockElement>>

package/dist/react/UTableBlock.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { UTableBlock as UTableBlockElement } from '../components/blocks/UTableBlock.js';
+import { UTableBlock as UTableBlockElement } from '@iyulab/chat-components/dist/components/blocks/UTableBlock.js';
 
 export const UTableBlock = createComponent({
   react: React,

package/dist/react/UTextBlock.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { UTextBlock as UTextBlockElement } from '../components/blocks/UTextBlock';
+import { UTextBlock as UTextBlockElement } from '@iyulab/chat-components/dist/components/blocks/UTextBlock.js';
 
 export declare const UTextBlock: React.ForwardRefExoticComponent<
   Omit<Partial<UTextBlockElement>, keyof React.HTMLAttributes<UTextBlockElement>>

package/dist/react/UTextBlock.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { UTextBlock as UTextBlockElement } from '../components/blocks/UTextBlock.js';
+import { UTextBlock as UTextBlockElement } from '@iyulab/chat-components/dist/components/blocks/UTextBlock.js';
 
 export const UTextBlock = createComponent({
   react: React,

package/dist/react/UVideoBlock.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { UVideoBlock as UVideoBlockElement } from '../components-extra/UVideoBlock';
+import { UVideoBlock as UVideoBlockElement } from '@iyulab/chat-components/dist/components-extra/UVideoBlock.js';
 
 export declare const UVideoBlock: React.ForwardRefExoticComponent<
   Omit<Partial<UVideoBlockElement>, keyof React.HTMLAttributes<UVideoBlockElement>>

package/dist/react/UVideoBlock.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { createComponent } from '@lit/react';
-import { UVideoBlock as UVideoBlockElement } from '../components-extra/UVideoBlock.js';
+import { UVideoBlock as UVideoBlockElement } from '@iyulab/chat-components/dist/components-extra/UVideoBlock.js';
 
 export const UVideoBlock = createComponent({
   react: React,

package/dist/utilities/HtmlPlaceholder.d.ts

@@ -1,11 +1,28 @@
 /**
  * Marked 파싱 중 HTML이 GFM에 의해 오염되는 것을 방지하기 위해
- * HTML을 주석 플레이스홀더로 치환하고, 나중에 원래 HTML로 복원하는 유틸입니다.
+ * HTML을 센티널로 치환하고, 나중에 원래 HTML로 복원하는 유틸입니다.
  */
+/**
+ * 문자열에서 ref 플레이스홀더 센티널을 제거합니다.
+ *
+ * 코드블록처럼 **복원 대상이 아닌** 경로에서 쓴다 — 거기서는 ref 태그를 렌더하지 않고
+ * 원문을 그대로 보여야 하므로, 남은 센티널은 지운다(안 지우면 PUA 문자가 두부로 보인다).
+ * 형태를 아는 곳이 이 파일 하나뿐이도록 함수로 내보낸다 — 패턴을 호출부에 복제하면
+ * 종전처럼 한쪽만 바뀌어 어긋난다.
+ */
+export declare function stripRefPlaceholders(value: string): string;
 export declare class HtmlPlaceholder {
     private map;
     private idx;
     reset(): void;
     store(html: string): string;
+    /**
+     * 파싱 결과에서 센티널을 원래 HTML로 되돌립니다.
+     *
+     * ⚠**아무것도 보관하지 않았으면 손대지 않는다**(`idx === 0`). 그 경우 문자열에 센티널이
+     * 있다면 그것은 **작성자가 직접 쓴 글자**이지 우리가 넣은 것이 아니므로, 지우는 것이
+     * 오히려 콘텐츠 손실이다. 보관분이 있을 때 매칭되지 않는 키는 빈 문자열로 지운다 —
+     * 우리 것이 아닌 센티널이 화면에 두부로 남는 것을 막는다.
+     */
     restore(html: string): string;
 }

package/dist/utilities/HtmlPlaceholder.js

@@ -1,8 +1,55 @@
 //#region src/utilities/HtmlPlaceholder.ts
 /**
 * Marked 파싱 중 HTML이 GFM에 의해 오염되는 것을 방지하기 위해
-* HTML을 주석 플레이스홀더로 치환하고, 나중에 원래 HTML로 복원하는 유틸입니다.
+* HTML을 센티널로 치환하고, 나중에 원래 HTML로 복원하는 유틸입니다.
 */
+/**
+* 센티널 경계 문자 — Unicode **Private Use Area**(U+E000..U+F8FF).
+*
+* ⚠**이 선택이 이 유틸의 계약 전부다.** 센티널은 marked 의 토크나이저를 **통과**해야 하고
+* (그래야 `restore()` 가 출력에서 되찾는다), 동시에 marked 가 **HTML로 분류하지 않아야**
+* 한다 — 분류되는 순간 `html` 토큰이 되어 소비자의 sanitizing 렌더러 손에 들어가고,
+* 거기서 형태가 바뀌면 `restore()` 는 자기가 넣은 것을 더 이상 알아보지 못한다.
+*
+* 🔴**종전 판은 HTML 주석(`<!--ref:N-->`)이었고 바로 그 이유로 깨졌다.** marked 는 주석을
+* `html` 토큰으로 잡고(실측: `text, html, text`), `UMarkedBlock` 의 XSS 하드닝 렌더러가
+* 그것을 escape 하면 `&lt;!--ref:N--&gt;` 가 되어 복원 패턴에 걸리지 않는다 — 플레이스홀더가
+* 화면에 **글자 그대로** 남는다. 「주석은 건드려지지 않는다」는 전제가 하드닝과 함께 깨진
+* 것이고, ***전제를 고치는 대신 하드닝에 예외를 두면 다음 하드닝에서 같은 자리가 다시 깨진다.***
+*
+* PUA 문자는 마크다운 문법에서 아무 의미가 없어 **평문 텍스트로만** 토큰화되고(실측),
+* `escapeHtmlText` 의 대상 문자(`& < > " '`)도 아니라 **escape 가 no-op** 이다. 코드블록·
+* 테이블 셀·강조 안에서도 원형이 보존되는 것을 확인했다. ⇒ ***어떤 sanitizing 렌더러가***
+* ***나중에 추가돼도 이 왕복은 깨지지 않는다.***
+*
+* ⚠**소스에는 escape 표기로 적는다** — 원시 PUA 문자를 파일에 두면 에디터·터미널·diff 에서
+* 두부(tofu)나 빈칸으로 보여 「거기 무엇이 있는지」를 읽을 수 없다.
+*/
+var SENTINEL_OPEN = "";
+var SENTINEL_CLOSE = "";
+/**
+* 센티널 매칭 패턴.
+*
+* `lastIndex` 상태를 공유하지 않도록 **매번 새로 만든다** — `g` 플래그가 붙은 정규식을
+* 모듈 상수로 두고 `test()`/`replace()` 에 섞어 쓰면 호출 순서에 따라 조용히 빗나간다.
+*
+* ⚠**정규식 «리터럴»로 적고 문자열로 조립하지 않는다.** 템플릿 리터럴로 `new RegExp(...)`
+* 을 만들면 백슬래시가 리터럴 단계에서 한 번 소비돼 숫자가 아니라 **글자 d 를 찾는** 정규식이
+* 조용히 만들어진다(이 파일을 쓰다 실제로 한 번 만들었다). 경계 문자를 위 상수와
+* 같은 값으로 두 번 적는 대가를 치르되, 두 자리가 **같은 파일 안**에 있고 회귀 테스트가 둘의 일치를 고정한다.
+*/
+var sentinelPattern = () => /\u{E000}\d+\u{E001}/gu;
+/**
+* 문자열에서 ref 플레이스홀더 센티널을 제거합니다.
+*
+* 코드블록처럼 **복원 대상이 아닌** 경로에서 쓴다 — 거기서는 ref 태그를 렌더하지 않고
+* 원문을 그대로 보여야 하므로, 남은 센티널은 지운다(안 지우면 PUA 문자가 두부로 보인다).
+* 형태를 아는 곳이 이 파일 하나뿐이도록 함수로 내보낸다 — 패턴을 호출부에 복제하면
+* 종전처럼 한쪽만 바뀌어 어긋난다.
+*/
+function stripRefPlaceholders(value) {
+	return value.replace(sentinelPattern(), "");
+}
 var HtmlPlaceholder = class {
 	constructor() {
 		this.map = {};
@@ -13,14 +60,22 @@ var HtmlPlaceholder = class {
 		this.idx = 0;
 	}
 	store(html) {
-		const key = `<!--ref:${this.idx++}-->`;
+		const key = `${SENTINEL_OPEN}${this.idx++}${SENTINEL_CLOSE}`;
 		this.map[key] = html;
 		return key;
 	}
+	/**
+	* 파싱 결과에서 센티널을 원래 HTML로 되돌립니다.
+	*
+	* ⚠**아무것도 보관하지 않았으면 손대지 않는다**(`idx === 0`). 그 경우 문자열에 센티널이
+	* 있다면 그것은 **작성자가 직접 쓴 글자**이지 우리가 넣은 것이 아니므로, 지우는 것이
+	* 오히려 콘텐츠 손실이다. 보관분이 있을 때 매칭되지 않는 키는 빈 문자열로 지운다 —
+	* 우리 것이 아닌 센티널이 화면에 두부로 남는 것을 막는다.
+	*/
 	restore(html) {
 		if (this.idx === 0) return html;
-		return html.replace(/<!--ref:\d+-->/g, (key) => this.map[key] ?? "");
+		return html.replace(sentinelPattern(), (key) => this.map[key] ?? "");
 	}
 };
 //#endregion
-export { HtmlPlaceholder };
+export { HtmlPlaceholder, stripRefPlaceholders };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/chat-components",
   "description": "llm chat components for building chat interfaces",
-  "version": "0.11.8",
+  "version": "0.11.9",
   "author": "iyulab",
   "license": "MIT",
   "keywords": [