@kubohiroya/turbowarp-webrtc-qrcode-pairing 0.1.0

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

@@ -0,0 +1,134 @@
+# 移設計画（turbowarp-realtime-motion-capture からの選別）
+
+対応要求: requirements.md §7 / Issue #1「既存コードの抽出範囲」
+
+抽出元: `/Users/hiroya/Dev/turbowarp-realtime-motion-capture`（`@kubohiroya/turbowarp-realtime-motion-capture`）。
+抽出元の削除は本Issueの完了条件ではない（NFR-5）。ここでは**コピー元と改変内容**だけを決める。
+
+## 0. 移設の区分
+
+| 区分 | 意味 |
+|---|---|
+| **A: ほぼそのまま** | import路とエラー文言のみ調整。ロジックは変更しない |
+| **B: 一般化して移設** | motion-capture固有の型・命名・前提を外す。ロジックの骨格は維持 |
+| **C: 分解して再設計** | 概念は流用するが、往復・多重session・取消のために書き直す |
+| **D: 新規** | 移設元に存在しない |
+| **E: 移設しない** | motion-capture固有の関心事 |
+
+## 1. 実装ファイル
+
+| 移設元 | 行数 | 移設先 | 区分 | 具体的な作業 |
+|---|---|---|---|---|
+| `src/qr-svg.ts` | 39 | `src/qr/svg.ts` | A | `import type {QrErrorCorrectionLevel} from "./qr-courier.js"` → `"./envelope.js"`。それ以外は同一 |
+| `src/sprite-skin.ts` | 112 | `src/ports/display.ts` | A | クラス名は`TemporarySpriteSkinManager`のまま。エラー文言の`Offer QR`→`Pairing QR`。`DisplayPort`をimplementsする宣言を追加 |
+| `src/qr-courier.ts` の定数群 | （冒頭6行） | `src/qr/limits.ts` | B | `MAX_MESSAGE_LENGTH` / `MAX_PART_COUNT` / `MAX_CHUNK_LENGTH`をそのまま移し、`MAX_PART_TEXT_LENGTH` / `MAX_ACTIVE_SESSIONS` / 期限定数を追加。単位と境界条件をコメントで明記（FR-2.7） |
+| `src/qr-courier.ts` の`QrCourierPartV1` / `validatePart` / `serializeQrCourierPart` / `parseQrCourierPart` / `partIdentity` / `requireIdentifier` / `requireTimestamp` / `requirePairingCode` | ~140 | `src/qr/envelope.ts` | B | ①`protocol`を`twqr/1`へ ②`peerId`→`senderPeerId`＋`targetPeerId` ③`replyTo`追加（offerは空文字、answerは非空を要求） ④`QrCourierKind`→`QrMessageKind` ⑤エラーを`QrPairingError(code, message)`へ置換 ⑥`Offer pairing code is empty.`のようなOffer前提の文言を種別非依存に ⑦`createdAt`が期限判定に使われないことをコメントで明記 ⑧payloadの印字可能ASCII検査をparse時にも行う |
+| `src/qr-courier.ts` の`sha256Base64Url` | ~8 | `src/qr/hash.ts` | A | envelopeとcourierの双方が使うため単独モジュールへ |
+| — | — | `src/errors.ts` | D | `PairingErrorCode`と`QrPairingError`。`qr/`と`pairing/`の双方が参照するので、依存を持たない葉モジュールとして`src/`直下に置く |
+| `src/qr-courier.ts` の`createQrCourierParts` / `maximumPayloadLength` | ~75 | `src/qr/courier.ts` | B | 二分探索とpart数収束ループはそのまま。`options`を`CreatePartsOptions`（sender/target/replyTo/sessionId）へ。戻り値に`sessionId`／`messageId`を追加 |
+| `src/qr-courier.ts` の`QrCourierAssembler` | ~45 | `src/qr/courier.ts`（`PartAssembler`） | B | ①入力を`string`から`QrEnvelopeV1`へ（parseは呼び出し側＝controllerが行い、session照合をparse直後に挟めるようにする） ②`missingParts()` / `receivedCount()` / `requiredCount()` / `isComplete()` / `clear()`を追加（FR-2.3） ③エラーを`QrPairingError`へ |
+| `src/webrtc-capability.ts` | 38 | `src/ports/webrtc.ts` | B | `WebRtcOfferCapabilityV2`→`WebRtcPairingPort`。要求versionを3へ。`acceptOffer` / `getAnswer` / `acceptAnswer` / `connectionState` / `closePeer`の存在検査を追加。エラーコード`webrtc-capability-missing` |
+| `src/extension.ts` L200-310（`prepareOfferQr` / `showOfferQrPart` / `offerQrPartCount` / `offerQrCurrentPart` / `showNextOfferQrPart` / `createAndShowOfferQr` / `endOfferQrDisplay` / `offerQrState` / `offerQrError`） | ~110 | `src/pairing/controller.ts` ＋ `src/pairing/session.ts` | C | 流用する概念: `operation`カウンタによる古い非同期結果の破棄（→`epoch`）、`state`／`lastError`の保持（→`phase`／`errorCode`）、part表示と巡回、`endOfferQrDisplay`での一括解放。書き直す理由: 単一session固定・Offer専用・camera側なし・期限なし・受信なしのため |
+| `src/extension.ts` のruntimeリスナ設定（L172-177, `runStopListener`／`stopListener`／`disposeListener`／`targetRemovedListener`） | ~25 | `src/extension.ts` | B | motion-capture固有の`pose`／`calibration`／`fusion`停止を除去し、本拡張の`stopTransient()`／`dispose()`へ束ねる |
+| `src/extension.ts` の`toScratchBlock`／`blockEnabled`／`requireEnabled` | ~40 | `src/extension.ts` | B | 既存scaffoldの`toScratchBlock`とほぼ同型。`feature`フィールドによるフィルタを`qrCodePairing`単独で復元 |
+| `config/feature-flags.ts` | 27 | `src/config/feature-flags.ts` | B | フラグを`qrCodePairing`1件へ。グローバル名`__TWMP_FEATURE_FLAGS__`→`__TWQP_FEATURE_FLAGS__`。Issueの指定どおり`src/`配下へ置く |
+| `config/qr-config.ts` | 19 | `src/config/qr-config.ts` | A | グローバル名`__TWMP_QR_CONFIG__`→`__TWQP_QR_CONFIG__` |
+| `src/globals.d.ts` の`TurboWarpRenderer` / `TurboWarpTarget` / `TurboWarpBlockUtility` / `TurboWarpRuntime` / `Scratch.vm` | ~30 | `src/globals.d.ts`（既存へ追記） | A | scaffoldの`globals.d.ts`にはrenderer／target／runtimeの宣言が無いので追加。`declare module "@kubohiroya/turbowarp-jsqr/jsqr.js"`も必要 |
+| — | — | `src/qr/courier.ts`のAnswer側分割呼出し | D | `kind='answer'`＋`replyTo`＋`sessionId`継承。移設元に相当物なし |
+| — | — | `src/ports/qr-scan.ts` | D | camera-sourceのlease保持＋jsqr`scanFrame`ポーリング。移設元は読取り側を持たない |
+| — | — | `src/pairing/types.ts` | D | phase／errorCode／portの定義 |
+| — | — | `src/clock.ts`（`MonotonicClock`） | D | 単調時計。移設元は`Date.now()`のみ |
+| `src/pose/**`, `src/fusion/**`, `src/calibration/**`, `src/avatar/**`, `src/frame-sync/**`, `src/markers/**`, `src/protocol/**` | 約8,900 | — | E | motion-capture固有。本拡張のスコープ外 |
+| `src/extension-manifest.ts`, `src/config.ts`, `src/index.ts` | — | — | E | scaffold側に同等物が既にある |
+
+移設対象の実コード合計はおよそ **620行**（うちAが約190行、Bが約320行、Cが約110行）。
+
+## 2. テスト
+
+| 移設元 | 行数 | 移設先 | 区分 | 作業 |
+|---|---|---|---|---|
+| `tests/qr-courier.test.ts` | 116 | `tests/qr-courier.test.ts` | B | 4件のitを維持。`peerId`→`senderPeerId`/`targetPeerId`、protocol名、`QrCourierAssembler`→`PartAssembler`（入力がenvelope）に合わせて更新。「順不同・重複・混在identity・欠落part・範囲外index・過大入力」の観点はそのまま使える（DoD 3/4に直結） |
+| `tests/turbowarp-jsqr-integration.test.ts` | 80 | `tests/qr-jsqr-integration.test.ts` | A | `createQrCourierParts`→`createParts`の呼び替えのみ。**`feat/pairing/optical-workflow`へ延期**: このテストは`@kubohiroya/turbowarp-jsqr`拡張の`scanFrame`経路を検証するもので、走査ポートを実装するPRで一緒に入れるほうが依存の追加が1回で済む。生成QRの実デコード検証自体は`qr-courier.test.ts`が`jsqr`パッケージ直接利用で担保する |
+| `tests/extension.test.ts` L85-130, L485-693（offer QRブロック関連） | ~250 | `tests/pairing-hub.test.ts` ほか | C | 流用する観点: フラグOFFでブロックが出ない／`disabled`を返す、peer名のtrim、単一part／複数part、次part巡回、表示終了で復元、webrtc未ロード時のエラー、進行中の二重起動拒否、スプライト削除時の復元。往復・camera側・取消・期限・複数peerは新規 |
+| — | — | `tests/pairing-camera.test.ts` | D | Offer受理→Answer生成→表示 |
+| — | — | `tests/pairing-roundtrip.test.ts` | D | hub↔cameraを同一プロセス内で結線した往復（DoD 1/3/6） |
+| — | — | `tests/pairing-lifecycle.test.ts` | D | 取消・期限・再試行・古い非同期応答・古いQR（DoD 5） |
+| — | — | `tests/extension-manifest.test.ts` | B | 既存を新opcode一覧に合わせて更新 |
+
+## 3. 依存パッケージの移設
+
+`package.json`へ追加する。
+
+```jsonc
+"dependencies": {
+  "qrcode": "1.5.4"                       // 移設元と同一版に固定
+},
+"peerDependencies": {                      // すべて optional
+  "@kubohiroya/turbowarp-webrtc": ">=0.4.0",     // capability v3 を含む版（後述）
+  "@kubohiroya/turbowarp-jsqr": "0.3.0",
+  "@kubohiroya/turbowarp-camera-source": "0.5.0"
+},
+"devDependencies": {
+  "@types/qrcode": "1.5.6",
+  "jsqr": "^1.4.0"                        // テストでの実デコード検証用
+}
+```
+
+`pnpm-workspace.yaml`の`minimumReleaseAgeExclude`に上記の`@kubohiroya/*`を追記する（移設元と同じ運用）。
+
+**注意点**:
+
+- 本リポジトリは`vitest ^5.0.0`、移設元は`vitest ^4.1.10`。移設テストがvitest 5で動くことを最初のPRで確認する
+  （`vi.stubGlobal`／`vi.unstubAllGlobals`は5系でも同APIだが、タイマ系APIの差異は要確認）。
+- 本リポジトリは`@kubohiroya/vite-plugin-turbowarp-extension` 0.3.0、移設元は0.4.0。
+  `qrcode`をバンドルできることは`refactor/pairing/qr-courier`で確認済み（`src/qr/courier.ts`を入口に
+  vite単体ビルドすると、外部importなし・node組込みなしの単一チャンク約88 KBになる）。
+  `src/extension.ts`が`qr/`を参照するのは`feat/pairing/optical-workflow`以降なので、
+  `pnpm run check:dist`での最終確認はそのPRで行う。
+- 移設元はprettierを使うが本リポジトリは使わない。移設したコードは本リポジトリのeslint設定に合わせる
+  （移設元はダブルクォート、本リポジトリのscaffoldはシングルクォート。`eslint.config.mjs`の実際の規則に従う）。
+
+## 4. 前提となる他リポジトリの変更（ブロッカー）
+
+### 4.1 `turbowarp-webrtc`: runtime capability v3
+
+現状のv3不在が**FR-1の実装を直接ブロックする**。
+
+- 現状（`src/runtime-capability.ts`）: `version` / `requireVersion` / `createOffer` / `getOffer` /
+  `setLatestDataEnabled` / `configureLatestDataChannel` / `sendLatestData` / `latestDataStats`。
+- 追加が必要: `acceptOffer(peer, code)` / `getAnswer(peer)` / `acceptAnswer(peer, code)` /
+  `connectionState(peer)` / `closePeer(peer)`。いずれも`PeerSessionPort`（`src/manual-peer-session.ts:36-59`）に
+  既に実装済みで、capabilityへ委譲を追加するだけで足りる。
+- 併せて`runtimeCapabilityVersion`を3にし、`requireVersion`が1/2/3を受理するようにする。
+- これは`turbowarp-webrtc`側の別Issue／PRとして起票し、本Issue #1からリンクする。
+
+**この作業が完了するまで**、本リポジトリでは`WebRtcPairingPort`をinterfaceとして定義し、
+テストではフェイクを注入して往復ロジックを完成させられる。実機検証だけがブロックされる。
+
+### 4.2 `turbowarp-jsqr` / `turbowarp-camera-source`
+
+変更不要。`ext_kubohiroyajsqr.scanFrame`と`ext_kubohiroyacamerasource.acquireCamera`をそのまま使う。
+ただし両者とも`runtime.ext_*`という非versioned な公開面なので、本拡張側で存在検査とエラーコード化を行う。
+将来的にversioned capabilityへ移行する提案は、それぞれのリポジトリの別Issueとする。
+
+## 5. PR分割（Issue #1の表を本設計で具体化）
+
+| # | ブランチ | 内容 | 依存 | 検証 |
+|---|---|---|---|---|
+| 0 | `turbowarp-webrtc` 側 `feat/runtime-capability/v3` | capability v3の追加 | なし | 当該リポジトリのcheck |
+| 1 | `feat/pairing/contracts` | 本設計文書一式、`src/pairing/types.ts`、`src/config/feature-flags.ts`、`src/config/qr-config.ts`、`globals.d.ts`の拡張 | なし | typecheck / lint |
+| 2 | `refactor/pairing/qr-courier` | `src/qr/**`（limits・envelope・courier・svg）と移設テスト、依存パッケージ追加 | #1 | `pnpm run check`、jsQR実デコード、部分・重複・欠落 |
+| 3 | `feat/pairing/offer-answer` | `src/ports/webrtc.ts`、`src/clock.ts`、`src/pairing/{limits,types,controller}.ts`、往復・取消・期限・複数peerのテスト | #1,#2（実機は#0） | フェイクWebRTCでの往復テスト |
+| 4 | `feat/pairing/optical-workflow` | `src/ports/display.ts`、`src/ports/qr-scan.ts`、ブロック定義とextension.ts、実機検証 | #3、#0、jsqr／camera-source | 実機での投影→読取り→搬送→接続 |
+| 5 | `docs/pairing/integration` | README（日英）、docs/index.html、利用ガイド、移行・切戻し手順 | #4 | `pnpm run docs:check`、DoD一覧の確認 |
+
+#2と#0は並行可能。#3は#0未完でもフェイク注入で進められるが、#4の実機検証は#0の完了を待つ。
+
+## 6. 移設時に必ず落とすもの（一般化チェックリスト）
+
+- [ ] `twmp` / `multiview` / `motion capture` を含む識別子・文字列・グローバル名が残っていない
+- [ ] `Offer`固有の文言（`Offer pairing code`, `Offer QR must be displayed…`）が種別非依存になっている
+- [ ] `pose` / `calibration` / `fusion` / `avatar` / `frame-sync` / `markers` への参照が無い
+- [ ] `qr/`配下がDOM・Scratch・runtimeに依存していない（importが`qrcode`と自モジュールのみ）
+- [ ] エラーが素のErrorではなく`QrPairingError`でコード付き
+- [ ] SDP・pairing code・payloadが例外メッセージへ混入していない

