@iyulab/chat-components 0.6.0 → 0.7.1

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

@@ -1,10 +1,10 @@
 ---
 name: iyulab-chat-components
-description: LLM chat UI component library. Covers all u-* custom elements for building chat interfaces — message rendering, chat input, markdown/code blocks, file attachments, reference citations, and the Intent/View system. Use when working with @iyulab/chat-components package.
+description: LLM chat UI component library. Covers all u-* custom elements for building chat interfaces — message rendering, chat input, markdown/code/table/file blocks, reference citations, and the block-json Extra system (chart/images/map/video). Use when working with @iyulab/chat-components package.
 license: MIT
 metadata:
   author: iyulab
-  version: "0.5.2"
+  version: "0.7.0"
 ---
 
 # @iyulab/chat-components
@@ -43,21 +43,13 @@ import '@iyulab/chat-components/dist/components/prompt/UPrompt.js';
 
 ### Content Blocks
 
-- [`u-marked-block`](./references/components/marked-block.md) — Renders markdown to HTML. KaTeX math, code highlighting, citation insertion, view-json/intent-json handling
+- [`u-marked-block`](./references/components/marked-block.md) — Renders markdown to HTML. KaTeX math, code highlighting, citation insertion, `block-json` extra handling
 - [`u-code-block`](./references/components/code-block.md) — Highlight.js code block with language label and clipboard copy
 - [`u-text-block`](./references/components/text-block.md) — Plain text display or editable textarea
-- [`u-think-block`](./references/components/think-block.md) — LLM reasoning (thinking) block. Collapse/expand, auto-scroll
-- [`u-tool-block`](./references/components/tool-block.md) — Tool call input/output display. Collapse/expand
-- [`u-file-block`](./references/components/file-block.md) — File attachment card. Type icon, upload status, download, remove
+- [`u-file-block`](./references/components/file-block.md) — File attachment card. Type icon or image/video thumbnail, click-to-preview, remove
 - [`u-ref-block`](./references/components/ref-block.md) — Reference source group block. Collapse/expand, grid of ref cards
-- [`u-json-block`](./references/components/json-block.md) — Visualizes JSON data as a collapsible tree
 - [`u-table-block`](./references/components/table-block.md) — Markdown table renderer. Column sort, search filter, CSV/XLS download
-
-### Action Buttons
-
-- [`u-copy-button`](./references/components/copy-button.md) — Clipboard copy button; icon changes after copy
-- [`u-vote-button`](./references/components/vote-button.md) — Thumbs-up / thumbs-down vote button pair
-- [`u-attach-button`](./references/components/attach-button.md) — File picker button; fires `attach` event with selected files
+- [`u-element-block`](./references/components/element-block.md) — Generic dynamic custom-element renderer, used internally to render `block-json` extras
 
 ### Reference Components
 
@@ -65,43 +57,36 @@ import '@iyulab/chat-components/dist/components/prompt/UPrompt.js';
 - [`u-ref-card`](./references/components/ref-card.md) — Reference source card. web/document type, favicon, tags
 - [`u-ref-card-group`](./references/components/ref-card-group.md) — Paginated group of reference cards
 
-### Intent Components
-
-- [`u-question-intent`](./references/components/question-intent.md) — LLM-generated question with clickable choice buttons
+### Extra Components (optional, `@iyulab/chat-components/extra`)
 
-### View Components
+Not part of the core entrypoint — see [./references/extra-system.md](./references/extra-system.md) for setup.
 
-- [`u-images-view`](./references/components/images-view.md) — Image gallery (carousel + lightbox)
-- [`u-video-view`](./references/components/video-view.md) — YouTube / Vimeo / direct video file player
-- [`u-chart-view`](./references/components/chart-view.md) — Chart.js charts (bar, line, pie, etc.)
-- [`u-map-view`](./references/components/map-view.md) — OpenStreetMap embed
-- [`u-view`](./references/components/view.md) — Dynamic custom element renderer (runtime for view-json blocks)
+- [`u-images-block`](./references/components/images-block.md) — Image gallery (carousel + lightbox)
+- [`u-video-block`](./references/components/video-block.md) — YouTube / Vimeo / direct video file player
+- [`u-chart-block`](./references/components/chart-block.md) — Chart.js charts (bar, line, pie, etc.)
+- [`u-map-block`](./references/components/map-block.md) — OpenStreetMap embed
 
 ---
 
 ## Utilities
 
