@iyulab/chat-components 0.18.1 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.19.0] - 2026-10-07
+
+### Added
+
+- **A citation source can carry a preview image** — `ReferenceSource.image` (`{ src, alt? }`, the shape of a
+  `u-images-block` item). `u-ref-card` draws it above the snippet, in `u-ref-block` and in the cards of an inline
+  citation's tooltip. Use it when the evidence is visual: a figure or chart taken from a document, a page
+  thumbnail, a web page's lead image. It passes the same origin policy as markdown images
+  (`setAllowedImagePrefixes`); a blocked image makes no request and its alt text shows as *Image blocked*.
+
 ## [0.18.1] - 2026-10-07
 
 ### Documentation

package/dist/components/blocks/UMarkedBlock.js

@@ -7,10 +7,10 @@ import { UElementBlock } from "./UElementBlock.js";
 import { messages } from "../../utilities/messages.js";
 import { markedKatex } from "../../utilities/markedKatex.js";
 import "../references/URefTag.js";
+import { resolveImageSource } from "../../utilities/imageSources.js";
 import { URefCard } from "../references/URefCard.js";
 import "../references/URefCardGroup.js";
 import { UTableBlock } from "./UTableBlock.js";
-import { resolveImageSource } from "../../utilities/imageSources.js";
 import { HtmlPlaceholder, extractRefPlaceholders, stripRefPlaceholders } from "../../utilities/HtmlPlaceholder.js";
 import { styles } from "./UMarkedBlock.styles.js";
 import { nothing } from "lit";

package/dist/components/blocks/URefBlock.js

@@ -43,6 +43,7 @@ var URefBlock = class URefBlock extends UElement {
               .title=${source.title || ""}
               .snippet=${source.snippet || ""}
               .tags=${source.tags}
+              .image=${source.image}
             ></u-ref-card>
           `;
 		})}

package/dist/components/references/URefCard.d.ts

@@ -1,4 +1,5 @@
 import { UDataElement } from '../UDataElement.js';
+import { ReferenceImage } from '../../types/References.js';
 /**
  * 웹 참조 카드의 파비콘 이미지 URL 을 정한다. `undefined` 를 돌려주면 파비콘 없이 그린다.
  * @param url 카드의 `url`
@@ -34,6 +35,8 @@ export declare class URefCard extends UDataElement {
     tags?: string[];
     /** 이 카드의 파비콘 리졸버 — `URefCard.defaultFaviconUrl` 보다 우선한다. */
     faviconUrl?: FaviconResolver;
+    /** 출처의 미리보기 이미지(`ReferenceSource.image`) — 이미지 출처 정책을 거친다. */
+    image?: ReferenceImage;
     render(): import('lit-html').TemplateResult<1>;
     /**
      * script-payload(UMarkedBlock 툴팁)와 property 바인딩(URefBlock) 두 사용
@@ -45,6 +48,11 @@ export declare class URefCard extends UDataElement {
     private handleAnchorClick;
     /** 리졸버가 URL 을 돌려줄 때만 파비콘을 그린다(장식 — 제목이 이름을 나른다). */
     private renderFavicon;
+    /**
+     * 미리보기 이미지 — 모델 출력의 이미지와 같은 출처 정책을 거친다. 막힌 이미지는 `<img>` 를 만들지 않는다(요청이 곧 반출
+     * 경로다) — 대체 텍스트를 «차단된 이미지» 로 보인다.
+     */
+    private renderImage;
     /** URL에서 도메인 사이트 주소를 반환합니다. */
     private getDomainName;
 }

package/dist/components/references/URefCard.js

@@ -5,6 +5,7 @@ import { sanitizeHref } from "../../utilities/sanitizers.js";
 import { UDataElement } from "../UDataElement.js";
 import { messages } from "../../utilities/messages.js";
 import { styles } from "./URefCard.styles.js";
+import { resolveImageSource } from "../../utilities/imageSources.js";
 import { html, nothing } from "lit";
 import { customElement, property } from "lit/decorators.js";
 import "@iyulab/components/dist/components/icon/UIcon.js";
@@ -58,6 +59,8 @@ var URefCard = class URefCard extends UDataElement {
           </div>
         </div>
 
+        ${this.renderImage()}
+
         <div class="body">
           ${this.snippet}
         </div>
@@ -92,6 +95,17 @@ var URefCard = class URefCard extends UDataElement {
 		if (!src) return nothing;
 		return html`<img class="favicon" src=${src} alt="" aria-hidden="true" />`;
 	}
+	/**
+	* 미리보기 이미지 — 모델 출력의 이미지와 같은 출처 정책을 거친다. 막힌 이미지는 `<img>` 를 만들지 않는다(요청이 곧 반출
+	* 경로다) — 대체 텍스트를 «차단된 이미지» 로 보인다.
+	*/
+	renderImage() {
+		const image = this.image;
+		if (!image?.src) return nothing;
+		const src = resolveImageSource(image.src);
+		if (src === null) return html`<div class="preview-blocked" part="preview-blocked">${image.alt ? messages.text("imageBlockedNamed", { name: image.alt }) : messages.text("imageBlocked")}</div>`;
+		return html`<img class="preview" part="preview" src=${src} alt=${image.alt ?? ""} loading="lazy" />`;
+	}
 	/** URL에서 도메인 사이트 주소를 반환합니다. */
 	getDomainName(url) {
 		if (!url) return "";
@@ -114,6 +128,7 @@ __decorate([property({
 	converter: arrayAttrConverter((v) => v)
 }), __decorateMetadata("design:type", Array)], URefCard.prototype, "tags", void 0);
 __decorate([property({ attribute: false }), __decorateMetadata("design:type", Object)], URefCard.prototype, "faviconUrl", void 0);
+__decorate([property({ type: Object }), __decorateMetadata("design:type", Object)], URefCard.prototype, "image", void 0);
 URefCard = _URefCard = __decorate([customElement("u-ref-card")], URefCard);
 //#endregion
 export { URefCard, googleFaviconUrl };

package/dist/components/references/URefCard.styles.js

@@ -82,6 +82,23 @@ var styles = css`
     margin-top: 8px;
   }
 
