@iyulab/chat-components 0.12.3 → 0.14.0

package/dist/utilities/ElementRegistry.d.ts

@@ -0,0 +1,13 @@
+import { ElementSchema } from '../types/Schema.js';
+/**
+ * 블록을 `block-json` 으로 렌더할 수 있게 등록합니다.
+ *
+ * 내장 블록(chart/images/map/video)은 모듈을 import 하면 스스로 등록되고,
+ * `ElementPromptBuilder.add()` 로 추가한 스키마도 함께 등록됩니다.
+ * 같은 태그를 다시 등록하면 속성 목록을 새 스키마로 바꿉니다.
+ */
+export declare function registerElementBlock(schema: Pick<ElementSchema, 'tag' | 'properties'>): void;
+/**
+ * 등록된 블록이면 대입을 허용하는 속성 이름 집합을, 아니면 `undefined` 를 돌려줍니다.
+ */
+export declare function getElementBlockProperties(tag: string): ReadonlySet<string> | undefined;

package/dist/utilities/ElementRegistry.js

@@ -0,0 +1,33 @@
+//#region src/utilities/ElementRegistry.ts
+/**
+* `block-json` 코드펜스로 만들 수 있는 블록의 허용 목록.
+*
+* `block-json` 은 LLM 출력이다 — 프롬프트 인젝션(검색 문서·첨부·도구 결과)으로 제3자가 쓸 수
+* 있는 입력이라, «등록된 커스텀 엘리먼트면 무엇이든 만든다 + 위험한 속성 이름만 막는다» 는
+* 경계가 되지 못한다. 페이지에는 신뢰된 HTML 을 받는 속성을 가진 엘리먼트가 있고, 거부 목록은
+* 그 이름을 모른다.
+*
+* ⇒ **LLM 에게 알린 스키마가 곧 허용 목록이다.** 태그는 스키마로 등록된 것만, 속성은 그
+* 스키마의 `properties` 에 적힌 이름만 대입한다. 스키마는 이미 LLM 과의 계약이므로 두 번째
+* 목록을 따로 유지할 필요가 없다.
+*/
+var blocks = /* @__PURE__ */ new Map();
+/**
+* 블록을 `block-json` 으로 렌더할 수 있게 등록합니다.
+*
+* 내장 블록(chart/images/map/video)은 모듈을 import 하면 스스로 등록되고,
+* `ElementPromptBuilder.add()` 로 추가한 스키마도 함께 등록됩니다.
+* 같은 태그를 다시 등록하면 속성 목록을 새 스키마로 바꿉니다.
+*/
+function registerElementBlock(schema) {
+	const tag = schema.tag.trim().toLowerCase();
+	blocks.set(tag, new Set(Object.keys(schema.properties ?? {})));
+}
+/**
+* 등록된 블록이면 대입을 허용하는 속성 이름 집합을, 아니면 `undefined` 를 돌려줍니다.
+*/
+function getElementBlockProperties(tag) {
+	return blocks.get(tag.trim().toLowerCase());
+}
+//#endregion
+export { getElementBlockProperties, registerElementBlock };

package/dist/utilities/PromptBuilder.d.ts