-- [`IntentPromptBuilder`](./references/utilities/intent-prompt-builder.md) — Build LLM system prompt instructions for intents and parse intent-json responses
-- [`ViewPromptBuilder`](./references/utilities/view-prompt-builder.md) — Build LLM system prompt instructions for views
+- [`ElementPromptBuilder`](./references/utilities/prompt-builder.md) — Build LLM system prompt instructions for `block-json` extras/elements
+- [`HtmlBuilder`](./references/utilities/html-builder.md) — Build custom-element HTML strings (used internally by `u-marked-block`)
 
 ---
 
 ## Types
 
-- [`BlockItem`](./references/types.md) — Union type for message content blocks (text, markdown, file, tool, reference, thinking)
+- [`BlockItem`](./references/types.md) — Union type for message content blocks (text, markdown, file, reference)
 - `ReferenceSource` / `ReferenceCitation` — Citation source and inline citation position types
-- `IntentDefinition` / `PresetIntent` — Intent definition and preset bit flags
-- `ViewDefinition` / `PresetView` — View definition and preset bit flags
+- `ElementSchema` / `JsonSchema` — Schema types for registering `block-json` extras/elements with `ElementPromptBuilder`
 
 ---
 
 ## Events
 
 | Event | Source | Detail Type | Description |
-|-------|--------|-------------|-------------|
-| `send` | `u-prompt` | `unknown` | Send button clicked or Enter pressed |
-| `stop` | `u-prompt` | `unknown` | Stop button clicked while loading |
-| `attach` | `u-attach-button` | `{ files: File[] }` | File selection completed |
-| `choice` | `u-question-intent` | `{ value: string }` | Choice button clicked |
-| `change` | `u-vote-button` | `Event` | Vote state changed |
+|-------|--------|-------------|--------------|
+| `send` | `u-prompt` | `SendEventDetail` (`{ value, files? }`) | Send button clicked or Enter pressed. Non-bubbling |
+| `stop` | `u-prompt` | `StopEventDetail` (`{}`) | Stop button clicked while loading. Non-bubbling |
 | `remove` | `u-file-block` | `RemoveEventDetail` | Remove button clicked |

package/skills/iyulab-chat-components/references/components/{chart-view.md → chart-block.md}

@@ -1,40 +1,40 @@
-# u-chart-view
+# u-chart-block
 
 ```ts
-import '@iyulab/chat-components/dist/components/views/UChartView.js';
+import '@iyulab/chat-components/dist/components-extra/UChartBlock.js';
 ```
 
-**Tag:** `u-chart-view`
+**Tag:** `u-chart-block` — one of the 4 built-in **extra** blocks. Not part of the core entrypoint; import it (or the whole `/extra` subpath) explicitly. See [../extra-system.md](../extra-system.md).
 
-Renders charts using Chart.js (lazy-loaded). Supports PNG and JSON download. Automatically re-renders when the page theme changes.
+Renders charts using Chart.js (statically imported). Supports PNG and JSON download, and a full-screen toggle. Automatically re-renders when the page theme changes.
 
 ```html
 <!-- Bar chart -->
-<u-chart-view
+<u-chart-block
   type="bar"
   .data=${{
     labels: ['Jan', 'Feb', 'Mar'],
     datasets: [{ label: 'Revenue', data: [100, 200, 150] }]
   }}
-></u-chart-view>
+></u-chart-block>
 
 <!-- Line chart with options -->
-<u-chart-view
+<u-chart-block
   type="line"
   .data=${{
     labels: ['A', 'B', 'C', 'D'],
     datasets: [{ label: 'Trend', data: [10, 40, 30, 60], fill: true }]
   }}
   .options=${{ plugins: { legend: { position: 'bottom' } } }}
-></u-chart-view>
+></u-chart-block>
 ```
 
