@kubohiroya/turbowarp-webrtc-qrcode-pairing 0.1.0 → 0.2.0

package/README.ja.md

@@ -8,14 +8,14 @@ QRコードを使ってWebRTCの接続情報を交換するTurboWarp拡張です
 
 ## できること
 
-- WebRTCのOfferとAnswerをQR搬送用の形式に符号化し、大きい場合は複数のQRに分割します。
-- スプライト上に1つずつ表示します。投影された各partを担当者が静止画で撮影できます。
-- 読み取ったpartを順不同で受け付け、同じpartの重複読取りを許容し、未取得のpartを報告します。
+- WebRTCのOfferとAnswerを連結QRコード（Structured Append、ISO/IEC 18004）として符号化します。QRの規格自身が定める、1つのメッセージを最大16枚に分ける方式です。
+- スプライト上に1枚ずつ表示します。統合側端末はOfferのQRをコマ送りでループ表示できます。
+- 読み取ったQRを順不同で受け付け、同じQRの重複読取りを許容し、別の連結QRの読取りは報告して無視し、未取得のQRを報告します。
 - 長さとハッシュを検証してからWebRTCへ渡し、検証済みの接続情報を一度だけ引き渡します。
 - Answerがどの Offer への応答かを追跡し、2台のカメラ側端末の接続情報が入れ替わらないようにします。
 - 搬送の進捗と接続状態を別々の状態として報告します。エラー、取消、再試行、期限にも対応します。
 
-`0.1.0`はローカルのパッケージ情報であり、npmへの公開済みバージョンを示すものではありません。
+`0.2.0`では、メッセージを連結QRコードで運び、1枚のQRを既定でOfferはversion 15、Answerはversion 20までに抑え、読んだペアリング用のQRをすべて報告します。`turbowarp-jsqr` 0.4.0以降が必要です。npmに公開済みなのは`0.1.0`です。
 
 > [!NOTE]
 > ペアリング用ブロックは起動時固定のフィーチャーフラグの内側にあり、既定は無効です。
@@ -37,15 +37,16 @@ QRコードを使ってWebRTCの接続情報を交換するTurboWarp拡張です
 3. 担当者がスマートフォンでAnswerを撮影し、統合側端末まで画像を運ぶ。
 4. 統合側端末のカメラで画像を読み取り、Answerを受理して接続成立を確認する。
 
-複数QRの場合は必要な各部分を搬送します。スマートフォンは接続情報を光学的に運び、接続成立後のカメラデータはWebRTC経由で送ります。担当者への案内や投影画面の構成は利用アプリが担当します。
+Offerは統合側端末がループ表示し、カメラ側端末は順不同で全部そろうまで読み取ります。Answerも複数枚の場合は各QRを搬送します。スマートフォンは接続情報を光学的に運び、接続成立後のカメラデータはWebRTC経由で送ります。担当者への案内や投影画面の構成は利用アプリが担当します。
 
 ## パッケージ間の責務
 
 | パッケージ | 責務 |
 |---|---|
 | `turbowarp-webrtc` | Offer／Answerの生成・受理、ICE、WebRTC接続 |
-| 本パッケージ | QR搬送形式、分割表示・再構成、ペアリングの進行 |
-| `turbowarp-jsqr` | カメラ画像からのQR読取り |
+| 本パッケージ | ペアリング用メッセージの形式、そのQRの表示と収集、ペアリングの進行 |
+| `qrcode-structured-append` | 連結QRコードの作成と結合。拡張ではなくライブラリ |
+| `turbowarp-jsqr` | カメラ画像からのQR読取り。連結QRコードの位置も読む |
 | `turbowarp-camera-source` | カメラ取得とフレームへのアクセス |
 | `turbowarp-time-space-sync` | 光学的な時刻対応の推定、カメラ配置の校正 |
 | `turbowarp-time-space-sync-app` | time-space-sync拡張の検証用アプリ |
@@ -59,13 +60,17 @@ QRコードを使ってWebRTCの接続情報を交換するTurboWarp拡張です
 
 ## 搬送形式
 
