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

package/README.ja.md

@@ -15,7 +15,7 @@ QRコードを使ってWebRTCの接続情報を交換するTurboWarp拡張です
 - Answerがどの Offer への応答かを追跡し、2台のカメラ側端末の接続情報が入れ替わらないようにします。
 - 搬送の進捗と接続状態を別々の状態として報告します。エラー、取消、再試行、期限にも対応します。
 
-`0.2.0`では、メッセージを連結QRコードで運び、1枚のQRを既定でOfferはversion 15、Answerはversion 20までに抑え、読んだペアリング用のQRをすべて報告します。`turbowarp-jsqr` 0.4.0以降が必要です。npmに公開済みなのは`0.1.0`です。
+`0.2.0`では、メッセージを連結QRコードで運び、1枚のQRを既定でOfferはversion 15、Answerはversion 20までに抑え、読んだペアリング用のQRをすべて報告します。`turbowarp-jsqr` 0.4.0以降が必要です。`0.2.1`では、QRがカメラに写り続けている間の読取りがページの処理を止めてしまう不具合を直しました。`0.2.2`では、1枚目に収まらないheaderを先頭から続くQRで読み、読取りを1つずつ処理して接続情報を一度だけ渡し、規格に合わないQRを読んでも集めていたものを消さないようにしました。
 
 > [!NOTE]
 > ペアリング用ブロックは起動時固定のフィーチャーフラグの内側にあり、既定は無効です。
@@ -62,9 +62,9 @@ Offerは統合側端末がループ表示し、カメラ側端末は順不同で
 
 ペアリング用メッセージは`twqr/2`形式のテキストです。protocol、JSONのheader、接続情報を1行ずつ並べます。headerには、session、送信側と受信側のpeer名、メッセージ種別、message ID、reply-to、接続情報の長さとSHA-256ハッシュを含みます。
 
