@kubohiroya/turbowarp-webrtc-qrcode-pairing 0.1.0

package/docs/architecture.ja.md

@@ -0,0 +1,57 @@
+# アーキテクチャ
+
+[English](architecture.md)
+
+使い方: [利用ガイド](integration-guide.ja.md) · [移行と切戻し](migration.ja.md)。
+設計の記録: [docs/design/qr-pairing](design/qr-pairing/README.md)。
+
+## 実行時の構造
+
+```text
+extension.ts        ブロックのファサード。引数のCastと委譲、runtimeリスナの保持
+  pairing/          sessionの状態機械。phase、epoch、期限、資源解放
+    qr/             純粋な搬送処理。envelope、分割、再構成、検証、SVG生成
+    ports/          アダプタ。WebRTC能力、カメラ走査、スプライトのskin
+  errors.ts         搬送層とドメイン層が共有するエラーコード
+```
+
+`qr/`は`qrcode`と`errors.ts`以外に依存しません。DOM、Scratch、WebRTCへの依存が無いため、
+搬送処理はruntimeなしで、かつフィーチャーフラグと独立して検証できます。`pairing/`は外部へ
+portのinterface経由でのみ到達します。`turbowarp-webrtc`のcapability v3が未公開の間も、
+フェイクを注入して往復をテストできるのはこのためです。
+
+併用拡張は読込み時ではなく呼び出し時に解決します。不在の場合は、読込みの失敗ではなく、それを
+必要としたブロックのエラーコードとして現れます。
+
+## ビルド出力
+
+このプロジェクトは実行時の動作と互換性メタデータを分離し、リポジトリに保存された同じソース定義から両方を生成します。
+
+```text
+src/index.ts + src/extension.ts
+  -> vite-plugin-turbowarp-extension
+  -> dist/<extension>.js
+
+src/config.ts + src/block-definitions.json
+  -> extension-api-manifest Viteプラグイン
+  -> dist/extension-manifest.json
+```
+
+manifestプラグインはViteのビルド後フェーズで実行されます。これにより、JavaScriptプラグインの単一出力検証を維持しながら、TurboWarpバンドルの完成後にだけmanifestを追加します。
+
+## 拡張機能API manifest v1
+
+`schemas/extension-manifest.schema.json`が規範となるJSON Schemaです。`formatVersion`は`1`で、互換性のないmanifest形式を導入するときに変更する必要があります。
+
+v1契約は次の情報を含みます。
+
+- TurboWarp拡張機能のID
+- 各ブロックのopcodeとブロック種類
+- 各引数のID、引数種類、任意のメニュー参照
+- 各メニューのIDとReporterブロックを受け付けるかどうか
+
+ブロック、引数、メニューは、シリアライズ前に識別子で並べ替えられます。テキスト、説明、既定値、静的メニュー項目は、保存済みプロジェクトのAPI参照を識別しないため、意図的に除外しています。そのため互換性チェッカーは、API変更とドキュメントまたはローカライズの変更を区別できます。
+
+## 差分の検出
+
+`dist/`はリリース成果物としてコミットされます。`npm run check:dist`は両方のファイルを再ビルドし、`dist/`配下に変更、削除、未追跡ファイルがある場合に失敗します。これにより、ローカル検証とCIの両方でmanifestとバンドルの差分を検出できます。

package/docs/architecture.md

@@ -0,0 +1,65 @@
+# Architecture
+
+[日本語](architecture.ja.md)
+
+Using the extension: [Integration guide](integration-guide.md) ·
+[Migration and rollback](migration.md). Design records: [docs/design/qr-pairing](design/qr-pairing/README.md).
+
+## Runtime structure
+
+```text
+extension.ts        block facade: casts arguments, delegates, owns runtime listeners
+  pairing/          session state machine: phases, epochs, deadlines, resource release
+    qr/             pure transport: envelope, splitting, reassembly, verification, SVG
+    ports/          adapters: WebRTC capability, camera scanning, sprite skins
+  errors.ts         error codes shared by the transport and the domain
+```
+
+`qr/` depends on nothing but `qrcode` and `errors.ts`: it has no DOM, Scratch, or WebRTC
+dependency, so the transport can be tested without a runtime and independently of the feature flag.
+`pairing/` reaches the outside world only through the port interfaces, which is what lets the round
+trip be tested with a fake WebRTC capability while `turbowarp-webrtc` capability v3 is unpublished.
+
+Companion extensions are resolved at call time, never at load time: a missing one becomes a specific
+error code on the block that needed it, rather than a failure to load.
+
+## Build outputs
+
+The project keeps runtime behavior and compatibility metadata separate while generating both from
+the same checked-in source definitions.
+
+```text
+src/index.ts + src/extension.ts
+  -> vite-plugin-turbowarp-extension
+  -> dist/<extension>.js
+
+src/config.ts + src/block-definitions.json
+  -> extension-api-manifest Vite plugin
+  -> dist/extension-manifest.json
+```
+
+The manifest plugin runs in Vite's post-build phase. This preserves the JavaScript plugin's
+single-output validation and adds the manifest only after the TurboWarp bundle is complete.
+
+## Extension API manifest v1
+
+`schemas/extension-manifest.schema.json` is the normative JSON Schema. `formatVersion` is `1` and
+must change when an incompatible manifest shape is introduced.
+
+The v1 contract contains:
+
+- the TurboWarp extension ID;
+- each block opcode and block type;
+- each argument ID, argument type, and optional menu reference;
+- each menu ID and whether it accepts reporter blocks.
+
+Blocks, arguments, and menus are sorted by their identifiers before serialization. Text,
+descriptions, default values, and static menu items are intentionally excluded because they do not
+identify saved-project API references. A compatibility checker can therefore distinguish API
+changes from documentation or localization changes.
+
+## Drift detection
+
+`dist/` is committed as a release artifact. `npm run check:dist` rebuilds both files and fails when
+Git reports any modified, deleted, or untracked file below `dist/`. This catches manifest and bundle
+drift in local checks and CI.

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

