simple-ai-sdk 1.0.45 → 1.0.47

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const usage = `Usage:
+  simple-ai-sdk spec
+`;
+async function main() {
+    const command = process.argv[2];
+    if (command !== "spec") {
+        process.stdout.write(usage);
+        process.exitCode = 1;
+        return;
+    }
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    const specPath = join(currentDir, "spec.md");
+    const spec = await readFile(specPath, "utf8");
+    process.stdout.write(spec);
+}
+void main().catch((error) => {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    process.stderr.write(`Failed to read spec.md: ${message}\n`);
+    process.exitCode = 1;
+});

package/dist/client/manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/client/manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,oBAAoB,EAEpB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAmB,MAAM,oBAAoB,CAAC;AAK9E,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,IAAI,CAAC;IACvD,WAAW,IAAI,kBAAkB,CAAC;IAClC;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IACvD,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAClE;;;;OAIG;IACH,kBAAkB,CAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,oBAAoB,GAAG,SAAS,GACxC,IAAI,CAAC;IACR;;OAEG;IACH,iBAAiB,CACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,SAAS,GAC5C,IAAI,CAAC;IACR;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC;;OAEG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC;;;OAGG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC;;;OAGG;IACH,WAAW,CACT,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,IAAI,CAAC;IACR,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE;QACP,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;KAClC,GACA,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;OAEG;IACH,cAAc,IAAI,IAAI,CAAC;IACvB;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,cAAM,aAAc,YAAW,cAAc;IAC3C,OAAO,CAAC,KAAK,CAEX;IAEF,OAAO,CAAC,SAAS,CAAoC;IAGrD,OAAO,CAAC,YAAY,CAAS;IAE7B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,gBAAgB,CAA8C;IAEtE,OAAO,CAAC,MAAM;IAsBd,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,KAAK,CAAC,CAAS;IACvB,OAAO,CAAC,UAAU,CAA+C;IAEjE,OAAO,CAAC,iBAAiB,CAA6B;IAEtD,OAAO,CAAC,cAAc,CAA2C;IAEjE,OAAO,CAAC,aAAa,CAA6C;IAIlE,OAAO,CAAC,eAAe,CAGnB;IACJ,OAAO,CAAC,cAAc,CAA4B;IAElD,OAAO,CAAC,SAAS,CAA6B;gBAElC,OAAO,GAAE,oBAAyB;IAoB9C,SAAS,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAOtD,kBAAkB,CAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,oBAAoB,GAAG,SAAS;IAmB3C,iBAAiB,CACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,SAAS;IAqB/C,WAAW,IAAI,kBAAkB;IAMjC,OAAO,CAAC,MAAM;IAsDd,OAAO,CAAC,yBAAyB;IASjC,OAAO,CAAC,aAAa;IAWrB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAOtD,YAAY,CAAC,SAAS,EAAE,MAAM;IAO9B,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,oBAAoB;IAgC5B,OAAO,CAAC,mBAAmB;IAgB3B,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,GAAE,OAAO,EAAO;IAiE9D,aAAa,CAAC,SAAS,EAAE,MAAM;IAS/B,cAAc,CAAC,SAAS,EAAE,MAAM;IAahC;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IA0D3B,OAAO,CAAC,cAAc;IAmBtB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IA4Bf,UAAU,CACd,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE;QACP,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;KAClC;IA4VH,WAAW,CACT,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,IAAI;IA4BP,UAAU,CAAC,SAAS,EAAE,MAAM;IAiB5B,cAAc;IAQd;;OAEG;IACH,OAAO,CAAC,YAAY;IAwCpB;;;OAGG;IACH,OAAO,IAAI,IAAI;CAkChB;AAGD,OAAO,EAAE,aAAa,EAAE,CAAC;AAIzB,eAAO,MAAM,aAAa,EAAE,cAAoC,CAAC"}
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/client/manager.ts"],"names":[],"mappings":"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"}

package/dist/client/manager.js

@@ -879,7 +879,7 @@ const isChunkPayload = (v) => isObject(v) &&
         typeof v.text === "string") &&
     (typeof v.meta === "undefined" ||
         Array.isArray(v.meta));
-// Note: customData is JSONValue so no special check is needed (any value is valid)
+// Note: keep runtime permissive for backward compatibility.
 const isErrorPayload = (v) => isObject(v) &&
     (typeof v.message === "undefined" ||
         typeof v.message === "string");

