@hidemikimura/chit-ui 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 バージョンは [Semantic Versioning](https://semver.org/lang/ja/) に従いますが、0.x の間は
 マイナー更新に破壊的変更が入ることがあります。
 
+## 0.3.2 — 2026-09-20
+
+### 追加
+
+- **AI コーディング支援向けの説明書を同梱しました**（`skills/chit-ui/`）。Claude Code などに
+  読ませると、`messages` の所有者が利用者側であること、`push` では描画されないこと、
+  `text` と `html` の使い分けといった、このライブラリの癖を踏まえたコードになります。
+  npm パッケージにも入っているので、`node_modules/@hidemikimura/chit-ui/skills/chit-ui/` から
+  そのまま参照できます。
+- **ドキュメントサイトを用意しました**（`site/`）。ビルド工程のない素の HTML/CSS/JS で、
+  ページの上で本物のウィジェットが動きます。GitHub Pages へ上げるワークフローも
+  同梱しています（npm パッケージには含めていません）。
+
 ## 0.3.1 — 2026-09-20
 
 ### 追加

package/README.md

@@ -8,7 +8,11 @@ JavaScript ライブラリです。通信も会話ロジックも、発言の中
 - 閉じた状態（ランチャー）・開いた状態（パネル）・非表示の 3 状態
 - 状態ごとのテーマ。閉じた状態は PC とスマホで別々に指定できます
 - 発言の中身は HTML 文字列でも Lit テンプレートでも `LitElement` を継承したコンポーネントでも可
-- 依存は Lit のみ。単一バンドルは gzip 約 19 KB
+- 依存は Lit のみ。単一バンドルは gzip 約 26 KB
+
+ドキュメントサイト（人間向け）は [`site/`](site/) にあります。`npm run dev` のあと
+`/site/` を開くとその場で読めます。AI コーディング支援向けの説明書は
+[`skills/chit-ui/`](skills/chit-ui/) にあり、npm パッケージにも同梱しています。
 
 ## はじめに
 
@@ -731,7 +735,7 @@ chat.addEventListener('chat-message-click', (event) => {
 - ストリーミング中の発言は `aria-busy="true"` なので、1 文字ずつ読み上げられません
 - `prefers-reduced-motion` を尊重します
 - 既定テーマの文字色と背景色の組み合わせはすべて WCAG AA（4.5:1）以上です
-- `npm run audit:a11y` で axe-core による監査を実行できます（6 状態、違反 0 を維持）
+- `npm run audit:a11y` で axe-core による監査を実行できます（10 状態、違反 0 を維持）
 
 ## ブラウザ
 
@@ -752,6 +756,13 @@ npm run build        # 型定義と単一バンドルを dist/ に出力
 npm run check        # 上記をまとめて
 ```
 
+### ドキュメントと skill
+
+API を変えたら、`README.md`・`site/`（ドキュメントサイト）・`skills/`（AI 向け）の 3 つを
+一緒に更新します。サイトはビルド工程を持たないので、`site/` の HTML を直せばそれで終わりです。
+公開は `.github/workflows/pages.yml` が `site/` を GitHub Pages へ上げます
+（Settings → Pages → Source を「GitHub Actions」にしておく）。
+
 ### リリース前の手動チェック
 
 IME の実挙動は合成イベントでは再現しきれないため、リリース前に実機で確認します。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hidemikimura/chit-ui",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Lit-based chat widget UI: launcher, panel, themable, any HTML or Lit component as a message",
   "license": "MIT",
   "author": "Hidemi Kimura",
@@ -26,6 +26,7 @@
   "files": [
     "src",
     "dist",
+    "skills",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/skills/README.md

@@ -0,0 +1,34 @@
+# AI 向けの skill
+
+`chit-ui/` は、Chit UI を組み込む人の AI コーディング支援（Claude Code、Cursor、
+その他 skill を読めるツール）向けの説明書です。npm パッケージにも同梱しているので、
+`node_modules/@hidemikimura/chit-ui/skills/chit-ui/` からそのまま参照できます。
+
+```
+chit-ui/
+├── SKILL.md              境界・最小の組み込み・間違えやすいところ
+└── references/
+    ├── api.md            全プロパティ・イベント・スロット・パーツ・CSS 変数・テーマ
+    └── recipes.md        用途別の書き方（ストリーミング、シナリオ型、添付、LIFF ほか）
+```
+
+## 使い方
+
+Claude Code なら、プロジェクトの `.claude/skills/` に置くか、シンボリックリンクを張ります。
+
+```sh
+mkdir -p .claude/skills
+ln -s ../../node_modules/@hidemikimura/chit-ui/skills/chit-ui .claude/skills/chit-ui
+```
+
+skill を読み込まないツールでも、`SKILL.md` と `references/` を渡せばそのまま使えます。
+
+## 書くときの約束
+
+人間向けの説明は README.md とドキュメントサイト（`site/`）が正本で、ここはその要約では
+ありません。**AI が間違えやすいところ**を優先して書きます。`messages` の所有者が利用者側で
+あること、`push` では描画されないこと、`text` と `html` の使い分け、`typing` と `loading`
+が排他であること、といった「知らないと自然に踏む地雷」が中心です。
+
+API を変えたら、README.md・`site/`・`skills/` の 3 つを一緒に更新してください。
+`references/api.md` の冒頭には対象バージョンを書いています。

package/skills/chit-ui/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: chit-ui
+description: Chit UI（@hidemikimura/chit-ui）でチャットウィジェットを組み込む・直すときに必ず使う。Lit 製のチャット UI を Web ページやアプリに載せる、吹き出しやランチャーの見た目を変える、発言にカスタムコンポーネントを差し込む、送信イベントをバックエンドにつなぐ、`<chit-ui>` というタグや chat-submit / chat-attach / chat-move といったイベントがコードに出てきた、といった場面で参照する。チャットウィジェット・チャット UI・問い合わせウィジェットを新しく作る相談にも使う。
+---
+
+# Chit UI
+
+Lit で書かれたチャットウィジェットのカスタム要素。ページの隅に丸いランチャーを置き、
+押すとパネルが開く。スマホ幅では全画面になる。
+
+**このライブラリが持たないもの**: 通信、状態管理、発言の保存。`messages` 配列の所有者は
+利用者側で、ライブラリはそれを読んで描くだけ。書き換えることは一度もない。送信も
+「送信された」というイベントを出すところまでで、そこから先は利用者のコードが決める。
+この境界を踏み外した設計（ライブラリが勝手に発言を足す、通信を始める）にしないこと。
+
+## 最小の組み込み
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@hidemikimura/chit-ui/dist/chit-ui.min.js"></script>
+<chit-ui id="chat"></chit-ui>
+
+<script type="module">
+  const chat = document.getElementById('chat');
+
+  chat.addEventListener('chat-submit', async (event) => {
+    const text = event.detail.text;
+
+    chat.messages = [...chat.messages, { id: crypto.randomUUID(), role: 'user', text }];
+    chat.busy = true;
+    chat.typing = true;
+
+    const reply = await yourBackend(text);
+
+    chat.typing = false;
+    chat.busy = false;
+    chat.messages = [...chat.messages,
+      { id: crypto.randomUUID(), role: 'assistant', text: reply }];
+  });
+</script>
+```
+
+npm から使うときは `npm install @hidemikimura/chit-ui lit` して `import '@hidemikimura/chit-ui';`。
+タグ名を自分で決めるなら `import { ChitUI } from '@hidemikimura/chit-ui/element.js';` を
+使って `customElements.define()` する。型は
+`import type { Message, Theme } from '@hidemikimura/chit-ui';`。
+
+**npm 版と単一バンドル（dist/chit-ui.min.js）を同じページで混ぜない。** Lit が二重に
+読み込まれる。`window.ChitUI` を作る IIFE 版（`dist/chit-ui.iife.min.js`）もある。
+
+## 間違えやすいところ
+
+**`messages` は必ず新しい配列を代入する。** `chat.messages.push(...)` は描画されない
+（Lit が同一参照を変更なしとみなす）。`[...chat.messages, next]` の形で代入する。
+
+**`id` は必須で、安定していること。** 差分描画のキーになる。毎回採番し直すと全部の
+吹き出しが作り直され、コンポーネント発言のインスタンスも捨てられる。
+
+**人が書いた文章は `text`、自分で組み立てた HTML だけ `html`。** `text` は Lit が
+テキストノードとして描くのでエスケープが構造的に保証され、改行もそのまま出る。
+`html` を使うなら `chat.sanitize = (html) => DOMPurify.sanitize(html)` を必ず設定する。
+バックエンドや LLM の出力をそのまま `html` に入れるのは事故のもと。
+
+**`typing` と `loading` は排他。** 一方を `true` にすると他方が `false` になる。
+相手が機械なら「入力中」より `loading`（スピナーや文言）が正しい。
+
+**`chat-submit` は中止できる。** `event.preventDefault()` すると入力欄は空にならず、
+`open.loading.auto` の自動ローディングも始まらない。
+
+**スマホ幅では `open.width` / `open.height` は無視される**（常に全画面）。
+`open.draggable` もスマホでは効かない。
+
+**`open.header.visible: false` にすると閉じるボタンも消える。** LINE LIFF のように
+外側がタイトルを持つ画面向け。Esc とランチャーでは閉じられる。
+
+## 発言の 5 形式
+
+`text` / `html` / `template`（Lit の `TemplateResult`）/ `element`（`HTMLElement`）/
+`component`（コンストラクタかタグ名 + `props`）のいずれか 1 つを持たせる。
+
+```js
+{ id: 'x', role: 'assistant', component: 'order-card', props: { orderId: '1001' } }
+```
+
+`component` は同じ `id` である限りインスタンスが再利用され、変わった `props` だけが
+再代入される。発言の中のボタンは個別にリスナーを付けるより
+`chat-message-click`（`detail: { message, target, originalEvent }`）で一括して受けるほうが楽。
+`target` はコンポーネントの Shadow DOM 内まで辿れている。
+
+`role` は `'user'` / `'assistant'` / `'system'`。`system` は中央寄せの連絡行で、
+名前もアイコンも出ない。
+
+## テーマ
+
+部分指定でよく、指定しなかった項目は既定値で埋まる。`null` を渡すと既定値を消せる。
+実行中に差し替えれば即反映される（ダークモードの切り替えなど）。
+
+```js
+chat.theme = {
+  breakpoint: 768,
+  closed: { pc: { size: 64, image: '/icon.png' }, mobile: { size: 56 }, draggable: true },
+  open: {
+    width: 380, height: 600,
+    colors: { accent: '#2563eb' },
+    bubble: { radius: 18, tail: 'top' },
+    header: { title: 'サポート', logo: '/logo.png', home: true },
+    loading: { auto: true, style: 'spinner' },
+    input: { attach: true, placeholder: 'ご質問をどうぞ' },
+  },
+};
+```
+
+付属テーマは `import { greenTheme } from '@hidemikimura/chit-ui/themes.js'`
+（単一バンドルなら `window.ChitUI.greenTheme`）。重ねて調整できる。
+
+細かい色だけ変えたいなら CSS のほうが早い。テーマの値は CSS カスタムプロパティになり、
+ページ側の指定が勝つ。
+
+```css
+chit-ui { --chit-color-accent: #d81b60; --chit-launcher-size: 72px; }
+chit-ui::part(bubble) { font-size: 15px; }
+```
+
+`--_chit-` で始まる変数は内部用。触らない。
+
+## よく使う API
+
+| 種類 | もの |
+| --- | --- |
+| プロパティ | `messages` `state` `theme` `typing` `loading` `busy` `value` `inputDisabled` `inputHidden` `maxLength` `sanitize` `locale` `labels` `dragOffset` |
+| メソッド | `open()` `close()` `toggle()` `submit(text?)` `focusInput()` `scrollToBottom()` `getMessageElement(id)` `home()` `openAttach()` `resetPosition()` |
+| イベント | `chat-submit` `chat-open` `chat-close` `chat-state-change` `chat-input` `chat-message-click` `chat-message-render` `chat-scroll-top` `chat-home` `chat-attach` `chat-move` `chat-breakpoint-change` |
+
+状態遷移のメソッドはアニメーション完了で resolve する Promise を返す（中止されたら `false`）。
+すべてのイベントは `bubbles` と `composed` が立っているので `document` でも拾える。
+
+網羅した表（全プロパティ・全イベントの `detail`・スロット・CSS パーツ・CSS 変数・
+テーマの全項目）は `references/api.md`。用途別の書き方（ストリーミング、シナリオ型、
+未読バッジ、LIFF、添付の送信）は `references/recipes.md`。
+
+## 作るときの順序
+
+1. `chat-submit` を受けて自分の発言を積み、返事を積むところまで作る。ここが本体。
+2. 待っている間の表示を決める（`busy` + `loading`、または `open.loading.auto`）。
+3. 見た目はテーマ、細部は CSS カスタムプロパティと `::part()`。
+4. 必要なら発言の中身を `component` にして、操作は `chat-message-click` で受ける。
+
+会話の保存・復元、未読管理、ログインの有無といった判断はすべて利用者側のコードに置く。
+ライブラリに寄せようとしないこと。

package/skills/chit-ui/references/api.md

@@ -0,0 +1,189 @@
+# Chit UI API リファレンス
+
+`@hidemikimura/chit-ui` 0.3.2 時点。パーツ名・プロパティ名・イベント名・スロット名・
+CSS カスタムプロパティ名は公開 API で、変更はメジャーバージョンでのみ行う。
+
+## プロパティ
+
+| プロパティ | 型 | 既定 | 内容 |
+| --- | --- | --- | --- |
+| `state` | `'closed' \| 'open' \| 'hidden'` | `'closed'` | 現在の状態 |
+| `theme` | `Theme` | `{}` | テーマ（部分指定可） |
+| `messages` | `Message[]` | `[]` | 描画する発言。必ず新しい配列を代入する |
+| `typing` | `boolean \| { html }` | `false` | 相手が入力中の表示。`loading` とは排他 |
+| `loading` | `boolean` | `false` | 応答待ちの表示。`typing` とは排他。属性にも反映される |
+| `busy` | `boolean` | `false` | 送信中。入力をロックする |
+| `inputDisabled` | `boolean` | `false` | 入力欄を見せたままロック |
+| `inputHidden` | `boolean` | `false` | 入力欄を消す（`submit(text)` は使える） |
+| `value` | `string` | `''` | 入力欄の内容 |
+| `placeholder` | `string` | テーマの値 | 入力欄のプレースホルダー |
+| `sendOnEnter` | `boolean` | `true` | Enter で送信するか |
+| `maxLength` | `number` | なし | 入力の上限（コードポイント単位） |
+| `focusOnOpen` | `'auto' \| 'always' \| 'never'` | `'auto'` | 開いたときの自動フォーカス。`auto` は PC のみ |
+| `sanitize` | `(html: string) => string` | なし | `html` 発言のサニタイズ |
+| `formatTime` | `(time: Date) => string` | `HH:mm` | 時刻表示 |
+| `messageStyles` | `string` | `''` | 発言の中に適用する追加 CSS |
+| `locale` | `string` | `<html lang>` | ラベルと時刻の言語（`ja` / `en`） |
+| `labels` | `Partial<Labels>` | なし | UI 文字列の上書き |
+| `dragOffset` | `{ x, y } \| null` | `null` | ドラッグで生じたずれ。読み書きできる |
+
+読み取り専用: `renderedState` `device`（`'pc' \| 'mobile'`）`hasUnseen` `canSend`
+`currentTheme` `currentLabels` `resolvedLocale`。
+
+## メソッド
+
+| メソッド | 内容 |
+| --- | --- |
+| `open()` `close()` `hide()` `show()` `toggle()` | 状態遷移。アニメーション完了で resolve する `Promise<boolean>`（中止なら `false`） |
+| `submit(text?)` | `chat-submit` を発火。省略時は入力欄の内容 |
+| `focusInput()` `clearInput()` | 入力欄の操作 |
+| `scrollToBottom({ smooth })` | 最新へスクロール。省略時はテーマの設定に従う |
+| `getMessageElement(id)` | その発言のコンテナ DOM（未描画なら `null`） |
+| `home()` | `chat-home` を発火（ホームボタンと同じ） |
+| `openAttach()` | 添付のファイル選択を開く |
+| `resetPosition()` | ドラッグで動かした位置を忘れる |
+
+## イベント
+
+すべて `CustomEvent`。`bubbles` と `composed` が立っているので `document` でも拾える。
+
+| イベント | タイミング | `detail` | 中止 |
+| --- | --- | --- | --- |
+| `chat-submit` | 送信された | `{ text }` | ○ |
+| `chat-before-open` / `chat-before-close` | 遷移の直前 | `{ from, trigger }` | ○ |
+| `chat-open` / `chat-close` | 遷移アニメーション完了 | `{ from, trigger }` | |
+| `chat-hide` / `chat-show` | 非表示になった / 戻った | `{ from, to }` | |
+| `chat-state-change` | `state` が変わった直後 | `{ from, to, trigger }` | |
+| `chat-input` | 入力欄が編集された | `{ value }` | |
+| `chat-message-render` | 発言が描画・更新された | `{ message, element, instance }` | |
+| `chat-message-click` | 発言の中がクリックされた | `{ message, target, originalEvent }` | ○ |
+| `chat-scroll-top` | 一覧が最上部に達した | `{}` | |
+| `chat-breakpoint-change` | PC / スマホの判定が変わった | `{ device }` | |
+| `chat-home` | ホームボタン、または `home()` | `{ trigger }` | |
+| `chat-attach` | 添付ファイルが選ばれた | `{ files: File[] }` | |
+| `chat-move` | ドラッグまたは矢印キー | `{ target, position, offset, displacement }` | |
+
+`trigger` は `'user'`（クリックや Esc）か `'api'`（メソッドやプロパティ代入）。
+
+## 発言オブジェクト
+
+```ts
+{
+  id: string,                       // 必須・安定していること
+  role: 'user' | 'assistant' | 'system',
+  name?: string | null,             // テーマの既定を打ち消すなら null
+  avatar?: string | null,
+  time?: Date | string | number,
+  status?: 'sending' | 'sent' | 'error',
+  streaming?: boolean,              // 末尾にカーソル、aria-busy
+  meta?: unknown,                   // 利用者の自由欄。イベントでそのまま返る
+  // 以下のいずれか 1 つ
+  text?: string,
+  html?: string,
+  template?: TemplateResult,
+  element?: HTMLElement,
+  component?: (new () => HTMLElement) | string,
+  props?: Record<string, unknown>,  // component のとき
+}
+```
+
+## テーマ
+
+```ts
+{
+  breakpoint?: number,              // 既定 768。これ未満をスマホとみなす
+  closed?: {
+    // pc / mobile に分けて書ける。分けなければ両方に同じ設定
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left',
+    offset?: { x: number, y: number },
+    size?: number | 'auto',
+    radius?: number,
+    image?: string | null,
+    label?: string | null,
+    component?: (new () => HTMLElement) | string,
+    props?: Record<string, unknown>,
+    colors?: { bg?, text?, shadow? },
+    draggable?: boolean,            // 既定 false
+    animation?: { enter?, exit?, duration? },
+  },
+  open?: {
+    width?: number, height?: number,         // スマホでは無視（常に全画面）
+    position?: Position, offset?: { x, y },
+    radius?: number,
+    launcher?: 'hidden' | 'visible',
+    draggable?: boolean,                     // 取っ手はタイトルバー。スマホでは無効
+    header?: { visible?: boolean, title?: string | null, logo?: string | null, home?: boolean },
+    bubble?: { radius?: number, tail?: 'none' | 'top' | 'bottom' },
+    speaker?: { assistant?: { name?, avatar? }, user?: { name?, avatar? } },
+    loading?: { auto?: boolean, style?: 'dots' | 'spinner' | 'text', text?: string | null, timeout?: number },
+    input?: { maxRows?: number, placeholder?: string | null, attach?: boolean, accept?: string, multiple?: boolean },
+    colors?: { bg?, text?, accent?, border?, userBubble?, userText?, assistantBubble?,
+               assistantText?, systemText?, headerBg?, headerText?, inputBg?, inputText?,
+               inputPlaceholder? },
+    bgImage?: string | null,
+    animation?: { enter?, exit?, duration?, scroll?: 'smooth' | 'instant' },
+  },
+  hidden?: { animation?: { exit?, duration? } },
+}
+```
+
+`animation` の `enter` / `exit` は `'fade' | 'scale' | 'slide' | 'none'`。
+
+## スロット
+
+| スロット | 差し替え対象 |
+| --- | --- |
+| `launcher` | 閉じた状態のアイコンの中身 |
+| `header` | パネルヘッダー全体（`header-title` / `header-actions` で部分差し替えも可） |
+| `empty` | 発言が 1 件もないときの表示 |
+| `input-before` / `input-after` | 入力欄の前後 |
+| `composer` | 入力欄全体。差し替えたら `submit(text)` を自分で呼ぶ |
+| `footer` | 入力欄の下（免責事項など） |
+
+## CSS パーツ
+
+`launcher` `launcher-icon` `launcher-label` `panel` `header` `header-title`
+`header-heading` `header-logo` `header-actions` `home-button` `close-button`
+`messages` `messages-inner` `message` `message-user` `message-assistant`
+`message-system` `bubble` `message-content` `avatar` `name` `meta` `time` `status`
+`cursor` `typing` `loading` `loading-text` `to-latest` `composer` `input`
+`attach-button` `attach-input` `counter` `send-button` `spinner`
+
+## CSS カスタムプロパティ（33）
+
+色: `--chit-color-bg` `--chit-color-text` `--chit-color-accent` `--chit-color-border`
+`--chit-color-user-bg` `--chit-color-user-text` `--chit-color-assistant-bg`
+`--chit-color-assistant-text` `--chit-color-system-text` `--chit-color-header-bg`
+`--chit-color-header-text` `--chit-color-input-bg` `--chit-color-input-text`
+`--chit-color-input-placeholder`
+
+ランチャー: `--chit-launcher-size` `--chit-launcher-radius` `--chit-launcher-offset-x`
+`--chit-launcher-offset-y` `--chit-launcher-bg` `--chit-launcher-text`
+`--chit-launcher-shadow` `--chit-launcher-image`
+
+吹き出し: `--chit-bubble-radius`
+
+パネル: `--chit-panel-width` `--chit-panel-height` `--chit-panel-radius`
+`--chit-panel-offset-x` `--chit-panel-offset-y` `--chit-panel-shadow`
+`--chit-panel-bg-image`
+
+全体: `--chit-font-family` `--chit-font-size` `--chit-z-index`
+
+アニメーションの長さは CSS 変数にしていない（遷移の完了を JavaScript 側が知る必要が
+あるため、テーマの `animation.duration` が唯一の設定箇所）。
+
+## エントリポイント
+
+| 指定 | 中身 |
+| --- | --- |
+| `@hidemikimura/chit-ui` | `<chit-ui>` を登録する。型もここから読める |
+| `@hidemikimura/chit-ui/element.js` | 登録しない。`ChitUI` クラスだけ |
+| `@hidemikimura/chit-ui/themes.js` | 付属テーマ（`greenTheme`） |
+| `dist/chit-ui.min.js` | Lit 同梱の ESM 単一バンドル |
+| `dist/chit-ui.iife.min.js` | 同上の IIFE 版。`window.ChitUI` |
+
+## 対応ブラウザ
+
+Chrome / Edge / Firefox / Safari の最新 2 バージョンと iOS Safari 16 以降。
+吹き出しのしっぽだけ `clip-path: path()` を使っていて、非対応の環境ではしっぽが出ない
+（他の機能には影響しない）。

package/skills/chit-ui/references/recipes.md

@@ -0,0 +1,204 @@
+# Chit UI レシピ
+
+よくある組み方。どれも「発言を持っているのは利用者側」という前提の上に乗っている。
+
+## 送信から返事まで（基本形）
+
+```js
+chat.addEventListener('chat-submit', async (event) => {
+  const text = event.detail.text.trim();
+  if (!text) { event.preventDefault(); return; }
+
+  const mine = { id: crypto.randomUUID(), role: 'user', text, status: 'sending' };
+  chat.messages = [...chat.messages, mine];
+  chat.busy = true;
+  chat.loading = true;
+
+  try {
+    const reply = await api.send(text);
+    chat.messages = chat.messages
+      .map((m) => (m.id === mine.id ? { ...m, status: 'sent' } : m))
+      .concat({ id: crypto.randomUUID(), role: 'assistant', text: reply });
+  } catch {
+    chat.messages = chat.messages.map((m) =>
+      m.id === mine.id ? { ...m, status: 'error' } : m,
+    );
+    chat.messages = [...chat.messages,
+      { id: crypto.randomUUID(), role: 'system', text: '送信できませんでした' }];
+  } finally {
+    chat.loading = false;
+    chat.busy = false;
+  }
+});
+```
+
+`open.loading.auto: true` にしておけば `chat.loading` の上げ下げは要らない。送信から
+相手側の発言が増えるまで自動で出て、`timeout`（ms）を過ぎれば自分で引っ込む。
+
+## ストリーミング
+
+同じ `id` の発言を書き換えていく。`streaming: true` の間は末尾にカーソルが出て、
+`aria-busy` が立つので 1 文字ずつ読み上げられない。
+
+```js
+const id = crypto.randomUUID();
+chat.messages = [...chat.messages, { id, role: 'assistant', text: '', streaming: true }];
+
+for await (const chunk of stream) {
+  chat.messages = chat.messages.map((m) =>
+    m.id === id ? { ...m, text: m.text + chunk } : m,
+  );
+}
+
+chat.messages = chat.messages.map((m) =>
+  m.id === id ? { ...m, streaming: false } : m,
+);
+```
+
+最下部にいる読み手は自動で追従する。上にさかのぼっている読み手は動かされず、
+「最新へ」のボタンが出る。
+
+## 履歴の追い読み
+
+```js
+chat.addEventListener('chat-scroll-top', async () => {
+  if (loadingOlder || !cursor) return;
+  loadingOlder = true;
+  const older = await api.history(cursor);
+  chat.messages = [...older, ...chat.messages];   // 前に足す
+  cursor = older.at(0)?.cursor ?? null;
+  loadingOlder = false;
+});
+```
+
+このイベントは最上部に着くたびに 1 回だけ出る（居座っても繰り返さない）。
+
+## シナリオ型（ホームボタンで最初に戻す）
+
+```js
+chat.theme = { open: { header: { home: true } } };
+
+chat.addEventListener('chat-home', async (event) => {
+  if (event.detail.trigger === 'user' && !confirm('最初からやり直しますか？')) return;
+  chat.messages = [firstMessage()];
+  scenario.reset();
+});
+```
+
+ボタンを押してもウィジェットは何も消さない。どこまで戻すかは利用者が決める。
+
+## 発言の中にコンポーネントを置く
+
+```js
+class OrderCard extends HTMLElement { /* props を受け取って描く */ }
+customElements.define('order-card', OrderCard);
+
+chat.messages = [...chat.messages, {
+  id: 'order-1001',
+  role: 'assistant',
+  component: 'order-card',
+  props: { orderId: '1001', total: 4800 },
+  meta: { orderId: '1001' },
+}];
+
+chat.addEventListener('chat-message-click', (event) => {
+  const action = event.detail.target.closest('[data-action]')?.dataset.action;
+  if (action === 'detail') showOrder(event.detail.message.meta.orderId);
+});
+```
+
+同じ `id` の間はインスタンスが再利用され、変わった `props` だけ再代入される。
+`chat-message-render` の `detail.instance` でインスタンスを直接触ることもできる。
+
+## 未読バッジ
+
+```html
+<chit-ui id="chat">
+  <span slot="launcher" class="badge" hidden></span>
+</chit-ui>
+```
+
+```js
+function pushFromServer(message) {
+  chat.messages = [...chat.messages, message];
+  if (chat.state !== 'open') {
+    unread += 1;
+    badge.textContent = String(unread);
+    badge.hidden = false;
+  }
+}
+
+chat.addEventListener('chat-open', () => { unread = 0; badge.hidden = true; });
+```
+
+パネルの中で上にさかのぼっている読み手に新着が届いたかどうかは `chat.hasUnseen` でわかる。
+
+## 添付ファイル
+
+```js
+chat.theme = { open: { input: { attach: true, accept: 'image/*', multiple: false } } };
+
+chat.addEventListener('chat-attach', async (event) => {
+  const [file] = event.detail.files;
+  const url = await api.upload(file);
+  chat.messages = [...chat.messages, {
+    id: crypto.randomUUID(), role: 'user',
+    html: `<img src="${url}" alt="添付した画像">`,
+  }];
+});
+```
+
+ライブラリはアップロードもプレビューもしない。同じファイルを続けて選んでも毎回発火する。
+
+## LINE LIFF など、外側がタイトルを持つ画面
+
+```js
+chat.theme = { open: { header: { visible: false } } };
+```
+
+タイトルバーごと消えるので閉じるボタンも消える。Esc とランチャーでは閉じられる。
+`title` は描かれなくても `role="dialog"` の読み上げ名には使われる。
+
+## ドラッグで動かす
+
+```js
+chat.theme = { closed: { draggable: true }, open: { draggable: true } };
+
+chat.addEventListener('chat-move', (event) => {
+  localStorage.setItem('chit-offset', JSON.stringify(event.detail.displacement));
+});
+
+const saved = localStorage.getItem('chit-offset');
+if (saved) chat.dragOffset = JSON.parse(saved);
+```
+
+閉じた状態と開いた状態は同じずれを共有するので、片方を動かせばもう片方も動く。
+`resetPosition()` でテーマの位置に戻る。保存するかどうかは利用者の判断。
+
+## ダークモード
+
+```js
+const dark = matchMedia('(prefers-color-scheme: dark)');
+const apply = () => { chat.theme = dark.matches ? darkTheme : lightTheme; };
+dark.addEventListener('change', apply);
+apply();
+```
+
+テーマは実行中に差し替えても即座に反映される。
+
+## 入力欄を消して選択肢だけで進める
+
+```js
+chat.inputHidden = true;
+chat.messages = [...chat.messages, {
+  id: 'q1', role: 'assistant',
+  html: '<p>どちらにしますか？</p><button data-choice="a">A</button><button data-choice="b">B</button>',
+}];
+
+chat.addEventListener('chat-message-click', (event) => {
+  const choice = event.detail.target.closest('[data-choice]')?.dataset.choice;
+  if (choice) chat.submit(choice === 'a' ? 'A' : 'B');
+});
+```
+
+入力欄を消しても `submit(text)` は使えるので、選択肢からの送信で会話を進められる。