@kubohiroya/turbowarp-webrtc-qrcode-pairing 0.1.0

package/src/block-definitions.json

@@ -0,0 +1,264 @@
+{
+  "extensionName": "TurboWarp-WebRTC-QRCode-Pairing",
+  "blocks": [
+    {
+      "opcode": "startOfferPairing",
+      "blockType": "COMMAND",
+      "text": "start offer pairing [SESSION] as [LOCAL_PEER] to [REMOTE_PEER]",
+      "description": "Creates a WebRTC offer for the integration machine and prepares its QR parts.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"},
+        "LOCAL_PEER": {"type": "STRING", "defaultValue": "hub"},
+        "REMOTE_PEER": {"type": "STRING", "defaultValue": "camera-1"}
+      }
+    },
+    {
+      "opcode": "startAnswerPairing",
+      "blockType": "COMMAND",
+      "text": "start answer pairing [SESSION] as [LOCAL_PEER]",
+      "description": "Waits for an offer on the camera machine. Leave the name empty to adopt the name the offer assigns.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"},
+        "LOCAL_PEER": {"type": "STRING", "defaultValue": ""}
+      }
+    },
+    {
+      "opcode": "ingestPairingQrText",
+      "blockType": "COMMAND",
+      "text": "receive pairing QR text [TEXT] for [SESSION]",
+      "description": "Accepts one decoded QR text. Repeated readings of the same part are ignored.",
+      "arguments": {
+        "TEXT": {"type": "STRING", "defaultValue": ""},
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "scanPairingQrFromCamera",
+      "blockType": "COMMAND",
+      "text": "scan pairing QR for [SESSION] from camera [CAMERA_ID]",
+      "description": "Reads parts from the named camera until the exchange has every part it needs.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"},
+        "CAMERA_ID": {"type": "STRING", "defaultValue": "default"}
+      }
+    },
+    {
+      "opcode": "pairingReceivedParts",
+      "blockType": "REPORTER",
+      "text": "received parts of [SESSION]",
+      "description": "Returns how many distinct parts have been accepted.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingRequiredParts",
+      "blockType": "REPORTER",
+      "text": "required parts of [SESSION]",
+      "description": "Returns how many parts the incoming message has, or zero before the first part arrives.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingMissingParts",
+      "blockType": "REPORTER",
+      "text": "missing parts of [SESSION]",
+      "description": "Returns the one-based part numbers that have not been read yet, separated by commas.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "showPairingQrPart",
+      "blockType": "COMMAND",
+      "text": "show pairing QR part [INDEX] of [SESSION] on this sprite",
+      "description": "Shows the selected one-based part using a temporary sprite skin.",
+      "arguments": {
+        "INDEX": {"type": "NUMBER", "defaultValue": 1},
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "showNextPairingQrPart",
+      "blockType": "COMMAND",
+      "text": "show next pairing QR part of [SESSION] on this sprite",
+      "description": "Shows the next part and wraps from the last part back to the first.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingQrPartCount",
+      "blockType": "REPORTER",
+      "text": "pairing QR part count of [SESSION]",
+      "description": "Returns how many parts are prepared for display, or zero when none are.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingQrCurrentPart",
+      "blockType": "REPORTER",
+      "text": "current pairing QR part of [SESSION]",
+      "description": "Returns the one-based part selected for display, or zero when none is selected.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingQrPartSvg",
+      "blockType": "REPORTER",
+      "text": "pairing QR part [INDEX] of [SESSION] as SVG",
+      "description": "Returns the part as SVG markup so a project can display it its own way.",
+      "arguments": {
+        "INDEX": {"type": "NUMBER", "defaultValue": 1},
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingQrPartDataUri",
+      "blockType": "REPORTER",
+      "text": "pairing QR part [INDEX] of [SESSION] as data URI",
+      "description": "Returns the part as a base64 SVG data URI for costumes and HTML images.",
+      "arguments": {
+        "INDEX": {"type": "NUMBER", "defaultValue": 1},
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "endPairingQrDisplay",
+      "blockType": "COMMAND",
+      "text": "end pairing QR display of [SESSION]",
+      "description": "Restores the sprites this session changed. The session itself stays open.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingPhase",
+      "blockType": "REPORTER",
+      "text": "pairing phase of [SESSION]",
+      "description": "Returns the session phase, such as offer-ready, receiving, answer-ready, connecting, or connected.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingConnectionState",
+      "blockType": "REPORTER",
+      "text": "pairing connection state of [SESSION]",
+      "description": "Returns the WebRTC connection state reported for this session's peer.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "isPairingConnected",
+      "blockType": "BOOLEAN",
+      "text": "pairing [SESSION] connected?",
+      "description": "Reports whether WebRTC has established the connection for this session.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "waitUntilPairingConnected",
+      "blockType": "COMMAND",
+      "text": "wait until pairing [SESSION] is connected",
+      "description": "Waits for the connection, or fails when the session is cancelled, times out, or fails.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingError",
+      "blockType": "REPORTER",
+      "text": "pairing error code of [SESSION]",
+      "description": "Returns the latest error code, such as hash-mismatch or peer-mismatch, or an empty string.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingErrorMessage",
+      "blockType": "REPORTER",
+      "text": "pairing error message of [SESSION]",
+      "description": "Returns the latest error message. Pairing codes and QR payloads are never included.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingLocalPeer",
+      "blockType": "REPORTER",
+      "text": "local peer of [SESSION]",
+      "description": "Returns the name this machine uses for itself in this exchange.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingRemotePeer",
+      "blockType": "REPORTER",
+      "text": "remote peer of [SESSION]",
+      "description": "Returns the name this machine uses for the other machine, which is also its WebRTC peer name.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingExchangeId",
+      "blockType": "REPORTER",
+      "text": "exchange id of [SESSION]",
+      "description": "Returns the identifier of the current offer and answer exchange. A retry allocates a new one.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingRemainingSeconds",
+      "blockType": "REPORTER",
+      "text": "remaining seconds of [SESSION]",
+      "description": "Returns the seconds left before the exchange times out.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "pairingSessions",
+      "blockType": "REPORTER",
+      "text": "pairing sessions",
+      "description": "Returns the open session names, separated by commas.",
+      "arguments": {}
+    },
+    {
+      "opcode": "cancelPairing",
+      "blockType": "COMMAND",
+      "text": "cancel pairing [SESSION]",
+      "description": "Cancels the exchange and releases displays, buffers, and unconnected peers. Established connections stay up.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "retryPairing",
+      "blockType": "COMMAND",
+      "text": "retry pairing [SESSION]",
+      "description": "Starts a new exchange for the same session. QR codes from the previous exchange stop being accepted.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"}
+      }
+    },
+    {
+      "opcode": "setPairingTimeout",
+      "blockType": "COMMAND",
+      "text": "set pairing timeout of [SESSION] to [SECONDS] seconds",
+      "description": "Sets how long the exchange waits, measured on this machine's own clock.",
+      "arguments": {
+        "SESSION": {"type": "STRING", "defaultValue": "pairing-1"},
+        "SECONDS": {"type": "NUMBER", "defaultValue": 600}
+      }
+    }
+  ]
+}