-LLM output example (`view-json` code block):
+LLM output example (`block-json` code fence, rendered via `u-element-block`):
 
 ````
-```view-json
+```block-json
 {
-  "tag": "u-chart-view",
+  "tag": "u-chart-block",
   "properties": {
     "type": "bar",
     "data": {
@@ -60,6 +60,10 @@ LLM output example (`view-json` code block):
 
 | Feature | Description |
 |---------|-------------|
-| Lazy load | Chart.js is dynamically imported on first render |
 | Download | Export chart as PNG or raw JSON data |
+| Full screen | Toggle the chart viewport into full-screen mode |
 | Theme sync | Watches `document.documentElement[theme]` and re-renders on change |
+
+## Requires
+
+`chart.js` (optional peer dependency) must be installed to use this component. It's imported statically at module load, not lazily.

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

@@ -6,7 +6,7 @@ import '@iyulab/chat-components/dist/components/blocks/UCodeBlock.js';
 
 **Tag:** `u-code-block`
 
-Syntax-highlighted code block powered by Highlight.js. Shows a language label, clipboard copy button, and loading spinner. Automatically rendered inside `u-marked-block` for fenced code blocks.
+Syntax-highlighted code block powered by Highlight.js. Shows a language label and a clipboard copy button (from `@iyulab/components`). Automatically rendered inside `u-marked-block` for fenced code blocks.
 
 ```html
 <!-- Direct usage -->
@@ -15,9 +15,6 @@ Syntax-highlighted code block powered by Highlight.js. Shows a language label, c
 <!-- Without header -->
 <u-code-block lang="json" headless .value=${JSON.stringify({key: 'value'}, null, 2)}></u-code-block>
 
-<!-- Loading state (streaming) -->
-<u-code-block lang="python" loading .value=${"def hello():"}></u-code-block>
-
 <!-- Inject code via slot -->
 <u-code-block lang="javascript">
   console.log("Hello from slot");
@@ -32,7 +29,6 @@ Syntax-highlighted code block powered by Highlight.js. Shows a language label, c
 |----------|------|---------|---------|-------------|
 | `lang` | `string` | `'plaintext'` | ✓ | Code language. Falls back to `plaintext` if not supported by Highlight.js |
 | `value` | `string` | `undefined` | — | Code content. Can also be set via slot `textContent` |
-| `loading` | `boolean` | `false` | ✓ | Loading state. Replaces the code icon with a spinner in the header |
 | `headless` | `boolean` | `false` | ✓ | Hides the header (language label + copy button) |
 
 ## Slots

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

@@ -0,0 +1,57 @@
+# u-element-block
+
+```ts
+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.
+
+Extends `UDataElement`, so `tag`/`properties` can also be injected via a `<script type="application/json">` slot.
+
+```html
+<!-- Render u-chart-block dynamically -->
+<u-element-block
+  tag="u-chart-block"
+  .properties=${{
+    type: 'bar',
+    data: { labels: ['A', 'B'], datasets: [{ data: [10, 20] }] }
+  }}
+></u-element-block>
+
+<!-- Loading state (skeleton placeholder) -->
+<u-element-block tag="u-chart-block" loading></u-element-block>
+```
+
+How `u-marked-block` processes a `block-json` fence:
+
+````
+```block-json
+{
+  "tag": "u-images-block",
+  "properties": { "items": [{ "src": "https://..." }] }
+}
+```
+````
+
+This is converted to `<u-element-block tag="u-images-block" ...>` via `UElementBlock.buildHTML()`.
+
+---
+
+## Properties
+
+| 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 |
+| `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.
+
+## Security
+
+The following property names are blocked by default to prevent XSS: `innerHTML`, `outerHTML`, `textContent`, `innerText`, `outerText`, `srcdoc`. Extend `blacklist` to add more restrictions.

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

@@ -6,22 +6,16 @@ import '@iyulab/chat-components/dist/components/blocks/UFileBlock.js';
 
 **Tag:** `u-file-block`
 
-Displays a single file as a card. Shows a type-appropriate icon, upload status, download link, and an optional remove button.
+Displays a single file as a card. Shows a type-appropriate icon (or an actual thumbnail for image/video files with a `url`), and an optional remove button. There is no download affordance — wire up your own using the `url` property if needed.
+
+Clicking anywhere on the card opens a full-size preview overlay, but only for image/video files that have a `url` set; other file types are not clickable.
 
 ```html
-<!-- Image file -->
-<u-file-block name="photo.png" type="image/png" size=${102400}></u-file-block>
+<!-- Generic file (icon by MIME type) -->
+<u-file-block name="report.xlsx" type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" size=${512000}></u-file-block>
 
-<!-- Uploading state -->
-<u-file-block name="document.pdf" type="application/pdf" status="uploading"></u-file-block>
-
-<!-- With download link -->
-<u-file-block
-  name="report.xlsx"
-  type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
-  size=${512000}
-  url="https://example.com/report.xlsx"
-></u-file-block>
+<!-- Image file — renders a thumbnail, click opens full-size preview -->
+<u-file-block name="photo.png" type="image/png" size=${102400} url="https://example.com/photo.png"></u-file-block>
 
 <!-- Removable (e.g. prompt attachment) -->
 <u-file-block
@@ -39,26 +33,29 @@ Displays a single file as a card. Shows a type-appropriate icon, upload status,
 | Property | Type | Default | Reflect | Description |
 |----------|------|---------|---------|-------------|
 | `removable` | `boolean` | `false` | ✓ | Shows the remove button |
-| `status` | `'idle'\|'uploading'\|'error'` | `undefined` | ✓ | File state. `uploading` shows spinner; `error` shows error icon |
 | `name` | `string` | `undefined` | — | File name |
-| `type` | `string` | `undefined` | — | MIME type (determines icon) |
-| `size` | `number` | `undefined` | — | File size in bytes; auto-formatted to KB/MB |
-| `url` | `string` | `undefined` | — | Download URL. Shows download button when set |
+| `type` | `string` | `undefined` | — | MIME type (determines icon / thumbnail) |
+| `size` | `number` | `undefined` | — | File size in bytes; auto-formatted to KB/MB/GB |
+| `url` | `string` | `undefined` | — | File URL, used for the image/video thumbnail and preview overlay |
 
 ## Events
 
 | Event | Detail | Description |
-|-------|--------|-------------|
+|-------|--------|--------------|
 | `remove` | `RemoveEventDetail` | Fired when the remove button is clicked. If not cancelled, the element removes itself from the DOM |
 
 ## Icon Resolution by MIME Type
 
+Only used when `type` doesn't start with `image/` or `video/` (or `url` is unset) — otherwise an actual `<img>`/`<video>` thumbnail is rendered instead.
+
 | MIME | Icon |
 |------|------|
-| `image/*` | `file-earmark-image` |
-| `video/*` | `file-earmark-play` |
-| `audio/*` | `file-earmark-music` |
-| `application/pdf` | `file-earmark-pdf` |
-| `application/zip` | `file-earmark-zip` |
-| `text/*` | `file-earmark-text` |
-| other | `file-earmark` |
+| `image/*` | photo |
+| `video/*` | video |
+| `audio/*` | file-music |
+| `application/pdf` | file-type-pdf |
+| code types (`application/json`, `text/html`, `text/x-*`, etc.) | file-code |
+| spreadsheet types (`.xls`, `.xlsx`, `text/csv`) | file-spreadsheet |
+| archive types (`.zip`, `.tar`, `.rar`, `.gz`, `.7z`) | file-zip |
+| `text/*` | file-text |
+| other | file |

package/skills/iyulab-chat-components/references/components/{images-view.md → images-block.md}

@@ -1,32 +1,32 @@
-# u-images-view
+# u-images-block
 
 ```ts
-import '@iyulab/chat-components/dist/components/views/UImagesView.js';
+import '@iyulab/chat-components/dist/components-extra/UImagesBlock.js';
 ```
 
-**Tag:** `u-images-view`
+**Tag:** `u-images-block` — one of the 4 built-in **extra** blocks. Not part of the core entrypoint; import it (or the whole `/extra` subpath) explicitly. See [../extra-system.md](../extra-system.md).
 
-Image gallery view. Uses `u-carousel` for a horizontal slide layout, with a click-to-open lightbox. Shows up to 3 slides at once. Keyboard arrow keys navigate the lightbox.
+Image gallery. Uses `u-carousel` for a horizontal slide layout, with a click-to-open lightbox. Shows up to 3 slides at once. Keyboard arrow keys navigate the lightbox.
 
-Automatically rendered by `u-marked-block` from a `view-json` code block.
+Automatically rendered by `u-marked-block` from a `block-json` code fence via `u-element-block`.
 
 ```html
 <!-- Direct usage -->
-<u-images-view
+<u-images-block
   .items=${[
     { src: 'https://example.com/photo1.jpg', alt: 'First photo', caption: 'Seoul at night' },
     { src: 'https://example.com/photo2.jpg', caption: 'Busan beach' },
     { src: 'https://example.com/photo3.jpg' }
   ]}
-></u-images-view>
+></u-images-block>
 ```
 
-LLM output example (`view-json` code block):
+LLM output example (`block-json` code fence):
 
 ````
-```view-json
+```block-json
 {
-  "tag": "u-images-view",
+  "tag": "u-images-block",
   "properties": {
     "items": [
       { "src": "https://example.com/photo.jpg", "alt": "Description", "caption": "Caption" }

package/skills/iyulab-chat-components/references/components/{map-view.md → map-block.md}

@@ -1,33 +1,33 @@
-# u-map-view
+# u-map-block
 
 ```ts
-import '@iyulab/chat-components/dist/components/views/UMapView.js';
+import '@iyulab/chat-components/dist/components-extra/UMapBlock.js';
 ```
 
-**Tag:** `u-map-view`
+**Tag:** `u-map-block` — one of the 4 built-in **extra** blocks. Not part of the core entrypoint; import it (or the whole `/extra` subpath) explicitly. See [../extra-system.md](../extra-system.md).
 
 Embeds an OpenStreetMap iframe centered on a given coordinate. A marker is placed at the specified `lat`/`lng` position.
 
 ```html
 <!-- Basic map -->
-<u-map-view lat="37.5665" lng="126.9780"></u-map-view>
+<u-map-block lat="37.5665" lng="126.9780"></u-map-block>
 
 <!-- With label, description, and zoom -->
-<u-map-view
+<u-map-block
   lat="37.5665"
   lng="126.9780"
   zoom="13"
   label="Seoul City Hall"
   description="110 Sejong-daero, Jung-gu, Seoul"
-></u-map-view>
+></u-map-block>
 ```
 
-LLM output example (`view-json` code block):
+LLM output example (`block-json` code fence, rendered via `u-element-block`):
 
 ````
-```view-json
+```block-json
 {
-  "tag": "u-map-view",
+  "tag": "u-map-block",
   "properties": {
     "lat": 37.5665,
     "lng": 126.9780,

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

@@ -6,13 +6,14 @@ import '@iyulab/chat-components/dist/components/blocks/UMarkedBlock.js';
 
 **Tag:** `u-marked-block`
 
-Renders markdown text to HTML. Supports KaTeX math equations, code syntax highlighting, inline citation tag injection, and special handling for `view-json` and `intent-json` code blocks. Applying an 80ms debounce makes it suitable for LLM streaming.
+Renders markdown text to HTML. Supports KaTeX math equations, code syntax highlighting, inline citation tag injection, and special handling for `block-json` code fences (the [extra system](../extra-system.md)). Applying an 80ms debounce makes it suitable for LLM streaming.
 
-**Special code fences:**
-- `` ```view-json `` → automatically rendered as a `u-view` component
-- `` ```intent-json `` → stripped from output (must be parsed separately via `IntentPromptBuilder`)
+**Special code fence:**
+- `` ```block-json `` → automatically rendered via [`u-element-block`](./element-block.md)
 - All other HTML inside markdown is escaped to prevent XSS
 
+Tracks a `streaming` state internally (resets a 1500ms idle timer on every `value` update). A `block-json` extra's `loading` stays `true` until both its own fence is closed and the message has been idle for 1500ms.
+
 ```html
 <!-- Basic markdown -->
 <u-marked-block value="# Hello\n\nThis is **bold** and `code`."></u-marked-block>

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

@@ -29,8 +29,7 @@ Chat message wrapper component. Arranges content blocks via slots, shows a loadi
   <div slot="header">AI Assistant</div>
   <u-marked-block .value=${content}></u-marked-block>
   <div slot="footer">
-    <u-copy-button .value=${content}></u-copy-button>
-    <u-vote-button></u-vote-button>
+    <!-- Add your own action buttons here (e.g. @iyulab/components's copy-button) -->
   </div>
 </u-message>
 ```

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

@@ -15,11 +15,9 @@ Chat input component. Combines a text input area, file attachment previews, and
 <!-- Loading (streaming) state -->
 <u-prompt loading></u-prompt>
 
-<!-- With file attach button -->
+<!-- Custom actions via slots (there is no built-in attach button) -->
 <u-prompt>
-  <u-attach-button slot="left-actions" multiple accept="image/*,application/pdf">
-    Attach
-  </u-attach-button>
+  <button slot="left-actions" @click=${openFilePicker}>Attach</button>
 </u-prompt>
 ```
 
@@ -37,20 +35,11 @@ prompt.addEventListener('stop', () => {
   console.log('stopped');
 });
 
-// Wire up file attach button
-prompt.addEventListener('attach', (e) => {
-  const { files } = e.detail;
-  prompt.files = [
-    ...(prompt.files ?? []),
-    ...files.map(f => ({
-      type: 'file' as const,
-      name: f.name,
-      size: f.size,
-      mimeType: f.type,
-      status: 'idle' as const,
-    }))
-  ];
-});
+// Attaching files (no built-in picker — wire up your own <input type="file">)
+prompt.files = [
+  ...(prompt.files ?? []),
+  { type: 'file' as const, name: 'photo.png', size: 12345, mimeType: 'image/png' }
+];
 
 // Programmatic submit
 prompt.submit();
@@ -63,7 +52,7 @@ prompt.submit();
 | Name | Description |
 |------|-------------|
 | `header` | Area above the input |
-| `left-actions` | Left side of the control bar (e.g. attach button) |
+| `left-actions` | Left side of the control bar (e.g. a custom attach button) |
 | `right-actions` | Right side of the control bar |
 | `footer` | Area below the input |
 
@@ -86,10 +75,12 @@ prompt.submit();
 
 ## Events
 
+Both `send` and `stop` are dispatched with `bubbles: false, composed: false` — listen directly on the `u-prompt` element, they won't bubble past it.
+
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `send` | `unknown` | Fired on Enter or send button click |
-| `stop` | `unknown` | Fired on send button click while loading |
+| `send` | `SendEventDetail` (`{ value, files? }`) | Fired on Enter or send button click (only when there's a value or files) |
+| `stop` | `StopEventDetail` (`{}`) | Fired on send button click while loading |
 | `remove` | `RemoveEventDetail` | Fired when an attached file's remove button is clicked |
 
 ## CSS Parts

package/skills/iyulab-chat-components/references/components/{video-view.md → video-block.md}

@@ -1,34 +1,34 @@
-# u-video-view
+# u-video-block
 
 ```ts
-import '@iyulab/chat-components/dist/components/views/UVideoView.js';
+import '@iyulab/chat-components/dist/components-extra/UVideoBlock.js';
 ```
 
-**Tag:** `u-video-view`
+**Tag:** `u-video-block` — one of the 4 built-in **extra** blocks. Not part of the core entrypoint; import it (or the whole `/extra` subpath) explicitly. See [../extra-system.md](../extra-system.md).
 
 Embeds a video from YouTube, Vimeo, or a direct file URL. Automatically detects the platform from the URL and selects the appropriate player.
 
 ```html
 <!-- YouTube -->
-<u-video-view src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"></u-video-view>
+<u-video-block src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"></u-video-block>
 
 <!-- Vimeo -->
-<u-video-view src="https://vimeo.com/123456789"></u-video-view>
+<u-video-block src="https://vimeo.com/123456789"></u-video-block>
 
 <!-- Direct video file -->
-<u-video-view
+<u-video-block
   src="https://example.com/video.mp4"
   poster="https://example.com/thumbnail.jpg"
   ratio="4:3"
-></u-video-view>
+></u-video-block>
 ```
 
-LLM output example (`view-json` code block):
+LLM output example (`block-json` code fence, rendered via `u-element-block`):
 
 ````
-```view-json
+```block-json
 {
-  "tag": "u-video-view",
+  "tag": "u-video-block",
   "properties": {
     "src": "https://www.youtube.com/watch?v=VIDEO_ID"
   }

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

@@ -0,0 +1,95 @@
+# Extra System
+
+Extras let the LLM render rich media content — charts, maps, image galleries, videos — directly inside a chat message by outputting a `block-json` fenced code block. **Extras are rendered automatically** by `u-marked-block`; no manual parsing is required.
+
+## How It Works
+
+1. **Register** extra schemas with `ElementPromptBuilder` (or just import the built-in `prompt`)
+2. **Inject** the resulting instruction string into your LLM system prompt
+3. **Automatic rendering**: `u-marked-block` detects `block-json` fences and passes them to [`u-element-block`](./components/element-block.md), which creates the appropriate custom element with the specified properties
+
+````
+```block-json
+{
+  "tag": "u-chart-block",
+  "properties": {
+    "type": "bar",
+    "data": { "labels": ["Jan", "Feb", "Mar"], "datasets": [{ "label": "Revenue ($k)", "data": [120, 98, 145] }] }
+  }
+}
+```
+````
+
+## Setup
+
+The 4 built-in extras (chart/images/map/video) are not part of the core package — import `@iyulab/chat-components/extra` to register all of them at once and get a ready-built prompt fragment:
+
+```ts
+import '@iyulab/chat-components';
+import { prompt } from '@iyulab/chat-components/extra';
+
+const systemPrompt = `You are a helpful assistant.\n\n${prompt}`;
+```
+
+`prompt` is built once at import time from the 4 built-in schemas. Registering additional custom extras via `ElementPromptBuilder.instance.add(...)`? Call `ElementPromptBuilder.instance.build()` again to get a fragment that includes both the built-ins and your custom extras.
+
+Need only one or two of the built-ins (e.g. to skip bundling `chart.js`)? Import the specific component directly instead of the bulk `/extra` entry:
+
+```ts
+import '@iyulab/chat-components/dist/components-extra/UImagesBlock.js';
+```
+
+## Built-in Extras
+
+| Tag | Doc |
+|-----|-----|
+| `u-images-block` | [components/images-block.md](./components/images-block.md) |
+| `u-video-block` | [components/video-block.md](./components/video-block.md) |
+| `u-chart-block` | [components/chart-block.md](./components/chart-block.md) |
+| `u-map-block` | [components/map-block.md](./components/map-block.md) |
+
+## Registering Custom Extras
+
+```ts
+import { ElementPromptBuilder } from '@iyulab/chat-components';
+import type { ElementSchema } from '@iyulab/chat-components';
+
+class MyTimelineBlock extends HTMLElement { /* ... */ }
+customElements.define('my-timeline-block', MyTimelineBlock);
+
+const def: ElementSchema = {
+  tag: 'my-timeline-block',
+  description: 'Display a sequence of events on a timeline',
+  properties: {
+    events: {
+      type: 'array',
+      items: { type: 'object', properties: {
+        date:  { type: 'string', description: 'ISO date string' },
+        title: { type: 'string', description: 'Event title' },
+      }, required: ['date', 'title'] },
+      description: 'Array of timeline events',
+    }
+  },
+  required: ['events'],
+};
+
+ElementPromptBuilder.instance.add(def);
+```
+
+The element just needs to accept standard property assignments — `u-element-block` binds `properties` keys directly to element properties.
+
+## 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.
+
+## 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.
+
+## `ElementPromptBuilder` API
+
+| Method | Description |
+|--------|-------------|
+| `ElementPromptBuilder.instance` | Singleton accessor |
+| `.add(definition: ElementSchema)` | Register a custom extra (throws on tag conflict) |
+| `.build(): string` | Generate system prompt instruction string |