+  /* 출처 미리보기 — 본문 위, 카드 폭 안. 도표·그림이 잘리지 않게 담는다(contain). */
+  .preview {
+    display: block;
+    align-self: flex-start;
+    max-width: 100%;
+    max-height: 160px;
+    margin-top: 8px;
+    object-fit: contain;
+    border-radius: 4px;
+  }
+  .preview-blocked {
+    margin-top: 8px;
+    color: var(--u-txt-color-weak);
+    font-size: 12px;
+    line-height: 1.5;
+  }
+
   .footer {
     display: flex;
     gap: 4px;

package/dist/index.js

@@ -6,10 +6,10 @@ import { getElementBlockProperties, registerElementBlock } from "./utilities/Ele
 import { UElementBlock } from "./components/blocks/UElementBlock.js";
 import { UFileBlock } from "./components/blocks/UFileBlock.js";
 import { URefTag } from "./components/references/URefTag.js";
+import { getAllowedImagePrefixes, resolveImageSource, setAllowedImagePrefixes } from "./utilities/imageSources.js";
 import { URefCard, googleFaviconUrl } from "./components/references/URefCard.js";
 import { URefCardGroup } from "./components/references/URefCardGroup.js";
 import { UTableBlock } from "./components/blocks/UTableBlock.js";
-import { getAllowedImagePrefixes, resolveImageSource, setAllowedImagePrefixes } from "./utilities/imageSources.js";
 import { UMarkedBlock } from "./components/blocks/UMarkedBlock.js";
 import { UTextBlock } from "./components/blocks/UTextBlock.js";
 import { URefBlock } from "./components/blocks/URefBlock.js";

package/dist/types/References.d.ts

@@ -12,6 +12,19 @@ export interface ReferenceSource {
     snippet?: string;
     /** 태그 */
     tags?: string[];
+    /**
+     * 출처의 미리보기 이미지 — 인용한 그림·도표 자체, 문서 쪽의 축소판, 웹 문서의 대표 이미지.
+     * 카드가 본문 위에 그린다. 모델 출력의 이미지와 같은 출처 정책(`setAllowedImagePrefixes`)을 거치며,
+     * 막히면 요청하지 않고 대체 텍스트를 «차단된 이미지» 로 보인다.
+     */
+    image?: ReferenceImage;
+}
+/** 출처의 미리보기 이미지 — `u-images-block` 의 항목과 같은 모양이다. */
+export interface ReferenceImage {
+    /** 이미지 URL */
+    src: string;
+    /** 대체 텍스트 — 이미지가 근거 자체(도표·그림)면 무엇을 보여 주는지 적는다. 없으면 장식으로 다룬다(카드 제목이 이름을 나른다). */
+    alt?: string;
 }
 /**
  * 본문 내 참조 인용 정보입니다.

package/package.json

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

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

@@ -41,5 +41,11 @@ interface ReferenceSource {
   title?: string;     // Card title
   snippet?: string;   // Excerpt text
   tags?: string[];    // Tag list
+  image?: ReferenceImage; // Preview image of the source (a figure, a page thumbnail, a page's lead image)
+}
+
+interface ReferenceImage {
+  src: string;
+  alt?: string;
 }
 ```

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

@@ -47,6 +47,7 @@ Extends `UDataElement`, so data can also be injected via a `<script type="applic
 | `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` |
+| `image` | `ReferenceImage` | `undefined` | — | Preview image (`{ src, alt? }`), drawn above the snippet. Passes the image origin policy (`setAllowedImagePrefixes`); a blocked image makes no request and shows its alt text as *Image blocked* |
 
 ---
 

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

@@ -7,12 +7,12 @@ is trusted to contain:
 |---|---|---|
 | `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` |
+| `refs` | untrusted | Text rendered as text · URLs protocol-checked in `u-ref-tag` and `u-ref-card` · a source `image` passes the image origin policy |
 | `u-table-block` cell `text` bound directly | untrusted | Rendered as text; search, sort and downloads use it |
 | `u-table-block` cell `html` bound directly | **trusted HTML** | Display only. 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
+Requests: markdown images, `u-images-block` and citation previews (`ReferenceSource.image`) 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

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

@@ -68,6 +68,13 @@ interface ReferenceSource {
   title?: string;
   snippet?: string;
   tags?: string[];
+  image?: ReferenceImage;
+}
+
+/** Preview image of a source — the same shape as a `u-images-block` item. Passes the image origin policy. */
+interface ReferenceImage {
+  src: string;
+  alt?: string;   // say what a figure shows; omit for a decorative image (the card title names the card)
 }
 
 interface ReferenceCitation {