@hidemikimura/chit-ui 0.3.0 → 0.3.2

package/dist/types/controllers/scroll-lock-controller.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Keeps a touch that lands on the open panel from scrolling the page behind
+ * it.
+ *
+ * `overscroll-behavior: contain` is on the message list already, and it does
+ * the job for the case it covers: a list that can scroll, dragged past its
+ * own end. It has nothing to say about the cases that actually leak. A short
+ * conversation does not overflow, so the list is not a scroll container at
+ * all and the touch goes straight through to the document — which is what a
+ * reader on an iPhone sees as the page sliding around underneath a chat that
+ * looks like it should be holding still. The same happens for a touch that
+ * starts on the title bar or beside the input.
+ *
+ * So the rule is decided here instead: a touch on the panel may scroll
+ * something inside the panel, and otherwise it does nothing. On the first
+ * move of each gesture the controller looks along the touch's own path —
+ * `composedPath`, so a scroller inside a consumer's component counts too —
+ * for something that can still travel in the direction the finger is going.
+ * Finding one, it stands aside for the rest of the gesture; finding none, it
+ * cancels the move, and iOS then takes the whole gesture as "not a scroll".
+ *
+ * Two touches are left alone: that is a pinch, and zooming is the reader's.
+ * A move that is no longer cancelable is left alone too — the browser has
+ * already committed to scrolling, and `overscroll-behavior` is what keeps
+ * that inside the list.
+ *
+ * @implements {ReactiveController}
+ */
+export class ScrollLockController implements ReactiveController {
+    /** @param {LitElement} host */
+    constructor(host: LitElement);
+    hostUpdated(): void;
+    hostDisconnected(): void;
+    #private;
+}
+import type { ReactiveController } from 'lit';
+import type { LitElement } from 'lit';

package/dist/types/controllers/viewport-controller.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Keeps the full-screen panel inside the part of the screen the reader can
+ * actually see.
+ *
+ * On a phone the panel is `position: fixed` across the whole viewport, and
+ * that viewport is not what is on screen once a keyboard slides up: the
+ * layout viewport keeps its full height, so the composer — and with it the
+ * last few messages — ends up behind the keyboard. iOS then scrolls the page
+ * to chase the focused field, which moves the fixed panel out of frame
+ * instead of helping. `dvh` is no use here either; it tracks the browser's
+ * own chrome collapsing, not the keyboard.
+ *
+ * `visualViewport` is the one thing that does report the visible box, so the
+ * panel is pinned to it: its top to `offsetTop`, its height to `height`. The
+ * composer lands just above the keyboard, and the conversation gets whatever
+ * is left.
+ *
+ * A pinch is left alone. Zooming is how a reader gets a closer look, and a
+ * panel that re-fitted itself to the magnified box would take that away by
+ * reflowing the text back to the same apparent size.
+ *
+ * @implements {ReactiveController}
+ */
+export class ViewportController implements ReactiveController {
+    /**
+     * @param {LitElement} host
+     * @param {{ enabled: () => boolean }} options
+     */
+    constructor(host: LitElement, { enabled }: {
+        enabled: () => boolean;
+    });
+    hostConnected(): void;
+    hostDisconnected(): void;
+    hostUpdated(): void;
+    #private;
+}
+import type { ReactiveController } from 'lit';
+import type { LitElement } from 'lit';

package/dist/types/index.d.ts

@@ -1,4 +1,166 @@
 /// <reference path="./global.d.ts" />
 export { ChitUI };
 export { Events } from "./events.js";
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Role = import("./types.js").Role;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type MessageStatus = import("./types.js").MessageStatus;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ChatState = import("./types.js").ChatState;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Trigger = import("./types.js").Trigger;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Device = import("./types.js").Device;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Effect = import("./types.js").Effect;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Position = import("./types.js").Position;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type BubbleTail = import("./types.js").BubbleTail;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type LoadingStyle = import("./types.js").LoadingStyle;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type MessageBase = import("./types.js").MessageBase;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type TextMessage = import("./types.js").TextMessage;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type HtmlMessage = import("./types.js").HtmlMessage;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type TemplateMessage = import("./types.js").TemplateMessage;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ElementMessage = import("./types.js").ElementMessage;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ComponentMessage = import("./types.js").ComponentMessage;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Message = import("./types.js").Message;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Animation = import("./types.js").Animation;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Offset = import("./types.js").Offset;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ClosedTheme = import("./types.js").ClosedTheme;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type OpenColors = import("./types.js").OpenColors;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type SpeakerTheme = import("./types.js").SpeakerTheme;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type LoadingTheme = import("./types.js").LoadingTheme;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type OpenTheme = import("./types.js").OpenTheme;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type Theme = import("./types.js").Theme;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ResolvedClosed = import("./types.js").ResolvedClosed;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ResolvedOpen = import("./types.js").ResolvedOpen;
+/**
+ * The public types, re-exported so a consumer can write
+ * `import type { Message } from '@hidemikimura/chit-ui'` instead of reaching
+ * into `dist/types/` for them.
+ */
+export type ResolvedTheme = import("./types.js").ResolvedTheme;
 import { ChitUI } from './chit-ui.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hidemikimura/chit-ui",
-  "version": "0.3.0",
+  "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()` を使っていて、非対応の環境ではしっぽが出ない
+（他の機能には影響しない）。