@@ -11,6 +11,9 @@ export declare class ElementPromptBuilder {
     static get instance(): ElementPromptBuilder;
     /**
      * Element 정의를 등록합니다. 같은 태그가 이미 등록되어 있으면 에러를 던집니다.
+     *
+     * LLM 에게 알리는 스키마가 곧 `u-element-block` 의 허용 목록이므로, 여기서 추가한 블록은
+     * `block-json` 으로도 렌더할 수 있게 함께 등록됩니다(`registerElementBlock`).
      * @throws {Error} 같은 태그가 이미 등록된 경우
      */
     add(schema: ElementSchema): ElementPromptBuilder;

package/dist/utilities/PromptBuilder.js

@@ -1,3 +1,4 @@
+import { registerElementBlock } from "./ElementRegistry.js";
 import element_prompt_md_default from "../_virtual/_glob-assets_raw/element-prompt.md.7047ffcc.js";
 //#region src/utilities/PromptBuilder.ts
 /**
@@ -16,11 +17,15 @@ var ElementPromptBuilder = class ElementPromptBuilder {
 	}
 	/**
 	* Element 정의를 등록합니다. 같은 태그가 이미 등록되어 있으면 에러를 던집니다.
+	*
+	* LLM 에게 알리는 스키마가 곧 `u-element-block` 의 허용 목록이므로, 여기서 추가한 블록은
+	* `block-json` 으로도 렌더할 수 있게 함께 등록됩니다(`registerElementBlock`).
 	* @throws {Error} 같은 태그가 이미 등록된 경우
 	*/
 	add(schema) {
 		if (this.elements.has(schema.tag)) throw new Error(`Element with tag "${schema.tag}" is already registered.`);
 		this.elements.set(schema.tag, schema);
+		registerElementBlock(schema);
 		return this;
 	}
 	/**

package/dist/utilities/icons.js

@@ -0,0 +1,52 @@
+import alert_triangle_fill_svg_default from "../_virtual/_glob-assets_raw/alert-triangle-fill.svg.4cfc4305.js";
+import arrows_sort_svg_default from "../_virtual/_glob-assets_raw/arrows-sort.svg.dda43a85.js";
+import code_svg_default from "../_virtual/_glob-assets_raw/code.svg.c69bc144.js";
+import download_svg_default from "../_virtual/_glob-assets_raw/download.svg.bce82177.js";
+import external_link_svg_default from "../_virtual/_glob-assets_raw/external-link.svg.a9f7f02d.js";
+import file_code_svg_default from "../_virtual/_glob-assets_raw/file-code.svg.0e706f93.js";
+import file_music_svg_default from "../_virtual/_glob-assets_raw/file-music.svg.b9970203.js";
+import file_spreadsheet_svg_default from "../_virtual/_glob-assets_raw/file-spreadsheet.svg.8c03bdfa.js";
+import file_text_svg_default from "../_virtual/_glob-assets_raw/file-text.svg.85bdd923.js";
+import file_type_pdf_svg_default from "../_virtual/_glob-assets_raw/file-type-pdf.svg.bc12db6d.js";
+import file_zip_svg_default from "../_virtual/_glob-assets_raw/file-zip.svg.76dde660.js";
+import file_svg_default from "../_virtual/_glob-assets_raw/file.svg.28f5d6f1.js";
+import photo_svg_default from "../_virtual/_glob-assets_raw/photo.svg.cc273cc1.js";
+import player_stop_fill_svg_default from "../_virtual/_glob-assets_raw/player-stop-fill.svg.5378b752.js";
+import send_svg_default from "../_virtual/_glob-assets_raw/send.svg.02326253.js";
+import sort_ascending_letters_svg_default from "../_virtual/_glob-assets_raw/sort-ascending-letters.svg.14a3df67.js";
+import sort_descending_letters_svg_default from "../_virtual/_glob-assets_raw/sort-descending-letters.svg.3e03647c.js";
+import video_svg_default from "../_virtual/_glob-assets_raw/video.svg.c183f03c.js";
+import world_svg_default from "../_virtual/_glob-assets_raw/world.svg.cd9903c8.js";
+import { IconRegistry } from "@iyulab/components/dist/utilities/icons.js";
+//#region src/utilities/icons.ts
+/**
+* vite의 `import.meta.glob`을 사용하여 chat-components 전용 SVG 아이콘을 빌드 시점에 번들링합니다.
+* 네트워크 요청 없이 즉시 조회 가능하며, 런타임 동안 불변입니다.
+*/
+var InternalChatIconBundle = new Map(Object.entries(/* #__PURE__ */ Object.assign({
+	"../assets/icons/alert-triangle-fill.svg": alert_triangle_fill_svg_default,
+	"../assets/icons/arrows-sort.svg": arrows_sort_svg_default,
+	"../assets/icons/code.svg": code_svg_default,
+	"../assets/icons/download.svg": download_svg_default,
+	"../assets/icons/external-link.svg": external_link_svg_default,
+	"../assets/icons/file-code.svg": file_code_svg_default,
+	"../assets/icons/file-music.svg": file_music_svg_default,
+	"../assets/icons/file-spreadsheet.svg": file_spreadsheet_svg_default,
+	"../assets/icons/file-text.svg": file_text_svg_default,
+	"../assets/icons/file-type-pdf.svg": file_type_pdf_svg_default,
+	"../assets/icons/file-zip.svg": file_zip_svg_default,
+	"../assets/icons/file.svg": file_svg_default,
+	"../assets/icons/photo.svg": photo_svg_default,
+	"../assets/icons/player-stop-fill.svg": player_stop_fill_svg_default,
+	"../assets/icons/send.svg": send_svg_default,
+	"../assets/icons/sort-ascending-letters.svg": sort_ascending_letters_svg_default,
+	"../assets/icons/sort-descending-letters.svg": sort_descending_letters_svg_default,
+	"../assets/icons/video.svg": video_svg_default,
+	"../assets/icons/world.svg": world_svg_default
+})).map(([path, module]) => {
+	return [path.split("/").pop()?.replace(".svg", "") || "", module];
+}).filter(([name]) => name !== ""));
+IconRegistry.register("internal-chat", (name) => {
+	return InternalChatIconBundle.get(name);
+});
+//#endregion

package/dist/utilities/imageSources.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 모델 출력의 이미지가 불러올 수 있는 URL 접두를 정합니다. 렌더하기 전에 한 번 부르세요 —
+ * 이미 그려진 블록은 다음 렌더 때 따릅니다.
+ *
+ * - `undefined`: 전부 허용(기본값).
+ * - `[]`: 전부 차단.
+ * - `['*']`: 전부 허용(명시).
+ * - `['https://cdn.example.com/images/']`: 이 접두로 시작하는 것만.
+ *
+ * 접두는 **해석된 절대 URL** 과 비교합니다 — 상대 경로는 `document.baseURI` 기준으로 풀린 뒤
+ * 비교되므로, 같은 출처 이미지를 허용하려면 `location.origin + '/'` 를 넣으세요.
+ * ⚠도메인 전체(`https://example.com/`)보다 경로(`https://example.com/images/`)를 주세요 —
+ * 허용한 도메인에 열린 리다이렉트가 있으면 그것을 거쳐 다른 곳으로 나갈 수 있습니다.
+ *
+ * @example
+ * setAllowedImagePrefixes([location.origin + '/', 'https://cdn.example.com/images/']);
+ */
+export declare function setAllowedImagePrefixes(prefixes?: readonly string[]): void;
+/** 현재 이미지 출처 정책을 돌려줍니다(`undefined` = 전부 허용). */
+export declare function getAllowedImagePrefixes(): readonly string[] | undefined;
+/**
+ * 모델이 쓴 이미지 URL 을 정책에 대어 봅니다. 불러와도 되면 프로토콜 검사를 거친 URL 을,
+ * 아니면 `null` 을 돌려줍니다(요청하지 말 것).
+ */
+export declare function resolveImageSource(src: string): string | null;

package/dist/utilities/imageSources.js

@@ -0,0 +1,61 @@
+import { sanitizeHref } from "./sanitizers.js";
+//#region src/utilities/imageSources.ts
+/**
+* 모델 출력이 불러오는 이미지의 출처 정책 — 페이지 전체에 하나다(CSP `img-src` 와 같은 범위).
+*
+* 마크다운 이미지(`u-marked-block`)와 `u-images-block` 은 모델이 쓴 URL 을 그대로 요청한다.
+* 프롬프트 인젝션된 응답은 이미지 URL 의 쿼리에 데이터를 실어 제3자에게 보낼 수 있다 —
+* 요청은 렌더되는 순간 일어나므로 사용자가 아무것도 누르지 않아도 된다.
+*
+* 기본값은 `undefined`(전부 허용 — 종전 동작)다. 목록을 주면 절대 URL 이 그 접두 중 하나로
+* 시작하는 이미지만 불러오고, 나머지는 요청 없이 «차단된 이미지» 로 그린다.
+* `data:image/…` 는 요청이 없으므로 정책과 무관하게 그린다.
+*/
+var allowedPrefixes;
+/** 요청 없이 그려지는 인라인 이미지 */
+var DATA_IMAGE_REGEX = /^data:image\/[a-z0-9.+-]+[;,]/i;
+/**
+* 모델 출력의 이미지가 불러올 수 있는 URL 접두를 정합니다. 렌더하기 전에 한 번 부르세요 —
+* 이미 그려진 블록은 다음 렌더 때 따릅니다.
+*
+* - `undefined`: 전부 허용(기본값).
+* - `[]`: 전부 차단.
+* - `['*']`: 전부 허용(명시).
+* - `['https://cdn.example.com/images/']`: 이 접두로 시작하는 것만.
+*
+* 접두는 **해석된 절대 URL** 과 비교합니다 — 상대 경로는 `document.baseURI` 기준으로 풀린 뒤
+* 비교되므로, 같은 출처 이미지를 허용하려면 `location.origin + '/'` 를 넣으세요.
+* ⚠도메인 전체(`https://example.com/`)보다 경로(`https://example.com/images/`)를 주세요 —
+* 허용한 도메인에 열린 리다이렉트가 있으면 그것을 거쳐 다른 곳으로 나갈 수 있습니다.
+*
+* @example
+* setAllowedImagePrefixes([location.origin + '/', 'https://cdn.example.com/images/']);
+*/
+function setAllowedImagePrefixes(prefixes) {
+	allowedPrefixes = prefixes ? [...prefixes] : void 0;
+}
+/** 현재 이미지 출처 정책을 돌려줍니다(`undefined` = 전부 허용). */
+function getAllowedImagePrefixes() {
+	return allowedPrefixes;
+}
+/**
+* 모델이 쓴 이미지 URL 을 정책에 대어 봅니다. 불러와도 되면 프로토콜 검사를 거친 URL 을,
+* 아니면 `null` 을 돌려줍니다(요청하지 말 것).
+*/
+function resolveImageSource(src) {
+	const trimmed = src.trim();
+	if (DATA_IMAGE_REGEX.test(trimmed)) return trimmed;
+	const safe = sanitizeHref(src);
+	if (safe === "#") return null;
+	if (!allowedPrefixes) return safe;
+	if (allowedPrefixes.includes("*")) return safe;
+	let absolute;
+	try {
+		absolute = new URL(safe, document.baseURI).href;
+	} catch {
+		return null;
+	}
+	return allowedPrefixes.some((prefix) => absolute.startsWith(prefix)) ? safe : null;
+}
+//#endregion
+export { getAllowedImagePrefixes, resolveImageSource, setAllowedImagePrefixes };

package/dist/utilities/messages.d.ts

@@ -5,5 +5,5 @@
  * 이 리포가 채택한 표준이 *"영어 기본 **+ 레지스트리**"* 이기 때문이다 — 영어 리터럴만으로는
  * 한국어 앱이 그 문구를 되돌릴 방법이 없다. 다음 문자열은 여기로 온다.
  */
-export type ChatMessageKey = 'canvasUnavailable' | 'previousReference' | 'nextReference' | 'closePreview' | 'closeLightbox' | 'previousImage' | 'nextImage' | 'sendMessage' | 'stopGenerating' | 'fullScreen' | 'remove' | 'pngDownload' | 'jsonDownload' | 'search' | 'rowCount' | 'excelDownload' | 'csvDownload' | 'openImage' | 'previewFile';
+export type ChatMessageKey = 'canvasUnavailable' | 'previousReference' | 'nextReference' | 'closePreview' | 'closeLightbox' | 'previousImage' | 'nextImage' | 'sendMessage' | 'stopGenerating' | 'fullScreen' | 'remove' | 'pngDownload' | 'jsonDownload' | 'search' | 'rowCount' | 'excelDownload' | 'csvDownload' | 'openImage' | 'previewFile' | 'imageBlocked' | 'imageBlockedNamed';
 export declare const messages: import('@iyulab/components/dist/utilities/Locale.js').LocaleNamespace<ChatMessageKey>;

package/dist/utilities/messages.js

@@ -20,7 +20,9 @@ messages.register("en", {
 	excelDownload: "Excel Download",
 	csvDownload: "CSV Download",
 	openImage: "Open image {index}",
-	previewFile: "Preview {name}"
+	previewFile: "Preview {name}",
+	imageBlocked: "Image blocked",
+	imageBlockedNamed: "Image blocked: {name}"
 });
 messages.register("ko", {
 	canvasUnavailable: "Canvas 2D context를 가져올 수 없습니다.",
@@ -41,7 +43,9 @@ messages.register("ko", {
 	excelDownload: "Excel 다운로드",
 	csvDownload: "CSV 다운로드",
 	openImage: "이미지 {index} 열기",
-	previewFile: "{name} 미리보기"
+	previewFile: "{name} 미리보기",
+	imageBlocked: "차단된 이미지",
+	imageBlockedNamed: "차단된 이미지: {name}"
 });
 //#endregion
 export { messages };

package/dist/utilities/sanitizers.d.ts

@@ -23,7 +23,16 @@ export declare function escapeHtmlText(value: string): string;
  */
 export declare function escapeHtmlAttr(value: string): string;
 /**
- * href / src attribute용 문자열 처리
+ * URL 의 프로토콜을 검사해 안전한 URL 문자열을 돌려줍니다 — HTML escape 는 하지 않습니다.
+ * Lit 의 속성 바인딩처럼 escape 를 스스로 하는 자리에서 씁니다(두 번 escape 하면 `&` 가 `&` 가 된다).
+ * 위험한 URL(javascript:/data:/vbscript:, protocol-relative)은 `#` 가 됩니다.
+ *
+ * 예:
+ *  html`<a href=${sanitizeHref(url)}>`
+ */
+export declare function sanitizeHref(value: string): string;
+/**
+ * href / src attribute용 문자열 처리 — HTML 문자열을 직접 조립하는 자리에서 씁니다.
  *
  * 예:
  *  <a href="{value}">

package/dist/utilities/sanitizers.js

@@ -76,18 +76,29 @@ var HREF_STRIP_CHARS_REGEX = /[\u0000-\u001F\u007F\s]+/g;
 /** href/src에서 차단해야 하는 위험 protocol */
 var HREF_UNSAFE_PROTOCOL_REGEX = /^(?:javascript|data|vbscript):/i;
 /**
-* href / src attribute용 문자열 처리
+* URL 의 프로토콜을 검사해 안전한 URL 문자열을 돌려줍니다 — HTML escape 는 하지 않습니다.
+* Lit 의 속성 바인딩처럼 escape 를 스스로 하는 자리에서 씁니다(두 번 escape 하면 `&` 가 `&` 가 된다).
+* 위험한 URL(javascript:/data:/vbscript:, protocol-relative)은 `#` 가 됩니다.
 *
 * 예:
-*  <a href="{value}">
+*  html`<a href=${sanitizeHref(url)}>`
 */
-function escapeHtmlHref(value) {
+function sanitizeHref(value) {
 	let normalized = value.replace(ZERO_WIDTH_STRICT_REGEX, "").trim();
 	if (HREF_STRIP_CHARS_REGEX.test(normalized)) normalized = normalized.replace(HREF_STRIP_CHARS_REGEX, "");
 	normalized = normalized.replace(/\\/g, "/");
 	if (normalized.startsWith("//")) return "#";
 	if (HREF_UNSAFE_PROTOCOL_REGEX.test(normalized)) return "#";
-	return escapeHtmlAttr(normalized);
+	return normalized;
+}
+/**
+* href / src attribute용 문자열 처리 — HTML 문자열을 직접 조립하는 자리에서 씁니다.
+*
+* 예:
+*  <a href="{value}">
+*/
+function escapeHtmlHref(value) {
+	return escapeHtmlAttr(sanitizeHref(value));
 }
 //#endregion
-export { escapeHtmlAttr, escapeHtmlHref, escapeHtmlText, stripZeroWidth };
+export { escapeHtmlAttr, escapeHtmlHref, escapeHtmlText, sanitizeHref, stripZeroWidth };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/chat-components",
   "description": "llm chat components for building chat interfaces",
-  "version": "0.12.3",
+  "version": "0.14.0",
   "author": "iyulab",
   "license": "MIT",
   "keywords": [
@@ -38,6 +38,8 @@
     "./src/extra.ts",
     "./dist/index.js",
     "./src/index.ts",
+    "./dist/utilities/icons.js",
+    "./src/utilities/icons.ts",
     "./dist/react/index.js"
   ],
   "exports": {
@@ -67,7 +69,7 @@
     "marked": "^18.0.6"
   },
   "peerDependencies": {
-    "@iyulab/components": ">=1.23.0",
+    "@iyulab/components": ">=1.51.0",
     "@lit/react": ">=1.0.8",
     "chart.js": ">=4.5.1",
     "react": ">=18.0.0"

package/skills/iyulab-chat-components/SKILL.md

@@ -31,6 +31,7 @@ import '@iyulab/chat-components/dist/components/prompt/UPrompt.js';
 ```
 
 > For detailed setup and usage patterns, see [./references/usage.md](./references/usage.md).
+> Model output is untrusted — see [./references/security.md](./references/security.md) for what each input may contain.
 
 ---
 

package/skills/iyulab-chat-components/references/components/element-block.md

@@ -6,7 +6,7 @@ import '@iyulab/chat-components/dist/components/blocks/UElementBlock.js';
 
 **Tag:** `u-element-block`
 
-Dynamic custom element renderer. Creates the element specified by `tag`, binds `properties` to it, and shows a skeleton placeholder while `loading`. Used internally by `u-marked-block` to render `block-json` code fences (see [../extra-system.md](../extra-system.md)) — you generally don't create it directly.
+Dynamic block renderer. Creates the registered block specified by `tag`, binds the schema's `properties` to it, and shows a skeleton placeholder while `loading`. Used internally by `u-marked-block` to render `block-json` code fences (see [../extra-system.md](../extra-system.md)) — you generally don't create it directly.
 
 Extends `UDataElement`, so `tag`/`properties` can also be injected via a `<script type="application/json">` slot.
 
@@ -43,15 +43,14 @@ This is converted to `<u-element-block tag="u-images-block" ...>` via `UElementB
 
 | Property | Type | Default | Reflect | Description |
 |----------|------|---------|---------|-------------|
-| `tag` | `string` | `undefined` | — | Custom element tag to render. Must already be registered |
-| `properties` | `Record<string, unknown>` | `undefined` | — | Properties to bind to the rendered element |
+| `tag` | `string` | `undefined` | — | Block tag to render. Must be a registered block (`registerElementBlock` or `ElementPromptBuilder.add`) whose element is defined |
+| `properties` | `Record<string, unknown>` | `undefined` | — | Values to bind. Only names listed in the block schema's `properties` are assigned |
 | `loading` | `boolean` | `false` | ✓ | Shows a skeleton placeholder instead of the element |
-| `blacklist` | `string[]` | `['innerHTML', 'outerHTML', 'textContent', 'innerText', 'outerText', 'srcdoc']` | — | Property names blocked from binding for XSS prevention |
 
 ## Error Handling
 
-If `tag` is missing, unregistered, or `properties` fails validation/assignment, `u-element-block` does **not** show an error card — it renders nothing and logs to the console (`[u-element-block] ...`). While `loading` is `true`, JSON parse failures from the underlying `UDataElement` are silently ignored too, since incomplete streamed JSON is expected mid-stream.
+If `tag` is missing or not a registered block, or `properties` is not an object or fails to assign, `u-element-block` does **not** show an error card — it renders nothing and logs to the console (`[u-element-block] ...`). While `loading` is `true`, JSON parse failures from the underlying `UDataElement` are silently ignored too, since incomplete streamed JSON is expected mid-stream.
 
 ## Security
 
-The following property names are blocked by default to prevent XSS: `innerHTML`, `outerHTML`, `textContent`, `innerText`, `outerText`, `srcdoc`. Extend `blacklist` to add more restrictions.
+`tag` and `properties` usually come from model output, so they are treated as untrusted. Only registered blocks are created, and only the property names in the block's schema are assigned — any other key (for example `style`) is dropped and logged. See [../extra-system.md](../extra-system.md#security).

package/skills/iyulab-chat-components/references/components/images-block.md

@@ -71,3 +71,4 @@ interface ImageSlide {
 | Carousel | Up to 3 slides visible; draggable |
 | Lightbox | Full-screen modal on image click |
 | Keyboard | `←` `→` to navigate, `Esc` to close |
+| Image origin policy | `setAllowedImagePrefixes()` applies — a blocked item shows its alt text and is not requested (see [../security.md](../security.md)) |

package/skills/iyulab-chat-components/references/components/marked-block.md

@@ -65,6 +65,18 @@ Vendored from GitHub's markdown theme — light values shown, dark auto-applies
 | `--base-size-4` / `-8` / `-16` / `-24` / `-40` | Spacing scale used throughout (margins, padding, gaps) |
 | `--base-text-weight-normal` / `-medium` / `-semibold` | Font-weight scale (body / table header / heading) |
 
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `image-blocked` | Alt text shown in place of an image the image origin policy blocked (see Images) |
+
+## Images
+
+Markdown images (table cells included) follow the page-wide image origin policy set with
+`setAllowedImagePrefixes()`. A blocked image is not requested; its alt text is shown in a
+`part="image-blocked"` span (`Image blocked: …`, localized). See [../security.md](../security.md).
+
 ## ReferenceCitation Type
 
 ```ts

package/skills/iyulab-chat-components/references/components/ref-card.md

@@ -6,7 +6,7 @@ import '@iyulab/chat-components/dist/components/references/URefCard.js';
 
 **Tag:** `u-ref-card`
 
-Displays a single reference source as a card. Supports `web` and `document` types. For web sources, automatically fetches a favicon via the Google Favicon API.
+Displays a single reference source as a card. Supports `web` and `document` types. A web card shows a favicon only when you give it a resolver — by default it makes no request of its own (see [Favicon](#favicon)).
 
 Extends `UDataElement`, so data can also be injected via a `<script type="application/json">` slot.
 
@@ -46,3 +46,22 @@ Extends `UDataElement`, so data can also be injected via a `<script type="applic
 | `title` | `string` | `''` | — | Card title (falls back to domain name for web type) |
 | `snippet` | `string` | `undefined` | — | Excerpt text |
 | `tags` | `string[]` | `undefined` | — | Tag list. Pass as JSON array string via HTML attribute |
+| `faviconUrl` | `FaviconResolver` | `undefined` | — | Favicon resolver for this card (property only). Overrides `URefCard.defaultFaviconUrl` |
+
+---
+
+## Favicon
+
+```ts
+import { URefCard, googleFaviconUrl } from '@iyulab/chat-components';
+
+// type FaviconResolver = (url: string) => string | undefined
+URefCard.defaultFaviconUrl = (url) => `/favicons/${new URL(url).hostname}.png`; // your own host
+// or, where the public internet is reachable and sending host names to Google is acceptable:
+URefCard.defaultFaviconUrl = googleFaviconUrl;
+```
+
+- **Default: no favicon, no request.** The card never contacts a third party unless you choose one — safe on a closed network.
+- `URefCard.defaultFaviconUrl` applies to every card, including those rendered inside `u-ref-block`, `u-ref-card-group` and marked-block tooltips. Set it before cards render.
+- A card's own `faviconUrl` property wins over the module-wide one. Returning `undefined` draws the card without a favicon.
+- `googleFaviconUrl` sends each card's host name (not the full URL) to `www.google.com`.

package/skills/iyulab-chat-components/references/extra-system.md

@@ -76,20 +76,20 @@ const def: ElementSchema = {
 ElementPromptBuilder.instance.add(def);
 ```
 
-The element just needs to accept standard property assignments — `u-element-block` binds `properties` keys directly to element properties.
+The element just needs to accept standard property assignments. `add()` also registers the schema as a renderable block — `u-element-block` assigns only the names in the schema's `properties`. If you write your own prompt instead, call `registerElementBlock(def)` (exported from `@iyulab/chat-components`).
 
 ## Error Handling
 
-If the LLM outputs a `tag` that isn't registered (e.g. missing `@iyulab/chat-components/extra` import, or a custom extra's element isn't defined yet), `u-element-block` does **not** show an error card — it renders nothing and logs to the console instead. Genuine data errors (invalid `properties`, assignment failures) are also console-only.
+If the LLM outputs a `tag` that isn't a registered block (e.g. missing `@iyulab/chat-components/extra` import, or a custom extra's schema was never registered or its element isn't defined yet), `u-element-block` does **not** show an error card — it renders nothing and logs to the console instead. Genuine data errors (invalid `properties`, assignment failures) are also console-only.
 
 ## Security
 
-`u-element-block` maintains a `blacklist` of dangerous property names that are never bound: `innerHTML`, `outerHTML`, `textContent`, `innerText`, `outerText`, `srcdoc`. Custom elements registered as extras should only accept well-typed, data-only properties.
+`block-json` is model output and is treated as untrusted. `u-element-block` creates only registered blocks (`ElementPromptBuilder.add()` or `registerElementBlock()`; built-in extras register on import) and assigns only the property names in the block's schema `properties` — other keys, including `style`, are dropped and logged. Custom extras should accept data only; if a property is rendered as HTML, sanitize it inside the element.
 
 ## `ElementPromptBuilder` API
 
 | Method | Description |
 |--------|-------------|
 | `ElementPromptBuilder.instance` | Singleton accessor |
-| `.add(definition: ElementSchema)` | Register a custom extra (throws on tag conflict) |
+| `.add(definition: ElementSchema)` | Register a custom extra (throws on tag conflict). Also registers it as a renderable block |
 | `.build(): string` | Generate system prompt instruction string |

package/skills/iyulab-chat-components/references/security.md

@@ -0,0 +1,23 @@
+# Security model
+
+Model output is **untrusted** (prompt injection can put third-party text in any response). What each input
+is trusted to contain:
+
+| Input | Treated as | Handling |
+|---|---|---|
+| `u-marked-block` `value` | untrusted | Raw HTML shown as text · link/image URLs protocol-checked (`javascript:`/`data:`/`vbscript:`/`//host` → `#`) · code fences escaped · table cells same rules |
+| `block-json` fences | untrusted | Only registered blocks; only the schema's property names are assigned |
+| `refs` | untrusted | Text rendered as text · URLs protocol-checked in `u-ref-tag` and `u-ref-card` |
+| `u-table-block` cell `text` bound directly | **trusted HTML** | Sanitize before binding. `block-json` cannot reach it |
+| Your custom block | your element's contract | The schema allows names, not content — sanitize HTML-rendered properties inside the element |
+
+Requests: markdown images and `u-images-block` load the `http:`/`https:` URL the model writes as soon as they
+render (an image URL can carry data out). When the model reads content you do not control, call
+`setAllowedImagePrefixes([location.origin + '/', 'https://cdn.example.com/images/'])` before rendering —
+images outside the list are not requested and show their alt text (`Image blocked: …`). Prefixes match the
+resolved absolute URL; prefer paths to whole domains (open redirects). `data:image/…` is always shown (no
+request). Default: all allowed. Add CSP `img-src` as a second layer.
+`u-map-block` (OpenStreetMap iframe) and `u-video-block` (YouTube/Vimeo/direct) embed external content.
+`u-ref-card` requests no favicon by default.
+
+Do not insert model output with `innerHTML` yourself; route it through `u-marked-block`.