@el-j/google-sheet-translations 3.0.0-beta.7 → 3.0.0-beta.9

package/dist/esm/index.js

@@ -3299,11 +3299,13 @@ function parsePadUrl(url) {
 	const match = urlObj.hash.match(/#\/(\d+)\/([^/]+)\/([^/]+)\/([^/]+)(\/p\/)?/);
 	if (!match) throw new Error(`Unsupported CryptPad URL format: "${url}". Expected "#/<version>/<app>/<mode>/<seed>[/p/]"`);
 	const [, versionStr, app, modeRaw, seed, passwordFlag] = match;
+	const version = parseInt(versionStr, 10);
+	if (version === 3) throw new Error(`CryptPad URL "${url}" is a version 3 "safe link" (hidden hash) which omits the encryption key to protect it in browser address bars. Please use the original pad share URL (version 2 format: "https://.../#/2/${app}/${modeRaw}/<secret>/..."), which can be copied via CryptPad's "Share" -> "Link" menu.`);
 	const mode = modeRaw === "edit" ? "edit" : "view";
 	const isPasswordProtected = Boolean(passwordFlag);
 	return {
 		origin: urlObj.origin,
-		version: parseInt(versionStr, 10),
+		version,
 		app,
 		mode,
 		seed,
@@ -3312,27 +3314,36 @@ function parsePadUrl(url) {
 	};
 }
 /**
-* Derives the Netflux channel ID (hex string) and symmetric encryption key (32 bytes)
-* from a CryptPad pad seed and optional password according to CryptPad's createEditCryptor2 / createViewCryptor2 protocol.
+* Derives the Netflux channel ID (hex string), symmetric encryption key (32 bytes),
+* and Ed25519 signing keypair from a CryptPad pad seed and optional password
+* according to CryptPad's createEditCryptor2 / createViewCryptor2 protocol.
 */
 function deriveCryptPadKeys(seedStr, password) {
 	const seed = b64Decode(seedStr);
 	if (!password) {
-		const seed2 = crypto.createHash("sha512").update(seed).digest().subarray(32, 64);
+		const hash = crypto.createHash("sha512").update(seed).digest();
+		const signKp = nacl.sign.keyPair.fromSeed(hash.subarray(0, 32));
+		const seed2 = hash.subarray(32, 64);
 		const hash2 = crypto.createHash("sha512").update(seed2).digest();
 		return {
 			channelHex: hash2.subarray(0, 16).toString("hex"),
-			cryptKey: new Uint8Array(hash2.subarray(16, 48))
+			cryptKey: new Uint8Array(hash2.subarray(16, 48)),
+			signKey: signKp.secretKey,
+			validateKey: signKp.publicKey
 		};
 	}
 	const pwBytes = decodeUTF8(password);
 	const superSeed1 = Buffer.concat([Buffer.from(pwBytes), Buffer.from(seed)]);
-	const seed2 = crypto.createHash("sha512").update(superSeed1).digest().subarray(32, 64);
+	const hash1 = crypto.createHash("sha512").update(superSeed1).digest();
+	const signKp = nacl.sign.keyPair.fromSeed(hash1.subarray(0, 32));
+	const seed2 = hash1.subarray(32, 64);
 	const superSeed2 = Buffer.concat([Buffer.from(pwBytes), Buffer.from(seed2)]);
 	const hash2 = crypto.createHash("sha512").update(superSeed2).digest();
 	return {
 		channelHex: hash2.subarray(0, 16).toString("hex"),
-		cryptKey: new Uint8Array(hash2.subarray(16, 48))
+		cryptKey: new Uint8Array(hash2.subarray(16, 48)),
+		signKey: signKp.secretKey,
+		validateKey: signKp.publicKey
 	};
 }
 /**
@@ -3363,13 +3374,16 @@ function decryptCryptPadPayload(payload, cryptKey) {
 }
 /**
 * Encrypts a plaintext message payload using TweetNaCl secretbox (XSalsa20-Poly1305).
-* Formats output as `base64(nonce)|base64(ciphertext)`.
+* If signKey is provided, signs the `nonce|ciphertext` string using TweetNaCl Ed25519
+* matching OnlyOffice / CryptPad real-time channel requirements.
 */
-function encryptCryptPadPayload(plaintext, cryptKey) {
+function encryptCryptPadPayload(plaintext, cryptKey, signKey) {
 	const nonce = nacl.randomBytes(24);
 	const msgBytes = decodeUTF8(plaintext);
 	const cipher = nacl.secretbox(msgBytes, nonce, cryptKey);
-	return `${b64Encode(nonce)}|${b64Encode(cipher)}`;
+	const encStr = `${b64Encode(nonce)}|${b64Encode(cipher)}`;
+	if (signKey) return b64Encode(nacl.sign(decodeUTF8(encStr), signKey));
+	return encStr;
 }
 //#endregion
 //#region src/providers/cryptpad/netflux.ts
@@ -3403,30 +3417,45 @@ function fetchChannelHistory(wsUrl, channelHex, cryptKey, options = {}) {
 		let quietTimer = null;
 		let overallTimeout = null;
 		let requestedHistory = false;
+		let abortListener = null;
+		let settled = false;
 		const cleanup = () => {
 			if (quietTimer) clearTimeout(quietTimer);
 			if (overallTimeout) clearTimeout(overallTimeout);
+			if (signal && abortListener) signal.removeEventListener("abort", abortListener);
 			try {
 				ws.close();
 			} catch {}
 		};
-		const finish = () => {
+		const finish = (result) => {
+			if (settled) return;
+			settled = true;
 			cleanup();
-			resolve(decryptedMessages);
+			resolve(result);
+		};
+		const rejectOnce = (error) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(error);
 		};
 		const resetQuietTimer = () => {
 			if (quietTimer) clearTimeout(quietTimer);
-			quietTimer = setTimeout(finish, quietPeriodMs);
+			quietTimer = setTimeout(() => {
+				if (decryptedMessages.length > 0) finish(decryptedMessages);
+				else rejectOnce(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms waiting for CryptPad channel "${channelHex}" history.`));
+			}, quietPeriodMs);
 		};
 		overallTimeout = setTimeout(() => {
-			cleanup();
-			if (decryptedMessages.length > 0) resolve(decryptedMessages);
-			else reject(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms waiting for CryptPad channel "${channelHex}" history.`));
+			if (decryptedMessages.length > 0) finish(decryptedMessages);
+			else rejectOnce(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms waiting for CryptPad channel "${channelHex}" history.`));
 		}, timeoutMs);
-		if (signal) signal.addEventListener("abort", () => {
-			cleanup();
-			reject(/* @__PURE__ */ new Error("Operation aborted"));
-		});
+		if (signal) {
+			abortListener = () => {
+				rejectOnce(/* @__PURE__ */ new Error("Operation aborted"));
+			};
+			signal.addEventListener("abort", abortListener);
+		}
 		ws.onopen = () => {
 			ws.send(JSON.stringify([
 				seq++,
@@ -3447,11 +3476,7 @@ function fetchChannelHistory(wsUrl, channelHex, cryptKey, options = {}) {
 							seq++,
 							"MSG",
 							peerId,
-							JSON.stringify([
-								"GET_HISTORY",
-								channelHex,
-								{}
-							])
+							JSON.stringify(["GET_FULL_HISTORY", channelHex])
 						]));
 						resetQuietTimer();
 					}
@@ -3461,7 +3486,11 @@ function fetchChannelHistory(wsUrl, channelHex, cryptKey, options = {}) {
 					if (!encStr && typeof msg[3] === "string" && msg[3].length > 50) encStr = msg[3];
 					try {
 						const parsed = JSON.parse(encStr);
-						if (Array.isArray(parsed) && parsed[2] === "MSG" && typeof parsed[4] === "string") encStr = parsed[4];
+						if (Array.isArray(parsed) && parsed[0] === "FULL_HISTORY" && Array.isArray(parsed[1])) encStr = parsed[1][4];
+						else if (Array.isArray(parsed) && parsed[0] === "FULL_HISTORY_END") {
+							finish(decryptedMessages);
+							return;
+						} else if (Array.isArray(parsed) && parsed[2] === "MSG" && typeof parsed[4] === "string") encStr = parsed[4];
 					} catch {}
 					if (typeof encStr === "string" && encStr.length > 30) {
 						const decrypted = decryptCryptPadPayload(encStr, cryptKey);
@@ -3475,7 +3504,9 @@ function fetchChannelHistory(wsUrl, channelHex, cryptKey, options = {}) {
 		};
 		ws.onerror = (err) => {
 			cleanup();
-			reject(/* @__PURE__ */ new Error(`CryptPad WebSocket error: ${String(err)}`));
+			const errObj = err;
+			const detail = errObj?.message || errObj?.error?.message || (errObj?.error ? String(errObj.error) : String(err));
+			reject(/* @__PURE__ */ new Error(`CryptPad WebSocket error: ${detail}`));
 		};
 	});
 }
@@ -3492,21 +3523,37 @@ function broadcastChannelMessage(wsUrl, channelHex, cryptKey, message, options =
 		let seq = 1;
 		let timeout = null;
 		let sent = false;
+		let abortListener = null;
+		let settled = false;
 		const cleanup = () => {
 			if (timeout) clearTimeout(timeout);
+			if (signal && abortListener) signal.removeEventListener("abort", abortListener);
 			try {
 				ws.close();
 			} catch {}
 		};
-		timeout = setTimeout(() => {
+		const resolveOnce = () => {
+			if (settled) return;
+			settled = true;
 			cleanup();
-			if (sent) resolve();
-			else reject(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms broadcasting message to CryptPad channel "${channelHex}".`));
-		}, timeoutMs);
-		if (signal) signal.addEventListener("abort", () => {
+			resolve();
+		};
+		const rejectOnce = (error) => {
+			if (settled) return;
+			settled = true;
 			cleanup();
-			reject(/* @__PURE__ */ new Error("Operation aborted"));
-		});
+			reject(error);
+		};
+		timeout = setTimeout(() => {
+			if (sent) resolveOnce();
+			else rejectOnce(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms broadcasting message to CryptPad channel "${channelHex}".`));
+		}, timeoutMs);
+		if (signal) {
+			abortListener = () => {
+				rejectOnce(/* @__PURE__ */ new Error("Operation aborted"));
+			};
+			signal.addEventListener("abort", abortListener);
+		}
 		ws.onopen = () => {
 			ws.send(JSON.stringify([
 				seq++,
@@ -3522,7 +3569,7 @@ function broadcastChannelMessage(wsUrl, channelHex, cryptKey, message, options =
 				const [, peerId, cmd] = msg;
 				if (cmd === "JOIN" && typeof peerId === "string" && !sent) {
 					sent = true;
-					const encrypted = encryptCryptPadPayload(message, cryptKey);
+					const encrypted = encryptCryptPadPayload(message, cryptKey, options.signKey);
 					ws.send(JSON.stringify([
 						seq++,
 						"MSG",
@@ -3530,15 +3577,15 @@ function broadcastChannelMessage(wsUrl, channelHex, cryptKey, message, options =
 						encrypted
 					]));
 					setTimeout(() => {
-						cleanup();
-						resolve();
+						resolveOnce();
 					}, 350);
 				}
 			} catch {}
 		};
 		ws.onerror = (err) => {
-			cleanup();
-			reject(/* @__PURE__ */ new Error(`CryptPad WebSocket broadcast error: ${String(err)}`));
+			const errObj = err;
+			const detail = errObj?.message || errObj?.error?.message || (errObj?.error ? String(errObj.error) : String(err));
+			rejectOnce(/* @__PURE__ */ new Error(`CryptPad WebSocket broadcast error: ${detail}`));
 		};
 	});
 }
@@ -3554,6 +3601,12 @@ function colIndexToLetter(colIndex) {
 	}
 	return letter;
 }
+/** Converts column letter to 0-based index: 'A' -> 0, 'Z' -> 25, 'AA' -> 26. */
+function letterToColIndex(letter) {
+	let index = 0;
+	for (let i = 0; i < letter.length; i++) index = index * 26 + (letter.charCodeAt(i) - 64);
+	return index - 1;
+}
 /**
 * Parses cell coordinates from a reference like "A1", "Sheet1!B2", or "$C$5".
 */
@@ -3572,18 +3625,51 @@ function parseCellRef(ref) {
 function extractOnlyOfficeChannelId(metadataMessages) {
 	for (const raw of metadataMessages) try {
 		const parsed = JSON.parse(raw);
+		if (parsed?.content?.channel && typeof parsed.content.channel === "string") return parsed.content.channel;
 		if (Array.isArray(parsed) && Array.isArray(parsed[1])) {
-			for (const edit of parsed[1]) if (Array.isArray(edit) && typeof edit[2] === "string") try {
-				const inner = JSON.parse(edit[2]);
-				if (inner?.content?.channel && typeof inner.content.channel === "string") return inner.content.channel;
-			} catch {}
+			const candidateContainers = [parsed[1], Array.isArray(parsed[1][0]) ? parsed[1][0] : null].filter(Boolean);
+			for (const container of candidateContainers) for (const item of container) if (Array.isArray(item)) {
+				for (const elem of item) if (typeof elem === "string" && elem.includes("channel")) try {
+					const inner = JSON.parse(elem);
+					if (inner?.content?.channel && typeof inner.content.channel === "string") return inner.content.channel;
+				} catch {}
+			}
 		}
-		if (parsed?.content?.channel && typeof parsed.content.channel === "string") return parsed.content.channel;
-	} catch {}
+		if (typeof raw === "string") {
+			const match = raw.match(/\\?"channel\\?"\s*:\s*\\?"([a-f0-9]{32})\\?"/i);
+			if (match) return match[1];
+		}
+	} catch {
+		if (typeof raw === "string") {
+			const match = raw.match(/\\?"channel\\?"\s*:\s*\\?"([a-f0-9]{32})\\?"/i);
+			if (match) return match[1];
+		}
+	}
 	return null;
 }
 /**
 * Parses OnlyOffice incremental binary change records into cell coordinates and text values.
+*
+* ### OnlyOffice Document Server / CryptPad Binary Protocol Specification
+* OnlyOffice collaborative document changes are broadcast over Netflux real-time channels.
+* Each message contains a `changes` array of transaction objects.
+*
+* Inside each transaction, `change` is formatted with a command prefix followed by base64 binary:
+* `asc_<version>;<base64_binary_payload>` (e.g., `asc_1;<base64>`).
+*
+* The decoded binary stream represents OnlyOffice document AST changes:
+* - Text and identifiers are serialized as length-prefixed UTF-16LE strings.
+* - The marker byte `0x08` indicates the start of a UTF-16LE string entry, followed by a 4-byte
+*   little-endian unsigned integer (`UInt32LE`) specifying byte length, followed by the UTF-16LE payload.
+*
+* Two layout patterns are supported:
+* - **Case A (Explicit coordinate reference)**: A string matching coordinate syntax (e.g. `A1` or `sheet!B2`)
+*   followed closely (within 30 bytes) by another `0x08` marker holding the cell's UTF-16LE text value.
+* - **Case B (Binary header coordinates)**: Header packets store 0-based column index `c1` at byte 14
+*   and row index `r1` at byte 18 as `UInt32LE`, followed by string values starting at byte 40+.
+*
+* @param rtMessages - Decrypted raw change messages retrieved from the OnlyOffice RT Netflux channel.
+* @returns A mapping of cell coordinates (`A1` or `sheet!A1`) to cell text values.
 */
 function parseOnlyOfficeChanges(rtMessages) {
 	const cells = {};
@@ -3616,12 +3702,20 @@ function parseOnlyOfficeChanges(rtMessages) {
 							break;
 						}
 					}
-					if (buf.length >= 30 && i >= 40) try {
+					if (buf.length >= 31 && buf.readUInt32BE(4) === 19468289 && buf[14] === 1) try {
+						const c1 = buf.readUInt32LE(15);
+						const r1 = buf.readUInt32LE(19);
+						if (r1 < 1e5 && c1 < 200) {
+							const cellRef = `${colIndexToLetter(c1)}${r1 + 1}`;
+							if (str.trim().length > 0 && !str.includes("!")) cells[cellRef] = str;
+						}
+					} catch {}
+					else if (buf.length >= 30 && i >= 40 && buf.readUInt32BE(4) === 0) try {
 						const c1 = buf.readUInt32LE(14);
 						const r1 = buf.readUInt32LE(18);
 						if (r1 < 1e5 && c1 < 200) {
 							const cellRef = `${colIndexToLetter(c1)}${r1 + 1}`;
-							if (!cells[cellRef] && str.trim().length > 0 && !str.includes("!")) cells[cellRef] = str;
+							if (str.trim().length > 0 && !str.includes("!")) cells[cellRef] = str;
 						}
 					} catch {}
 				}
@@ -3690,11 +3784,70 @@ function convertCellsToMultiSheetRows(cells, defaultSheet = "Sheet1") {
 	return result;
 }
 /**
-* Encodes a single cell update record into OnlyOffice binary format (0x08 prefix + UTF-16LE string).
+* Encodes a single cell update record into OnlyOffice binary format:
+* - Native AscCH.historyitem_Cell_ChangeValue (0x01291001) with 32-bit LE coordinates c1, r1.
+* - Explicit UTF-16LE cell reference tags for backward-compatibility and multi-sheet routing.
 */
-function encodeOnlyOfficeCellRecord(cellRef, value) {
-	const refBuf = Buffer.from(cellRef, "utf16le");
+function encodeOnlyOfficeCellRecord(cellRef, value, sheetId = 6) {
+	let c1 = 0;
+	let r1 = 0;
+	const parsed = parseCellRef(cellRef);
+	if (parsed) {
+		c1 = letterToColIndex(parsed.col);
+		r1 = Math.max(0, parsed.row - 1);
+	}
 	const valBuf = Buffer.from(value, "utf16le");
+	const L = valBuf.length;
+	const tail = Buffer.from([
+		1,
+		0,
+		2,
+		0,
+		3,
+		2,
+		1,
+		2,
+		0,
+		3,
+		1
+	]);
+	const body = Buffer.alloc(60 + L + tail.length);
+	body.writeUInt32BE(19468289, 0);
+	body.writeUInt32LE(2, 4);
+	body[8] = 48 + sheetId % 10;
+	body[9] = 0;
+	body[10] = 1;
+	body.writeUInt32LE(c1, 11);
+	body.writeUInt32LE(r1, 15);
+	body.writeUInt32LE(c1, 19);
+	body.writeUInt32LE(r1, 23);
+	body[27] = 0;
+	body.writeUInt32LE(39 + L, 28);
+	body[32] = 0;
+	body[33] = 2;
+	body[34] = r1 & 255;
+	body[35] = 1;
+	body[36] = 2;
+	body[37] = c1 & 255;
+	body[38] = 2;
+	body[39] = 9;
+	body[40] = 3;
+	body.writeUInt32LE(26 + L, 41);
+	body[45] = 0;
+	body[46] = 0;
+	body[47] = 1;
+	body[48] = 9;
+	body[49] = 1;
+	body.writeUInt32LE(13 + L, 50);
+	body[54] = 0;
+	body[55] = 8;
+	body.writeUInt32LE(L, 56);
+	valBuf.copy(body, 60);
+	tail.copy(body, 60 + L);
+	const header = Buffer.alloc(4);
+	header.writeUInt32LE(body.length, 0);
+	const nativeBuf = Buffer.concat([header, body]);
+	const refBuf = Buffer.from(cellRef, "utf16le");
 	const refHeader = Buffer.alloc(5);
 	refHeader[0] = 8;
 	refHeader.writeUInt32LE(refBuf.length, 1);
@@ -3702,6 +3855,7 @@ function encodeOnlyOfficeCellRecord(cellRef, value) {
 	valHeader[0] = 8;
 	valHeader.writeUInt32LE(valBuf.length, 1);
 	return Buffer.concat([
+		nativeBuf,
 		refHeader,
 		refBuf,
 		valHeader,
@@ -3712,12 +3866,19 @@ function encodeOnlyOfficeCellRecord(cellRef, value) {
 * Formats a list of cell updates into an OnlyOffice change transaction JSON string.
 */
 function buildOnlyOfficeChangePayload(updates) {
+	const txOpen = Buffer.from("0a0000000129000000ff00000000", "hex");
 	const records = updates.map((u) => {
 		const colStr = typeof u.col === "number" ? colIndexToLetter(u.col) : u.col.toUpperCase();
 		return encodeOnlyOfficeCellRecord(`${u.sheet && u.sheet.trim().length > 0 ? `${u.sheet.trim()}!` : ""}${colStr}${u.row}`, u.value);
 	});
-	const changeEntry = `asc_1;${Buffer.concat(records).toString("base64")}`;
-	return JSON.stringify({ changes: [{ change: changeEntry }] });
+	const changeEntry = `asc_1;${Buffer.concat([txOpen, ...records]).toString("base64")}`;
+	return JSON.stringify({
+		type: "saveChanges",
+		changes: [{ change: changeEntry }],
+		startSaveChanges: true,
+		endSaveChanges: true,
+		isExcel: true
+	});
 }
 //#endregion
 //#region src/providers/cryptpad/client.ts
@@ -3732,36 +3893,73 @@ var CryptPadClient = class {
 		this.password = options.password ?? process.env.CRYPTPAD_PASSWORD;
 		this.websocketUrl = options.websocketUrl;
 		this.timeoutMs = options.timeoutMs ?? 1e4;
+		this.onProgress = options.onProgress;
 		if (this.parsedUrl.isPasswordProtected && !this.password) throw new Error(`CryptPad pad "${this.parsedUrl.cleanUrl}" is password protected, but no password was provided. Set "password" option or CRYPTPAD_PASSWORD environment variable.`);
 	}
-	/** Gets or derives the symmetric key and primary Netflux channel ID. */
+	/**
+	* Gets or derives the symmetric key and primary Netflux channel ID.
+	*
+	* @returns The derived CryptPad channel hex ID and 32-byte TweetNaCl secretbox key.
+	*/
 	getKeys() {
 		if (!this.derivedKeys) this.derivedKeys = deriveCryptPadKeys(this.parsedUrl.seed, this.password);
 		return this.derivedKeys;
 	}
-	/** Resolves the Netflux WebSocket endpoint to connect to. */
+	/**
+	* Resolves the Netflux WebSocket endpoint to connect to.
+	*
+	* @param signal - Optional AbortSignal to cancel connection discovery.
+	* @returns The WebSocket endpoint URL (wss:// or ws://).
+	*/
 	async getWebsocketUrl(signal) {
 		if (this.websocketUrl) return this.websocketUrl;
 		return resolveCryptPadWebsocketUrl(this.parsedUrl.origin, signal);
 	}
 	/**
 	* Initializes the OnlyOffice RT channel for a brand-new CryptPad sheet that has never
-	* been opened in a browser. Generates a random 32-hex channel ID, broadcasts it as an
-	* encrypted metadata patch on the Netflux channel (the same thing the OnlyOffice browser
-	* client does on first open), and returns the new RT channel ID.
+	* been opened in a browser.
 	*
-	* This removes the requirement to open the sheet in a browser before the CLI can write to it.
+	* ### CryptPad Protocol Details
+	* CryptPad pads use Netflux channels for real-time collaboration. The main pad channel
+	* stores document metadata. When a spreadsheet pad is opened in OnlyOffice, the OnlyOffice
+	* web wrapper creates a secondary Netflux channel for real-time document change frames
+	* and registers it in the pad's metadata channel.
+	*
+	* The metadata update is formatted as an edit sequence:
+	* `[sequenceNumber, [[offset, length, innerJsonString]]]`
+	* where `sequenceNumber` is 1, and `innerJsonString` is:
+	* `{"content":{"channel":"<32-hex-channel-id>"}}`.
+	*
+	* Broadcasting this envelope over the main channel headlessly replicates OnlyOffice's
+	* first-open handshake without requiring a browser or headless browser session.
+	*
+	* @param signal - Optional AbortSignal to cancel the initialization.
+	* @returns The newly allocated 32-character hexadecimal RT channel ID.
 	*/
 	async initializeRtChannel(signal) {
 		const wsUrl = await this.getWebsocketUrl(signal);
 		const { channelHex, cryptKey } = this.getKeys();
 		const newRtChannel = crypto.randomBytes(16).toString("hex");
-		const innerJson = JSON.stringify({ content: { channel: newRtChannel } });
-		await broadcastChannelMessage(wsUrl, channelHex, cryptKey, JSON.stringify([1, [[
-			0,
-			0,
-			innerJson
-		]]]), {
+		const innerJson = JSON.stringify({
+			content: {
+				hashes: {},
+				ids: {},
+				mediasSources: {},
+				originalVersion: 9,
+				version: 9,
+				channel: newRtChannel
+			},
+			metadata: { type: "oo" }
+		});
+		await broadcastChannelMessage(wsUrl, channelHex, cryptKey, JSON.stringify([
+			2,
+			[[[
+				0,
+				0,
+				innerJson
+			]], "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"],
+			"a4b411975be1d48a91f0ebfcd967add000f69564b2dc5ee644b87bf2bbfd786f"
+		]), {
 			timeoutMs: this.timeoutMs,
 			signal
 		});
@@ -3770,6 +3968,9 @@ var CryptPadClient = class {
 	/**
 	* Fetches the complete sheet data, including raw cell coordinate mappings,
 	* multi-sheet tabs, and structured rows formatted for translation ingestion.
+	*
+	* @param signal - Optional AbortSignal to cancel the fetch.
+	* @returns The structured {@link CryptPadSheetResult} containing grids, rows, and metadata.
 	*/
 	async fetchSheetData(signal) {
 		const wsUrl = await this.getWebsocketUrl(signal);
@@ -3810,6 +4011,10 @@ var CryptPadClient = class {
 	/**
 	* Directly fetches tabular translation rows `[ { key: '...', en: '...', de: '...' } ]`.
 	* If `sheetName` is provided, returns rows for that specific tab.
+	*
+	* @param sheetName - Optional tab/sheet name to extract rows from.
+	* @param signal - Optional AbortSignal to cancel the operation.
+	* @returns An array of {@link SheetRow} objects.
 	*/
 	async fetchSheetRows(sheetName, signal) {
 		const result = await this.fetchSheetData(signal);
@@ -3820,30 +4025,42 @@ var CryptPadClient = class {
 	* Broadcasts cell updates to the OnlyOffice real-time collaboration channel.
 	* If the sheet has never been opened in a browser (RT channel is None), it is
 	* automatically initialized headlessly — no browser required.
+	*
+	* @param updates - Array of cell updates containing coordinates and text values.
+	* @param signal - Optional AbortSignal to cancel the broadcast.
+	* @param existingRtChannel - Optional pre-fetched RT channel ID to avoid refetching sheet data.
 	*/
-	async sendCellUpdates(updates, signal) {
+	async sendCellUpdates(updates, signal, existingRtChannel) {
 		if (updates.length === 0) return;
-		let rtChannel = (await this.fetchSheetData(signal)).metadata.rtChannelId;
+		let rtChannel = existingRtChannel;
+		if (!rtChannel) rtChannel = (await this.fetchSheetData(signal)).metadata.rtChannelId;
 		if (!rtChannel) {
-			console.log("No OnlyOffice RT channel found. Initializing headlessly (no browser required)...");
+			this.onProgress?.("No OnlyOffice RT channel found. Initializing headlessly (no browser required)...");
 			rtChannel = await this.initializeRtChannel(signal);
-			console.log(`RT channel initialized: ${rtChannel}`);
+			this.onProgress?.(`RT channel initialized: ${rtChannel}`);
 			await new Promise((r) => setTimeout(r, 800));
 		}
 		const wsUrl = await this.getWebsocketUrl(signal);
-		const { cryptKey } = this.getKeys();
+		const { cryptKey, signKey } = this.getKeys();
 		const payload = buildOnlyOfficeChangePayload(updates);
 		await broadcastChannelMessage(wsUrl, rtChannel, cryptKey, payload, {
 			timeoutMs: this.timeoutMs,
-			signal
+			signal,
+			signKey
 		});
 	}
 	/**
 	* Updates or appends rows in a target sheet tab, creating new cells as needed.
+	*
+	* @param sheetName - Target sheet tab name (e.g. 'i18n' or 'common').
+	* @param rows - Array of translation rows to write.
+	* @param options - Write options: override existing non-empty values and optional signal.
+	* @returns The total number of cell update records sent.
 	*/
 	async writeSheetRows(sheetName, rows, options = {}) {
 		if (rows.length === 0) return 0;
-		const existingRows = (await this.fetchSheetData(options.signal)).sheets[sheetName]?.rows ?? [];
+		const data = await this.fetchSheetData(options.signal);
+		const existingRows = data.sheets[sheetName]?.rows ?? [];
 		let keyColName = "var";
 		const firstExisting = existingRows[0];
 		const firstIncoming = rows[0];
@@ -3892,7 +4109,7 @@ var CryptPadClient = class {
 				}
 			}
 		}
-		await this.sendCellUpdates(updates, options.signal);
+		await this.sendCellUpdates(updates, options.signal, data.metadata.rtChannelId);
 		return updates.length;
 	}
 };
@@ -3979,7 +4196,7 @@ const CRYPTPAD_SHEET_OUTPUT_CAPABILITIES = createCapabilitySet({ writeTables: tr
 * Converts nested TranslationData `[locale][sheet][key] = value` into
 * tabular rows `Record<sheetName, SheetRow[]>`.
 */
-function convertTranslationsToSheetRows(translations, localeMapping = {}, keyColumnName = "key") {
+function convertTranslationsToSheetRows(translations, localeMapping = {}, keyColumnName = "var") {
 	const reverseMapping = {};
 	for (const [header, norm] of Object.entries(localeMapping)) reverseMapping[norm] = header;
 	const sheetRowsMap = {};
@@ -4018,13 +4235,14 @@ function createCryptPadSheetOutputProvider(options = {}) {
 				timeoutMs: options.timeoutMs
 			});
 			const effectiveMapping = options.localeMapping ?? payload.localeMapping ?? {};
-			const sheetRowsMap = convertTranslationsToSheetRows(payload.translations, effectiveMapping, options.keyColumnName ?? "key");
+			const sheetRowsMap = convertTranslationsToSheetRows(payload.translations, effectiveMapping, options.keyColumnName ?? "var");
 			const updatedSheets = [];
 			let totalUpdatedCells = 0;
 			for (const [sheetName, rows] of Object.entries(sheetRowsMap)) {
 				const count = await client.writeSheetRows(sheetName, rows, { override: options.override ?? false });
 				updatedSheets.push(sheetName);
 				totalUpdatedCells += count;
+				await new Promise((r) => setTimeout(r, 400));
 			}
 			return {
 				wroteFiles: [url],
@@ -4400,7 +4618,7 @@ function createCryptPadWorkspaceOutputProvider(options, depsOverrides = {}) {
 		displayName: options.displayName ?? "CryptPad Workspace Output",
 		capabilities: CRYPTPAD_WORKSPACE_OUTPUT_CAPABILITIES,
 		async writeTranslations(payload) {
-			const snapshot = await deps.readSnapshot(options.filePath, options.authToken);
+			const snapshot = await deps.readSnapshot(options.filePath);
 			assertRevision(snapshot, options.expectedRevision);
 			const merged = mergeTranslations$1(snapshot.translations, payload.translations);
 			const nextRevision = snapshot.revision + 1;
@@ -4411,7 +4629,7 @@ function createCryptPadWorkspaceOutputProvider(options, depsOverrides = {}) {
 					...snapshot.metadata,
 					lastWriteProvider: "cryptpad-workspace-output"
 				}
-			}, options.authToken);
+			});
 			return {
 				wroteFiles: [options.filePath],
 				metadata: {
@@ -4422,6 +4640,14 @@ function createCryptPadWorkspaceOutputProvider(options, depsOverrides = {}) {
 		}
 	};
 }
+/**
+* Builds the {@link BuildSyncPlanInput} from a {@link TranslationSyncPayload}.
+* Falls back to using `payload.remoteTranslations` as the base if `payload.metadata.baseTranslations`
+* is not supplied.
+*
+* @param payload - The incoming sync payload containing local, remote, and optional base translations.
+* @returns The structured three-way sync plan input.
+*/
 function buildSyncInput(payload) {
 	return {
 		baseTranslations: payload.metadata?.baseTranslations ?? payload.remoteTranslations,
@@ -4447,7 +4673,7 @@ function createCryptPadWorkspaceSyncProvider(options, depsOverrides = {}) {
 		displayName: options.displayName ?? "CryptPad Workspace Sync",
 		capabilities: CRYPTPAD_WORKSPACE_SYNC_CAPABILITIES,
 		async syncTranslations(payload) {
-			const snapshot = await deps.readSnapshot(options.filePath, options.authToken);
+			const snapshot = await deps.readSnapshot(options.filePath);
 			assertRevision(snapshot, options.expectedRevision ?? (Number.isFinite(payload.metadata?.expectedRevision) ? Number(payload.metadata?.expectedRevision) : void 0));
 			const resolution = resolveSyncPlan(buildSyncInput(payload), options.conflictPolicy ?? "manual");
 			const nextRevision = snapshot.revision + 1;
@@ -4459,7 +4685,7 @@ function createCryptPadWorkspaceSyncProvider(options, depsOverrides = {}) {
 					lastSyncProvider: "cryptpad-workspace-sync",
 					policy: resolution.policy
 				}
-			}, options.authToken);
+			});
 			return {
 				changedKeys: resolution.appliedLocalChanges,
 				skippedKeys: resolution.skippedConflicts,
@@ -4921,7 +5147,6 @@ function createOutputProvider(providerId, options) {
 			if (typeof options.filePath !== "string" || options.filePath.trim().length === 0) throw new Error("cryptpad-workspace output provider requires a non-empty \"filePath\" option.");
 			return createCryptPadWorkspaceOutputProvider({
 				filePath: options.filePath,
-				authToken: typeof options.authToken === "string" ? options.authToken : void 0,
 				expectedRevision: typeof options.expectedRevision === "number" ? options.expectedRevision : void 0,
 				providerId: typeof options.providerId === "string" ? options.providerId : void 0,
 				displayName: typeof options.displayName === "string" ? options.displayName : void 0
@@ -4947,7 +5172,6 @@ function createSyncProvider(providerId, options) {
 			if (typeof options.filePath !== "string" || options.filePath.trim().length === 0) throw new Error("cryptpad-workspace sync provider requires a non-empty \"filePath\" option.");
 			return createCryptPadWorkspaceSyncProvider({
 				filePath: options.filePath,
-				authToken: typeof options.authToken === "string" ? options.authToken : void 0,
 				expectedRevision: typeof options.expectedRevision === "number" ? options.expectedRevision : void 0,
 				conflictPolicy: options.conflictPolicy === "remote-wins" || options.conflictPolicy === "local-wins" || options.conflictPolicy === "manual" ? options.conflictPolicy : void 0,
 				providerId: typeof options.providerId === "string" ? options.providerId : void 0,