-QR partは`twqr/1`のenvelopeを使います。protocol、session、送信側と受信側のpeer名、メッセージ種別、message ID、reply-to、part indexとcount、メッセージ長、SHA-256ハッシュ、payloadを含みます。
+ペアリング用メッセージは`twqr/2`形式のテキストです。protocol、JSONのheader、接続情報を1行ずつ並べます。headerには、session、送信側と受信側のpeer名、メッセージ種別、message ID、reply-to、接続情報の長さとSHA-256ハッシュを含みます。
 
-ハッシュは光学搬送での破損を検出するためのもので、認証ではありません。QRを撮影できる人は誰でも同じ値を計算できます。投影された接続情報は、その投影を見られる全員に見えているものとして扱ってください。
+メッセージは1つの連結QRコードとして運びます。作成には[`@kubohiroya/qrcode-structured-append`](https://github.com/kubohiroya/qrcode-structured-append)を使います。各QRは規格のheaderに自分の位置、枚数、連結QRのparityを持つため、本拡張独自の包みなしに、読み手はどのQRを読んだかが分かります。headerの行が先頭にあるため、連結QRの1枚目だけで誰宛てのメッセージかが分かります。
 
-`turbowarp-realtime-motion-capture`の`twmp-qr/1`が出発点ですが、両者は相互運用しません。`twmp-qr/1`はpeer名を1つしか持たずreply-toもないため、本拡張が必要とするpeerの対応付けとAnswerの追跡を表現できません。`twmp-qr/1`のQRは互換モードで受理せず`unsupported-protocol`として拒否します。曖昧な受理は誤った端末同士の接続につながりうるためです。
+読取りは連結QR単位です。最初に読んだQRが収集する連結QRを決め、それ以外の連結QRのQRは`foreign`として報告して無視します。ただし収集中の連結QRの1枚目をまだ読んでいない間は、この交換に属する1枚目が読まれれば入れ替えます。古い投影のQRが1枚写り込んでも、正しいOfferの収集を妨げないためです。別の交換のものや破損していたと分かった連結QRは破棄し、表示が続いているQRから集め直します。
 
-上限は、64 part、1 partあたりpayload 4096文字、1メッセージ131072文字です。payloadを印字可能ASCIIに限定しているため、文字数とバイト数は一致します。誤り訂正レベルMではpart数が先に上限となり、およそ126000文字が実効上限です。
+parityは連結QRをまとめるだけのもので、256回に1回は一致してしまいます。光学搬送での破損や混在を検出するのはheader内のハッシュです。これは認証ではありません。QRを撮影できる人は誰でも同じ値を計算できます。投影された接続情報は、その投影を見られる全員に見えているものとして扱ってください。
+
+QRごとにJSONのenvelopeを入れていた`twqr/1`と、`turbowarp-realtime-motion-capture`の`twmp-qr/1`は、この形式と相互運用せず、`unsupported-protocol`として拒否します。
+
+上限は、1メッセージ16枚（連結QRコードの規格上の上限）、接続情報32768文字です。約1,250文字のOfferはversion 15のQR約4枚になり、文字数の上限より先にversionの上限が効きます。
 
 ## フィーチャーフラグと切戻し
 
@@ -79,12 +84,14 @@ globalThis.__TWQP_FEATURE_FLAGS__ = {qrCodePairing: true};
 
 切り戻すときはフラグの設定をやめ、`turbowarp-webrtc`のブロック（`create offer code`、`accept offer code`、`answer code`、`accept answer code`）で直接ペアリングします。フラグの無効化は経路の選択であり、成立済みの接続を切断することはありません。
 
-誤り訂正レベルも同じ方法で起動時に固定できます。
+誤り訂正レベルと、方向ごとに1枚のQRが使えるversionの上限も、同じ方法で起動時に固定できます。
 
 ```js
-globalThis.__TWQP_QR_CONFIG__ = {errorCorrectionLevel: 'Q'};
+globalThis.__TWQP_QR_CONFIG__ = {errorCorrectionLevel: 'M', offerMaxVersion: 15, answerMaxVersion: 20};
 ```
 
+上限（1〜40）は、1枚のQRをどこまで細かくしてよいかを決めます。Offer全体を1枚にしたversion 29〜32のQRは、投影をカメラで読むには画面の大半を占める必要があります。Offerは既定でversion 15、約4枚で、統合側端末が自動でループ表示し、測定したすべての条件でカメラが読めました。Answerは既定でversion 20、担当者が手で切り替える約2枚です。
+
 ## 開発と確認
 
 Node.js >=22.18.0、pnpm 11.11.0を利用します。
@@ -104,7 +111,7 @@ pnpm run dev
 ## 必要な環境と注意
 
 - Node.js >=22.18.0、pnpm 11.11.0。
-- 併用する拡張: 接続は`turbowarp-webrtc`、QRのデコードは`turbowarp-jsqr`、カメラフレームは`turbowarp-camera-source`。本拡張より先に読み込んでください。
+- 併用する拡張: 接続は`turbowarp-webrtc`、QRのデコードは`turbowarp-jsqr` 0.4.0以降、カメラフレームは`turbowarp-camera-source`。本拡張より先に読み込んでください。それより前の`turbowarp-jsqr`はテキストしか返さないため、`qr-decoder-missing`として拒否します。
 - `turbowarp-webrtc`はruntime capability v3（`acceptOffer`、`getAnswer`、`acceptAnswer`、`connectionState`、`hasPeer`、`closePeer`）を公開している必要があります。0.4.0以降が該当します。0.3.0以前はv2までで、Offerは作れても受理できないため往復を完結できません。
 - QRで接続情報を運べたことは、接続が到達可能であることを意味しません。ネットワーク条件、ICE、STUN／TURNは`turbowarp-webrtc`の責務です。
 

package/README.md

@@ -8,14 +8,14 @@ A TurboWarp extension for exchanging WebRTC connection information through QR co
 
 ## What it does
 
-- Encodes a WebRTC Offer or Answer into QR envelopes, splitting large ones across several codes.
-- Displays one part at a time on a sprite, so an operator can photograph each part of a projection.
-- Accepts decoded parts in any order, tolerates repeated readings, and reports which parts are still missing.
+- Encodes a WebRTC Offer or Answer as a Structured Append sequence (ISO/IEC 18004), the QR standard's own way of splitting one message across up to 16 codes.
+- Displays one code at a time on a sprite, so the integration machine can cycle the Offer codes in a loop.
+- Reads the codes in any order, tolerates repeated readings, reports codes of other sequences and ignores them, and reports which codes are still missing.
 - Verifies length and hash before a code reaches WebRTC, and hands each verified code over exactly once.
 - Tracks which offer an answer replies to, so two camera machines never receive each other's connection.
 - Reports transport progress and connection state as separate states, plus errors, cancellation, retry and deadlines.
 
-Version 0.1.0 is local package metadata; it does not imply an npm release.
+Version 0.2.0 carries messages as Structured Append sequences, caps Offer codes at QR version 15 and Answer codes at 20, and reports every pairing code read. It needs `turbowarp-jsqr` 0.4.0 or later. 0.1.0 is the version published on npm.
 
 > [!NOTE]
 > The pairing blocks are behind a startup feature flag that is off by default. See
@@ -44,8 +44,9 @@ The smartphone carries signaling information optically. Camera data is sent over
 | Package | Responsibility |
 |---|---|
 | `turbowarp-webrtc` | Offer/Answer creation and acceptance, ICE and WebRTC connections |
-| `turbowarp-webrtc-qrcode-pairing` | QR transport protocol, multipart display/assembly and pairing orchestration |
-| `turbowarp-jsqr` | Decode QR codes from camera frames |
+| `turbowarp-webrtc-qrcode-pairing` | Pairing message format, display and collection of its codes, and pairing orchestration |
+| `qrcode-structured-append` | Creating and joining Structured Append sequences; a library, not an extension |
+| `turbowarp-jsqr` | Decode QR codes from camera frames, including Structured Append positions |
 | `turbowarp-camera-source` | Camera acquisition and frame access |
 | `turbowarp-time-space-sync` | Optical time correspondence and camera placement calibration |
 | `turbowarp-time-space-sync-app` | Verification app for the time-space-sync extension |
@@ -59,13 +60,17 @@ A pairing session cannot be handed from one app to another. Opening a different
 
 ## Transport format
 
-QR parts use the `twqr/1` envelope: protocol, session, sender and target peer names, message kind, message id, reply-to, part index and count, message length, SHA-256 hash and payload.
+A pairing message is text in the `twqr/2` format: the protocol, a JSON header, and the pairing code, one per line. The header names the session, the sender and target peers, the message kind, the message id, what it replies to, the code's length and its SHA-256 hash.
 
-The hash detects optical damage. It is not authentication: anyone who can photograph the codes can recompute it. Treat a projected pairing code as visible to everyone who can see the projection.
+The message is carried as one Structured Append sequence, made by [`@kubohiroya/qrcode-structured-append`](https://github.com/kubohiroya/qrcode-structured-append). Each code holds its position, the count and the sequence's parity in the standard header, so a reader knows which code it has without any wrapper of this extension's. The header line comes first, so the first code of a sequence already tells a reader whose message it is.
 
-`twmp-qr/1` from `turbowarp-realtime-motion-capture` is the format this one grew out of, but the two do not interoperate. `twmp-qr/1` carries a single peer name and no reply-to, so it cannot express the peer mapping and answer tracking this extension needs. A `twmp-qr/1` code is rejected with `unsupported-protocol` rather than accepted in a compatibility mode, because an ambiguous acceptance could pair the wrong machines.
+Reading goes by sequence. The first code read decides the sequence being collected; codes of any other sequence are reported as `foreign` and ignored. Until the first code of that sequence has been read, a first code that belongs to this exchange replaces it, so a stray code of an old projection cannot block the right one. A sequence that turns out to be another exchange's, or damaged, is dropped and collected again from the codes still being shown.
 
-Limits: at most 64 parts, 4096 payload characters per part, and 131072 characters per message. Character counts equal byte counts because payloads are printable ASCII. At error correction level M the binding limit is the part count, which allows about 126000 characters.
+The parity only groups codes and collides one time in 256, so the hash in the header is what detects optical damage and mixed sequences. It is not authentication: anyone who can photograph the codes can recompute it. Treat a projected pairing code as visible to everyone who can see the projection.
+
+`twqr/1`, which put a JSON envelope into every code, and `twmp-qr/1` from `turbowarp-realtime-motion-capture` do not interoperate with this format and are rejected with `unsupported-protocol`.
+
+Limits: at most 16 codes per message, the Structured Append limit, and 32768 characters per pairing code. A pairing offer of about 1,250 characters is about four version 15 codes; the version cap binds long before the character limit.
 
 ## Feature flag and rollback
 
@@ -79,16 +84,18 @@ Set it before the extension loads. While the flag is off, `getInfo` publishes no
 
 To roll back, stop setting the flag and pair with the `turbowarp-webrtc` blocks directly: `create offer code`, `accept offer code`, `answer code` and `accept answer code`. Turning the flag off selects the other route; it never disconnects an established connection.
 
-Error correction level can be fixed at startup the same way:
+Error correction level and the largest QR version each direction uses can be fixed at startup the same way:
 
 ```js
-globalThis.__TWQP_QR_CONFIG__ = {errorCorrectionLevel: 'Q'};
+globalThis.__TWQP_QR_CONFIG__ = {errorCorrectionLevel: 'M', offerMaxVersion: 15, answerMaxVersion: 20};
 ```
 
+The caps (1 to 40) decide how fine each code gets. A single version 29-32 code for a whole offer is read off a projection only when it fills most of the frame. Offer codes default to version 15, about four codes that the integration machine cycles automatically and a camera read under every measured condition; Answer codes default to version 20, about two codes an operator turns by hand.
+
 ## Requirements and safety
 
 - Node.js >=22.18.0 and pnpm 11.11.0.
-- Companion extensions: `turbowarp-webrtc` for the connection, `turbowarp-jsqr` for decoding and `turbowarp-camera-source` for camera frames. Load them before this one.
+- Companion extensions: `turbowarp-webrtc` for the connection, `turbowarp-jsqr` 0.4.0 or later for decoding and `turbowarp-camera-source` for camera frames. Load them before this one. Earlier `turbowarp-jsqr` versions return text only and are refused with `qr-decoder-missing`.
 - `turbowarp-webrtc` must publish runtime capability v3, which adds `acceptOffer`, `getAnswer`, `acceptAnswer`, `connectionState`, `hasPeer` and `closePeer`. Version 0.4.0 publishes it; 0.3.0 and earlier publish v2, which can produce an offer but not accept one, so a round trip cannot complete.
 - Carrying a code by QR does not make a connection reachable. Network conditions, ICE and STUN/TURN belong to `turbowarp-webrtc`.
 
@@ -109,7 +116,7 @@ pnpm run dev
 
 Build output: `dist/webrtc-qrcode-pairing.js` and `dist/extension-manifest.json`. Load the JavaScript file as a custom TurboWarp extension. The manifest always records every declared block, including blocks the feature flag hides at runtime: it is the build-time contract, not the runtime state.
 
-Package name and version for future consumers (not a claim of publication): `@kubohiroya/turbowarp-webrtc-qrcode-pairing@0.1.0`.
+Package name and version: `@kubohiroya/turbowarp-webrtc-qrcode-pairing@0.2.0` (0.1.0 is the latest published on npm).
 
 ## Block reference
 
@@ -117,7 +124,7 @@ Package name and version for future consumers (not a claim of publication): `@ku
 
 ### `start offer pairing [SESSION] as [LOCAL_PEER] to [REMOTE_PEER]`
 
-Creates a WebRTC offer for the integration machine and prepares its QR parts.
+Creates a WebRTC offer for the integration machine and prepares it as a Structured Append sequence of QR codes.
 
 | Property | Value |
 |---|---|
@@ -138,9 +145,9 @@ Waits for an offer on the camera machine. Leave the name empty to adopt the name
 | `SESSION` | String, default: `pairing-1` |
 | `LOCAL_PEER` | String, default: `` |
 
-### `receive pairing QR text [TEXT] for [SESSION]`
+### `receive pairing message [TEXT] for [SESSION]`
 
-Accepts one decoded QR text. Repeated readings of the same part are ignored.
+Accepts a whole pairing message as text, such as one pasted or carried some other way. Camera scanning reads the QR codes of a sequence itself.
 
 | Property | Value |
 |---|---|
@@ -151,7 +158,7 @@ Accepts one decoded QR text. Repeated readings of the same part are ignored.
 
 ### `scan pairing QR for [SESSION] from camera [CAMERA_ID]`
 
-Reads parts from the named camera until the exchange has every part it needs.
+Reads QR codes from the named camera, in any order, until the exchange has every code of the sequence. Codes of other sequences are reported and ignored.
 
 | Property | Value |
 |---|---|
@@ -162,7 +169,7 @@ Reads parts from the named camera until the exchange has every part it needs.
 
 ### `received parts of [SESSION]`
 
-Returns how many distinct parts have been accepted.
+Returns how many distinct codes of the incoming sequence have been read.
 
 | Property | Value |
 |---|---|
@@ -172,7 +179,7 @@ Returns how many distinct parts have been accepted.
 
 ### `required parts of [SESSION]`
 
-Returns how many parts the incoming message has, or zero before the first part arrives.
+Returns how many codes the incoming sequence has, or zero before the first code arrives.
 
 | Property | Value |
 |---|---|
@@ -182,7 +189,7 @@ Returns how many parts the incoming message has, or zero before the first part a
 
 ### `missing parts of [SESSION]`
 
-Returns the one-based part numbers that have not been read yet, separated by commas.
+Returns the one-based code numbers that have not been read yet, separated by commas.
 
 | Property | Value |
 |---|---|
@@ -190,9 +197,39 @@ Returns the one-based part numbers that have not been read yet, separated by com
 | Opcode | `pairingMissingParts` |
 | `SESSION` | String, default: `pairing-1` |
 
+### `pairing QR reads of [SESSION]`
+
+Returns how many pairing QR codes this session has read, of any result. It rises by one per read, so a change means there is a new result to show.
+
+| Property | Value |
+|---|---|
+| Type | Reporter |
+| Opcode | `pairingReadCount` |
+| `SESSION` | String, default: `pairing-1` |
+
+### `last pairing QR read of [SESSION]`
+
+Returns what the latest pairing QR code was: accepted (a new code of the sequence), duplicate (a code already read), foreign (a code this exchange cannot use, which is ignored), or an empty string before the first read. QR codes that are not pairing codes are not reported.
+
+| Property | Value |
+|---|---|
+| Type | Reporter |
+| Opcode | `pairingLastRead` |
+| `SESSION` | String, default: `pairing-1` |
+
+### `last pairing QR read detail of [SESSION]`
+
+Returns the code as "2 / 4" for accepted and duplicate reads, or why a foreign code was ignored as an error code such as message-mismatch (another sequence), stale-exchange or peer-mismatch.
+
+| Property | Value |
+|---|---|
+| Type | Reporter |
+| Opcode | `pairingLastReadDetail` |
+| `SESSION` | String, default: `pairing-1` |
+
 ### `show pairing QR part [INDEX] of [SESSION] on this sprite`
 
-Shows the selected one-based part using a temporary sprite skin.
+Shows the selected one-based code of the sequence using a temporary sprite skin.
 
 | Property | Value |
 |---|---|
@@ -203,7 +240,7 @@ Shows the selected one-based part using a temporary sprite skin.
 
 ### `show next pairing QR part of [SESSION] on this sprite`
 
-Shows the next part and wraps from the last part back to the first.
+Shows the next code and wraps from the last back to the first, so a loop with a short wait cycles the whole sequence.
 
 | Property | Value |
 |---|---|
@@ -213,7 +250,7 @@ Shows the next part and wraps from the last part back to the first.
 
 ### `pairing QR part count of [SESSION]`
 
-Returns how many parts are prepared for display, or zero when none are.
+Returns how many codes are prepared for display, or zero when none are.
 
 | Property | Value |
 |---|---|
@@ -223,7 +260,7 @@ Returns how many parts are prepared for display, or zero when none are.
 
 ### `current pairing QR part of [SESSION]`
 
-Returns the one-based part selected for display, or zero when none is selected.
+Returns the one-based code selected for display, or zero when none is selected.
 
 | Property | Value |
 |---|---|
@@ -233,7 +270,7 @@ Returns the one-based part selected for display, or zero when none is selected.
 
 ### `pairing QR part [INDEX] of [SESSION] as SVG`
 
-Returns the part as SVG markup so a project can display it its own way.
+Returns the code as SVG markup so a project can display it its own way.
 
 | Property | Value |
 |---|---|
@@ -244,7 +281,7 @@ Returns the part as SVG markup so a project can display it its own way.
 
 ### `pairing QR part [INDEX] of [SESSION] as data URI`
 
-Returns the part as a base64 SVG data URI for costumes and HTML images.
+Returns the code as a base64 SVG data URI for costumes and HTML images.
 
 | Property | Value |
 |---|---|

package/dist/extension-manifest.json

@@ -86,6 +86,26 @@
         }
       ]
     },
+    {
+      "opcode": "pairingLastRead",
+      "blockType": "REPORTER",
+      "arguments": [
+        {
+          "id": "SESSION",
+          "type": "STRING"
+        }
+      ]
+    },
+    {
+      "opcode": "pairingLastReadDetail",
+      "blockType": "REPORTER",
+      "arguments": [
+        {
+          "id": "SESSION",
+          "type": "STRING"
+        }
+      ]
+    },
     {
       "opcode": "pairingLocalPeer",
       "blockType": "REPORTER",
@@ -164,6 +184,16 @@
         }
       ]
     },
+    {
+      "opcode": "pairingReadCount",
+      "blockType": "REPORTER",
+      "arguments": [
+        {
+          "id": "SESSION",
+          "type": "STRING"
+        }
+      ]
+    },
     {
       "opcode": "pairingReceivedParts",
       "blockType": "REPORTER",