@wcstack/speech 1.13.1

package/README.ja.md

@@ -0,0 +1,186 @@
+# @wcstack/speech
+
+`@wcstack/speech` は wcstack エコシステム向けの、ヘッドレスな Web Speech コンポーネント2点セットです。
+
+これらは視覚的な UI ウィジェットではありません。`@wcstack/fetch` がネットワークリクエストを、`@wcstack/geolocation` が現在地をリアクティブな状態に変えるのと同じように、ブラウザの Web Speech API を**リアクティブな状態に変える非同期プリミティブノード**です。
+
+同一プロトコルの両半身となる2つのタグを提供します:
+
+| タグ | API | 向き | プロトコル上の役割 |
+|---|---|---|---|
+| **`<wcs-speak>`** | SpeechSynthesis（TTS） | state → 音声 | command-token（state が発話を駆動） |
+| **`<wcs-listen>`** | SpeechRecognition（STT） | 音声 → state | event-token（認識結果が state へ流れる） |
+
+両者が1つのパッケージに同居していること自体が要点です。`<wcs-speak>` は **command 駆動の出力**、`<wcs-listen>` は **event 駆動の入力**のショーケース。両者を繋げば speak ⇄ listen のループになります。
+
+いずれも [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md)（Core / Shell / Binding Contract）アーキテクチャに従います:
+
+- **Core**（`SpeakCore` / `ListenCore`）はネイティブ API のラップ・データ正規化・ライフサイクル/permission 管理を担い、決して throw しません（失敗は `error` で表面化）。
+- **Shell**（`<wcs-speak>` / `<wcs-listen>`）はそれを DOM 属性・ライフサイクル・宣言的コマンドに接続します。
+- **Binding Contract**（`static wcBindable`）が観測可能な `properties`・書き込み可能な `inputs`・呼び出し可能な `commands` を宣言します。
+
+## インストール
+
+```bash
+npm install @wcstack/speech
+```
+
+ビルドレス（CDN・両タグ登録）:
+
+```html
+<script type="module" src="https://esm.run/@wcstack/speech/auto"></script>
+```
+
+---
+
+## `<wcs-speak>` — 音声合成
+
+### 発話の2つの方法
+
+`<wcs-speak>` は同じ「発話」という動作を、**いつ発火するか**が異なる2つのサーフェスで提供します:
+
+```html
+<!-- 1. reactive: status が変わるたびに発話（同値は再発話しない） -->
+<wcs-speak data-wcs="say: status"></wcs-speak>
+
+<!-- 2. imperative: command token 経由で、同じ文でも都度発話 -->
+<wcs-speak data-wcs="command.speak: $command.announce"></wcs-speak>
+```
+
+```js
+export default {
+  $commandTokens: ["announce"],
+  status: "準備完了。",
+  onClick() {
+    this.$command.announce.emit("もう一度クリックされました。");  // imperative — 同値でも発話
+  },
+};
+```
+
+| サーフェス | 発火条件 | 同値で再発話 | 用途 |
+|---|---|---|---|
+| `say`（reactive input） | 束縛値が**変化**したとき | しない（ガード） | ステータス・a11y アナウンス |
+| `speak`（imperative command） | command が**起動**されたとき | する | 「クリックで読む」「もう一度読む」 |
+
+> **ヒント:** `<input>` の value など高頻度ソースに束縛するときは `\|debounce` を挟まないと1キーストロークごとに発話します。`manual` 属性で `say` を完全にミュートできます（認識中の発話ミュート＝echo 回避のフックにもなります）。
+
+### 単語境界ハイライト
+
+`charIndex` / `spokenWord` は読み上げ中の単語に応じて更新されます。束縛すれば「いま読んでいる単語」をハイライトできます（カラオケ風）。
+
+### 属性 / Inputs
+
+| 属性 | Input | 型 | 既定 | 意味 |
+|---|---|---|---|---|
+| — | `say` | string | — | reactive: 新しい値を書くと発話 |
+| `rate` | `rate` | number | `1` | 速度（0.1–10） |
+| `pitch` | `pitch` | number | `1` | ピッチ（0–2） |
+| `volume` | `volume` | number | `1` | 音量（0–1） |
+| `voice` | `voice` | string | — | `name` で voice 選択 |
+| `lang` | `lang` | string | — | BCP-47 言語タグ |
+| `manual` | `manual` | boolean | `false` | `say` パスをミュート |
+
+### 観測プロパティ（出力）
+
+| プロパティ | 型 | 意味 |
+|---|---|---|
+| `voices` | `SpeechVoiceInfo[]` | 利用可能な voice（非同期で確定） |
+| `speaking` | boolean | 発話中 |
+| `paused` | boolean | 一時停止中 |
+| `pending` | boolean | キューに発話あり |
+| `charIndex` | number \| null | 読み上げ中の単語の位置 |
+| `spokenWord` | string \| null | 読み上げ中の単語 |
+| `error` | `WcsSpeakErrorDetail` \| null | 直近の失敗 |
+| `unsupported` | boolean | SpeechSynthesis 非対応 |
+
+### コマンド
+
+| コマンド | 意味 |
+|---|---|
+| `speak(text)` | 発話をキュー（現在の `rate`/`pitch`/… 属性を使用） |
+| `cancel()` | キューをクリアして停止 |
+| `pause()` / `resume()` | 一時停止 / 再開 |
+
+### DOM トリガ（任意）
+
+`autoTrigger` 有効時（既定）、`data-speaktarget="<id>"` を持つ要素のクリックで、その `data-speaktext`（無ければ textContent）を `<wcs-speak id="<id>">` で発話します。
+
+```html
+<wcs-speak id="tts"></wcs-speak>
+<button data-speaktarget="tts" data-speaktext="こんにちは！">読み上げ</button>
+```
+
+---
+
+## `<wcs-listen>` — 音声認識
+
+```html
+<!-- 接続時に自動開始し、transcript を state に束縛 -->
+<wcs-listen lang="ja-JP" interim data-wcs="finalTranscript: transcript; interimTranscript: draft"></wcs-listen>
+
+<!-- manual・continuous・command 駆動 -->
+<wcs-listen manual continuous max-restarts="5"
+  data-wcs="command.start: $command.listen; finalTranscript: transcript; listening: isListening"></wcs-listen>
+```
+
+`<wcs-geo>` と同様に二相を持ちます: **一発**認識（既定）と、**連続**セッション（`continuous` 属性）。ブラウザは無音でセッションを終了しますが、自動再開は **`max-restarts` でのオプトイン**です — `continuous` **単独**（既定 `max-restarts="0"`）では無音で再開**しません**。`max-restarts="5"` で最大5回の無音をまたぎます。この上限は意図的です（無制限再開は無限ループ/クォータ枯渇のリスク）。
+
+> **マイクの自動起動。** `manual` を付けないと `<wcs-listen>` は接続時に `start()` を呼びます — タグを DOM に置くだけで認識が始まります（permission プロンプト→継続キャプチャ）。**明示的な `start()` / DOM トリガ / `trigger` 書き込みを要求したい場合は `manual` を付けてください。** `<wcs-geo>` の `manual` 慣習に倣っていますが、マイクキャプチャはよりプライバシー感度が高い点に注意。
+
+### 属性 / Inputs
+
+| 属性 | Input | 型 | 既定 | 意味 |
+|---|---|---|---|---|
+| `lang` | `lang` | string | — | BCP-47 言語タグ |
+| `continuous` | `continuous` | boolean | `false` | セッション継続＋end で自動再開 |
+| `interim` | `interim` | boolean | `false` | 途中経過の interim を出す |
+| `max-restarts` | `maxRestarts` | number | `0` | 自動再開の上限（continuous） |
+| `manual` | `manual` | boolean | `false` | 接続時に自動開始しない |
+| — | `trigger` | boolean | — | モーメンタリ: `false`→`true` で開始 |
+
+### 観測プロパティ（出力）
+
+| プロパティ | 型 | 意味 |
+|---|---|---|
+| `interimTranscript` | string | 未確定の途中テキスト |
+| `finalTranscript` | string | 蓄積された確定テキスト |
+| `result` | `WcsListenResultDetail` \| null | 直近結果（transcript / confidence / alternatives / isFinal） |
+| `listening` | boolean | セッション中 |
+| `permission` | `"prompt"\|"granted"\|"denied"\|"unsupported"` | マイク permission |
+| `error` | `WcsListenErrorDetail` \| null | 直近の失敗 |
+| `unsupported` | boolean | SpeechRecognition 非対応 |
+
+### コマンド
+
+| コマンド | 意味 |
+|---|---|
+| `start()` | セッション開始（transcript をリセット） |
+| `stop()` | 穏やかに停止（自動再開しない） |
+| `abort()` | 即時停止 |
+
+### DOM トリガ（任意）
+
+`data-listentarget="<id>"` を持つ要素のクリックで、対象 `<wcs-listen>` の `start()` / `stop()` をトグルします。
+
+---
+
+## 注意・制限
+
+- **セキュアコンテキスト必須。** 両 API とも HTTPS か `localhost` が必要。`<wcs-listen>` はさらにマイク permission が必要です。
+- **ブラウザ対応。** SpeechSynthesis は広く対応。SpeechRecognition は Chrome 系のみ（`webkitSpeechRecognition`）で、それ以外では `<wcs-listen>` は `unsupported` を報告します。
+- **SpeechSynthesis はグローバルシングルトン。** `<wcs-speak>` は切断時に `cancel()` しません（他インスタンスまで止まるため）。音声を止めるには明示的に `cancel()` を。切断された要素は追跡を止めますが、発話中の utterance は自然に完了します。
+- **echo ループ。** `<wcs-listen>` → state → `<wcs-speak>` を繋ぐときは、認識中は発話をミュート（例: `manual` を束縛）して合成音声が再認識されないように。echo の例を参照。
+
+## ヘッドレス利用（`SpeakCore` / `ListenCore`）
+
+どちらの Core もフレームワーク非依存で、カスタム要素なしに `@wc-bindable/core` の `bind()` 経由で利用できます:
+
+```js
+import { SpeakCore } from "@wcstack/speech";
+const core = new SpeakCore();
+core.speak("こんにちは。");
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,187 @@
+# @wcstack/speech
+
+`@wcstack/speech` is a headless Web Speech component pair for the wcstack ecosystem.
+
+These are not visual UI widgets. They are **async primitive nodes** that turn the browser's Web Speech APIs into reactive state — the same way `@wcstack/fetch` turns a network request into reactive state and `@wcstack/geolocation` turns the device's location into reactive state.
+
+The package ships two complementary tags, the two halves of the same protocol:
+
+| Tag | API | Direction | Protocol role |
+|---|---|---|---|
+| **`<wcs-speak>`** | SpeechSynthesis (TTS) | state → speech | command-token (state drives speech) |
+| **`<wcs-listen>`** | SpeechRecognition (STT) | speech → state | event-token (recognition flows to state) |
+
+Their coexistence in one package is the point: `<wcs-speak>` is a perfect showcase of **command-driven output**, `<wcs-listen>` of **event-driven input**. Wire them together for a speak ⇄ listen loop.
+
+Both follow the [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md) (Core / Shell / Binding Contract) architecture:
+
+- **Core** (`SpeakCore` / `ListenCore`) wraps the native API, normalizes data, manages lifecycle/permission, and never throws (failures surface through `error`).
+- **Shell** (`<wcs-speak>` / `<wcs-listen>`) connects that state to DOM attributes, lifecycle, and declarative commands.
+- **Binding Contract** (`static wcBindable`) declares observable `properties`, writable `inputs`, and callable `commands`.
+
+## Install
+
+```bash
+npm install @wcstack/speech
+```
+
+Or buildless via CDN (registers both tags):
+
+```html
+<script type="module" src="https://esm.run/@wcstack/speech/auto"></script>
+```
+
+---
+
+## `<wcs-speak>` — text to speech
+
+### Two ways to speak
+
+`<wcs-speak>` exposes the same action through two surfaces that differ in **when they fire**:
+
+```html
+<!-- 1. Reactive: speaks whenever `status` changes (same value is NOT re-spoken). -->
+<wcs-speak data-wcs="say: status"></wcs-speak>
+
+<!-- 2. Imperative: speaks on demand, even the same text again, via the command token. -->
+<wcs-speak data-wcs="command.speak: $command.announce"></wcs-speak>
+```
+
+```js
+// state
+export default {
+  $commandTokens: ["announce"],
+  status: "Ready.",
+  onClick() {
+    this.$command.announce.emit("Button clicked again.");  // imperative — re-speaks same text
+  },
+};
+```
+
+| Surface | Fires when | Same value re-speaks? | Use for |
+|---|---|---|---|
+| `say` (reactive input) | the bound value **changes** | no (guarded) | status / a11y announcements |
+| `speak` (imperative command) | the command is **invoked** | yes | "speak this on click", "say it again" |
+
+> **Tip:** wire `say` through a `\|debounce` filter when binding to a rapidly-changing source (e.g. an `<input>` value), or it will speak on every keystroke. Set the `manual` attribute to mute the `say` path entirely (also the hook for muting speech while listening — see the echo example).
+
+### Word-boundary highlighting
+
+`charIndex` / `spokenWord` update as each word is spoken — bind them to highlight the currently-spoken word (karaoke-style).
+
+### Attributes / Inputs
+
+| Attribute | Input | Type | Default | Meaning |
+|---|---|---|---|---|
+| — | `say` | string | — | reactive: writing a new value speaks it |
+| `rate` | `rate` | number | `1` | speech rate (0.1–10) |
+| `pitch` | `pitch` | number | `1` | pitch (0–2) |
+| `volume` | `volume` | number | `1` | volume (0–1) |
+| `voice` | `voice` | string | — | voice selected by `name` |
+| `lang` | `lang` | string | — | BCP-47 language tag |
+| `manual` | `manual` | boolean | `false` | mute the `say` path |
+
+### Observable Properties (outputs)
+
+| Property | Type | Meaning |
+|---|---|---|
+| `voices` | `SpeechVoiceInfo[]` | available voices (populated asynchronously) |
+| `speaking` | boolean | an utterance is being spoken |
+| `paused` | boolean | speech is paused |
+| `pending` | boolean | utterances are queued |
+| `charIndex` | number \| null | offset of the word being spoken |
+| `spokenWord` | string \| null | the word being spoken |
+| `error` | `WcsSpeakErrorDetail` \| null | last failure |
+| `unsupported` | boolean | SpeechSynthesis is unavailable |
+
+### Commands
+
+| Command | Meaning |
+|---|---|
+| `speak(text)` | queue an utterance (uses current `rate`/`pitch`/… attributes) |
+| `cancel()` | clear the queue and stop |
+| `pause()` / `resume()` | suspend / resume |
+
+### Optional DOM triggering
+
+With `autoTrigger` on (default), clicking an element carrying `data-speaktarget="<id>"` speaks its `data-speaktext` (or its text content) through the `<wcs-speak id="<id>">`.
+
+```html
+<wcs-speak id="tts"></wcs-speak>
+<button data-speaktarget="tts" data-speaktext="Hello!">Speak</button>
+```
+
+---
+
+## `<wcs-listen>` — speech to text
+
+```html
+<!-- Auto-start on connect; bind the transcript to state -->
+<wcs-listen lang="en-US" interim data-wcs="finalTranscript: transcript; interimTranscript: draft"></wcs-listen>
+
+<!-- Manual, continuous, command-driven -->
+<wcs-listen manual continuous max-restarts="5"
+  data-wcs="command.start: $command.listen; finalTranscript: transcript; listening: isListening"></wcs-listen>
+```
+
+Like `<wcs-geo>`, it has two phases: a **one-shot** recognition (default) and a **continuous** session (`continuous` attribute). The browser still ends a session on silence; auto-restart bridges that, but is **opt-in via `max-restarts`** — `continuous` *alone* (with the default `max-restarts="0"`) does **not** restart on silence. Set `max-restarts="5"` to bridge up to 5 silences. This bound is deliberate: unbounded restart is an infinite-loop / quota-exhaustion risk.
+
+> **Microphone auto-start.** Without `manual`, `<wcs-listen>` calls `start()` on connect — placing the tag in the DOM begins recognition (a permission prompt, then continuous capture). **Add `manual` to require an explicit `start()` / DOM-trigger / `trigger` write instead.** Mirrors `<wcs-geo>`'s `manual` convention, but mind that microphone capture is more privacy-sensitive.
+
+### Attributes / Inputs
+
+| Attribute | Input | Type | Default | Meaning |
+|---|---|---|---|---|
+| `lang` | `lang` | string | — | BCP-47 language tag |
+| `continuous` | `continuous` | boolean | `false` | keep the session open & auto-restart on end |
+| `interim` | `interim` | boolean | `false` | emit live interim transcripts |
+| `max-restarts` | `maxRestarts` | number | `0` | cap on automatic restarts (continuous) |
+| `manual` | `manual` | boolean | `false` | do not auto-start on connect |
+| — | `trigger` | boolean | — | momentary: `false`→`true` starts a session |
+
+### Observable Properties (outputs)
+
+| Property | Type | Meaning |
+|---|---|---|
+| `interimTranscript` | string | live, not-yet-final text |
+| `finalTranscript` | string | accumulated final text |
+| `result` | `WcsListenResultDetail` \| null | latest result (transcript / confidence / alternatives / isFinal) |
+| `listening` | boolean | a session is active |
+| `permission` | `"prompt"\|"granted"\|"denied"\|"unsupported"` | microphone permission |
+| `error` | `WcsListenErrorDetail` \| null | last failure |
+| `unsupported` | boolean | SpeechRecognition is unavailable |
+
+### Commands
+
+| Command | Meaning |
+|---|---|
+| `start()` | begin a session (resets transcripts) |
+| `stop()` | stop gracefully (no auto-restart) |
+| `abort()` | stop immediately |
+
+### Optional DOM triggering
+
+Clicking an element with `data-listentarget="<id>"` toggles `start()` / `stop()` on the target `<wcs-listen>`.
+
+---
+
+## Notes & limitations
+
+- **Secure context required.** Both APIs need HTTPS or `localhost`; `<wcs-listen>` additionally needs microphone permission.
+- **Browser support.** SpeechSynthesis is broad; SpeechRecognition is Chrome-only (vendor-prefixed `webkitSpeechRecognition`) — `<wcs-listen>` reports `unsupported` elsewhere.
+- **SpeechSynthesis is a global singleton.** `<wcs-speak>` does **not** `cancel()` on disconnect (that would stop other instances); call `cancel()` explicitly to stop audio. A disconnected element stops tracking but any in-flight utterance finishes.
+- **Echo loop.** When wiring `<wcs-listen>` → state → `<wcs-speak>`, mute speaking while listening (e.g. bind `manual`) so the synthesized audio is not re-recognized. See the echo example.
+
+## Headless usage (`SpeakCore` / `ListenCore`)
+
+Both Cores are framework-agnostic and usable without the custom elements, via `bind()` from `@wc-bindable/core`:
+
+```js
+import { SpeakCore } from "@wcstack/speech";
+const core = new SpeakCore();
+core.speak("Hello, world.");
+```
+
+## License
+
+MIT

package/dist/auto.js

@@ -0,0 +1,3 @@
+import { bootstrapSpeech } from "./index.esm.js";
+
+bootstrapSpeech();

package/dist/auto.min.js

@@ -0,0 +1 @@
+import{bootstrapSpeech}from"./index.esm.min.js";bootstrapSpeech();