-メッセージは1つの連結QRコードとして運びます。作成には[`@kubohiroya/qrcode-structured-append`](https://github.com/kubohiroya/qrcode-structured-append)を使います。各QRは規格のheaderに自分の位置、枚数、連結QRのparityを持つため、本拡張独自の包みなしに、読み手はどのQRを読んだかが分かります。headerの行が先頭にあるため、連結QRの1枚目だけで誰宛てのメッセージかが分かります。
+メッセージは1つの連結QRコードとして運びます。作成には[`@kubohiroya/qrcode-structured-append`](https://github.com/kubohiroya/qrcode-structured-append)を使います。各QRは規格のheaderに自分の位置、枚数、連結QRのparityを持つため、本拡張独自の包みなしに、読み手はどのQRを読んだかが分かります。headerの行が先頭にあるため、全部そろう前に、先頭のQRで誰宛てのメッセージかが分かります。既定の設定では1枚目だけで、QRが小さいときや誤り訂正が高いときは先頭の数枚で分かります。
 
-読取りは連結QR単位です。最初に読んだQRが収集する連結QRを決め、それ以外の連結QRのQRは`foreign`として報告して無視します。ただし収集中の連結QRの1枚目をまだ読んでいない間は、この交換に属する1枚目が読まれれば入れ替えます。古い投影のQRが1枚写り込んでも、正しいOfferの収集を妨げないためです。別の交換のものや破損していたと分かった連結QRは破棄し、表示が続いているQRから集め直します。
+読取りは連結QR単位です。最初に読んだQRが収集する連結QRを決め、それ以外の連結QRのQRは`foreign`として報告して無視します。ただし収集中の連結QRのheaderをまだ読めていない間は、別の連結QRのQRも脇で集め、そのheaderからこの交換のものと分かれば入れ替えます。古い投影のQRが1枚写り込んでも、正しいOfferの収集を妨げないためです。別の交換のものや破損していたと分かった連結QRは破棄し、表示が続いているQRから集め直します。
 
 parityは連結QRをまとめるだけのもので、256回に1回は一致してしまいます。光学搬送での破損や混在を検出するのはheader内のハッシュです。これは認証ではありません。QRを撮影できる人は誰でも同じ値を計算できます。投影された接続情報は、その投影を見られる全員に見えているものとして扱ってください。
 

package/README.md

@@ -15,7 +15,7 @@ A TurboWarp extension for exchanging WebRTC connection information through QR co
 - 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.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.
+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.2.1 fixes a camera scan that starved the page while a code stayed in view. 0.2.2 reads a header that runs past the first code, takes reads one at a time so a code is handed over once, and keeps a sequence when a malformed code is read.
 
 > [!NOTE]
 > The pairing blocks are behind a startup feature flag that is off by default. See
@@ -62,9 +62,9 @@ A pairing session cannot be handed from one app to another. Opening a different
 
 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 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.
+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 leading codes of a sequence tell a reader whose message it is before the rest arrive: the first code alone at the default settings, the first few when codes are small or the error correction is high.
 
-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.
+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 that sequence's header has been read, codes of another sequence are collected on the side, and if their header shows they belong to this exchange they replace 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.
 
 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.
 
@@ -116,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: `@kubohiroya/turbowarp-webrtc-qrcode-pairing@0.2.0` (0.1.0 is the latest published on npm).
+Package name and version: `@kubohiroya/turbowarp-webrtc-qrcode-pairing@0.2.2`.
 
 ## Block reference
 

package/dist/webrtc-qrcode-pairing.js

@@ -3021,30 +3021,43 @@
   	if (await sha256Base64Url(message.payload) !== message.header.messageHash) throw new QrPairingError("hash-mismatch", "The pairing code failed its hash check.");
   	return message;
   }
-  /** The header, if the given first code of a sequence holds all of it. */
-  function headerOfFirstCode(read) {
-  	return parseHeader(latin1(read.bytes));
-  }
   /**
   * Collects the codes of one pairing message, in any order.
   *
-  * The first code read decides the sequence. Until the first code of that
-  * sequence has shown whose message it is, another sequence whose first code
-  * does belong to this exchange may take its place: a camera may well see an
-  * old projection before the right one.
+  * The first code read decides the sequence. The header comes first in the
+  * message, so the codes from the first onwards tell whose message it is before
+  * all of them have arrived — in the first code alone at the default settings,
+  * across the first few when codes are small or the error correction is high.
   */
   var PairingAssembler = class {
   	constructor() {
   		this.inner = new StructuredAppendAssembler();
+  		this.shares = /* @__PURE__ */ new Map();
   		this.headerVerified = false;
   	}
   	/** Throws `conflicting-part` for a position that arrives twice with different content. */
   	add(read) {
+  		let outcome;
   		try {
-  			return this.inner.add(read);
+  			outcome = this.inner.add(read);
   		} catch (error) {
   			throw translate(error);
   		}
+  		if (outcome.result === "accepted") this.shares.set(read.index, read.bytes);
+  		return outcome;
+  	}
+  	/**
+  	* The header, once the codes from the first onwards hold all of it.
+  	* Undefined while they do not; throws as soon as they cannot be a pairing
+  	* message, or the header is malformed.
+  	*/
+  	header() {
+  		let prefix = "";
+  		for (let index = 0; this.shares.has(index); index += 1) prefix += latin1(this.shares.get(index) ?? /* @__PURE__ */ new Uint8Array());
+  		return prefix === "" ? void 0 : parseHeader(prefix);
+  	}
+  	isEmpty() {
+  		return this.inner.received() === 0;
   	}
   	receivedCount() {
   		return this.inner.received();
@@ -3072,6 +3085,7 @@
   	}
   	clear() {
   		this.inner.clear();
+  		this.shares.clear();
   		this.headerVerified = false;
   	}
   };
@@ -3207,6 +3221,7 @@
   		this.runtime = runtime;
   		this.owner = owner;
   		this.leasedCameraId = "";
+  		this.nextReadAt = 0;
   	}
   	async scanOnce(options) {
   		if (options.signal.aborted) throw cancelled();
@@ -3244,6 +3259,7 @@
   				}
   				if (settled) return;
   				if (read !== null) {
+  					this.nextReadAt = Date.now() + interval;
   					cleanup();
   					resolve(read);
   					return;
@@ -3251,7 +3267,7 @@
   				timer = setTimeout(() => void tick(), interval);
   			};
   			options.signal.addEventListener("abort", onAbort, { once: true });