package/src/clock.ts

@@ -0,0 +1,18 @@
+/**
+ * Monotonic time source.
+ *
+ * Deadlines are measured as elapsed time on the device that owns the session.
+ * The two devices in a pairing are not time-synchronized, so nothing may depend
+ * on their wall clocks agreeing, and a wall clock that is corrected mid-session
+ * must not move a deadline.
+ */
+export interface MonotonicClock {
+  nowMilliseconds(): number;
+}
+
+export const systemMonotonicClock: MonotonicClock = {
+  nowMilliseconds: () =>
+    typeof performance === 'object' && typeof performance.now === 'function'
+      ? performance.now()
+      : Date.now()
+};

package/src/config/feature-flags.ts

@@ -0,0 +1,18 @@
+export interface QrPairingFeatureFlags {
+  readonly qrCodePairing: boolean;
+}
+
+interface FeatureFlagGlobal {
+  readonly __TWQP_FEATURE_FLAGS__?: Partial<QrPairingFeatureFlags>;
+}
+
+const overrides = (globalThis as FeatureFlagGlobal).__TWQP_FEATURE_FLAGS__;
+
+/**
+ * Startup-fixed flags, read once and frozen. The QR pairing path stays opt-in
+ * until it is verified on hardware; turning it off is a route switch back to
+ * manual offer/answer exchange, not a disconnect of established connections.
+ */
+export const featureFlags: QrPairingFeatureFlags = Object.freeze({
+  qrCodePairing: overrides?.qrCodePairing === true
+});

package/src/config/qr-config.ts

