@kubohiroya/turbowarp-webrtc-qrcode-pairing 0.1.0

package/docs/design/qr-pairing/requirements.md

@@ -0,0 +1,152 @@
+# 要求仕様の把握（Issue #1）
+
+出典: [Issue #1](https://github.com/kubohiroya/turbowarp-webrtc-qrcode-pairing/issues/1)。
+本書はIssue本文を設計入力として再構成したもので、新しい要求の追加はしない。
+
+信頼性の凡例: 🟢 Issue本文に明記 / 🟡 Issue本文＋既存実装からの妥当な導出 / 🔴 Issue本文にない設計上の追加判断。
+
+## 1. 目的とスコープ
+
+🟢 QRコードの光学的搬送でWebRTCのOffer／AnswerをやりとりするTurboWarp拡張。時刻同期・空間校正・モーションキャプチャに依存せず、複数アプリから再利用できる「接続準備」機能に限定する。
+
+🟢 スコープ外: 光学的な時刻対応推定、レンズ校正、カメラ配置校正、姿勢推定、映像転送の独自実装。シグナリングサーバ。ICE／STUN／TURNの設計そのもの。
+
+🟢 現状: テンプレート0.4.0由来の初期構成のみ。実行可能なのは`hello [NAME]`のみで、ペアリング実装は存在しない。
+
+## 2. 役割と用語
+
+| 用語 | 定義 | 由来 |
+|---|---|---|
+| 統合側端末 (hub) | Offerを生成・投影し、Answerを読み取る側 | 🟢 |
+| カメラ側端末 (camera) | Offerを読み取り、Answerを表示する側 | 🟢 |
+| 搬送担当者 | Answer QRをスマートフォンで撮影して統合側へ運ぶ人 | 🟢 |
+| exchange（交換） | 1回のOffer→Answer往復。取消・再試行で新しいexchangeになる | 🟡 |
+| part | 1枚のQRに収まる分割片 | 🟢 |
+| courier envelope | partに載せる搬送用メタデータ＋payload | 🟢 |
+
+## 3. 標準操作（正常系）
+
+🟢 Issue「利用場面と標準操作」の7手順。
+
+1. hubが対象cameraとのペアリングを開始しOfferを生成する。
+2. hubがプロジェクタでOffer QRを表示する。
+3. cameraがカメラでQRを読み取り、全partを取得してOfferを受理する。
+4. cameraがAnswerを生成し、そのQRを画面に表示する。
+5. 担当者がスマートフォンでAnswer QRを（複数partならすべて）撮影し、hubまで運ぶ。
+6. 担当者がスマートフォン画面をhubのカメラにかざす。hubは全partを再構成しAnswerを受理する。
+7. WebRTC接続の成立を確認し、結果を利用アプリへ提供する。
+
+🟢 制約: スマートフォンに専用アプリ・ネットワークを要求しない（撮影画像の表示だけで搬送できる）。操作案内・端末配置・投影レイアウトは利用アプリの責務。
+
+## 4. 責務分担
+
+| 対象 | 責務 | 
+|---|---|
+| 本拡張 | QR搬送形式、QR生成・分割・表示、再構成・検証、Offer／Answer交換の進行と結果提供 |
+| `turbowarp-webrtc` | Offer／Answer生成・受理、ICE、接続状態、接続とデータ通信 |
+| `turbowarp-jsqr` | カメラフレームからのQRデコード |
+| `turbowarp-camera-source` | カメラの取得・選択とフレームへのアクセス |
+| 利用アプリ | 役割選択、操作案内、投影・表示レイアウト、接続後の処理 |
+
+🟢 すべてIssue本文の表のとおり。
+
+## 5. 機能要求（FR）
+
+### FR-1 Offer／Answerの対称な搬送
+
+| ID | 要求 | 受け入れ観点 |
+|---|---|---|
+| FR-1.1 | hub側のOffer生成・表示・Answer受理と、camera側のOffer受理・Answer生成・表示を両方実装する 🟢 | 両ロールのブロックが存在する |
+| FR-1.2 | 再構成した接続情報は、正しい役割・対象のWebRTC能力に一度だけ渡す 🟢 | 二重受理が起きない |
+| FR-1.3 | 送信側peer識別子と受信側ローカルpeer識別子の対応を定義し、両端で同じ識別子設定を暗黙に要求しない 🟢 | 非対称な命名で接続できる |
+| FR-1.4 | AnswerがどのOffer交換への応答かを追跡し、別ペアリングへ誤適用しない 🟢 | 別exchangeのAnswerを拒否する |
+
+### FR-2 QR搬送形式と再構成
+
+| ID | 要求 |
+|---|---|
+| FR-2.1 | protocol version, session ID, peer対応情報, Offer／Answer種別, message ID, part index／count, message length, hash, payload を扱う 🟢 |
+| FR-2.2 | QR容量と誤り訂正レベルに応じて分割し、単一QR／複数QRの両方に対応する 🟢 |
+| FR-2.3 | partの順不同・重複読取りに対応し、取得済み数・必要数・未取得partを取得できる 🟢 |
+| FR-2.4 | 全partが揃い、長さとhashを検証した後にのみWebRTCへ渡す 🟢 |
+| FR-2.5 | 不正形式／非対応version／範囲外index／過大入力／異なるsession・messageの混在／矛盾した重複part／hash不一致を検出する 🟢 |
+| FR-2.6 | hashは破損検出用であり本人性認証と区別する（文書化） 🟢 |
+| FR-2.7 | message length・part数・受信状態保持に上限を設ける。既存上限（128 Ki、64 part、chunk 4096）を出発点に、単位と境界条件を明記する 🟢 |
+| FR-2.8 | `twmp-qr/1`を移設の出発点とする。互換性を壊すならversionを変更し、旧形式の扱いと移行方法を明記する 🟢 |
+
+### FR-3 表示と読取りの連携
+
+| ID | 要求 |
+|---|---|
+| FR-3.1 | QR画像・part数・現在partを取得し、指定partの表示／次partへの切替／表示終了ができる 🟢 |
+| FR-3.2 | 静止画撮影でも各partを確実に取得できるよう、手動切替とpart識別情報を提供する 🟢 |
+| FR-3.3 | 読取り処理を独自に重複実装せず、jsqrのデコード文字列を受け取る入口を設ける 🟢 |
+| FR-3.4 | camera-sourceの所有・lease規則を尊重し、同じカメラを後続の撮影用途へ引き継げるようにする 🟢 |
+| FR-3.5 | skinを変更した場合、表示終了・取消・プロジェクト停止時に元へ復帰する。アプリ側の画像表示経路を妨げない 🟢 |
+
+### FR-4 状態・エラー・ライフサイクル
+
+| ID | 要求 |
+|---|---|
+| FR-4.1 | 生成中／表示・受信待ち／部分受信／接続中／接続成立／取消／失敗をアプリが区別できる。最終的な状態名と遷移は実装前に定義する 🟢 |
+| FR-4.2 | QR読取り完了とWebRTC接続成立を別の状態として提供する 🟢 |
+| FR-4.3 | session単位の開始・取消・再試行・状態／進捗／エラー参照を公開する。opcodeと引数は実装時に確定しmanifestへ反映する 🟢 |
+| FR-4.4 | 取消・再試行後に到着した古い非同期結果を新しいsessionへ反映しない 🟢 |
+| FR-4.5 | 再試行時は新しい交換を識別でき、遅れて読み取った古いQRが接続に使われない 🟢 |
+| FR-4.6 | 待ち時間の上限を設定可能とする。期限判定は未同期端末の壁時計一致を前提にしない 🟢 |
+| FR-4.7 | 複数camera端末との接続を対象peer／sessionごとに区別する。初期フローは1台ずつでよく、同時ペアリング画面は必須としない 🟢 |
+| FR-4.8 | 停止・破棄時に所有する表示・購読・タイマ・受信バッファを解放する。共有カメラや成立済み接続の切断は所有関係と明示操作に従う 🟢 |
+| FR-4.9 | 生のSDP・ICE情報・QR payloadを通常ログへ自動出力しない。エラー分類と進捗は診断に利用できる 🟢 |
+
+## 6. 非機能要求（NFR）
+
+| ID | 要求 | 由来 |
+|---|---|---|
+| NFR-1 | 人手の搬送（数分オーダー）に耐える。Offer／Answer生成時のICE収集完了条件と接続情報の有効性を既存実装に照らして確認する | 🟢 |
+| NFR-2 | QR搬送だけで接続可能性が保証されるとは扱わない（ネットワーク条件は`turbowarp-webrtc`の責務） | 🟢 |
+| NFR-3 | 新経路は`src/config/feature-flags.ts`の`qrCodePairing`（仮称）を起動時に読み取り、既定OFFで段階導入する | 🟢 |
+| NFR-4 | courier等の純粋処理の単体検証はフラグと独立に実行できる | 🟢 |
+| NFR-5 | motion-capture側の既存QR／manual pairing経路を削除せず維持する | 🟢 |
+| NFR-6 | 利用アプリが新経路を無効化し従来のmanual Offer／Answer交換へ戻す手順を記載する。フラグOFFは経路選択の切戻しであり、成立済み接続の自動切断ではない | 🟢 |
+| NFR-7 | `pnpm run check`（型検査・lint・テスト・README生成検証・ビルド再現性・repo検査・pack dry-run）が通る | 🟢 |
+| NFR-8 | README（日英）、公開契約・manifest、操作手順、形式互換性、制約、回帰・切戻し手順を更新する | 🟢 |
+
+## 7. 移設の出発点
+
+🟢 `turbowarp-realtime-motion-capture`から次を抽出の出発点とする。
+
+- `src/qr-courier.ts`: envelope生成、分割、parse、再構成、整合性検証
+- `src/qr-svg.ts`: QRのSVG生成
+- `src/extension.ts`: Offer QR準備・表示・part切替・表示終了と関連する状態管理
+
+🟢 現在のcourier形式はOffer／Answerに対応するが、高水準の表示処理はOffer側のみ。コピーで完了とせず、Answer側と往復状態管理を補完する。抽出元のテストを移設し、追加部分の受け入れテストを整備する。汎用QR搬送コードからmotion-capture固有の型・命名・runtime依存を切り離す。
+
+詳細な選別表は [extraction-plan.md](extraction-plan.md) を参照。
+
+## 8. 受け入れ基準（DoD）
+
+🟢 Issueのチェックリストをそのまま採用する。テストへの写像は [test-plan.md](test-plan.md) を参照。
+
+1. 投影Offer → camera読取り → Answer撮影・スマートフォン搬送 → hub読取りの全工程で接続が成立する。
+2. 接続成立後、既存WebRTC能力によるテストメッセージ送受信を確認する。
+3. 単一QRと複数QRで往復できる。順不同・重複・不足partを検証する。
+4. 不正QR、別session／別peer対応、矛盾part、hash不一致、上限超過が誤った接続情報の受理につながらない。
+5. 取消・期限切れ・再試行・古い非同期応答・古いQRを検証する。
+6. 2台以上のcameraを順に接続し、Answerと対象peerの対応が混線しない。
+7. 表示の復元と所有資源の解放を確認し、共有カメラの利用を妨げない。
+8. 進捗、QR受信完了、WebRTC接続成立、エラーをアプリから参照できる。
+9. 起動時固定・既定OFFの新経路とmanual pairingへの切戻しを確認する。
+10. `pnpm run check`が通る。
+11. README（日英）ほかドキュメントを更新する。
+12. 実機検証では端末・ブラウザ・QR表示条件・ネットワーク条件・part数・結果を記録する。未検証条件を成功済みと扱わない。
+
+## 9. 設計時に判明した制約（Issue本文にない事実）
+
+| # | 事実 | 影響 | 確認元 |
+|---|---|---|---|
+| C-1 | `turbowarp-webrtc`のruntime capability v2は`createOffer`／`getOffer`しか公開していない。`acceptOffer`／`getAnswer`／`acceptAnswer`／`connectionState`はブロック専用で、他拡張から呼べない | FR-1.1がv2のままでは実装不能。capability v3の追加が前提作業になる | `turbowarp-webrtc/src/runtime-capability.ts:19-24`、`src/manual-peer-session.ts:36-59` |
+| C-2 | `createOffer`／`acceptOffer`はどちらも`waitForIceGathering`で収集完了まで待つ（trickle ICEではない） | 搬送に数分かかってもコード自体は不変で完結している。NFR-1の確認は「収集完了待ちである」ことをもって満たす | `turbowarp-webrtc/src/manual-peer-session.ts:109-149, 484-498` |
+| C-3 | pairing codeは`base64url(JSON)`で印字可能ASCIIのみ。courierの`[\x20-\x7E]`制約と適合する | 形式変換は不要 | `turbowarp-webrtc/src/protocol.ts:26-42` |
+| C-4 | `jsqr`の`waitForQrText`は呼び出しごとにcamera leaseを取得・解放する。partごとに呼ぶとlease取得・解放が繰り返される | session中は自前で1つのleaseを保持し、デコードは`scanFrame`を再利用する | `turbowarp-jsqr/src/extension.ts:95-155` |
+| C-5 | 誤り訂正M・QR v40での1part容量は2331バイト。envelope v2のヘッダ最大長は362文字なので、payloadは最大1969文字／part、64partで126,016文字 | `MAX_MESSAGE_LENGTH = 128 Ki (131,072)`はM以下では到達しない。実効上限はpart数×chunk長 | 本設計での実測（`interfaces.ts`の定数コメント参照） |
+| C-6 | motion-captureはvitest 4系、本リポジトリはvitest 5系 | 移設テストの実行確認が必要 | 両`package.json` |

package/docs/design/qr-pairing/test-plan.md

@@ -0,0 +1,126 @@
+# 検証計画（DoD → テスト対応）
+
+対応要求: requirements.md §8
+
+## 1. テストの層
+
+| 層 | 対象 | 依存の扱い |
+|---|---|---|
+| 単体（純粋） | `src/qr/**` | 依存なし。フィーチャーフラグと独立に動く（NFR-4） |
+| 単体（ドメイン） | `src/pairing/**` | `WebRtcPairingPort` / `QrScanPort` / `DisplayPort` / `MonotonicClock`をフェイク注入 |
+| 連携（プロセス内） | hub controller ↔ camera controller | 2つのcontrollerをQRテキスト受け渡しで結線。WebRTCは`RTCPeerConnection`のフェイク、またはNode環境では純粋なコード交換フェイク |
+| 実デコード | `qr/svg.ts` → jsQR | 生成SVG／モジュール行列をラスタライズし`jsqr`で復号（移設元の手法を流用） |
+| 実機 | 全工程 | 手順書に従い記録する（自動化しない） |
+
+## 2. DoD対応表
+
+| DoD | 検証方法 | テストファイル |
+|---|---|---|
+| 1. 全工程で接続成立 | プロセス内往復（自動）＋実機（手動） | `tests/pairing-roundtrip.test.ts` / 実機記録 |
+| 2. 接続後のメッセージ送受信 | 実機で`turbowarp-webrtc`の`send event`／`next received message`を確認 | 実機記録 |
+| 3. 単一QRと複数QRの往復、順不同・重複・不足 | 短いコード（1part）と6000文字相当（複数part）で往復。partを逆順投入、同一part再投入、1つ欠落 | `tests/qr-courier.test.ts` / `tests/pairing-roundtrip.test.ts` |
+| 4. 不正QR・別session・別peer・矛盾part・hash不一致・上限超過 | 各エラーコードごとにケースを用意し、いずれも`delivered`が立たないことを確認 | `tests/qr-courier.test.ts` / `tests/pairing-validation.test.ts` |
+| 5. 取消・期限・再試行・古い非同期応答・古いQR | フェイク時計を進めて期限、遅延resolveするフェイクWebRTCでepoch検証、retry後に旧QRを投入 | `tests/pairing-lifecycle.test.ts` |
+| 6. 2台以上のcameraの混線なし | hub 1つに対しcamera A/Bを順に接続。Bの回答をAのsession keyへ投入して拒否されることを確認 | `tests/pairing-multi-peer.test.ts` |
+| 7. 表示復元と資源解放、共有カメラを妨げない | フェイクrendererで`updateDrawableSkinId`の復元呼び出しと`destroySkin`を確認。leaseの`release`回数と、アプリ側leaseが残る場合にカメラが停止しないことを確認 | `tests/pairing-display.test.ts` |
+| 8. 進捗・受信完了・接続成立・エラーの参照 | 各phaseで`progress()`の全フィールドを検証。`offer-received`と`connected`が別状態であることを明示的にassert | `tests/pairing-progress.test.ts` |
+| 9. 既定OFFとmanual pairingへの切戻し | フラグ未設定で`getInfo()`にペアリングブロックが無いこと、直接呼出しが`feature-disabled`、`pairingPhase`が`disabled`を返すこと。切戻し手順はREADMEに記載 | `tests/extension.test.ts` |
+| 10. `pnpm run check` | CIとローカル | — |
+| 11. ドキュメント更新 | `pnpm run docs:check`＋レビュー | — |
+| 12. 実機記録 | 下記テンプレートで記録 | — |
+
+## 3. 重点ケース（受け入れテストの具体）
+
+### 3.1 形式・検証（FR-2.5）
+
+各ケースは「エラーコードが期待どおり」かつ「WebRTCへ引き渡されない」の両方をassertする。
+
+| ケース | 入力 | 期待コード |
+|---|---|---|
+| JSONでない | `"not json"` | `invalid-json` |
+| 旧protocol | `twmp-qr/1`のenvelope | `unsupported-protocol` |
+| 未知version | `twqr/2` | `unsupported-protocol` |
+| partIndex >= partCount | `{partIndex:3,partCount:3}` | `index-out-of-range` |
+| partCount > 64 | `{partCount:65}` | `invalid-envelope` |
+| messageLength = 0 | | `invalid-envelope` |
+| messageLength > 131072 | | `message-too-large` |
+| payload > 4096 | | `invalid-envelope` |
+| QRテキスト > 8192 | | `part-too-large` |
+| hashが43文字でない | | `invalid-envelope` |
+| 別sessionIdのpartを混ぜる | | `message-mismatch` |
+| 同indexで異なるpayload | | `conflicting-part` |
+| hashだけ書き換える | 全part揃った状態 | `hash-mismatch` |
+| messageLengthだけ書き換える | 全part揃った状態 | `length-mismatch` |
+| 1part欠落で`assemble` | | `missing-parts` |
+| 分割で65part必要な長さ | | `too-many-parts` |
+
+### 3.2 交換の同一性（FR-1.4 / FR-4.5）
+
+| ケース | 期待 |
+|---|---|
+| Answerの`replyTo`が別Offerのmessage ID | `reply-mismatch`、`acceptAnswer`未呼出 |
+| Answerの`senderPeerId`がsessionの`remotePeerId`と不一致 | `peer-mismatch` |
+| `retryPairing`後に旧exchangeのAnswerを投入 | `stale-exchange`、`acceptAnswer`未呼出 |
+| 存在しないsessionキーへ投入 | `unknown-session` |
+| cameraでkind=`answer`のQRを読む | `unexpected-kind` |
+| 完成済みsessionへ同じ全partを再投入 | `already-accepted`、`acceptAnswer`は1回だけ |
+
+### 3.3 peer対応の非対称性（FR-1.3）
+
+hubが`localPeerId="studio"`, `remotePeerId="cam-A"`、cameraが`expectedLocalPeerId=""`のとき:
+
+- camera側のWebRTC呼出しは`acceptOffer("studio", …)`であること
+- hub側のWebRTC呼出しは`createOffer("cam-A", …)`／`acceptAnswer("cam-A", …)`であること
+- 両端で同じ文字列を設定していないのに接続が成立すること
+- cameraが`expectedLocalPeerId="cam-B"`を指定した場合は`peer-mismatch`で拒否されること
+
+### 3.4 ライフサイクル（FR-4.4 / FR-4.8）
+
+| ケース | 期待 |
+|---|---|
+| `createOffer`が遅延resolveする間に`cancelPairing` | 遅延結果が捨てられ、phaseは`cancelled`のまま |
+| `acceptOffer`遅延中に期限到来 | phaseは`expired`、遅延結果でphaseが動かない |
+| 期限到来（未接続） | 表示復元・lease解放・タイマ停止・`closePeer`呼出し |
+| 期限到来（接続済み） | `closePeer`を呼ばない |
+| `PROJECT_RUN_STOP` | 表示復元とlease解放。成立済み接続は維持 |
+| `RUNTIME_DISPOSED` | 全session破棄とリスナ解除 |
+| `targetWasRemoved` | 当該スプライトの表示のみ終了、sessionは継続 |
+| session数が9個目 | `session-limit` |
+
+### 3.5 期限が壁時計に依存しないこと（FR-4.6）
+
+フェイク`MonotonicClock`だけを進め、`Date.now()`は動かさない（あるいは逆方向へ飛ばす）状態で
+期限が正しく判定されることをassertする。`createdAt`を未来・過去に改竄したenvelopeを投入しても
+期限判定に影響しないことも確認する。
+
+### 3.6 プライバシー（FR-4.9）
+
+- `console`の全メソッドをスパイし、正常系・異常系いずれでも呼ばれないことを確認する。
+- 全エラーの`message`について、pairing code本文・payload断片を含まないことを検証する
+  （テスト用に識別可能なマーカー文字列をpairing codeへ埋め、それが例外メッセージへ現れないこと）。
+
+## 4. 実機検証の記録テンプレート（DoD 12）
+
+各試行につき以下を記録し、Issue #1のコメントへ貼る。未実施の条件を成功として扱わない。
+
+```
+日時:
+役割/端末: hub = <機種/OS/ブラウザ/版>  camera = <機種/OS/ブラウザ/版>
+搬送機: <スマートフォン機種/OS/カメラアプリ>
+ICEモード: lan | stun
+ネットワーク: 同一LAN / 別セグメント / その他
+Offer: part数 =   / QR version =   / ECC =   / 表示面 = プロジェクタ(投影サイズ, 距離, 照度)
+Answer: part数 =   / QR version =   / ECC =   / 表示面 = 端末画面(輝度)
+読取り: cameraの読取り所要 =   秒 / hubの読取り所要 =   秒 / 再撮影回数 =
+結果: 接続成立 = yes|no  / connectionState =  / 疎通確認(送受信) = yes|no
+エラー: code =  / 状況 =
+備考:
+```
+
+## 5. 自動化しない／できないもの
+
+- プロジェクタ投影の実読取り、スマートフォンでの撮影・搬送。
+- 実ネットワークでのICE成否（NFR-2）。
+- 端末カメラの露出・フォーカス条件によるデコード成功率。
+
+これらは実機記録でのみ担保し、CIの通過をもって「実機で動く」とは主張しない。

package/docs/index.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>TurboWarp-WebRTC-QRCode-Pairing</title>
+</head>
+<body>
+  <h1>TurboWarp-WebRTC-QRCode-Pairing</h1>
+  <p>A TurboWarp extension that pairs WebRTC peers by carrying the offer and the answer optically, as QR codes.</p>
+  <h2>How the workflow runs</h2>
+  <ol>
+    <li>The integration machine creates an offer and projects its QR parts.</li>
+    <li>A camera machine scans the parts, accepts the offer, and shows the answer QR parts on its screen.</li>
+    <li>An operator photographs every answer part with a smartphone and carries the images back.</li>
+    <li>The integration machine scans those images, accepts the answer, and reports the connection.</li>
+  </ol>
+  <p>No signaling server and no app on the smartphone: showing the photographed image is enough.</p>
+  <h2>Before you start</h2>
+  <ul>
+    <li>Load <code>turbowarp-webrtc</code>, <code>turbowarp-jsqr</code> and <code>turbowarp-camera-source</code> first.</li>
+    <li>Run the extension unsandboxed.</li>
+    <li>Turn on the pairing blocks at startup with <code>globalThis.__TWQP_FEATURE_FLAGS__ = {qrCodePairing: true};</code></li>
+  </ul>
+  <p>A projected pairing code is visible to everyone who can see the projection. The QR hash detects damage; it does not authenticate the other machine.</p>
+  <h2>Documentation</h2>
+  <ul>
+    <li><a href="integration-guide.md">Integration guide</a> (<a href="integration-guide.ja.md">日本語</a>) &mdash; setup, block sequences for both machines, projection and scanning, error codes, hardware test record</li>
+    <li><a href="migration.md">Migration and rollback</a> (<a href="migration.ja.md">日本語</a>) &mdash; coming from turbowarp-realtime-motion-capture, returning to manual pairing, regression checks</li>
+    <li><a href="architecture.md">Architecture</a> (<a href="architecture.ja.md">日本語</a>) &mdash; runtime structure, build outputs, extension API manifest</li>
+    <li><a href="https://github.com/kubohiroya/turbowarp-webrtc-qrcode-pairing#readme">Repository documentation and block reference</a></li>
+  </ul>
+</body>
+</html>

package/docs/initialization-issue.ja.md

@@ -0,0 +1,34 @@
+# chore(scaffold): QR搬送によるWebRTCペアリング拡張の初期化
+
+GitHub Issue用の未投稿草案。今回の依頼はローカル初期化であり、外部への投稿は含まない。
+
+## Doing / ToDo / Done
+
+- Doing: なし。
+- ToDo: GitHubへのタスク記録と公開操作は別途の指示を受けて行う。
+- Done: 専用metadata、ソース、検証環境、README、生成物の整備と全チェック。
+
+## ブランチと依存
+
+- ブランチ: `chore/scaffold/qrcode-pairing-initialization`
+- 依存: `turbowarp-extension-template` 0.4.0。QRコード搬送の実装移設は本タスクの後続。
+- 将来の依存: webrtcのOffer／Answer能力、jsqrの読取り、camera-sourceのフレーム取得。
+- 本タスクは初期構成のみ。実際のペアリングと他リポジトリの修正は含まない。
+
+## 受け入れ基準
+
+- [x] 専用package名・拡張ID・クラス名・リポジトリURLを設定する。
+- [x] 日本語／英語READMEに未実装の状態、目的、責務分担、移設元を記載する。
+- [x] 型検査、lint、既存テスト、README生成検証、ビルド再現性、repo検査、pack dry-runが通る。
+- [x] 生成JavaScriptとmanifestを配置する。
+
+## フラグとロールバック
+
+初期版にはペアリングの実行経路がなく、フィーチャーフラグは不要。移設時は既存経路を維持し、新経路を既定OFFで段階導入する。初期化のロールバックは、この変更で追加したファイルだけを取り除く。既存の`.git`は保持する。
+
+## 運用ログ
+
+- start: 2026-09-15 ローカル初期化に着手。
+- blocked: 初回checkのdist検査が未追跡ファイルを不一致と判定。初期リポジトリでも機能する内容比較方式へ調整。README検査もGitの追跡状態に依存しない比較へ変更。
+- blocked: README検査の.ts動的importが型検査に非対応。Node子プロセスで生成スクリプトを実行する方式へ修正。
+- done: 2026-09-15 pnpm run check成功。型検査、lint、7テスト、README検査、ビルド再現性、repo検査、pack dry-runを確認。

package/docs/integration-guide.ja.md

@@ -0,0 +1,245 @@
+# 利用ガイド
+
+[English](integration-guide.md)
+
+TurboWarpのプロジェクトから本拡張で2台の端末をペアリングする手順です。ブロック単位の一覧は
+[Block reference](../README.md#block-reference)を参照してください。
+
+## 1. 準備
+
+次の拡張を本拡張より**先に**読み込み、すべてunsandboxedで動かします。
+
+| 拡張 | 役割 |
+|---|---|
+| `turbowarp-webrtc` | Offer／Answerの生成と受理、接続の保持 |
+| `turbowarp-jsqr` | カメラフレームからのQRデコード |
+| `turbowarp-camera-source` | カメラの取得とフレームの提供 |
+
+`turbowarp-webrtc`はruntime capability **v3**を公開している必要があります。0.4.0以降が該当します。
+0.3.0以前はv2までで、`createOffer`と`getOffer`はありますが`acceptOffer`、`getAnswer`、
+`acceptAnswer`、`connectionState`が無いため往復を完結できません。古い版では
+`webrtc-capability-missing`になります。
+
+ペアリング用ブロックは、拡張の読込み前に起動時フラグで有効にします。
+
+```js
+globalThis.__TWQP_FEATURE_FLAGS__ = {qrCodePairing: true};
+```
+
+無効の間はブロックが現れず、`pairing phase of [SESSION]`は`disabled`を返します。
+
+フラグはバンドルの評価時に一度だけ読まれるため、後から設定しても効きません。設定済みの
+1ファイルを得るには、リポジトリの補助スクリプトを使います。
+
+```bash
+pnpm run build:flagged      # 例: pnpm run build:flagged Q
+```
+
+`local/webrtc-qrcode-pairing.flagged.js`を書き出し、カスタム拡張として読み込む`file://`のURLを
+表示します。引数で誤り訂正レベルを固定できます。このファイルは作業コピー内のみで公開されません。
+既定でブロックが出ないことの確認は、代わりに`dist/webrtc-qrcode-pairing.js`を読み込んで行います。
+
+## 2. 役割と名前
+
+一方が**統合側（hub）**で、Offerを作って投影し、Answerを読み取ります。もう一方が
+**カメラ側端末**で、Offerを読み取ってAnswerを表示します。
+
+名前は各端末が自分で決めます。**両端で一致している必要はありません。**
+
+- hubは自分を`studio`、カメラ側を`cam-A`と呼ぶ。
+- カメラ側はOfferから両方の名前を受け取り、接続を`studio`というキーで登録し、`cam-A`として応答する。
+
+つまりhubの`remote peer`がカメラ側の`local peer`であり、その逆も同様です。名前は画面を見る人に
+とって意味があれば十分です。
+
+カメラ側の`LOCAL_PEER`を空にすると、Offerが割り当てた名前をそのまま採用します。名前を指定すると
+それを要求し、別の端末宛のOfferは`peer-mismatch`で拒否されます。担当者が誤った投影を読み取った
+場合の検出に使えます。
+
+## 3. hub側のスクリプト
+
+```
+緑の旗が押されたとき
+  start offer pairing [pairing-1] as [studio] to [cam-A]
+  set pairing timeout of [pairing-1] to (600) seconds
+  show pairing QR part (1) of [pairing-1] on this sprite
+```
+
+期限の設定はsessionを開いた後に置きます。2つの`start`ブロック以外はすべて
+開いているsessionを必要とし、無い場合は`no-session`になります。期限はsessionを
+開いた時点からの経過で測るため、直後に設定しても失うものはありません。
+
+`start offer pairing`はOfferが生成されQR partの準備が終わると戻り、phaseは`offer-ready`になります。
+Offer生成はICE収集の完了を待つため、少し時間がかかります。
+
+partを投影してカメラ側に読み取らせ、担当者がAnswerを運んできたら次を実行します。
+
+```
+scan pairing QR for [pairing-1] from camera [default]
+wait until pairing [pairing-1] is connected
+end pairing QR display of [pairing-1]
+```
+
+`scan pairing QR`はAnswerの全partが揃い検証を通った時点で戻ります。phaseは`answer-received`から
+`connecting`へ進みます。`wait until ... is connected`はWebRTCが接続を報告すると戻り、取消・期限
+切れ・失敗のときは失敗します。
+
+## 4. カメラ側のスクリプト
+
+```
+緑の旗が押されたとき
+  start answer pairing [pairing-1] as []
+  set pairing timeout of [pairing-1] to (600) seconds
+  scan pairing QR for [pairing-1] from camera [default]
+  show pairing QR part (1) of [pairing-1] on this sprite
+  wait until pairing [pairing-1] is connected
+  end pairing QR display of [pairing-1]
+```
+
+Offerが揃うと拡張が自動でOfferを受理しAnswerを準備するので、phaseは`receiving`→`offer-received`
+→`creating-answer`→`answer-ready`とブロックを追加せずに進みます。
+
+## 5. 撮影しやすいpartの見せ方
+
+接続情報が長いとQRは複数枚になります。自動で巡回させず、**1枚ずつ表示して担当者が送る**形にして
+ください。投影を撮影する人は、各partが静止している必要があります。
+
+```
+show pairing QR part (1) of [pairing-1] on this sprite
+say (join (join (current pairing QR part of [pairing-1]) " / ") (pairing QR part count of [pairing-1]))
+
+[スペース] キーが押されたとき
+  show next pairing QR part of [pairing-1] on this sprite
+```
+
+実務上の注意です。
+
+- 「2 / 3」のようにpart番号と総数を出すと、担当者が残りを把握できます。
+- スプライトの元のコスチュームは保持されます。`end pairing QR display`のほか、取消、期限切れ、
+  停止ボタン、スプライトの削除でも元に戻ります。
+- 投影ではスプライトを大きく正方形に保ち、コード周囲の白い余白を削らないでください。余白も
+  シンボルの一部です。
+- 誤り訂正レベルを上げると光学条件に強くなりますが、1枚あたりの文字数が減るためpart数が増え、
+  運ぶ手間も増えます。既定は`M`です。読取りが不安定なら起動時に`Q`や`H`を指定します。
+  `globalThis.__TWQP_QR_CONFIG__ = {errorCorrectionLevel: 'Q'};`
+- スプライトのskinではなく自前で描画する場合は、
+  `pairing QR part [INDEX] of [SESSION] as data URI`または`... as SVG`を読みます。この経路は
+  rendererが無くても動きます。
+
+## 6. partの読取り
+
+`scan pairing QR for [SESSION] from camera [CAMERA_ID]`はsessionの間1つのcamera leaseを保持し、
+全partが揃うまで読み続けます。同じpartを何度も読むのは正常で、害はありません。ポスターや別の
+session、前回の試行など、自分のものではないQRは黙って読み飛ばします。
+
+実行中は進捗を表示できます。
+
+```
+say (join (join (received parts of [pairing-1]) " / ") (required parts of [pairing-1]))
+say (join "未取得: " (missing parts of [pairing-1]))
+```
+
+part数はpartの中に入っているため、`required parts`は最初のpartが届くまで0です。
+
+QRの文字列を別の方法で得ている場合は、`receive pairing QR text [TEXT] for [SESSION]`で直接
+投入できます。こちらが正規の入口で、カメラ走査はその上に作られています。
+
+## 7. 進捗の観測
+
+`pairing phase of [SESSION]`が交換の位置を返します。
+
+| phase | 意味 |
+|---|---|
+| `disabled` | フィーチャーフラグが無効 |
+| `idle` | その名前のsessionが無い |
+| `creating-offer` | hub: WebRTCのOffer生成待ち |
+| `offer-ready` | hub: Offer QRの投影準備ができた |
+| `awaiting-answer` | hub: Answerのpartを部分受信中 |
+| `answer-received` | hub: Answerが検証を通った |
+| `awaiting-offer` | camera: 最初のOffer partを待っている |
+| `receiving` | camera: Offerのpartを部分受信中 |
+| `offer-received` | camera: Offerが検証を通った |
+| `creating-answer` | camera: WebRTCのAnswer生成待ち |
+| `answer-ready` | camera: Answer QRの表示準備ができた |
+| `connecting` | 接続情報をWebRTCへ渡した。接続はまだ |
+| `connected` | WebRTCが接続成立を報告した |
+| `cancelled` / `expired` / `failed` | 交換が終了した |
+
+**運べたことと繋がったことは別です。** `answer-received`と`offer-received`は光学搬送が成功した
+ことを意味し、`connected`はネットワーク経路が通ったことを意味します。接続情報が完全に届いても
+接続が失敗することはあります。到達性はQRではなくネットワークの条件で決まります。
+
+## 8. カメラ側端末が2台以上のとき
+
+session名と相手の呼称を分けて、1台ずつ順に接続します。
+
+```
+start offer pairing [pairing-A] as [studio] to [cam-A]
+...
+start offer pairing [pairing-B] as [studio] to [cam-B]
+```
+
+`cam-B`のAnswerを`pairing-A`へ投入すると拒否されます。各Answerはsessionと応答対象のOfferを
+持っているため、接続が入れ替わることはありません。`pairing sessions`で開いているsession名を
+確認できます。
+
+## 9. 期限、取消、再試行
+
+- `set pairing timeout of [SESSION] to [SECONDS] seconds` — 1〜3600秒、既定600秒。期限は
+  **その端末自身の時計**で測るため、2台の時刻同期は不要です。`remaining seconds of [SESSION]`で
+  残りを表示できます。
+- `cancel pairing [SESSION]` — 表示を戻し、カメラと受信バッファを解放し、**まだ接続していない**
+  場合はpeer接続を閉じます。成立済みの接続はそのままです。
+- `retry pairing [SESSION]` — 取消して新しい交換を始めます。新しい交換は別のIDを持つため、前回の
+  試行で撮影したQRは適用されずに拒否されます。
+
+停止ボタンは表示とカメラを解放し、進行中の交換を取り消します。成立済みの接続は切断しません。
+
+## 10. うまくいかないとき
+
+`pairing error code of [SESSION]`が安定したコードを、`pairing error message of [SESSION]`が
+担当者向けの文を返します。どちらにも接続情報そのものは含まれません。
+
+| コード | 状況 | 対処 |
+|---|---|---|
+| `feature-disabled` | 起動時フラグが無効 | 読込み前に`__TWQP_FEATURE_FLAGS__`を設定する |
+| `webrtc-capability-missing` | `turbowarp-webrtc`が無いかv3未満 | 先に読み込む。capability v3が必要 |
+| `qr-decoder-missing` / `camera-unavailable` | `turbowarp-jsqr`か`turbowarp-camera-source`が無い、またはカメラ取得に失敗 | 先に読み込む。カメラの許可を確認する |
+| `renderer-unavailable` | スプライトに一時skinを設定できない | ステージやクローンではなく通常のスプライトを使う。またはSVGを自分で表示する |
+| `unsupported-protocol` | `twqr/1`ではないQR | 旧`twmp-qr/1`か、別製品のQR |
+| `hash-mismatch` / `length-mismatch` | partは揃ったが内容が壊れている | 全partを読み直す。誤り訂正レベルを上げる |
+| `conflicting-part` | 同じpart番号が別内容で届いた | 異なる交換が混ざっている。やり直す |
+| `missing-parts` | 全partが揃っていない | `missing parts of [SESSION]`で不足を確認する |
+| `peer-mismatch` | 別の端末同士を指すQR | 誤った投影を読み取っている |
+| `reply-mismatch` / `stale-exchange` | 別のOfferへの応答、または前回の試行のQR | 現在のQRを撮り直す |
+| `already-accepted` | この交換はすでにWebRTCへ渡している | 対処不要 |
+| `timeout` | 期限が過ぎた | `retry pairing`する |
+| `webrtc-rejected` | WebRTCが受理を拒否、または接続が失敗 | 搬送ではなくネットワークの問題 |
+| `session-exists` / `session-limit` / `no-session` | 同名が開いている、開きすぎ、開いていない | sessionを閉じるか、名前を確認する |
+
+## 11. 本拡張が担当しないこと
+
+- **認証ではありません。** ハッシュは破損の検出用です。QRを撮影できる人は同じ値を計算でき、
+  投影を見られる人は接続情報を読めます。投影の可視範囲は運用で管理してください。
+- **到達性は保証しません。** ICE、STUN、TURNは`turbowarp-webrtc`の責務です。
+- **映像は運びません。** カメラのデータは接続成立後にWebRTCで送ります。
+- **画面構成は行いません。** 担当者への案内、投影レイアウト、接続後の処理は利用アプリの責務です。
+
+## 12. 実機検証の記録
+
+光学条件はCIで確認できません。試行ごとに記録し、未検証の条件を検証済みとして扱わないでください。
+
+```
+日時:
+hub端末: <機種 / OS / ブラウザと版>
+カメラ側端末: <機種 / OS / ブラウザと版>
+搬送機: <スマートフォン機種 / OS / カメラアプリ>
+ICEモード: lan | stun
+ネットワーク: 同一LAN / 別セグメント / その他
+Offer: part数 =   / QR version =   / 誤り訂正 =   / プロジェクタ（投影サイズ, 距離, 照度）
+Answer: part数 =   / QR version =   / 誤り訂正 =   / 画面輝度
+読取り: カメラ側   秒 / hub側   秒 / 撮り直し回数 =
+結果: 接続成立 = yes|no / connection state =   / テストメッセージ送受信 = yes|no
+エラー: code =   / 状況 =
+備考:
+```