-  			tick();
+  			timer = setTimeout(() => void tick(), Math.max(0, this.nextReadAt - Date.now()));
   		});
   	}
   	async release() {
@@ -3417,13 +3433,35 @@
   	*
   	* A lone code — one that is not part of a sequence — is read as a whole
   	* message, the way `ingestQrText` reads one.
+  	*
+  	* Reads of one session are taken one at a time, in the order they came, so
+  	* two scripts feeding codes at once cannot both complete the message.
   	*/
   	async ingestQrRead(sessionKey, read) {
   		this.requireEnabled();
-  		const session = this.requireReceiving(sessionKey);
+  		const session = this.requireSession(sessionKey);
+  		return this.inTurn(session, () => this.takeRead(session, read));
+  	}
+  	/**
+  	* Accepts a whole pairing message as text, the way it would arrive through
+  	* something other than a camera, or in one QR code.
+  	*/
+  	async ingestQrText(sessionKey, text) {
+  		this.requireEnabled();
+  		const session = this.requireSession(sessionKey);
+  		return this.inTurn(session, () => this.takeText(session, text));
+  	}
+  	/** Runs `work` after every read of the session that came before it has finished. */
+  	inTurn(session, work) {
+  		const turn = session.readQueue.then(work);
+  		session.readQueue = turn.catch(() => void 0);
+  		return turn;
+  	}
+  	async takeRead(session, read) {
+  		this.requireOpen(session);
   		const position = read.structuredAppend;
   		if (position === null) {
-  			await this.ingestQrText(sessionKey, read.text);
+  			await this.takeText(session, read.text);
   			return;
   		}
   		const symbol = {
@@ -3431,42 +3469,40 @@
   			bytes: read.bytes
   		};
   		const part = `${symbol.index + 1} / ${symbol.count}`;
-  		const assembler = session.assembler;
-  		let outcome;
-  		try {
-  			outcome = assembler.add(symbol);
-  			if (outcome.result === "foreign" && this.replacesUnverifiedSequence(session, symbol)) {
-  				assembler.clear();
-  				outcome = assembler.add(symbol);
+  		if (session.delivered) {
+  			let repeat = false;
+  			try {
+  				repeat = session.assembler.add(symbol).result === "duplicate";
+  			} catch (error) {
+  				if (!isReported(error)) throw error;
   			}
-  		} catch (error) {
-  			assembler.clear();
-  			this.noteRead(session, "foreign", codeOf(error));
-  			throw error;
+  			this.noteRead(session, repeat ? "duplicate" : "foreign", repeat ? part : "message-mismatch");
+  			throw alreadyAccepted();
   		}
+  		let outcome = this.addTo(session, session.assembler, symbol);
+  		if (outcome.result === "foreign" && !session.assembler.headerVerified) outcome = this.offerToCandidate(session, symbol) ?? outcome;
   		if (outcome.result === "foreign") {
   			this.noteRead(session, "foreign", "message-mismatch");
   			throw new QrPairingError("message-mismatch", "QR code belongs to another sequence than the one being collected.");
   		}
-  		if (session.delivered) {
-  			this.noteRead(session, "duplicate", part);
-  			throw alreadyAccepted();
-  		}
-  		if (outcome.result === "accepted" && symbol.index === 0) try {
-  			const header = headerOfFirstCode(symbol);
+  		const assembler = session.assembler;
+  		if (outcome.result === "accepted" && !assembler.headerVerified) try {
+  			const header = assembler.header();
   			if (header) {
   				this.verifyHeader(session, header);
   				assembler.headerVerified = true;
   			}
   		} catch (error) {
   			assembler.clear();
-  			if (error instanceof QrPairingError && unreportedCodes.has(error.code)) throw error;
+  			if (!isReported(error)) throw error;
   			this.noteRead(session, "foreign", codeOf(error));
   			throw error;
   		}
-  		this.noteRead(session, outcome.result, part);
   		session.phase = session.role === "hub" ? "awaiting-answer" : "receiving";
-  		if (!assembler.isComplete()) return;
+  		if (!assembler.isComplete()) {
+  			this.noteRead(session, outcome.result, part);
+  			return;
+  		}
   		const epoch = session.epoch;
   		let message;
   		try {
@@ -3480,15 +3516,11 @@
   			throw error;
   		}
   		assembler.headerVerified = true;
+  		this.noteRead(session, "accepted", part);
   		await this.deliver(session, message, epoch);
   	}
-  	/**
-  	* Accepts a whole pairing message as text, the way it would arrive through
-  	* something other than a camera, or in one QR code.
-  	*/
-  	async ingestQrText(sessionKey, text) {
-  		this.requireEnabled();
-  		const session = this.requireReceiving(sessionKey);
+  	async takeText(session, text) {
+  		this.requireOpen(session);
   		const epoch = session.epoch;
   		const message = await readPairingMessage(text);
   		if (this.isStale(session, epoch)) return;
@@ -3506,22 +3538,48 @@
   		await this.deliver(session, message, epoch);
   	}
   	/**
-  	* Whether a code of another sequence should replace the one being collected.
+  	* Adds a code to a sequence. A position read twice with different content
+  	* means this sequence is damaged, so it is dropped and collected again from
+  	* the codes still being shown. Anything else wrong with the code leaves the
+  	* sequence as it was.
+  	*/
+  	addTo(session, assembler, symbol) {
+  		try {
+  			return assembler.add(symbol);
+  		} catch (error) {
+  			if (codeOf(error) !== "conflicting-part") throw error;
+  			assembler.clear();
+  			this.noteRead(session, "foreign", "conflicting-part");
+  			throw error;
+  		}
+  	}
+  	/**
+  	* Collects a code of another sequence on the side, while the sequence held
+  	* has not shown whose it is. If the other sequence's header shows it is this
+  	* exchange's, it takes the place of the one held.
   	*
-  	* Only while the sequence held has not shown whose it is, and only by the
-  	* first code of a sequence that shows it is this exchange's. A camera that
-  	* first catches a stray code of an old projection would otherwise wait for
-  	* the rest of that old sequence forever.
+  	* A camera that first catches a stray code of an old projection would
+  	* otherwise wait for the rest of that old sequence forever. Returns the
+  	* outcome in the sequence that took over, or undefined when nothing changed.
   	*/
-  	replacesUnverifiedSequence(session, symbol) {
-  		if (symbol.index !== 0 || session.assembler.headerVerified || session.delivered) return false;
+  	offerToCandidate(session, symbol) {
+  		const candidate = session.candidate;
   		try {
-  			const header = headerOfFirstCode(symbol);
-  			if (!header) return false;
+  			let outcome = candidate.add(symbol);
+  			if (outcome.result === "foreign") {
+  				candidate.clear();
+  				outcome = candidate.add(symbol);
+  			}
+  			const header = candidate.header();
+  			if (!header) return void 0;
   			this.verifyHeader(session, header);
-  			return true;
+  			candidate.headerVerified = true;
+  			session.assembler = candidate;
+  			session.candidate = new PairingAssembler();
+  			return outcome;
   		} catch {
-  			return false;
+  			candidate.clear();
+  			return;
   		}
   	}
   	/** Hands a checked pairing code to WebRTC, once per exchange. */
@@ -3533,10 +3591,8 @@
   		if (session.role === "hub") await this.acceptAnswer(session, message.payload, epoch);
   		else await this.acceptOfferAndPrepareAnswer(session, message.payload, epoch);
   	}
-  	requireReceiving(sessionKey) {
-  		const session = this.requireSession(sessionKey);
+  	requireOpen(session) {
   		if (isTerminalPhase(session.phase)) throw new QrPairingError(session.phase === "connected" ? "already-accepted" : "stale-exchange", `Pairing session ${session.sessionKey} is no longer receiving codes.`);
-  		return session;
   	}
   	/** Records what a pairing code turned out to be, for the application to show. */
   	noteRead(session, result, detail) {
@@ -3859,6 +3915,8 @@
   			outgoingSvgs: [],
   			outgoingCurrentIndex: -1,
   			assembler: new PairingAssembler(),
+  			candidate: new PairingAssembler(),
+  			readQueue: Promise.resolve(),
   			delivered: false,
   			peerCreated: false,
   			timeoutMilliseconds: 6e5,
@@ -3885,6 +3943,7 @@
   		session.outgoingSvgs = [];
   		session.outgoingCurrentIndex = -1;
   		session.assembler = new PairingAssembler();
+  		session.candidate = new PairingAssembler();
   		session.delivered = false;
   		session.peerCreated = false;
   		session.startedAtMonotonic = this.clock.nowMilliseconds();
@@ -3944,6 +4003,7 @@
   		this.releaseDisplay(session);
   		if (!connected) {
   			session.assembler.clear();
+  			session.candidate.clear();
   			if (session.peerCreated) {
   				try {
   					this.webrtc().closePeer(session.remotePeerId);
@@ -4027,6 +4087,10 @@
   function alreadyAccepted() {
   	return new QrPairingError("already-accepted", "The pairing code for this exchange has already been accepted.");
   }
+  /** Whether a failure is about a pairing code, rather than about text that is not one at all. */
+  function isReported(error) {
+  	return !(error instanceof QrPairingError && unreportedCodes.has(error.code));
+  }
   //#endregion
   //#region src/extension.ts
   var blockDefinitions = block_definitions_default.blocks;

package/docs/integration-guide.ja.md

@@ -150,12 +150,13 @@ say (join (join (current pairing QR part of [pairing-1]) " / ") (pairing QR part
 害はありません。別の連結QRのQRは報告して無視し、交換は終わらせません。ポスターなど、ペアリング用
 ではないQRは何も言わずに読み飛ばします。
 
-最初に読んだQRで、どの連結QRを集めるかが決まります。各連結QRの1枚目にはheaderが入っているので、
-それを読めば誰宛てのメッセージかが分かります。
+最初に読んだQRで、どの連結QRを集めるかが決まります。headerはメッセージの先頭にあるので、先頭のQRを
+読めば誰宛てのメッセージかが分かります。既定の設定では1枚目だけで、QRが小さいときや誤り訂正が高いときは
+先頭の数枚で分かります。
 
 - 別の交換、別の相手、逆向きのものなら、その連結QRを破棄し、理由を付けて`foreign`と報告します。
-- 集めている連結QRの1枚目をまだ読んでいない間は、この交換に属する連結QRの1枚目が読まれれば、
-  そちらに入れ替えます。古い投影のQRが1枚写り込んでも、正しいOfferの収集を妨げません。
+- 集めている連結QRのheaderをまだ読めていない間は、別の連結QRのQRも脇で集め、そのheaderからこの交換の
+  ものと分かれば、そちらに入れ替えます。古い投影のQRが1枚写り込んでも、正しいOfferの収集を妨げません。
 - 全QRが揃うと、メッセージをハッシュで検査します。壊れていた連結QRは破棄して`foreign`
   （`hash-mismatch`）と報告し、表示が続いているQRから集め直します。
 

package/docs/integration-guide.md

@@ -156,14 +156,15 @@ Reading the same code repeatedly is normal and costs nothing. A code of another
 and ignored without ending the exchange. QR codes that are not pairing codes at all, such as a
 poster, are skipped without a word.
 
-The first code read decides which sequence the session collects. The first code of each sequence
-carries its header, so once that one is read the session knows whose message it is:
+The first code read decides which sequence the session collects. The header comes first in the
+message, so once the leading codes are read the session knows whose message it is — the first code
+alone at the default settings, the first few when codes are small or the error correction is high:
 
 - if it belongs to another exchange, another pair of peers or the other direction, the sequence is
   dropped and reported as `foreign` with the reason;
-- while the first code of the sequence being collected has not been read yet, the first code of a
-  sequence that does belong to this exchange takes its place. A stray code of an old projection
-  therefore cannot block the right one;
+- while the header of the sequence being collected has not been read yet, codes of another sequence
+  are collected on the side, and a sequence whose header shows it belongs to this exchange takes its
+  place. A stray code of an old projection therefore cannot block the right one;
 - when every code has arrived, the message is checked against its hash. A damaged sequence is
   dropped, reported as `foreign` with `hash-mismatch`, and collected again from the codes still being
   cycled.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-webrtc-qrcode-pairing",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "TurboWarp extension that pairs WebRTC peers by carrying offers and answers as QR codes.",
   "author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
   "license": "MPL-2.0",

package/src/pairing/controller.ts

@@ -5,7 +5,6 @@ import {QrPairingError, type PairingErrorCode} from '../errors.js';
 import type {AddOutcome, StructuredAppendRead} from '@kubohiroya/qrcode-structured-append';
 import {
   createPairingCodes,
-  headerOfFirstCode,
   PairingAssembler,
   readPairingMessage,
   type CreateCodesOptions,
@@ -186,32 +185,58 @@ export class PairingController {
    *
    * A lone code — one that is not part of a sequence — is read as a whole
    * message, the way `ingestQrText` reads one.
+   *
+   * Reads of one session are taken one at a time, in the order they came, so
+   * two scripts feeding codes at once cannot both complete the message.
    */
   public async ingestQrRead(sessionKey: string, read: QrRead): Promise<void> {
     this.requireEnabled();
-    const session = this.requireReceiving(sessionKey);
+    const session = this.requireSession(sessionKey);
+    return this.inTurn(session, () => this.takeRead(session, read));
+  }
+
+  /**
+   * Accepts a whole pairing message as text, the way it would arrive through
+   * something other than a camera, or in one QR code.
+   */
+  public async ingestQrText(sessionKey: string, text: string): Promise<void> {
+    this.requireEnabled();
+    const session = this.requireSession(sessionKey);
+    return this.inTurn(session, () => this.takeText(session, text));
+  }
+
+  /** Runs `work` after every read of the session that came before it has finished. */
+  private inTurn(session: PairingSessionState, work: () => Promise<void>): Promise<void> {
+    const turn = session.readQueue.then(work);
+    session.readQueue = turn.catch(() => undefined);
+    return turn;
+  }
+
+  private async takeRead(session: PairingSessionState, read: QrRead): Promise<void> {
+    this.requireOpen(session);
     const position = read.structuredAppend;
     if (position === null) {
-      await this.ingestQrText(sessionKey, read.text);
+      await this.takeText(session, read.text);
       return;
     }
     const symbol = {...position, bytes: read.bytes};
     const part = `${symbol.index + 1} / ${symbol.count}`;
-    const assembler = session.assembler;
 
-    let outcome: AddOutcome;
-    try {
-      outcome = assembler.add(symbol);
-      if (outcome.result === 'foreign' && this.replacesUnverifiedSequence(session, symbol)) {
-        assembler.clear();
-        outcome = assembler.add(symbol);
+    if (session.delivered) {
+      // The code has been handed over; a read can only be a repeat or something else.
+      let repeat = false;
+      try {
+        repeat = session.assembler.add(symbol).result === 'duplicate';
+      } catch (error) {
+        if (!isReported(error)) throw error;
       }
-    } catch (error) {
-      // A position read twice with different content: this sequence is damaged,
-      // so it is dropped and collected again from the codes still being shown.
-      assembler.clear();
-      this.noteRead(session, 'foreign', codeOf(error));
-      throw error;
+      this.noteRead(session, repeat ? 'duplicate' : 'foreign', repeat ? part : 'message-mismatch');
+      throw alreadyAccepted();
+    }
+
+    let outcome = this.addTo(session, session.assembler, symbol);
+    if (outcome.result === 'foreign' && !session.assembler.headerVerified) {
+      outcome = this.offerToCandidate(session, symbol) ?? outcome;
     }
     if (outcome.result === 'foreign') {
       this.noteRead(session, 'foreign', 'message-mismatch');
@@ -220,28 +245,28 @@ export class PairingController {
         'QR code belongs to another sequence than the one being collected.'
       );
     }
-    if (session.delivered) {
-      this.noteRead(session, 'duplicate', part);
-      throw alreadyAccepted();
-    }
-    if (outcome.result === 'accepted' && symbol.index === 0) {
+    const assembler = session.assembler;
+    if (outcome.result === 'accepted' && !assembler.headerVerified) {
       try {
-        const header = headerOfFirstCode(symbol);
+        const header = assembler.header();
         if (header) {
           this.verifyHeader(session, header);
           assembler.headerVerified = true;
         }
       } catch (error) {
         assembler.clear();
-        if (error instanceof QrPairingError && unreportedCodes.has(error.code)) throw error;
+        if (!isReported(error)) throw error;
         this.noteRead(session, 'foreign', codeOf(error));
         throw error;
       }
     }
-    this.noteRead(session, outcome.result, part);
     session.phase = session.role === 'hub' ? 'awaiting-answer' : 'receiving';
-    if (!assembler.isComplete()) return;
+    if (!assembler.isComplete()) {
+      this.noteRead(session, outcome.result, part);
+      return;
+    }
 
+    // The last code is reported once, as what the whole message turned out to be.
     const epoch = session.epoch;
     let message: PairingMessage;
     try {
@@ -255,16 +280,12 @@ export class PairingController {
       throw error;
     }
     assembler.headerVerified = true;
+    this.noteRead(session, 'accepted', part);
     await this.deliver(session, message, epoch);
   }
 
-  /**
-   * Accepts a whole pairing message as text, the way it would arrive through
-   * something other than a camera, or in one QR code.
-   */
-  public async ingestQrText(sessionKey: string, text: string): Promise<void> {
-    this.requireEnabled();
-    const session = this.requireReceiving(sessionKey);
+  private async takeText(session: PairingSessionState, text: string): Promise<void> {
+    this.requireOpen(session);
     // Text that is not a pairing message at all throws here and is not reported.
     const epoch = session.epoch;
     const message = await readPairingMessage(text);
@@ -284,25 +305,56 @@ export class PairingController {
   }
 
   /**
-   * Whether a code of another sequence should replace the one being collected.
+   * Adds a code to a sequence. A position read twice with different content
+   * means this sequence is damaged, so it is dropped and collected again from
+   * the codes still being shown. Anything else wrong with the code leaves the
+   * sequence as it was.
+   */
+  private addTo(
+    session: PairingSessionState,
+    assembler: PairingAssembler,
+    symbol: StructuredAppendRead
+  ): AddOutcome {
+    try {
+      return assembler.add(symbol);
+    } catch (error) {
+      if (codeOf(error) !== 'conflicting-part') throw error;
+      assembler.clear();
+      this.noteRead(session, 'foreign', 'conflicting-part');
+      throw error;
+    }
+  }
+
+  /**
+   * Collects a code of another sequence on the side, while the sequence held
+   * has not shown whose it is. If the other sequence's header shows it is this
+   * exchange's, it takes the place of the one held.
    *
-   * Only while the sequence held has not shown whose it is, and only by the
-   * first code of a sequence that shows it is this exchange's. A camera that
-   * first catches a stray code of an old projection would otherwise wait for
-   * the rest of that old sequence forever.
+   * A camera that first catches a stray code of an old projection would
+   * otherwise wait for the rest of that old sequence forever. Returns the
+   * outcome in the sequence that took over, or undefined when nothing changed.
    */
-  private replacesUnverifiedSequence(
+  private offerToCandidate(
     session: PairingSessionState,
     symbol: StructuredAppendRead
-  ): boolean {
-    if (symbol.index !== 0 || session.assembler.headerVerified || session.delivered) return false;
+  ): AddOutcome | undefined {
+    const candidate = session.candidate;
     try {
-      const header = headerOfFirstCode(symbol);
-      if (!header) return false;
+      let outcome = candidate.add(symbol);
+      if (outcome.result === 'foreign') {
+        candidate.clear();
+        outcome = candidate.add(symbol);
+      }
+      const header = candidate.header();
+      if (!header) return undefined;
       this.verifyHeader(session, header);
-      return true;
+      candidate.headerVerified = true;
+      session.assembler = candidate;
+      session.candidate = new PairingAssembler();
+      return outcome;
     } catch {
-      return false;
+      candidate.clear();
+      return undefined;
     }
   }
 
@@ -325,17 +377,16 @@ export class PairingController {
     }
   }
 
-  private requireReceiving(sessionKey: string): PairingSessionState {
-    const session = this.requireSession(sessionKey);
+  private requireOpen(session: PairingSessionState): void {
     if (isTerminalPhase(session.phase)) {
       throw new QrPairingError(
         session.phase === 'connected' ? 'already-accepted' : 'stale-exchange',
         `Pairing session ${session.sessionKey} is no longer receiving codes.`
       );
     }
-    return session;
   }
 
+
   /** Records what a pairing code turned out to be, for the application to show. */
   private noteRead(
     session: PairingSessionState,
@@ -779,6 +830,8 @@ export class PairingController {
       outgoingSvgs: [],
       outgoingCurrentIndex: -1,
       assembler: new PairingAssembler(),
+      candidate: new PairingAssembler(),
+      readQueue: Promise.resolve(),
       delivered: false,
       peerCreated: false,
       timeoutMilliseconds: DEFAULT_TIMEOUT_SECONDS * 1000,
@@ -806,6 +859,7 @@ export class PairingController {
     session.outgoingSvgs = [];
     session.outgoingCurrentIndex = -1;
     session.assembler = new PairingAssembler();
+    session.candidate = new PairingAssembler();
     session.delivered = false;
     session.peerCreated = false;
     session.startedAtMonotonic = this.clock.nowMilliseconds();
@@ -879,6 +933,7 @@ export class PairingController {
     this.releaseDisplay(session);
     if (!connected) {
       session.assembler.clear();
+      session.candidate.clear();
       if (session.peerCreated) {
         try {
           this.webrtc().closePeer(session.remotePeerId);
@@ -1004,3 +1059,8 @@ function alreadyAccepted(): QrPairingError {
     'The pairing code for this exchange has already been accepted.'
   );
 }
+
+/** Whether a failure is about a pairing code, rather than about text that is not one at all. */
+function isReported(error: unknown): boolean {
+  return !(error instanceof QrPairingError && unreportedCodes.has(error.code));
+}

package/src/pairing/types.ts

@@ -103,6 +103,13 @@ export interface PairingSessionState {
   /** Zero-based index into `outgoingSvgs`, or -1 when nothing is selected. */
   outgoingCurrentIndex: number;
   assembler: PairingAssembler;
+  /**
+   * Another sequence, collected on the side while the one in `assembler` has
+   * not shown whose it is, in case it turns out to be this exchange's.
+   */
+  candidate: PairingAssembler;
+  /** Settles when every read taken so far has been handled; reads wait their turn on it. */
+  readQueue: Promise<void>;
   /** True once the reassembled code has been handed to WebRTC. Prevents a second delivery. */
   delivered: boolean;
   /** True once a WebRTC peer exists for `remotePeerId`, so its state is worth polling. */

package/src/ports/qr-scan.ts

@@ -66,6 +66,15 @@ export interface QrScanPort {
 export class CameraQrScanner implements QrScanPort {
   private lease: CameraLease | undefined;
   private leasedCameraId = '';
+  /**
+   * Wall-clock time before which the next frame is not read.
+   *
+   * A code left in front of the camera reads on every frame, and a sequence is read code after
+   * code, so the caller asks again at once. Without a pause between reads the loop would run on
+   * promise callbacks alone and never give the page its turn: no redraw, no Scratch thread, no
+   * timer. Every read therefore waits for the poll interval after the one before it.
+   */
+  private nextReadAt = 0;
 
   public constructor(
     private readonly runtime: TurboWarpRuntime,
@@ -118,6 +127,7 @@ export class CameraQrScanner implements QrScanPort {
         // Aborted while the frame was decoding: the abort handler already rejected.
         if (settled) return;
         if (read !== null) {
+          this.nextReadAt = Date.now() + interval;
           cleanup();
           resolve(read);
           return;
@@ -125,7 +135,9 @@ export class CameraQrScanner implements QrScanPort {
         timer = setTimeout(() => void tick(), interval);
       };
       options.signal.addEventListener('abort', onAbort, {once: true});
-      void tick();
+      // Always through a timer, even when no wait is due, so a read never follows the previous
+      // one within the same turn of the event loop.
+      timer = setTimeout(() => void tick(), Math.max(0, this.nextReadAt - Date.now()));
     });
   }
 

package/src/qr/courier.ts

@@ -125,31 +125,48 @@ export async function readPairingMessage(text: string): Promise<PairingMessage>
   return message;
 }
 
-/** The header, if the given first code of a sequence holds all of it. */
-export function headerOfFirstCode(read: StructuredAppendRead): PairingMessageHeader | undefined {
-  return parseHeader(latin1(read.bytes));
-}
-
 /**
  * Collects the codes of one pairing message, in any order.
  *
- * The first code read decides the sequence. Until the first code of that
- * sequence has shown whose message it is, another sequence whose first code
- * does belong to this exchange may take its place: a camera may well see an
- * old projection before the right one.
+ * The first code read decides the sequence. The header comes first in the
+ * message, so the codes from the first onwards tell whose message it is before
+ * all of them have arrived — in the first code alone at the default settings,
+ * across the first few when codes are small or the error correction is high.
  */
 export class PairingAssembler {
   private readonly inner = new StructuredAppendAssembler();
-  /** True once the sequence's first code showed a header this exchange accepts. */
+  /** Each position's share of the message, as it arrived. */
+  private readonly shares = new Map<number, Uint8Array>();
+  /** True once the header showed this sequence belongs to the exchange. */
   public headerVerified = false;
 
   /** Throws `conflicting-part` for a position that arrives twice with different content. */
   public add(read: StructuredAppendRead): AddOutcome {
+    let outcome: AddOutcome;
     try {
-      return this.inner.add(read);
+      outcome = this.inner.add(read);
     } catch (error) {
       throw translate(error);
     }
+    if (outcome.result === 'accepted') this.shares.set(read.index, read.bytes);
+    return outcome;
+  }
+
+  /**
+   * The header, once the codes from the first onwards hold all of it.
+   * Undefined while they do not; throws as soon as they cannot be a pairing
+   * message, or the header is malformed.
+   */
+  public header(): PairingMessageHeader | undefined {
+    let prefix = '';
+    for (let index = 0; this.shares.has(index); index += 1) {
+      prefix += latin1(this.shares.get(index) ?? new Uint8Array());
+    }
+    return prefix === '' ? undefined : parseHeader(prefix);
+  }
+
+  public isEmpty(): boolean {
+    return this.inner.received() === 0;
   }
 
   public receivedCount(): number {
@@ -183,6 +200,7 @@ export class PairingAssembler {
 
   public clear(): void {
     this.inner.clear();
+    this.shares.clear();
     this.headerVerified = false;
   }
 }