@@ -0,0 +1,22 @@
+import type {QrErrorCorrectionLevel} from '../qr/envelope.js';
+
+interface QrConfigGlobal {
+  readonly __TWQP_QR_CONFIG__?: {
+    readonly errorCorrectionLevel?: QrErrorCorrectionLevel;
+  };
+}
+
+const configuredLevel = (globalThis as QrConfigGlobal).__TWQP_QR_CONFIG__?.errorCorrectionLevel;
+
+/**
+ * Startup-fixed QR settings. M is the software-validated default; higher levels
+ * survive worse optical conditions but carry fewer characters per symbol, which
+ * raises the part count the operator has to carry.
+ */
+export const qrConfig = Object.freeze({
+  errorCorrectionLevel: isLevel(configuredLevel) ? configuredLevel : ('M' as const)
+});
+
+function isLevel(value: unknown): value is QrErrorCorrectionLevel {
+  return value === 'L' || value === 'M' || value === 'Q' || value === 'H';
+}

package/src/config.ts

@@ -0,0 +1,12 @@
+export const extensionConfig = {
+  id: 'kubohiroyawebrtcqrcodepairing',
+  slug: 'webrtc-qrcode-pairing',
+  name: 'TurboWarp-WebRTC-QRCode-Pairing',
+  description: 'Exchanges WebRTC offers and answers by carrying them optically as QR codes.',
+  author: 'Hiroya Kubo',
+  license: 'MPL-2.0',
+  unsandboxed: true,
+  docsURI: 'https://kubohiroya.github.io/turbowarp-webrtc-qrcode-pairing/',
+  blockIconURI:
+    'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0OCA0OCI+PHJlY3QgeD0iNCIgeT0iOCIgd2lkdGg9IjE4IiBoZWlnaHQ9IjE0IiByeD0iMyIgZmlsbD0iIzRDOTdGRiIvPjxyZWN0IHg9IjI2IiB5PSI4IiB3aWR0aD0iMTgiIGhlaWdodD0iMTQiIHJ4PSIzIiBmaWxsPSIjNTlDMDU5Ii8+PHJlY3QgeD0iMTUiIHk9IjI2IiB3aWR0aD0iMTgiIGhlaWdodD0iMTQiIHJ4PSIzIiBmaWxsPSIjRkZBQjE5Ii8+PC9zdmc+'
+} as const;

package/src/errors.ts

@@ -0,0 +1,51 @@
+/**
+ * Error contract shared by the QR transport layer and the pairing domain.
+ *
+ * Messages must never contain SDP, ICE details, pairing codes, or QR payload
+ * fragments: callers surface them to project authors and diagnostics.
+ */
+export type PairingErrorCode =
+  // Feature flag and external dependencies.
+  | 'feature-disabled'
+  | 'webrtc-capability-missing'
+  | 'qr-decoder-missing'
+  | 'camera-unavailable'
+  | 'renderer-unavailable'
+  // Transport format and integrity.
+  | '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'
+  // Exchange identity.
+  | 'unknown-session'
+  | 'stale-exchange'
+  | 'unexpected-kind'
+  | 'peer-mismatch'
+  | 'reply-mismatch'
+  | 'already-accepted'
+  // Lifecycle.
+  | 'session-limit'
+  | 'session-exists'
+  | 'no-session'
+  | 'invalid-argument'
+  | 'timeout'
+  | 'cancelled'
+  | 'webrtc-rejected';
+
+export class QrPairingError extends Error {
+  public readonly code: PairingErrorCode;
+
+  public constructor(code: PairingErrorCode, message: string, options?: {cause?: unknown}) {
+    super(message, options);
+    this.name = 'QrPairingError';
+    this.code = code;
+  }
+}

package/src/extension-manifest.ts