@@ -0,0 +1,16 @@
+# QR搬送WebRTCペアリング 設計文書
+
+出典: [Issue #1](https://github.com/kubohiroya/turbowarp-webrtc-qrcode-pairing/issues/1)
+
+| 文書 | 内容 |
+|---|---|
+| [requirements.md](requirements.md) | Issue #1の要求仕様の整理（FR/NFR/DoD）と、設計時に判明した制約 |
+| [architecture.md](architecture.md) | モジュール構成、外部依存の契約、peer対応、期限、ライフサイクル、フラグ |
+| [dataflow.md](dataflow.md) | 往復シーケンス、ロール別状態遷移、part受理の判定フロー |
+| [interfaces.ts](interfaces.ts) | 型契約（搬送形式 `twqr/1`、port、状態、エラーコード、上限定数） |
+| [block-api.md](block-api.md) | 公開ブロック契約（26 opcode）とmanifest反映、形式互換性 |
+| [extraction-plan.md](extraction-plan.md) | `turbowarp-realtime-motion-capture`からの移設選別表とPR分割 |
+| [test-plan.md](test-plan.md) | DoDとテストの対応、重点ケース、実機記録テンプレート |
+
+本文書群は`kairo-design`の構成に準拠しつつ、TurboWarp拡張という対象に合わせて
+`database-schema.sql`を省略し、`api-endpoints.md`を`block-api.md`（ブロック契約）に置き換えている。

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

@@ -0,0 +1,191 @@
+# QR搬送WebRTCペアリング アーキテクチャ設計
+
+対応要求: [requirements.md](requirements.md) / 元Issue: #1
+
+## 1. システム概要
+
+本拡張は「接続情報を光学的に運ぶ運び屋」に徹する。SDPの中身を解釈せず、WebRTCの接続確立そのものも行わない。
+`turbowarp-webrtc`が生成した不透明な文字列（pairing code）を、QRに載る大きさへ分割し、表示・読取り・再構成・検証して、
+正しい相手・正しい交換に対して一度だけ`turbowarp-webrtc`へ返す。
+
+```
+[hub端末]                                   [camera端末]
+turbowarp-webrtc ──createOffer──▶ offer code
+        │                             │
+        │                     本拡張: 分割・QR化・表示
+        │                             │  (プロジェクタ投影)
+        │                             ▼   ~~~ 光学搬送 ~~~
+        │                     本拡張: 読取り・再構成・検証 ◀── jsqr + camera-source
+        │                             │
+        │                     turbowarp-webrtc ──acceptOffer──▶ answer code
+        │                             │
+        │                     本拡張: 分割・QR化・表示（画面）
+        │                             ▼   ~~~ スマートフォン撮影による搬送 ~~~
+本拡張: 読取り・再構成・検証 ◀── jsqr + camera-source
+        │
+turbowarp-webrtc ──acceptAnswer──▶ 接続成立
+```
+
+## 2. アーキテクチャパターン
+
+- パターン: **ヘキサゴナル（ports and adapters）＋ロール別ステートマシン**
+- 理由:
+  - courier（形式・分割・検証）はDOM・Scratch・WebRTCに依存しない純粋関数群にできる。NFR-4（フラグと独立した単体検証）を満たす。
+  - WebRTC／QRデコード／カメラ／レンダラは、いずれも他拡張のruntime capabilityという外部依存。portで抽象化すれば、依存が無い環境でもテストでき、依存不足を明示的なエラーとして扱える。
+  - 往復・多重session・取消／再試行・期限は状態遷移として定義しないとFR-4を満たせない。
+
+## 3. レイヤとモジュール
+
+```
+src/
+  index.ts                     登録エントリ（既存）
+  config.ts                    拡張ID・名前・アイコン（既存）
+  block-definitions.json       ブロック定義（置換）
+  extension.ts                 ブロックのファサード。引数のCast・翻訳・委譲のみ
+  globals.d.ts                 Scratch/runtime/renderer型（motion-captureから統合）
+  errors.ts                    PairingErrorCode と QrPairingError（依存なしの葉モジュール）
+  clock.ts                     単調時計（performance.now系）
+
+  config/
+    feature-flags.ts           起動時固定フラグ qrCodePairing（既定OFF）
+    qr-config.ts               errorCorrectionLevel など起動時固定設定
+
+  qr/                          ── 純粋層（DOM・Scratch非依存） ──
+    limits.ts                  上限定数と単位・境界条件
+    hash.ts                    SHA-256 base64url（破損検出用）
+    envelope.ts                envelope v1 (twqr/1) の型・serialize・parse・検証
+    courier.ts                 分割（createParts）と再構成（PartAssembler）
+    svg.ts                     QRのSVG生成（表示層が使う純粋関数）
+
+  pairing/                     ── ドメイン層 ──
+    limits.ts                  session上限・期限既定値・tick間隔
+    types.ts                   PairingRole / PairingPhase / PairingProgress / session状態の形
+    controller.ts              session集合の管理、状態遷移、往復手順の進行、資源解放
+
+  ports/                       ── アダプタ層 ──
+    webrtc.ts                  runtime capability v3 の取得と適合検査
+    qr-scan.ts                 jsqr(scanFrame) + camera-source(lease) の取得と走査ループ
+    display.ts                 TemporarySpriteSkinManager（skin退避・復元）
+```
+
+依存方向は `extension.ts → pairing/ → qr/` と `pairing/ → ports/`（interfaceのみ）。
+`qr/`は`pairing/`・`ports/`を参照しない。エラー型は両層が使うため、依存を持たない葉モジュール
+`src/errors.ts`に置き、`qr/`と`pairing/`の双方がそこだけを参照する。
+
+## 4. 外部依存と契約
+
+| 依存 | 取得方法 | 本拡張が使う操作 | 不在時の扱い |
+|---|---|---|---|
+| `turbowarp-webrtc` | `runtime.kubohiroyaWebRtcCapability`、`requireVersion(3)` | `createOffer` / `getOffer` / `acceptOffer` / `getAnswer` / `acceptAnswer` / `connectionState` / `closePeer` | `webrtc-capability-missing` で失敗。部分機能での縮退はしない |
+| `turbowarp-jsqr` | `runtime.ext_kubohiroyajsqr` | `scanFrame(frameSource)` | カメラ走査ブロックのみ`qr-decoder-missing`。テキスト投入経路は動作する |
+| `turbowarp-camera-source` | `runtime.ext_kubohiroyacamerasource` | `acquireCamera({owner, cameraId})` → `lease.getFrameSource()` / `lease.release()` | 同上（`camera-unavailable`） |
+| TurboWarp renderer | `runtime.renderer` | `createSVGSkin` / `updateDrawableSkinId` / `destroySkin` | スプライト表示ブロックのみ`renderer-unavailable`。SVG取得ブロックは動作する |
+
+> **前提作業（ブロッカー）**: `turbowarp-webrtc`のruntime capabilityは現在v2で、`createOffer`／`getOffer`しか公開していない。
+> `acceptOffer`／`getAnswer`／`acceptAnswer`／`connectionState`／`closePeer`は`PeerSessionPort`には存在するがブロック経由でしか呼べない。
+> 本拡張のFR-1（対称な搬送）はこれらを必要とするため、**`turbowarp-webrtc`側にcapability v3を追加するPRが先行して必要**。
+> 詳細は [extraction-plan.md](extraction-plan.md) の「前提となる他リポジトリの変更」。
+
+## 5. peer識別子の対応（FR-1.3）
+
+`turbowarp-webrtc`のpeer名は各端末ローカルのキーでしかなく、両端で一致している必要はない。
+本拡張はこれを利用し、**envelopeに送信側の自称と受信側への呼称の両方を載せる**ことで対応関係を明示する。
+
+| 端末 | 自分の呼称 `localPeerId` | 相手の呼称 `remotePeerId` | WebRTCに渡すpeerキー |
+|---|---|---|---|
+| hub | `hub`（アプリが指定） | `camera-1`（アプリが指定） | `camera-1` |
+| camera | `camera-1`（Offerの`targetPeerId`から受領） | `hub`（Offerの`senderPeerId`） | `hub` |
+
+- Offer envelope: `senderPeerId = "hub"`, `targetPeerId = "camera-1"`
+- Answer envelope: `senderPeerId = "camera-1"`, `targetPeerId = "hub"`, `replyTo = <Offerのmessage ID>`
+- camera側は`startAnswerPairing`で期待する自称を任意指定できる。空なら`targetPeerId`をそのまま採用し、
+  非空で不一致なら`peer-mismatch`で拒否する（誤った投影を読んだ場合の検出）。
+- hub側はAnswerの`senderPeerId`／`targetPeerId`が自分のsessionの`remotePeerId`／`localPeerId`と一致することを検証する。
+
+これにより「両端で同じ識別子が設定されていること」を要求せず、かつ2台以上のcameraを順に接続しても
+Answerが別peerへ適用されない（DoD 6）。
+
+## 6. 交換の同一性と鮮度（FR-1.4 / FR-4.4 / FR-4.5）
+
+3層で守る。
+
+1. **exchangeId（＝`sessionId`）**: hubがOffer生成時にUUIDで採番。Answerは同じ`sessionId`を反映する。
+   再試行では必ず新しい`sessionId`になるので、古いQRは`unknown-session`／`stale-exchange`で弾かれる。
+2. **`replyTo`**: Answerが応答するOfferの`messageId`。hubのsessionが保持する`messageId`と一致しなければ拒否。
+3. **epoch（世代番号）**: sessionごとの単調増加カウンタ。`await`から復帰した非同期処理は、
+   再開時に`session.epoch`が自分の取得時と同じかを確認し、異なれば結果を捨てる（motion-capture `this.operation`の一般化）。
+   取消・再試行・期限切れ・破棄はいずれもepochを進める。
+
+`messageId`は既存実装と同じく`<sessionId>.<messageHash先頭12文字>`で、内容が変われば必ず変わる。
+
+## 7. 期限（FR-4.6）
+
+- 期限は**単調時計**（`performance.now()`、無ければ`Date.now()`のフォールバックを明示）で、
+  session開始時刻からの経過で判定する。envelopeの`createdAt`は診断・表示用であり期限判定には使わない。
+  これにより未同期端末間の壁時計差に依存しない。
+- 既定値: 600秒（人手搬送を想定）。`setPairingTimeout`で1〜3600秒に設定可能。
+- 期限到来時は`expired`へ遷移し、表示・lease・タイマを解放する。**成立済み接続は切断しない**（NFR-6と同じ方針）。
+  未成立のRTCPeerConnectionのみ`closePeer`する。
+
+## 8. 状態と資源のライフサイクル（FR-4.8）
+
+| イベント | 動作 |
+|---|---|
+| `cancelPairing` | epoch++、表示復元、lease解放、タイマ停止、受信バッファ破棄、未成立ならclosePeer、phase=`cancelled` |
+| `retryPairing` | cancel相当の後、新`sessionId`で同じロールの交換を開始 |
+| `PROJECT_RUN_STOP` | 表示復元とlease解放（進行中sessionは`cancelled`）。成立済み接続は維持 |
+| `PROJECT_STOP_ALL` | 同上。停止ボタンでは成立済み接続を切断しない。FR-4.8の「切断は所有関係と明示操作に従う」に従い、sessionも保持する |
+| `PROJECT_LOADED` | 全sessionを破棄し、未成立・成立済みを問わずpeerを閉じる。旧プロジェクトのsessionは新しいプロジェクトから到達できないため。**runtimeリスナは維持する**（拡張インスタンスは読込みをまたいで生き残り、以降の停止やスプライト削除に反応し続ける必要がある） |
+| `targetWasRemoved` | そのスプライトへの表示のみ終了 |
+| `RUNTIME_DISPOSED` | 全解放＋runtimeリスナ解除 |
+
+共有カメラのleaseは本拡張が取得したものだけを解放する（camera-sourceは参照カウント方式なので、
+アプリ側が別途leaseを持っていればカメラは止まらない、FR-3.4）。
+
+## 9. 表示（FR-3.5）
+
+- `TemporarySpriteSkinManager`（motion-captureから移設）でスプライトの元skin IDを退避し、
+  表示終了・取消・停止・スプライト削除時に復元、一時skinは破棄する。
+- 併せて`pairingQrPartSvg`／`pairingQrPartDataUri`リポーターを提供し、
+  アプリが独自にHTML／コスチューム等で表示する経路を塞がない。
+- 静止画撮影での確実な取得のため、自動アニメーションは行わず**手動切替**を基本とする（FR-3.2）。
+  現在part番号・総part数をリポーターで提供し、アプリが「1/3」などの案内を出せるようにする。
+
+## 10. 読取り（FR-3.3）
+
+- 正規の入口は`ingestPairingQrText(TEXT, SESSION)`。デコード済み文字列を受け取るだけで、画像処理はしない。
+- 利便のため`scanPairingQrFromCamera(SESSION, CAMERA_ID)`を提供するが、実装は
+  `camera-source`から**session中1つだけ**leaseを取得し、`jsqr.scanFrame(frameSource)`を間隔ポーリングで呼ぶ。
+  jsqrの`waitForQrText`はpartごとにlease取得・解放を繰り返すため使わない（[requirements.md](requirements.md) C-4）。
+- 走査は`AbortController`で中断可能。取消・期限・全part受信で停止する。
+- 同一partの重複読取りは正常系として黙って無視する（カメラは同じQRを何度も読む）。
+
+## 11. フィーチャーフラグとロールバック（NFR-3/5/6）
+
+```ts
+// src/config/feature-flags.ts
+(globalThis as FeatureFlagGlobal).__TWQP_FEATURE_FLAGS__?.qrCodePairing === true
+```
+
+- 起動時に1回だけ読み、以後変化しない（`Object.freeze`）。既定OFF。
+- OFF時: `getInfo()`はペアリングブロックを返さない。直接呼ばれた場合は`feature-disabled`で失敗し、
+  `pairingPhase`は`disabled`を返す。
+- OFF化は経路選択の切戻しであり、成立済み接続を切断しない。
+- 切戻し手順: フラグをOFF（または設定しない）にし、アプリは`turbowarp-webrtc`の
+  `create offer code` / `accept offer code` / `answer code` / `accept answer code` ブロックによる
+  従来のmanual交換に戻す。motion-capture側の既存QR経路は本Issueでは削除しない。
+- `qr/`配下の純粋処理はフラグを参照しないので、単体テストはフラグと独立に動く。
+
+## 12. 診断とプライバシー（FR-4.9）
+
+- 既定でSDP・ICE・pairing code・QR payloadを一切ログ出力しない。例外メッセージにも含めない
+  （courierのエラーは「長さ」「index」「code」のみを述べる）。
+- 診断用に公開するのは、phase、part進捗（received/required/missing）、エラーコード、
+  そしてサニタイズ済みエラーメッセージのみ。
+- 長さ・hash・peer IDは診断に出してよい情報として扱う（hashは破損検出用であり、本人性の保証ではない、FR-2.6）。
+
+## 13. 想定外として明示すること
+
+- QRを見た第三者は接続情報を取得できる。QR搬送は認証ではない。投影の可視範囲は運用で管理する（FR-2.6の帰結）。
+- `twqr/1`と`twmp-qr/1`は非互換。混在は`unsupported-protocol`で検出される（[block-api.md](block-api.md) 参照）。
+- 接続の成立可否はネットワーク条件次第であり、QR搬送の成功は接続成功を意味しない（NFR-2）。

package/docs/design/qr-pairing/block-api.md

@@ -0,0 +1,123 @@
+# 公開契約（ブロックAPI）と形式互換性
+
+対応要求: FR-4.3（opcodeと引数を確定しmanifestへ反映）/ FR-2.8（形式互換性）
+
+`kairo-design`標準の`api-endpoints.md`に相当する。本拡張の公開面はRESTではなくTurboWarpブロックなので、
+opcodeとその引数をAPI契約として定義する。
+
+## 0. 契約の生成経路
+
+`src/block-definitions.json` と `src/config.ts` から `dist/extension-manifest.json`（`formatVersion: 1`）が生成される。
+manifestはopcode・blockType・引数ID・引数型・menu参照のみを含み、テキストや説明は含まない
+（[docs/architecture.md](../../architecture.md)）。本設計の変更はmanifestの中身を全面的に差し替えるが、
+`formatVersion`は1のまま（manifest形式自体は変えない）。
+
+`hello`ブロックは削除する。初期scaffold専用の動作確認ブロックであり、保存済みプロジェクトからの参照はない。
+
+## 1. 共通引数
+
+| 引数ID | 型 | 既定値 | 意味 |
+|---|---|---|---|
+| `SESSION` | STRING | `pairing-1` | アプリが決めるsessionキー。同時に`MAX_ACTIVE_SESSIONS`(8)まで |
+| `LOCAL_PEER` | STRING | `hub` / 空 | 自分の呼称 |
+| `REMOTE_PEER` | STRING | `camera-1` | 相手の呼称 |
+| `INDEX` | NUMBER | `1` | 1始まりのpart番号 |
+| `TEXT` | STRING | 空 | デコード済みQR文字列 |
+| `CAMERA_ID` | STRING | `default` | camera-sourceのカメラID |
+| `SECONDS` | NUMBER | `600` | 期限（1〜3600） |
+
+## 2. hub（統合側）ブロック
+
+| opcode | 種類 | テキスト | 効果・戻り値 |
+|---|---|---|---|
+| `startOfferPairing` | COMMAND | `start offer pairing [SESSION] as [LOCAL_PEER] to [REMOTE_PEER]` | `createOffer`→分割→`offer-ready`。既存の同名sessionがあれば`session-exists` |
+| `acceptAnswerFromQr` | — | （明示ブロックなし） | 全part検証完了時に`ingestPairingQrText`／`scanPairingQrFromCamera`の内部で自動的に1回だけ`acceptAnswer`を呼ぶ（FR-1.2） |
+
+## 3. camera（カメラ側）ブロック
+
+| opcode | 種類 | テキスト | 効果・戻り値 |
+|---|---|---|---|
+| `startAnswerPairing` | COMMAND | `start answer pairing [SESSION] as [LOCAL_PEER]` | `awaiting-offer`へ。`LOCAL_PEER`が空ならOfferの`targetPeerId`を採用、非空なら照合し不一致で`peer-mismatch` |
+
+Offer全part受信後の`acceptOffer`とAnswer分割は内部で自動実行し、`answer-ready`へ遷移する。
+
+## 4. 受信（両ロール共通）
+
+| opcode | 種類 | テキスト | 備考 |
+|---|---|---|---|
+| `ingestPairingQrText` | COMMAND | `receive pairing QR text [TEXT] for [SESSION]` | 正規入口。重複partは成功扱い。不正partは対応するエラーコードで失敗 |
+| `scanPairingQrFromCamera` | COMMAND | `scan pairing QR for [SESSION] from camera [CAMERA_ID]` | 全part受信・取消・期限までブロックする。session中1つのleaseを保持 |
+| `pairingReceivedParts` | REPORTER | `received parts of [SESSION]` | 取得済み数 |
+| `pairingRequiredParts` | REPORTER | `required parts of [SESSION]` | 必要数。最初のpart受信前は0 |
+| `pairingMissingParts` | REPORTER | `missing parts of [SESSION]` | 未取得の1始まり番号をカンマ区切りで返す |
+
+## 5. 表示（両ロール共通）
+
+| opcode | 種類 | テキスト | 備考 |
+|---|---|---|---|
+| `showPairingQrPart` | COMMAND | `show pairing QR part [INDEX] of [SESSION] on this sprite` | 一時skinへ差し替え。範囲外は`invalid-argument` |
+| `showNextPairingQrPart` | COMMAND | `show next pairing QR part of [SESSION] on this sprite` | 最終partから先頭へ巡回 |
+| `pairingQrPartCount` | REPORTER | `pairing QR part count of [SESSION]` | 未準備は0 |
+| `pairingQrCurrentPart` | REPORTER | `current pairing QR part of [SESSION]` | 1始まり。未表示は0 |
+| `pairingQrPartSvg` | REPORTER | `pairing QR part [INDEX] of [SESSION] as SVG` | アプリ独自表示用（FR-3.5） |
+| `pairingQrPartDataUri` | REPORTER | `pairing QR part [INDEX] of [SESSION] as data URI` | コスチューム差替え等に使える形 |
+| `endPairingQrDisplay` | COMMAND | `end pairing QR display of [SESSION]` | 元skinへ復元。sessionは維持する |
+
+## 6. 進行・状態・診断
+
+| opcode | 種類 | テキスト | 戻り値 |
+|---|---|---|---|
+| `pairingPhase` | REPORTER | `pairing phase of [SESSION]` | `PairingPhase`の文字列。未知のsessionは`idle`、フラグOFFは`disabled` |
+| `pairingConnectionState` | REPORTER | `pairing connection state of [SESSION]` | `turbowarp-webrtc`の接続状態そのまま |
+| `isPairingConnected` | BOOLEAN | `pairing [SESSION] connected?` | `phase === 'connected'` |
+| `waitUntilPairingConnected` | COMMAND | `wait until pairing [SESSION] is connected` | 接続成立・失敗・取消・期限まで待つ |
+| `pairingError` | REPORTER | `pairing error code of [SESSION]` | `PairingErrorCode`または空 |
+| `pairingErrorMessage` | REPORTER | `pairing error message of [SESSION]` | サニタイズ済み文言（SDP・payloadを含まない） |
+| `pairingLocalPeer` | REPORTER | `local peer of [SESSION]` | 自称 |
+| `pairingRemotePeer` | REPORTER | `remote peer of [SESSION]` | 相手の呼称 |
+| `pairingExchangeId` | REPORTER | `exchange id of [SESSION]` | 現在のexchangeId（診断・実機記録用） |
+| `pairingRemainingSeconds` | REPORTER | `remaining seconds of [SESSION]` | 期限までの残り |
+| `pairingSessions` | REPORTER | `pairing sessions` | 有効なsessionキーをカンマ区切り |
+
+## 7. 制御
+
+| opcode | 種類 | テキスト | 備考 |
+|---|---|---|---|
+| `cancelPairing` | COMMAND | `cancel pairing [SESSION]` | epoch++、資源解放、`cancelled`へ。成立済み接続は切らない |
+| `retryPairing` | COMMAND | `retry pairing [SESSION]` | 取消後に新しい`exchangeId`で同ロールの交換を再開 |
+| `setPairingTimeout` | COMMAND | `set pairing timeout of [SESSION] to [SECONDS] seconds` | 1〜3600。範囲外は`invalid-argument` |
+
+合計 28 opcode（COMMAND 11 / REPORTER 16 / BOOLEAN 1）。実装時に `pairingQrPartDataUri` と `pairingRemainingSeconds` を加え、表示選択と表示適用を分けた結果。
+
+## 8. エラーの返し方
+
+- COMMANDは失敗時に例外を投げる（TurboWarpはスクリプトを停止する）。同時に`pairingError`／`pairingErrorMessage`へ記録する。
+- REPORTERは例外を投げず、既定値（空文字・0）を返す。状態はphaseとエラーコードで観測する。
+- 重複partの受理、未接続時の`connectionState`照会などの正常系はエラーにしない。
+
+## 9. 形式互換性（FR-2.8）
+
+| 形式 | 発行元 | 本拡張の扱い |
+|---|---|---|
+| `twqr/1` | 本拡張 | 受理する |
+| `twmp-qr/1` | `turbowarp-realtime-motion-capture`（Offerのみ） | 受理しない。`unsupported-protocol`で明示的に失敗する |
+
+**非互換にした理由**: `twmp-qr/1`は`peerId`が1つだけで「送信側の自称」と「受信側への呼称」を区別できず、
+`replyTo`も持たないため、FR-1.3（両端で同じ識別子を要求しない）とFR-1.4（Answerの応答先追跡）を満たせない。
+これらは必須フィールドの追加にあたるので、後方互換の拡張ではなくversion変更とした。
+
+**移行方法**:
+
+1. 本拡張は`twqr/1`のみを発行・受理する。旧形式の読取り互換モードは設けない
+   （ambiguousな受理より、明示的な`unsupported-protocol`のほうが誤接続を防ぐ）。
+2. `turbowarp-realtime-motion-capture`は当面`twmp-qr/1`のまま維持する（NFR-5）。
+   両者を同一会場で使うと相互に読めないが、`unsupported-protocol`として検出されるので誤接続にはならない。
+3. motion-capture側を本拡張へ委譲する変更は、当該リポジトリの別Issue／PRとして記録する（Issue #1の方針どおり）。
+4. 将来`twqr/2`が必要になった場合も、受理側は`protocol`完全一致で判定し、未知versionは常に拒否する。
+
+## 10. manifest反映時の注意
+
+- ブロック・引数・menuは識別子でソートされて出力されるので、`block-definitions.json`の記述順は契約に影響しない。
+- menuは使わない（`SESSION`等はすべて自由入力のSTRING）。動的menuを将来入れる場合はmanifestに`menu`参照が現れるため、契約変更として扱う。
+- フィーチャーフラグOFF時は`getInfo()`がペアリングブロックを返さないが、**manifestは常に全ブロックを出力する**
+  （manifestはビルド時の静的契約であり、実行時のフラグ状態ではない）。この点はREADMEに明記する。

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

@@ -0,0 +1,202 @@
+# データフローと状態遷移
+
+対応要求: FR-1 / FR-3 / FR-4 — [requirements.md](requirements.md)
+
+## 1. 全体シーケンス（正常系・DoD 1）
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant App1 as 利用アプリ(hub)
+  participant Ext1 as 本拡張(hub)
+  participant W1 as turbowarp-webrtc(hub)
+  participant Human as 担当者/光学搬送
+  participant Ext2 as 本拡張(camera)
+  participant W2 as turbowarp-webrtc(camera)
+  participant App2 as 利用アプリ(camera)
+
+  App2->>Ext2: startAnswerPairing(s, localPeer="")
+  Note over Ext2: phase=awaiting-offer
+
+  App1->>Ext1: startOfferPairing(s, "hub", "camera-1")
+  Ext1->>W1: createOffer("camera-1")
+  W1-->>Ext1: offer code (ICE収集完了済み)
+  Ext1->>Ext1: createParts() 分割・hash・QR化
+  Note over Ext1: phase=offer-ready
+  App1->>Ext1: showPairingQrPart(1..n) 投影
+
+  loop 各part
+    Human-->>Ext2: カメラでQR読取り → scanFrame
+    Ext2->>Ext2: parse → assembler.add()
+    Note over Ext2: phase=receiving (received/required)
+  end
+
+  Ext2->>Ext2: assemble() 長さ・hash検証
+  Note over Ext2: phase=offer-received
+  Ext2->>W2: acceptOffer("hub", offerCode)
+  W2-->>Ext2: answer code (ICE収集完了済み)
+  Ext2->>Ext2: createParts(kind=answer, replyTo=offerMessageId)
+  Note over Ext2: phase=answer-ready
+  App2->>Ext2: showPairingQrPart(1..m) 画面表示
+
+  Human->>Human: スマートフォンで全partを撮影し hubへ運ぶ
+  loop 各part
+    Human-->>Ext1: スマホ画面をhubのカメラへ → scanFrame
+    Ext1->>Ext1: parse → sessionId/replyTo/peer検証 → assembler.add()
+  end
+
+  Ext1->>Ext1: assemble() 長さ・hash検証
+  Note over Ext1: phase=answer-received
+  Ext1->>W1: acceptAnswer("camera-1", answerCode)
+  Note over Ext1: phase=connecting
+  loop connectionStateをポーリング
+    Ext1->>W1: connectionState("camera-1")
+  end
+  Note over Ext1: phase=connected
+  Ext1-->>App1: isPairingConnected = true
+  Note over Ext2: phase=connected（W2のconnectionStateで確認）
+  App1->>W1: sendEvent/sendLatestData で疎通確認 (DoD 2)
+```
+
+## 2. 状態遷移（hub）
+
+```mermaid
+stateDiagram-v2
+  [*] --> idle
+  idle --> creating_offer: startOfferPairing
+  creating_offer --> offer_ready: offer code 取得・分割成功
+  creating_offer --> failed: webrtc失敗 / 分割失敗
+  offer_ready --> awaiting_answer: 最初のAnswer partを受理
+  offer_ready --> answer_received: 単一partで完結
+  awaiting_answer --> answer_received: 全part検証成功
+  answer_received --> connecting: acceptAnswer 呼出し
+  connecting --> connected: connectionState=connected
+  connecting --> failed: connectionState=failed / closed
+  offer_ready --> expired: 期限超過
+  awaiting_answer --> expired: 期限超過
+  connecting --> expired: 期限超過
+  creating_offer --> cancelled: cancelPairing
+  offer_ready --> cancelled: cancelPairing
+  awaiting_answer --> cancelled: cancelPairing
+  connecting --> cancelled: cancelPairing
+  cancelled --> creating_offer: retryPairing(新sessionId)
+  expired --> creating_offer: retryPairing(新sessionId)
+  failed --> creating_offer: retryPairing(新sessionId)
+  connected --> [*]
+```
+
+`offer_ready`／`awaiting_answer`は「Offerを表示しながらAnswerを待つ」段階で、
+表示の有無は`pairingQrPartCount`／`pairingQrCurrentPart`、受信進捗は
+`pairingReceivedParts`／`pairingRequiredParts`／`pairingMissingParts`で別々に観測する。
+
+## 3. 状態遷移（camera）
+
+```mermaid
+stateDiagram-v2
+  [*] --> idle
+  idle --> awaiting_offer: startAnswerPairing
+  awaiting_offer --> receiving: 最初のOffer partを受理
+  receiving --> receiving: 追加part / 重複part
+  awaiting_offer --> offer_received: 単一partで完結
+  receiving --> offer_received: 全part検証成功
+  offer_received --> creating_answer: acceptOffer 呼出し
+  creating_answer --> answer_ready: answer code 取得・分割成功
+  creating_answer --> failed: webrtc失敗 / 分割失敗
+  answer_ready --> connecting: 表示完了後もconnectionStateを監視
+  connecting --> connected: connectionState=connected
+  connecting --> failed: connectionState=failed / closed
+  awaiting_offer --> expired: 期限超過
+  receiving --> expired: 期限超過
+  answer_ready --> expired: 期限超過
+  awaiting_offer --> cancelled: cancelPairing
+  receiving --> cancelled: cancelPairing
+  answer_ready --> cancelled: cancelPairing
+  cancelled --> awaiting_offer: retryPairing
+  expired --> awaiting_offer: retryPairing
+  failed --> awaiting_offer: retryPairing
+  connected --> [*]
+```
+
+**FR-4.2の分離**: QR読取り完了は`offer_received`／`answer_received`、
+WebRTC接続成立は`connected`。両者は必ず別の状態として観測できる。
+
+## 4. part受理の判定フロー（FR-2.3 / FR-2.5）
+
+```mermaid
+flowchart TD
+  A[QRテキスト到着] --> B{長さ <= MAX_PART_TEXT}
+  B -- No --> E1[part-too-large]
+  B -- Yes --> C{JSON parse 可}
+  C -- No --> E2[invalid-json]
+  C -- Yes --> D{protocol == twqr/1}
+  D -- No --> E3[unsupported-protocol]
+  D -- Yes --> F{envelope各フィールドが範囲内}
+  F -- No --> E4[invalid-envelope / index-out-of-range / message-too-large]
+  F -- Yes --> G{sessionId が対象sessionのもの}
+  G -- No --> E5[unknown-session / stale-exchange]
+  G -- Yes --> H{kind と role の組合せが正しい}
+  H -- No --> E6[unexpected-kind]
+  H -- Yes --> I{peer対応が一致 / Answerならreply-to一致}
+  I -- No --> E7[peer-mismatch / reply-mismatch]
+  I -- Yes --> J{既存partと同一identity}
+  J -- No --> E8[message-mismatch]
+  J -- Yes --> K{同indexの既存partと payload一致}
+  K -- No --> E9[conflicting-part]
+  K -- Yes --> L[assembler へ格納]
+  L --> M{received == partCount}
+  M -- No --> N[phase=receiving を維持]
+  M -- Yes --> O{結合長 == messageLength}
+  O -- No --> E10[length-mismatch]
+  O -- Yes --> P{SHA-256 == messageHash}
+  P -- No --> E11[hash-mismatch]
+  P -- Yes --> Q[検証済みメッセージ確定 → WebRTCへ1回だけ引渡し]
+```
+
+重複partで`payload`が一致する場合は`duplicate=true`を返し、エラーにはしない（正常系）。
+
+## 5. 古い非同期結果の破棄（FR-4.4）
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant Ctl as PairingController
+  participant W as turbowarp-webrtc
+
+  App->>Ctl: startOfferPairing(s) 
+  Note over Ctl: epoch=1 を捕捉
+  Ctl->>W: createOffer("camera-1")  (時間がかかる)
+  App->>Ctl: cancelPairing(s)
+  Note over Ctl: epoch=2、表示・lease解放、phase=cancelled
+  App->>Ctl: retryPairing(s)
+  Note over Ctl: epoch=3、新 sessionId
+  W-->>Ctl: 旧createOfferの解決 (epoch=1で開始)
+  Note over Ctl: epoch不一致 → 結果を破棄。状態は変更しない
+```
+
+同じ仕組みを`acceptOffer`／`acceptAnswer`／分割処理／connectionStateポーリングにも適用する。
+
+## 6. 資源の取得と解放
+
+```mermaid
+flowchart LR
+  S[session開始] --> T[タイマ登録]
+  S --> L[camera lease 取得<br/>scanブロック使用時のみ]
+  S --> K[一時skin 生成<br/>表示ブロック使用時のみ]
+  S --> P[connectionState ポーリング開始<br/>connecting以降]
+  subgraph 終了契機
+    C1[cancel] 
+    C2[expire]
+    C3[connected]
+    C4[PROJECT_RUN_STOP]
+    C5[RUNTIME_DISPOSED]
+  end
+  C1 --> R
+  C2 --> R
+  C3 --> R
+  C4 --> R
+  C5 --> R
+  R[解放: タイマ停止 / lease.release /<br/>元skin復元・一時skin破棄 /<br/>ポーリング停止 / assembler破棄]
+```
+
+`connected`到達時も走査・表示・タイマは解放するが、RTCPeerConnectionは維持する。
+`RUNTIME_DISPOSED`ではruntimeイベントリスナも解除する。