package/docs/design/qr-pairing/interfaces.ts

@@ -0,0 +1,473 @@
+/**
+ * QR搬送WebRTCペアリング 型契約（設計文書）
+ *
+ * 対応要求: requirements.md / Issue #1
+ * 本ファイルは設計の規範であり、ビルド対象ではない（tsconfig の include は src/tests/scripts）。
+ * 実装時は各セクションを src/ 配下の該当モジュールへ分割する（architecture.md 参照）。
+ */
+
+/* ============================================================================
+ * src/qr/limits.ts  — 上限・単位・境界条件（FR-2.7）
+ * ==========================================================================*/
+
+/**
+ * メッセージ（pairing code）の最大長。
+ * 単位: 文字数。payload は印字可能ASCII `[\x20-\x7E]` に限定されるため、
+ * 1文字 = 1 UTF-16 code unit = 1 バイトであり、文字数とバイト数は一致する。
+ * 境界: 1 <= messageLength <= MAX_MESSAGE_LENGTH。0 は不正。
+ *
+ * 注意（実効上限）: 実際に搬送できる長さは MAX_PART_COUNT × chunk長 で頭打ちになる。
+ * chunk長 = (QR v40 の該当ECCレベルのバイト容量) - (envelopeヘッダ長 <= 362)。
+ *   L: 2953 - 362 = 2591 → 64part で 165,824 → MAX_MESSAGE_LENGTH が binding
+ *   M: 2331 - 362 = 1969 → 64part で 126,016 → part数が binding
+ *   Q: 1663 - 362 = 1301 → 64part で  83,264 → part数が binding
+ *   H: 1273 - 362 =  911 → 64part で  58,304 → part数が binding
+ * 上限超過は分割時に `message-too-large` もしくは `too-many-parts` で失敗する。
+ */
+export const MAX_MESSAGE_LENGTH = 128 * 1024; // 131072
+
+/** 1メッセージあたりの最大part数。境界: 1 <= partCount <= 64、0 <= partIndex < partCount。*/
+export const MAX_PART_COUNT = 64;
+
+/** 1partのpayload最大長（文字数）。QR容量による実効上限より常に大きい安全弁。*/
+export const MAX_CHUNK_LENGTH = 4096;
+
+/** 受理するQRテキストの最大長（文字数）。envelopeヘッダ + payload の上限。*/
+export const MAX_PART_TEXT_LENGTH = 8192;
+
+/** 同時に保持できるsession数（受信状態の保持上限、FR-2.7）。*/
+export const MAX_ACTIVE_SESSIONS = 8;
+
+/** 期限の既定値と範囲（秒、FR-4.6）。*/
+export const DEFAULT_TIMEOUT_SECONDS = 600;
+export const MIN_TIMEOUT_SECONDS = 1;
+export const MAX_TIMEOUT_SECONDS = 3600;
+
+/** connectionState のポーリング間隔（ミリ秒）。*/
+export const CONNECTION_POLL_INTERVAL_MS = 250;
+
+/** カメラ走査のポーリング間隔（ミリ秒）。jsqr の既定と揃える。*/
+export const SCAN_POLL_INTERVAL_MS = 150;
+
+/* ============================================================================
+ * src/qr/envelope.ts  — 搬送形式 twqr/1（FR-2.1, FR-2.8）
+ * ==========================================================================*/
+
+/**
+ * protocol識別子。
+ * 移設元 `twmp-qr/1` に peer対応情報（senderPeerId/targetPeerId）と replyTo を追加した
+ * 非互換形式のため、新しい名前空間とversionを与える。
+ * `twmp-qr/1` は本拡張では受理しない（`unsupported-protocol`）。相互運用しない理由と
+ * motion-capture側の移行方針は block-api.md「形式互換性」を参照。
+ */
+export const QR_PROTOCOL = 'twqr/1' as const;
+
+export type QrMessageKind = 'offer' | 'answer';
+export type QrErrorCorrectionLevel = 'L' | 'M' | 'Q' | 'H';
+
+export interface QrEnvelopeV1 {
+  /** 固定値 'twqr/1'。*/
+  readonly protocol: typeof QR_PROTOCOL;
+  /** 1回のOffer→Answer往復を識別する。hubがOffer生成時にUUIDで採番し、Answerが反映する。*/
+  readonly sessionId: string;
+  /** 送信側が自分を呼ぶ名前。受信側はこれを自分のWebRTC peerキーに使う。*/
+  readonly senderPeerId: string;
+  /** 送信側が受信側を呼ぶ名前。受信側は自分の自称としてこれを採用（または照合）する。*/
+  readonly targetPeerId: string;
+  readonly kind: QrMessageKind;
+  /** `<sessionId>.<messageHashの先頭12文字>`。内容が変われば必ず変わる。*/
+  readonly messageId: string;
+  /** kind='answer' のとき、応答対象のOfferの messageId。kind='offer' のときは空文字。*/
+  readonly replyTo: string;
+  /** 送信端末のローカル壁時計（ミリ秒）。診断・表示用。期限判定には使わない（FR-4.6）。*/
+  readonly createdAt: number;
+  /** 0 <= partIndex < partCount。*/
+  readonly partIndex: number;
+  /** 1 <= partCount <= MAX_PART_COUNT。*/
+  readonly partCount: number;
+  /** 1 <= messageLength <= MAX_MESSAGE_LENGTH（文字数）。*/
+  readonly messageLength: number;
+  /** メッセージ全体の SHA-256、base64url無パディング（43文字）。破損検出用で認証ではない（FR-2.6）。*/
+  readonly messageHash: string;
+  /** メッセージの一部。印字可能ASCII、長さ <= MAX_CHUNK_LENGTH。*/
+  readonly payload: string;
+}
+
+/** JSONへ直列化する。検証を通らないenvelopeは直列化しない。*/
+export declare function serializeEnvelope(envelope: QrEnvelopeV1): string;
+
+/** QRテキストをparseし全フィールドを検証する。失敗時は QrPairingError を投げる。*/
+export declare function parseEnvelope(text: string): QrEnvelopeV1;
+
+/**
+ * 同一メッセージの part であることを判定するための同一性キー。
+ * payload と partIndex を除く全フィールドを連結する。
+ */
+export declare function envelopeIdentity(envelope: QrEnvelopeV1): string;
+
+/* ============================================================================
+ * src/qr/courier.ts  — 分割と再構成（FR-2.2, FR-2.3, FR-2.4）
+ * ==========================================================================*/
+
+export interface CreatePartsOptions {
+  readonly senderPeerId: string;
+  readonly targetPeerId: string;
+  readonly kind: QrMessageKind;
+  /** kind='answer' のとき必須。Offerの messageId。*/
+  readonly replyTo?: string;
+  /** 省略時は crypto.randomUUID()。Answerでは必ずOfferの sessionId を渡す。*/
+  readonly sessionId?: string;
+  readonly errorCorrectionLevel?: QrErrorCorrectionLevel;
+  /** 省略時は Date.now()。テストのため注入可能。*/
+  readonly createdAt?: number;
+}
+
+export interface QrParts {
+  readonly parts: readonly QrEnvelopeV1[];
+  /** parts と同順の QRテキスト。*/
+  readonly texts: readonly string[];
+  readonly sessionId: string;
+  readonly messageId: string;
+}
+
+/**
+ * メッセージをQR容量に合わせて分割する。
+ * chunk長は「ヘッダ込みでQR v40に収まる最大payload長」を二分探索で決め、
+ * part数が確定するまで反復する（移設元の手順を維持）。
+ */
+export declare function createParts(
+  message: string,
+  options: CreatePartsOptions
+): Promise<QrParts>;
+
+export interface PartAcceptResult {
+  readonly received: number;
+  readonly total: number;
+  /** 同一indexの同一payloadを再受理した場合 true。エラーではない。*/
+  readonly duplicate: boolean;
+}
+
+/** 再構成器。1つの PartAssembler は1メッセージ分の part しか受け付けない。*/
+export declare class PartAssembler {
+  add(envelope: QrEnvelopeV1): PartAcceptResult;
+  /** 未取得の partIndex を昇順で返す（FR-2.3）。*/
+  missingParts(): readonly number[];
+  receivedCount(): number;
+  /** 最初のpartを受けるまでは 0。*/
+  requiredCount(): number;
+  isComplete(): boolean;
+  /** 長さとhashを検証して結合結果を返す。未完成・不一致は QrPairingError。*/
+  assemble(): Promise<string>;
+  /** 受信状態を破棄する。*/
+  clear(): void;
+}
+
+/* ============================================================================
+ * src/qr/svg.ts  — 表示用のQR画像生成（FR-3.1）
+ * ==========================================================================*/
+
+export declare function createQrSvg(
+  text: string,
+  errorCorrectionLevel?: QrErrorCorrectionLevel
+): string;
+
+/** 診断用。実機検証記録の「QR表示条件」に使う。*/
+export declare function qrVersion(
+  text: string,
+  errorCorrectionLevel?: QrErrorCorrectionLevel
+): number;
+
+/* ============================================================================
+ * src/pairing/types.ts  — ロール・状態・エラー（FR-4.1, FR-4.2）
+ * ==========================================================================*/
+
+export type PairingRole = 'hub' | 'camera';
+
+/**
+ * 公開する状態名。hub と camera で到達する集合が異なる（dataflow.md 参照）。
+ * 'offer-received' / 'answer-received' が「QR読取り完了」、
+ * 'connected' が「WebRTC接続成立」であり、両者は必ず区別される（FR-4.2）。
+ */
+export type PairingPhase =
+  | 'disabled'          // フィーチャーフラグOFF
+  | 'idle'              // sessionが存在しない
+  | 'creating-offer'    // hub: createOffer 実行中
+  | '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: acceptOffer 実行中
+  | 'answer-ready'      // camera: Answer QR 準備完了・表示可能
+  | 'connecting'        // WebRTCへ引渡し済み、接続待ち
+  | 'connected'         // 接続成立
+  | 'cancelled'
+  | 'expired'
+  | 'failed';
+
+export type PairingErrorCode =
+  // フラグ・依存
+  | 'feature-disabled'
+  | 'webrtc-capability-missing'
+  | 'qr-decoder-missing'
+  | 'camera-unavailable'
+  | 'renderer-unavailable'
+  // 形式・検証（FR-2.5）
+  | 'invalid-json'
+  | 'unsupported-protocol'
+  | 'invalid-envelope'
+  | 'part-too-large'
+  | 'index-out-of-range'
+  | 'message-too-large'
+  | 'too-many-parts'
+  | 'message-mismatch'
+  | 'conflicting-part'
+  | 'missing-parts'
+  | 'length-mismatch'
+  | 'hash-mismatch'
+  // 交換の同一性（FR-1.4, FR-4.5）
+  | 'unknown-session'
+  | 'stale-exchange'
+  | 'unexpected-kind'
+  | 'peer-mismatch'
+  | 'reply-mismatch'
+  | 'already-accepted'
+  // ライフサイクル
+  | 'session-limit'
+  | 'session-exists'
+  | 'no-session'
+  | 'invalid-argument'
+  | 'timeout'
+  | 'cancelled'
+  | 'webrtc-rejected';
+
+/**
+ * 公開エラー。message は必ずサニタイズ済みで、SDP・ICE・pairing code・payload を含まない（FR-4.9）。
+ */
+export declare class QrPairingError extends Error {
+  readonly code: PairingErrorCode;
+  constructor(code: PairingErrorCode, message: string, options?: { cause?: unknown });
+}
+
+export interface PairingProgress {
+  readonly phase: PairingPhase;
+  readonly role: PairingRole;
+  readonly sessionKey: string;
+  readonly exchangeId: string;      // = envelope の sessionId
+  readonly localPeerId: string;
+  readonly remotePeerId: string;
+  /** 表示中QRの総part数。未準備なら0。*/
+  readonly outgoingPartCount: number;
+  /** 1始まり。未表示なら0。*/
+  readonly outgoingCurrentPart: number;
+  readonly receivedParts: number;
+  /** 最初のpartを受けるまでは0。*/
+  readonly requiredParts: number;
+  readonly missingParts: readonly number[];
+  readonly connectionState: string;
+  readonly errorCode: PairingErrorCode | '';
+  readonly errorMessage: string;
+  /** 残り秒数。期限なし・終了済みは0。*/
+  readonly remainingSeconds: number;
+}
+
+/* ============================================================================
+ * src/ports/*.ts  — 外部依存の抽象（architecture.md §4）
+ * ==========================================================================*/
+
+/**
+ * turbowarp-webrtc runtime capability v3。
+ * v2 は createOffer/getOffer しか公開していないため、本拡張は v3 を必須とする。
+ * 取得: runtime['kubohiroyaWebRtcCapability'] → requireVersion(3)
+ */
+export const WEBRTC_CAPABILITY_KEY = 'kubohiroyaWebRtcCapability';
+export const REQUIRED_WEBRTC_CAPABILITY_VERSION = 3;
+
+export interface WebRtcPairingPort {
+  readonly version: number;
+  createOffer(peer: string): Promise<string>;
+  getOffer(peer: string): string;
+  /** Offerを受理しAnswerコードを返す。*/
+  acceptOffer(peer: string, code: string): Promise<string>;
+  getAnswer(peer: string): string;
+  acceptAnswer(peer: string, code: string): Promise<void>;
+  /** RTCPeerConnectionState 相当の文字列。未知のpeerは 'new' 以外の既定値を返してよい。*/
+  connectionState(peer: string): string;
+  closePeer(peer: string): void;
+}
+
+export declare function requireWebRtcPairingPort(
+  runtime: TurboWarpRuntime
+): WebRtcPairingPort;
+
+/** turbowarp-jsqr のデコード能力。画像処理は本拡張で実装しない（FR-3.3）。*/
+export interface QrDecodePort {
+  scanFrame(frame: CameraFrameSource): string | null;
+}
+
+/** turbowarp-camera-source のlease規則を尊重する最小面（FR-3.4）。*/
+export interface CameraFrameSource {
+  readonly element: HTMLVideoElement | HTMLCanvasElement;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface CameraLease {
+  getFrameSource(): CameraFrameSource;
+  release(): Promise<void>;
+}
+
+export interface CameraSourcePort {
+  acquireCamera(options: { owner: string; cameraId: string }): Promise<CameraLease>;
+}
+
+/** session中に1つのleaseを保持し、jsqrのscanFrameでポーリングする走査器。*/
+export interface QrScanPort {
+  /**
+   * 1件のQRテキストを取得する。abort されたら AbortError を投げる。
+   * 同じテキストを連続で返さないための抑制は行わない（重複はassemblerが吸収する）。
+   */
+  scanOnce(options: {
+    cameraId: string;
+    signal: AbortSignal;
+    intervalMilliseconds?: number;
+  }): Promise<string>;
+  /** session終了時に呼ぶ。保持中のleaseを解放する。*/
+  release(): Promise<void>;
+}
+
+/** 一時skinの退避・復元（FR-3.5）。移設元 TemporarySpriteSkinManager と同一契約。*/
+export interface DisplayPort {
+  validateTarget(target: TurboWarpTarget | undefined): TurboWarpTarget;
+  show(target: TurboWarpTarget | undefined, svg: string): void;
+  releaseTarget(target: TurboWarpTarget): void;
+  releaseAll(): void;
+  isDisplaying(target: TurboWarpTarget): boolean;
+}
+
+/** 単調時計。壁時計に依存しない期限判定に使う（FR-4.6）。*/
+export interface MonotonicClock {
+  nowMilliseconds(): number;
+}
+
+/* ============================================================================
+ * src/pairing/session.ts  — 1 exchange の状態
+ * ==========================================================================*/
+
+export interface PairingSessionOptions {
+  readonly sessionKey: string;
+  readonly role: PairingRole;
+  readonly localPeerId: string;
+  /** hub では必須。camera では空でよく、Offer受理時に確定する。*/
+  readonly remotePeerId: string;
+  readonly timeoutSeconds: number;
+  readonly errorCorrectionLevel: QrErrorCorrectionLevel;
+}
+
+export interface PairingSessionState {
+  readonly options: PairingSessionOptions;
+  phase: PairingPhase;
+  /** 世代番号。cancel / retry / expire / dispose で加算される（FR-4.4）。*/
+  epoch: number;
+  exchangeId: string;
+  /** 自分が送出したメッセージのID。hubならOffer、cameraならAnswer。*/
+  outgoingMessageId: string;
+  /** 受理した相手メッセージのID。*/
+  incomingMessageId: string;
+  outgoing: QrParts | undefined;
+  outgoingSvgs: readonly string[];
+  outgoingCurrentIndex: number;
+  assembler: PartAssembler | undefined;
+  /** WebRTCへ引き渡し済みか。二重引渡しを防ぐ（FR-1.2）。*/
+  delivered: boolean;
+  startedAtMonotonic: number;
+  errorCode: PairingErrorCode | '';
+  errorMessage: string;
+}
+
+/* ============================================================================
+ * src/pairing/controller.ts  — 公開API（extension.ts はこれを薄く包む）
+ * ==========================================================================*/
+
+export interface PairingControllerOptions {
+  readonly runtime: TurboWarpRuntime;
+  readonly enabled?: boolean;
+  readonly errorCorrectionLevel?: QrErrorCorrectionLevel;
+  readonly webrtc?: WebRtcPairingPort;
+  readonly scan?: QrScanPort;
+  readonly display?: DisplayPort;
+  readonly clock?: MonotonicClock;
+}
+
+export declare class PairingController {
+  constructor(options: PairingControllerOptions);
+
+  // --- 開始・終了（FR-4.3） ---
+  startOfferPairing(input: {
+    sessionKey: string;
+    localPeerId: string;
+    remotePeerId: string;
+  }): Promise<void>;
+  startAnswerPairing(input: {
+    sessionKey: string;
+    /** 空なら Offer の targetPeerId を採用。非空なら一致検証する。*/
+    expectedLocalPeerId: string;
+  }): void;
+  cancelPairing(sessionKey: string): void;
+  retryPairing(sessionKey: string): Promise<void>;
+  setTimeoutSeconds(sessionKey: string, seconds: number): void;
+
+  // --- 受信（FR-2, FR-3.3） ---
+  /** デコード済み文字列の正規入口。完了時は内部でWebRTCへ1回だけ引き渡す。*/
+  ingestQrText(sessionKey: string, text: string): Promise<void>;
+  /** カメラ走査。全part受信・取消・期限のいずれかまでブロックする。*/
+  scanFromCamera(sessionKey: string, cameraId: string): Promise<void>;
+
+  // --- 表示（FR-3.1） ---
+  showPart(sessionKey: string, oneBasedIndex: number, target: TurboWarpTarget | undefined): void;
+  showNextPart(sessionKey: string, target: TurboWarpTarget | undefined): void;
+  partSvg(sessionKey: string, oneBasedIndex: number): string;
+  endDisplay(sessionKey: string): void;
+
+  // --- 観測（FR-4.1, FR-4.2） ---
+  progress(sessionKey: string): PairingProgress;
+  sessionKeys(): readonly string[];
+  isConnected(sessionKey: string): boolean;
+  /** 接続成立・失敗・取消・期限まで待つ。*/
+  waitUntilConnected(sessionKey: string): Promise<void>;
+
+  // --- ライフサイクル（FR-4.8） ---
+  /** PROJECT_RUN_STOP 相当。表示とleaseを解放し、進行中sessionを取り消す。*/
+  stopTransient(): void;
+  /** RUNTIME_DISPOSED 相当。全解放とリスナ解除。*/
+  dispose(): void;
+}
+
+/* ============================================================================
+ * src/config/feature-flags.ts（NFR-3）
+ * ==========================================================================*/
+
+export interface QrPairingFeatureFlags {
+  readonly qrCodePairing: boolean;
+}
+
+interface FeatureFlagGlobal {
+  readonly __TWQP_FEATURE_FLAGS__?: Partial<QrPairingFeatureFlags>;
+}
+
+/** 起動時に一度だけ評価し freeze する。既定 OFF。*/
+export declare const featureFlags: QrPairingFeatureFlags;
+
+/* ============================================================================
+ * src/config/qr-config.ts
+ * ==========================================================================*/
+
+interface QrConfigGlobal {
+  readonly __TWQP_QR_CONFIG__?: {
+    readonly errorCorrectionLevel?: QrErrorCorrectionLevel;
+  };
+}
+
+/** 起動時固定。既定 'M'。*/
+export declare const qrConfig: { readonly errorCorrectionLevel: QrErrorCorrectionLevel };