@@ -0,0 +1,149 @@
+import type {Plugin} from 'vite';
+
+export const EXTENSION_MANIFEST_FORMAT_VERSION = 1 as const;
+
+export interface ExtensionManifestArgument {
+  id: string;
+  type: string;
+  menu?: string;
+}
+
+export interface ExtensionManifestBlock {
+  opcode: string;
+  blockType: string;
+  arguments: ExtensionManifestArgument[];
+}
+
+export interface ExtensionManifestMenu {
+  id: string;
+  acceptReporters: boolean;
+}
+
+export interface ExtensionManifest {
+  formatVersion: typeof EXTENSION_MANIFEST_FORMAT_VERSION;
+  id: string;
+  blocks: ExtensionManifestBlock[];
+  menus: ExtensionManifestMenu[];
+}
+
+export interface ExtensionManifestPluginOptions {
+  id: string;
+  definitions: unknown;
+  fileName?: string;
+}
+
+export function createExtensionManifest(id: string, definitions: unknown): ExtensionManifest {
+  if (!/^[a-z0-9]+$/.test(id)) {
+    throw new TypeError('Extension manifest ID must contain only lowercase letters and numbers.');
+  }
+
+  const source = requireRecord(definitions, 'Block definitions');
+  const sourceBlocks = source.blocks;
+  if (!Array.isArray(sourceBlocks)) {
+    throw new TypeError('Block definitions must contain a blocks array.');
+  }
+
+  const menus = normalizeMenus(source.menus);
+  const menuIds = new Set(menus.map((menu) => menu.id));
+  const seenOpcodes = new Set<string>();
+  const blocks = sourceBlocks.map((block, index) => {
+    const normalized = normalizeBlock(block, index, menuIds);
+    if (seenOpcodes.has(normalized.opcode)) {
+      throw new TypeError(`Duplicate block opcode: ${normalized.opcode}`);
+    }
+    seenOpcodes.add(normalized.opcode);
+    return normalized;
+  });
+
+  return {
+    formatVersion: EXTENSION_MANIFEST_FORMAT_VERSION,
+    id,
+    blocks: blocks.sort((left, right) => compareIds(left.opcode, right.opcode)),
+    menus
+  };
+}
+
+export function serializeExtensionManifest(id: string, definitions: unknown): string {
+  return `${JSON.stringify(createExtensionManifest(id, definitions), null, 2)}\n`;
+}
+
+export function extensionManifestPlugin(options: ExtensionManifestPluginOptions): Plugin {
+  return {
+    name: 'extension-api-manifest',
+    apply: 'build',
+    enforce: 'post',
+    generateBundle() {
+      this.emitFile({
+        type: 'asset',
+        fileName: options.fileName ?? 'extension-manifest.json',
+        source: serializeExtensionManifest(options.id, options.definitions)
+      });
+    }
+  };
+}
+
+function normalizeBlock(
+  value: unknown,
+  index: number,
+  menuIds: ReadonlySet<string>
+): ExtensionManifestBlock {
+  const block = requireRecord(value, `Block at index ${index}`);
+  const opcode = requireNonEmptyString(block.opcode, `Block at index ${index} opcode`);
+  const blockType = requireNonEmptyString(block.blockType, `Block ${opcode} blockType`);
+  const sourceArguments = block.arguments ?? {};
+  const argumentRecord = requireRecord(sourceArguments, `Block ${opcode} arguments`);
+  const argumentsList = Object.entries(argumentRecord).map(([argumentId, argument]) => {
+    requireNonEmptyString(argumentId, `Block ${opcode} argument ID`);
+    const definition = requireRecord(argument, `Block ${opcode} argument ${argumentId}`);
+    const type = requireNonEmptyString(
+      definition.type,
+      `Block ${opcode} argument ${argumentId} type`
+    );
+    const menu = definition.menu;
+    if (menu !== undefined && (typeof menu !== 'string' || !menuIds.has(menu))) {
+      throw new TypeError(`Block ${opcode} argument ${argumentId} references unknown menu: ${menu}`);
+    }
+    return menu === undefined ? {id: argumentId, type} : {id: argumentId, type, menu};
+  });
+
+  return {
+    opcode,
+    blockType,
+    arguments: argumentsList.sort((left, right) => compareIds(left.id, right.id))
+  };
+}
+
+function normalizeMenus(value: unknown): ExtensionManifestMenu[] {
+  const menuRecord = requireRecord(value ?? {}, 'Block definition menus');
+  return Object.entries(menuRecord)
+    .map(([id, menu]) => {
+      requireNonEmptyString(id, 'Menu ID');
+      const definition = requireRecord(menu, `Menu ${id}`);
+      const acceptReporters = definition.acceptReporters ?? false;
+      if (typeof acceptReporters !== 'boolean') {
+        throw new TypeError(`Menu ${id} acceptReporters must be a boolean.`);
+      }
+      return {id, acceptReporters};
+    })
+    .sort((left, right) => compareIds(left.id, right.id));
+}
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireNonEmptyString(value: unknown, label: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function compareIds(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}