package/dist/server/createChatHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createChatHandler.d.ts","sourceRoot":"","sources":["../../src/server/createChatHandler.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,aAAa,EAGb,iBAAiB,EAIlB,MAAM,YAAY,CAAC;AAMpB,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,aAAa,GAAG,iBAAiB,CA2f3E"}
+{"version":3,"file":"createChatHandler.d.ts","sourceRoot":"","sources":["../../src/server/createChatHandler.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,aAAa,EAGb,iBAAiB,EAIlB,MAAM,YAAY,CAAC;AAMpB,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,aAAa,GAAG,iBAAiB,CAwgB3E"}

package/dist/server/createChatHandler.js

@@ -2,7 +2,7 @@ import { isAbortError } from "../shared/error-utils.js";
 import { normalizeFinishReason } from "./server-utils.js";
 // Implemented for usage inside Hono's `streamText()` callback.
 export function createChatHandler(options) {
-    const { providers, transforms = [], throttle, onFinish, onError, messages, timeoutMs = 60000, maxOutputTokens, debug = false, userId, } = options;
+    const { providers, transforms = [], throttle, onFinish, onFirstToken, onError, messages, timeoutMs = 60000, maxOutputTokens, debug = false, userId, } = options;
     // Convert single provider config to array for consistent handling
     const providerConfigs = Array.isArray(providers) ? providers : [providers];
     // Shared metadata queue for this handler instance.
@@ -59,6 +59,7 @@ export function createChatHandler(options) {
         let currentModel = "";
         let currentProvider = "openai";
         let overallFinishReason = null;
+        let firstTokenNotified = false;
         // Content send control for throttling
         let lastContentSendTime = 0;
         // Tracks the accText length at last send. Used to compute delta size when sending chunks.
@@ -261,6 +262,16 @@ export function createChatHandler(options) {
                             };
                         }
                         if (delta?.content) {
+                            if (!firstTokenNotified && onFirstToken) {
+                                firstTokenNotified = true;
+                                const ttftMs = Date.now() - startTime;
+                                void Promise.resolve(onFirstToken({ ttftMs })).catch((e) => {
+                                    // onFirstToken failure is not fatal; do not block streaming
+                                    if (debug) {
+                                        console.error("[cch] onFirstToken error:", e);
+                                    }
+                                });
+                            }
                             let text = delta.content;
                             const ctx = {
                                 accText: localAccText,

package/dist/server/types.d.ts

@@ -1,5 +1,5 @@
 import type { OpenAI } from "openai";
-import type { JSONValue, Message, SessionMetadata } from "../shared/index.js";
+import type { CustomDataValue, Message, SessionMetadata } from "../shared/index.js";
 import type { StreamingApi } from "hono/utils/stream.js";
 export type HonoStreamType = StreamingApi;
 /**
@@ -38,17 +38,17 @@ export type FinishInfo = {
 export type StreamTransformContext = {
     accText: string;
     sendMetadata: (meta: SessionMetadata) => void;
-    sendCustomData: (data: JSONValue) => void;
+    sendCustomData: (data: CustomDataValue) => void;
 };
 export type ServerEmitTools = {
     sendMetadata: (meta: SessionMetadata) => void;
-    sendCustomData: (data: JSONValue) => void;
+    sendCustomData: (data: CustomDataValue) => void;
 };
 export type ChatHandler = (req: Request, stream: StreamingApi) => Promise<void>;
 export type ChatHandlerResult = {
     handler: ChatHandler;
     sendMetadata: (meta: SessionMetadata) => void;
-    sendCustomData: (data: JSONValue) => void;
+    sendCustomData: (data: CustomDataValue) => void;
 };
 export type StreamTransform = (chunk: string, ctx: StreamTransformContext) => string | Promise<string>;
 export type ThrottleSettings = {
@@ -64,12 +64,30 @@ export type StreamHandlerOnError = (err: unknown, details: {
     streamedChars: number;
 }) => string;
 export type StreamHandlerOnFinish = (info: FinishInfo) => void | Promise<void>;
+export type StreamHandlerOnFirstToken = (info: {
+    /**
+     * リクエスト処理を開始してから、
+     * プロバイダーから最初の「空でない content トークン」を受信するまでの経過時間（ミリ秒）
+     * - 計測開始点は `createChatHandler` が返す `handler()` の実行開始時点
+     * - `handler()` 呼び出し前に行った処理（認証・DB・JSON parse など）は含まれない
+     */
+    ttftMs: number;
+}) => void | Promise<void>;
 export type ServerOptions = {
     providers: AIProviderConfig | AIProviderConfig[];
     userId: string;
     transforms?: StreamTransform[];
     throttle?: ThrottleSettings;
     onFinish?: StreamHandlerOnFinish;
+    /**
+     * Called once when the first non-empty content token is received.
+     *
+     * Performance note:
+     * - This callback is fired at most once per request.
+     * - The handler does NOT await this callback to avoid delaying text streaming.
+     * - Keep work lightweight; offload heavy tasks (DB writes, etc.) asynchronously.
+     */
+    onFirstToken?: StreamHandlerOnFirstToken;
     onError: StreamHandlerOnError;
     maxOutputTokens: undefined | number;
     timeoutMs?: number;

package/dist/server/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}

package/dist/shared/types.d.ts

@@ -3,10 +3,14 @@ export type Message = {
     id: string;
     role: Role;
     content: string;
-    customData?: JSONValue;
+    customData?: CustomDataValue;
 };
-export type JSONValue = null | boolean | number | string | JSONValue[] | {
+export type JSONPrimitive = null | boolean | number | string;
+export type JSONObject = {
     [k: string]: JSONValue;
 };
+export type JSONArray = JSONValue[];
+export type JSONValue = JSONPrimitive | JSONArray | JSONObject;
+export type CustomDataValue = JSONArray | JSONObject;
 export type SessionMetadata = Record<string, JSONValue>;
 //# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEnD,MAAM,MAAM,OAAO,GAAG;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,SAAS,GACjB,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,EAAE,GACX;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE/B,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEnD,MAAM,MAAM,OAAO,GAAG;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAC7D,MAAM,MAAM,UAAU,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AACpD,MAAM,MAAM,SAAS,GAAG,SAAS,EAAE,CAAC;AAEpC,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AAE/D,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,UAAU,CAAC;AAErD,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC"}

package/dist/shared/wire.d.ts

@@ -1,4 +1,4 @@
-import type { JSONValue } from "./types.js";
+import type { CustomDataValue, JSONValue } from "./types.js";
 export type SSEEventType = "chunk" | "error" | "done";
 export type SSEChunkData = {
     text: string;
@@ -13,8 +13,9 @@ export type SSEChunkData = {
     /**
      * Optional custom data to attach to the current assistant message.
      * When sent multiple times, the last value wins (overwrites previous).
+     * Primitive values are intentionally excluded at the type level.
      */
-    customData?: JSONValue;
+    customData?: CustomDataValue;
 };
 export type SSEErrorData = {
     message: string;

package/dist/shared/wire.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/shared/wire.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,MAAM,YAAY,GACpB,OAAO,GACP,OAAO,GACP,MAAM,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC,CAAC;IACzC;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,QAAQ,GAChB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GACtC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GACtC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC"}
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/shared/wire.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE7D,MAAM,MAAM,YAAY,GACpB,OAAO,GACP,OAAO,GACP,MAAM,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC,CAAC;IACzC;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,QAAQ,GAChB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GACtC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GACtC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC"}

package/dist/spec.md

@@ -0,0 +1,649 @@
+# simple-ai-sdk — React + TypeScript 向けストリーミング AI SDK（クライアント & サーバ）
+- 個人用の非公開ライブラリなので、後方互換性は保証しなくてOK
+
+OpenAI/Gemini（OpenAI 互換エンドポイント）を **OpenAI 公式 SDK** 経由で呼び出し、サーバで受けたストリーミング結果を **SSE (Server‑Sent Events)** に統一して React に中継する最小構成。
+- クライアント: React 19+ 専用フック / 並列ストリーム / ルーティング耐性
+- サーバ: typescript前提。開発時にはHonoを使う
+
+
+---
+
+## 目的 / スコープ
+
+- OpenAI / Google Gemini を **同一コードパス** でストリーミング。
+- サーバ側で **チャンク毎のテキスト変換（伏字・句読点揃え・文単位フラッシュ等）** が可能。
+- サーバは **onFinish** で使用トークン数や全文を受け取り、ロギングや課金連携に利用可能。
+- クライアントは **`useChatSession()`** フックで messages と状態を一元管理。**複数セッション並列**に扱える。
+- **ページ遷移（SPA 内）ではストリームを止めない**。タブを閉じた/完全リロード時は特別な対応は行わない（下記参照）。
+
+> **NOTE**: 「タブを閉じた / リロード」時の継続は **行いません**（仕様）。アプリ要件上必要なら Service Worker / SharedWorker 拡張は別途検討してください。
+
+---
+
+## パッケージ構成（提案）
+
+単一リポジトリ内に **client** / **server** / **shared** を配置します。パッケージ名は例示です。
+
+```
+./
+├─ client/                  # React 19+ 向けフックとユーティリティ
+│  ├─ useChatSession.ts
+│  ├─ context.tsx           # SimpleAIProvider（並列・ルーティング耐性の要）
+│  ├─ manager.ts            # 外部ストア（StreamManager）
+│  └─ types.ts
+├─ server/                  # フレームワーク非依存ハンドラ
+│  ├─ createChatHandler.ts
+│  └─ types.ts
+├─ shared/
+│  ├─ types.ts              # Message 型等の共有
+│  └─ wire.ts               # SSE のイベント種別とワイヤプロトコル
+└─ README.md
+```
+
+- npm 公開時のエントリ例：
+  - `"exports": { "./client": "./client/index.js", "./server": "./server/index.js" }`
+  - `type: module`（ESM）
+
+---
+
+## インストール
+
+```bash
+# サーバ側
+npm i openai hono            # hono は任意（例では使用）
+# クライアント側（React 19+ 前提）
+npm i react
+```
+
+> TODO: パッケージ名・エクスポートポリシー（monorepo か単一 pkg か）を確定。
+
+---
+
+## 共有データモデル（`shared/types.ts`）
+
+```ts
+export type Role = 'user' | 'assistant' | 'system'
+
+export type Message = {
+  id: string
+  role: Role
+  content: string
+  customData?: CustomDataValue  // アシスタントメッセージに紐づくカスタムデータ（非プリミティブのみ）
+}
+
+export type JSONPrimitive = null | boolean | number | string
+export type JSONObject = { [k: string]: JSONValue }
+export type JSONArray = JSONValue[]
+export type JSONValue = JSONPrimitive | JSONArray | JSONObject
+export type CustomDataValue = JSONArray | JSONObject
+```
+
+---
+
+## ワイヤプロトコル（SSE）
+
+- **エンドポイント**: `POST /api/chat`（任意）
+- **リクエスト**: `application/json`
+
+
+- **レスポンス**: `text/event-stream`（Honoの`streamText`によって自動的に設定）。`data:` には JSON を入れます。
+  - `event: chunk` → `{ text: string, meta?: Array<{ [k: string]: JSONValue }>, customData?: CustomDataValue }`
+    - `meta` は、そのチャンク時点までにサーバが送信したメタデータ（0個以上）を配列で同梱
+    - `customData` は、現在ストリーミング中の assistant メッセージに紐づけるカスタムデータ（配列/オブジェクトのみ）。複数回送信された場合は最後の値で上書き（last write wins）
+    - 非プリミティブ制約は型レベルの厳格化であり、ランタイムでは後方互換のため受信処理を許容する
+    - テキスト更新が無い場合でも、`{ text: "", meta: [...], customData: ... }` のような「メタのみチャンク」を送ることがあります
+  - `event: error` → `{ message: string, code?: string }`
+  - `event: done` → `{ finished_reason: "length" | "stop" | "content_filter" | null }`
+
+
+---
+
+## サーバ API（`server`）
+
+### 依存
+- `openai`（公式 SDK）
+- `hono`（streamText APIを使用）
+
+### `createChatHandler(opts)`
+Honoの`streamText`と連携するためのハンドラ群を返します。返り値は `handler` / `sendMetadata` / `sendCustomData` を持つオブジェクトです。SSE でクライアントに中継します。
+
+メタデータは個別SSEイベントではなく、`chunk` イベントの `meta` 配列に同梱されます。`sendMetadata` はストリーム開始前に呼んでも安全で、開始後に最初のタイミングでメタのみチャンクとしてフラッシュされます。
+`onFirstToken` を指定すると、最初の非空 `delta.content` を受信した時点で 1 回だけ呼び出されます（`onFinish` より前）。ストリーミング遅延を避けるため、ハンドラ側は `onFirstToken` を await しません。
+
+**返り値の型**:
+```ts
+type ChatHandlerResult = {
+  handler: (req: Request, stream: HonoStreamType) => Promise<void>
+  /**
+   * メタデータを送信キューに積む。ストリーム中なら次の `chunk.meta` に同梱、
+   * 直後に必要ならメタのみチャンクとして即時フラッシュされる。
+   */
+  sendMetadata: (meta: SessionMetadata) => void
+  /**
+   * 現在ストリーミング中の assistant メッセージにカスタムデータを紐づける。
+   * 複数回呼び出した場合は最後の値で上書き（last write wins）。
+  * ストリーム中なら次の `chunk.customData` として配送される。
+  */
+  sendCustomData: (data: CustomDataValue) => void
+}
+```
+
+```ts
+import OpenAI from 'openai'
+import { createChatHandler } from 'simple-ai-sdk/server'
+
+// 単一プロバイダー設定
+const { handler } = createChatHandler({
+  providers: {
+    openai: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+    provider: 'openai',
+    model: 'gpt-4.1-nano',
+  },
+  userId: 'user-123',
+  transforms: [/* redact(), sentenceAggregator() など */],
+  throttle: { ...}, // throttleの設定
+  onFinish(info) {
+    console.log('usage:', info.usage)
+  },
+  onError(err, details) { 
+    console.error(details.reason, err)
+    return "An error occurred" // クライアントに送信されるメッセージ
+  }
+})
+
+// フォールバック設定（複数プロバイダー）
+const handlerWithFallback = createChatHandler({
+  providers: [
+    {
+      openai: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+      provider: 'openai',
+      model: 'gpt-4',
+    },
+    {
+      openai: new OpenAI({ apiKey: process.env.OPENAI_API_KEY_BACKUP }),
+      provider: 'openai',
+      model: 'gpt-3.5-turbo',
+    },
+    {
+      openai: new OpenAI({
+        apiKey: process.env.GEMINI_API_KEY,
+        baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai/',
+      }),
+      provider: 'gemini',
+      model: 'gemini-2.0-flash',
+    },
+  ],
+  userId: 'user-123',
+  onFinish(info) {
+    console.log(`Completed with ${info.provider}/${info.model}`, info.usage)
+  },
+  onError(err, details) { 
+    console.error('All providers failed:', details.reason, err)
+    return "Service temporarily unavailable" // クライアントに送信されるメッセージ
+  }
+})
+
+// 例1: handler を使う最小構成
+app.post('/api/chat', (c) => streamText(c, async (stream) => {
+  await handler(c.req.raw, stream)
+}))
+
+// 例2: 新しい使い方（分割代入で sendMetadata を取得）
+app.post('/api/chat', (c) => streamText(c, async (stream) => {
+  const { handler, sendMetadata } = createChatHandler({ /* options */ })
+  
+  // リクエスト開始時にメタデータを投入（ストリーム開始時に flush される）
+  sendMetadata({ phase: 'start', timestamp: Date.now() })
+  
+  const promise = handler(c.req.raw, stream)
+  
+  // 任意のタイミングでメタデータを送信（次の chunk.meta かメタのみチャンクで配送）
+  setTimeout(() => {
+    sendMetadata({ phase: 'processing', progress: 0.5 })
+  }, 1000)
+  
+  await promise
+}))
+```
+
+#### Gemini（OpenAI 互換）設定例
+
+Google Gemini は OpenAI 公式 SDK をそのまま使い、`baseURL` に OpenAI 互換エンドポイントを指定して利用できます。
+
+```ts
+import OpenAI from 'openai'
+import { createChatHandler } from 'simple-ai-sdk/server'
+
+const handler = createChatHandler({
+  providers: {
+    openai: new OpenAI({
+      apiKey: process.env.GEMINI_API_KEY, // 例: 環境変数に設定
+      baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai/',
+    }),
+    provider: 'gemini',
+    // 例: Gemini のモデル ID を指定（実環境に合わせて変更）
+    model: 'gemini-1.5-pro',
+  },
+  userId: 'user-123',
+  onError(err, details) {
+    console.error(err, details)
+    return "An error occurred"
+  }
+})
+```
+
+最小サンプル（OpenAI SDK インスタンスのみ）
+
+```ts
+import OpenAI from 'openai'
+
+const openai = new OpenAI({
+  apiKey: 'GEMINI_API_KEY',
+  baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai/',
+})
+```
+
+#### `ProviderConfig`
+
+プロバイダー設定をグループ化した型です。フォールバック時に一緒に切り替わります。
+
+```ts
+export type ProviderConfig = {
+  openai: OpenAI          // OpenAI SDK インスタンス（必須）
+  provider: Provider      // 'openai' | 'gemini'
+  model: string          // 使用するモデル名
+}
+```
+
+#### `ServerOptions`
+
+| オプション | 型 | 必須 | 説明 |
+|---|---|---|---|
+| `providers` | `ProviderConfig \| ProviderConfig[]` | ✅ | プロバイダー設定。単一または配列で指定。配列の場合、エラー時に順番にフォールバック試行。 |
+| `userId` | `string` | ✅ | 不正検知用ユーザーID。`provider: 'openai'` のとき `safety_identifier` として送信。 |
+| `transforms` | `Transform[]` | 任意 | チャンク毎のテキスト変換。複数可、上から順に適用。 |
+| `throttle` | `ThrottleSettings` | 任意 | スロットリング設定。最初のチャンクは常に即送信。 |
+| `onFinish` | `(info: FinishInfo) => void \| Promise<void>` | 任意 | ストリーム完了時。使用トークンや全文、処理時間を受け取る。`done` イベント送信前に `await` されるため、非同期処理（DB保存、`sendCustomData` 呼び出し等）を行える。失敗しても `done` は送信される。 |
+| `onFirstToken` | `(info: { ttftMs: number }) => void \| Promise<void>` | 任意 | 最初の非空トークン受信時に 1 回だけ呼ばれる。`ttftMs` は「リクエスト開始から最初の非空 `delta.content` 受信まで」の時間（ms）。ハンドラは await しないため、重い処理は非同期にオフロードすること。 |
+| `onError` | `(err: unknown, details: { reason: "unknown" \| "timeout" \| "aborted", streamedChars: number }) => string` | ✅ | エラー時。返り値の文字列がクライアントへのエラーメッセージとして送信される。サーバー内部エラーを隠蔽し、安全なメッセージのみクライアントに返すために使用。 |
+| `timeoutMs` | `number` | 任意 | タイムアウト秒数。超過時にストリームを中断。 |
+
+#### `FinishInfo`
+```ts
+export type FinishInfo = {
+  model: string
+  provider: 'openai' | 'gemini'
+  text: string
+  usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number; [k: string]: JSONValue }
+  durationMs: number
+}
+```
+
+> 使用トークンは、SDK のストリーム最終チャンクで `usage` が提供される場合のみ取得できます。互換レイヤや一部モデルでは `undefined` の可能性があります。**TODO:** Gemini での `usage` 提供差分を要確認。
+
+#### Transform API
+
+```ts
+export type StreamTransformContext = {
+  accText: string                  // これまでクライアントへ流した合計テキスト
+  sendMetadata: (meta: SessionMetadata) => void  // 次の chunk.meta に同梱（必要ならメタのみ即時フラッシュ）
+  sendCustomData: (data: CustomDataValue) => void      // 現在の assistant メッセージにカスタムデータを紐づける（配列/オブジェクトのみ）
+}
+
+export type StreamTransform = (chunk: string, ctx: StreamTransformContext) => string | Promise<string>
+```
+
+- 各チャンクの `delta.content` に対して順次適用され、戻り値がクライアントに送られます。
+- **文アグリゲータ**のようにチャンクを内部バッファに貯めたい場合、戻り値を `''` にして、最終フラッシュをハンドラ側が終了直前に呼び出す実装とします。
+
+##### サンプル
+
+```ts
+// 伏字
+export const redact: Transform = (s) => s.replace(/(NGワード)/g, '***')
+
+// 文単位で出力
+export const sentenceAggregator = (): Transform => {
+  let buf = ''
+  return (s, ctx) => {
+    buf += s
+    const parts = buf.split(/(?<=。)|\n\n/)
+    buf = parts.pop() ?? ''
+    const out = parts.join('')
+    if (out) ctx.sendMetadata({ flushed: out.length }) // 任意のメタ送信（chunk.meta）
+    return out
+  }
+}
+```
+
+#### sendCustomData の使用例
+
+```ts
+// onFinish 内で LLM の回答を元に追加データを取得し、メッセージに紐づける例
+app.post('/api/chat', (c) => {
+  return streamText(c, async (stream) => {
+    const { handler, sendCustomData } = createChatHandler({
+      providers: { /* ... */ },
+      userId: 'user-123',
+      onFinish: async (info) => {
+        // LLM の回答テキストを元に DB から関連データを取得
+        const relatedItems = await db.findRelated(info.text)
+        // assistant メッセージにカスタムデータを紐づける
+        sendCustomData({ sources: relatedItems, generatedAt: Date.now() })
+      },
+      onError(err, details) {
+        return "エラーが発生しました"
+      }
+    })
+    await handler(c.req.raw, stream)
+  })
+})
+```
+
+クライアント側では `message.customData` でアクセス可能:
+
+```tsx
+{messages.map((message) => (
+  <div key={message.id}>
+    <p>{message.content}</p>
+    {message.customData && (
+      <pre>{JSON.stringify(message.customData, null, 2)}</pre>
+    )}
+  </div>
+))}
+```
+
+---
+
+## クライアント API（`client`）
+
+### 設計方針
+- **StreamManager（外部ストア）**に実ネットワーク処理を持たせ、React ライフサイクルから分離。
+- React では **Context + `useSyncExternalStore`** で購読。コンポーネントがアンマウントしてもストリームは継続。
+- **フレーム単位バッチ（rAF）**：ストリーミング中の更新は requestAnimationFrame で1フレームにまとめて通知。初回は即時反映、以降はフレーム内でバッチ処理。
+- **購読者0の最適化**：`activeSubscribers` が 0 のセッションに対する「ストリーミング由来の message 更新」では再レンダリング通知を抑制します。`onFinish`/`onError` などのイベント（ステータス変更）は通知されます。
+- **参照の更新ポリシー**：ストリーミング中の各チャンクで `messages` の配列参照を新規にします。これにより、`useMemo([messages])` や `useEffect([messages])` といった参照依存でも確実に再評価されます。
+  - さらに、`messages` 内容更新のたびにインクリメントされる `messagesVersion` も返します。重い処理の再計算制御に利用できます（任意）。
+  - 0→1 の購読遷移時は、セッションが `streaming/submitted` の場合に一度だけ即時通知します（UX 改善のためのベストエフォート）。
+- **購読のライフサイクル**：`useChatSession` は `useSyncExternalStore` の subscribe 内で `retainSession`（マウント）/ `releaseSession`（アンマウント）を同期的に行い、購読者数と通知抑制の整合を保証します。
+
+### `SimpleAIProvider` / `useChatSession(sessionId, options)`
+
+```tsx
+// ルートに配置（Next.js App Router なら app/layout.tsx）
+<SimpleAIProvider>{children}</SimpleAIProvider>
+
+// オプション
+// - maxSessions: セッション数上限（デフォルト: 5）。超過時は LRU で破棄（ストリーミング中は優先的に除外）
+// - debug: マネージャ内部ログの有効化
+// - ttlMs: 購読者が 0 かつ ready/error のセッションを TTL 経過後に自動掃除（ブラウザ環境のみ定期実行）
+<SimpleAIProvider maxSessions={10} debug ttlMs={60_000}>{children}</SimpleAIProvider>
+```
+
+```ts
+// 取得できる値
+export type ChatStatus = 'ready' | 'submitted' | 'streaming' | 'error' | 'aborted'
+
+type UseChatSessionReturn = {
+  messages: Message[]
+  /**
+   * 受信済みのメタデータ一覧。新しいものが末尾に追加される。
+   */
+  metadata: Array<SessionMetadata>
+  /**
+   * messages の内容更新を検知するためのバージョン番号。
+   * useMemo の依存などに利用可能（任意）。
+   */
+  messagesVersion: number
+  status: ChatStatus
+  error: Error | null
+  /**
+   * API を呼ばずに現在のセッションの messages を即時上書きする。
+   * 内部的に messagesVersion がインクリメントされる。
+   */
+  setMessages: (messages: Message[], options?: { resetStatus?: boolean }) => void
+  sendMessage: (content: string, params?: { body?: Record<string, JSONValue>; dropFromMessageId?: string }) => Promise<void>
+  reload: (params?: { body?: Record<string, JSONValue> }) => Promise<void>
+  stop: () => void
+  stopAll: () => void
+}
+```
+
+```tsx
+const chatA = useChatSession('session-A', {
+  api: '/api/chat',
+  initialMessages: [{ id: 'usr-1', role: 'user', content: 'You are helpful.' }],
+  onError(err) { console.error('A err', err) },
+  onFinish(messages, details) {
+    console.log('A finished', messages.length, details.finishedReason)
+    console.log('metadata:', details.metadata)
+  }
+})
+
+const chatB = useChatSession('session-B', { api: '/api/chat' })
+
+// 2 つのセッションを並列実行可能
+await Promise.all([
+  chatA.sendMessage('こんにちは！'),
+  chatB.sendMessage('Hello!'),
+])
+```
+
+#### ふるまい
+- `sendMessage` は **新規 user メッセージを push** した上で、**全 messages** をサーバへ送ります。`params.dropFromMessageId` を指定すると、そのid以降(そのIDを含む)のメッセージを破棄してから新規メッセージを追加します。
+- `reload` は **最後の user 以降** を削除して再送します（再試行・プロンプト修正に有用）。
+- `stop` は現在のストリームを中断します。
+- `stopAll` はアクティブな全ストリーム（submitted/streaming 状態）を中断します。ページ離脱やグローバルなキャンセルボタンで利用できます。
+- `setMessages` は **API 呼び出しを行わず**、現在のセッションの `messages` を即時上書きします。UI に即時反映され、内部で `messagesVersion` がインクリメントされます。
+  - 通常は `status` を変更しません（例: ローカルでの編集や一時的な整形結果の反映に使用）。
+  - `options.resetStatus` を指定すると `status/error/finishedReason/nextAssistantMessageId` を初期化します（`submitted/streaming` 中は無視）。
+- **SPA 内のページ遷移ではストリーム継続**。Provider 配下から外れても、再マウント時に最新スナップショットを購読し直します。
+- **セッション数制限**: メモリ使用量を抑えるため、最大セッション数を制限（デフォルト: 5）。上限に達すると LRU 方式で最も古いセッションを自動削除。ストリーミング中のセッションは削除対象から優先的に除外。
+ - **メモ化のコツ**: ストリーミング中は各チャンクで `messages` 参照が更新されるため、`useMemo(..., [messages])` で確実に再評価されます。より厳密な制御が必要な場合は `messagesVersion` を依存に加えることもできます。
+ - **prefetch の挙動**: マウント前（購読 0）のチャンクは通知を抑制しますが、内部状態は更新され、マウント後の最初のスナップショットで最新内容を取得できます。購読開始直後（0→1）で `streaming/submitted` の場合は即時通知を1回行います。
+
+> **タブを閉じた / リロードの扱い**: 特に対策は行いません。ブラウザプロセス終了により接続は切断されます（仕様）。
+
+#### onFinish/onError の扱い（クライアント）
+- セッション単位で保持: `useChatSession(..., { onFinish })` のハンドラは、変更のたびにマネージャへ登録し、セッションごとに「最新のみ」を保持します。
+- 完了時は常に最新を呼ぶ: ストリーム完了時は常に最新の `onFinish` が呼ばれます。コンポーネントがアンマウント済み（購読 0）でも呼ばれます。
+- `onFinish` の `details.metadata` は、そのストリーム中に受信したメタデータの最新スナップショットです。
+- 複数購読時の優先: 同一 `sessionId` を複数コンポーネントが使用する場合、最後に登録された `onFinish` が有効です。
+- `onError` は per-call: `sendMessage`/`reload` 呼び出し時に渡されたハンドラが呼ばれます（最新保持は行いません）。
+
+### ページ遷移前のセッション事前準備（`usePrefetchChatSession`）
+
+ページ遷移前にセッションを事前に初期化し、オプションでストリーミングを開始することで、遷移後の応答時間を短縮できます。
+
+#### 基本的な使用方法
+
+```tsx
+import { usePrefetchChatSession } from 'simple-ai-sdk/client'
+
+function PageA() {
+  const prefetch = usePrefetchChatSession()
+  
+  const handleNavigate = () => {
+    // セッション初期化とストリーミング開始（完了を待たない）
+    prefetch('chat-session-1', {
+      api: '/api/chat',
+      streamMessageContent: 'Hello AI!' // 即座に送信される
+    })
+    
+    // 即座にページBへ遷移
+    router.push('/page-b')
+  }
+}
+
+function PageB() {
+// すでにストリーミング中のセッションを取得
+  const chat = useChatSession('chat-session-1')
+  // chat.messagesにはストリーミング中の内容が含まれる
+  // chat.metadataにはこれまで受信したメタデータが含まれる
+}
+```
+
+#### オプション
+
+| オプション | 型 | 必須 | 説明 |
+|---|---|---|---|
+| `api` | `string` | ✅ | APIエンドポイント |
+| `streamMessageContent` | `string` | 任意 | 指定すると即座にユーザーメッセージとして送信され、ストリーミングが開始される |
+| `body` | `Record<string, JSONValue>` | 任意 | 追加のリクエストボディ |
+
+#### 動作の特徴
+
+- **非同期完了を待たない**: ストリーミングはバックグラウンドで開始され、関数は即座に返る
+- **セッション購読者カウントに影響しない**: `retainSession`/`releaseSession`を呼ばないため、既存のライフサイクル管理と干渉しない
+- **既存セッションとの共存**: 同一sessionIdのセッションが既に存在する場合は初期化をスキップ
+- **エラーハンドリング**: バックグラウンドエラーはコンソールに出力され、遷移後のページで適切にハンドリング可能
+
+#### 使用シーン
+
+- **SPA内でのページ遷移**: ユーザーの操作に先立ってAIレスポンスの準備を開始
+- **ウィザード形式のUI**: 次のステップで必要なAI処理を事前開始
+- **プリロード戦略**: ユーザーが次に実行する可能性の高いアクションを予測して事前準備
+
+### ローディング中メッセージ判定（`useLoadingMessageId`）
+
+ストリーミング中・送信直後のメッセージだけにアニメーションを付けたい場合のフック。
+
+```ts
+import { useChatSession } from "simple-ai-sdk/client/useChatSession";
+import { useLoadingMessageId } from "simple-ai-sdk/client/utils/useLoadingMessageId";
+
+const session = useChatSession("s1", { api: "/api/chat" });
+const loadingId = useLoadingMessageId(session, { holdMs: 750 });
+
+// message.id === loadingId のときだけスケルトン/バウンス等を表示する
+```
+
+- `status === "submitted"` のときは `nextAssistantMessageId` を返す。
+- `status === "streaming"` のときは最新の assistant メッセージ ID を返す。
+- ストリーミングが終わってもデフォルト 750ms (`holdMs` で変更可) は最後の ID を維持し、アニメーションが即座に消えないようにする。
+- `index.ts` からは再エクスポートしない。`simple-ai-sdk/client/utils/useLoadingMessageId` から直接 import する。
+
+---
+
+## クイックスタート
+
+### サーバ（Hono）
+
+```ts
+// server.ts
+import { Hono } from 'hono'
+import { streamText } from 'hono/streaming'
+import OpenAI from 'openai'
+import { createChatHandler } from 'simple-ai-sdk/server'
+import { redact, sentenceAggregator } from 'simple-ai-sdk/server/transforms'
+import { marked } from 'marked'
+
+const app = new Hono()
+
+// 通常のテキストストリーミング
+app.post('/api/chat', (c) => {
+  return streamText(c, async (stream) => {
+    const { handler, sendMetadata } = createChatHandler({
+      providers: {
+        openai: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+        provider: 'openai',
+        model: 'gpt-4o-mini',
+      },
+      transforms: [redact, sentenceAggregator()],
+      onFinish(info) {
+        console.log('tokens:', info.usage)
+      },
+      onError(err, details) {
+        console.error(err, details)
+        return "An error occurred"
+      }
+    })
+    
+    // ストリーム開始時にメタデータを送信
+    sendMetadata({ phase: 'start', timestamp: Date.now() })
+    
+    await handler(c.req.raw, stream)
+  })
+})
+
+export default app
+```
+
+### クライアント（React 19+）
+
+```tsx
+import { SimpleAIProvider } from 'simple-ai-sdk/client/context'
+import { useChatSession } from 'simple-ai-sdk/client/useChatSession'
+
+export default function App() {
+  return (
+    <SimpleAIProvider>
+      <DualChats />
+    </SimpleAIProvider>
+  )
+}
+
+function DualChats() {
+  const a = useChatSession('A', { api: '/api/chat' })
+  const b = useChatSession('B', { api: '/api/chat' })
+
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 }}>
+      <Panel title="A" s={a} />
+      <Panel title="B" s={b} />
+    </div>
+  )
+}
+
+function Panel({ title, s }: { title: string; s: ReturnType<typeof useChatSession> }) {
+  return (
+    <div>
+      <h3>{title}</h3>
+      <div style={{ minHeight: 120, border: '1px solid #ddd', padding: 8 }}>
+        {s.messages.map(m => <p key={m.id}><b>{m.role}:</b> {m.content}</p>)}
+      </div>
+      <button onClick={() => s.sendMessage('Hello')} disabled={s.status === 'streaming'}>Send</button>
+      <button onClick={() => s.stop()}>Stop</button>
+      <button onClick={() => s.reload()}>Reload</button>
+      <div>Status: {s.status}{s.error && ` (${s.error.message})`}</div>
+    </div>
+  )
+}
+```
+
+---
+
+## セキュリティ & 運用ノート
+
+- **API キーはサーバ側のみ**に保持。クライアントへ渡さない。
+- **CORS/キャッシュ**: SSE は中間プロキシで圧縮されると切れることがあるため `Cache-Control: no-cache, no-transform` を推奨。
+- **ログ/課金**: `onFinish` で `usage` と全文を受け取り、監査や課金算定に利用。
+- **GC（掃除）**: セッション購読者が 0 の場合、`done` 後に TTL で破棄する設計が望ましい。
+- **エラーハンドリング**: 各種エラーに対する適切なハンドリングを実装すること。
+- **Timeout**: オプションでタイムアウト秒数を設定し、超過時にストリームを中断する
+
+---
+
+## よくある拡張
+
+- **プロバイダーフォールバック**: `providers` を配列で指定することで、エラー時に自動的に次のプロバイダーへフォールバック。OpenAI障害時にGeminiへの切り替えなどが可能。
+- **Gemini 互換**: `provider: 'gemini'` で OpenAI SDK の `baseURL` に Google の OpenAI 互換エンドポイントを設定して動作可能。
+- **メタデータ連携**:
+  - Transform 内: `StreamTransformContext.sendMetadata()` でメタデータを送信（次の `chunk.meta` に同梱。必要に応じてメタのみチャンクで即時配送）
+  - ハンドラ外: `createChatHandler` の返り値から `sendMetadata` を取得して、リクエストの任意タイミングでメタデータ送信（開始時、進捗通知など）。ストリーム開始前に呼んだ場合も、開始直後にフラッシュされる。
+- **複雑な出力**: `chunk` に `type` を導入してツールコールや引用ハイライトなどを段階的に配信。
+
+> TODO: 今後`onStart`/`onChunk` といった追加ライフサイクルフックの導入を検討する
+
+---
+
+## 既知の制約
+
+- `usage` はモデル/ベンダや SDK のバージョンにより **ストリーム内で未提供** の場合があります（`onFinish.usage` が `undefined`）。
+- タブ閉鎖・リロードでの接続維持は **行いません**（仕様）。必要なら別パッケージで実装予定。 
+
+---
+
+## ライセンス
+
+MIT

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "simple-ai-sdk",
-  "version": "1.0.45",
+  "version": "1.0.47",
   "private": false,
   "description": "Simple AI SDK for Hono / React19+ / OpenAI",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "simple-ai-sdk": "./dist/cli.js"
+  },
   "exports": {
     "./client": {
       "types": "./dist/client/index.d.ts",
@@ -52,7 +55,7 @@
   "author": "catnose <hello@catnose.me> (https://catnose.me)",
   "license": "MIT",
   "scripts": {
-    "build": "rm -rf dist && tsc",
+    "build": "rm -rf dist && tsc && node ./scripts/copy-spec.mjs",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",