Skip to content

Offline, privacy-first grammar checker. Fast, open-source, Rust-powered

36.5 KB
Raw Blame
import type { LintFramework } from 'lint-framework';
import GoogleDocsBridgeClient from './GoogleDocsBridgeClient';
import {
	createGoogleDocsLineBand,
	extendGoogleDocsLineBand,
	type GoogleDocsLineBand,
	type GoogleDocsRectLayout,
	getGoogleDocsParagraphBreakThreshold,
	rectSharesGoogleDocsLineBand,
	shouldInsertGoogleDocsSpace,
} from './googleDocsLayout';

declare global {
	interface Window {
		__harperGoogleDocsBridgeClient?: GoogleDocsBridgeClient;
	}
}

const GOOGLE_DOCS_TARGET_ID = 'harper-google-docs-target';
const GOOGLE_DOCS_MAIN_WORLD_BRIDGE_ID = 'harper-google-docs-main-world-bridge';
const GOOGLE_DOCS_EDITOR_SELECTOR = '.kix-appview-editor';
const GOOGLE_DOCS_RECT_SELECTOR = 'rect[aria-label]';
const GOOGLE_DOCS_SYNCING_ATTR = 'data-harper-gdocs-syncing';
const GOOGLE_DOCS_IGNORED_LAYOUT_REASONS = new Set(['scroll', 'wheel', 'key-scroll']);
const GOOGLE_DOCS_MIN_PARAGRAPH_BREAK_GAP_PX = 6;
const GOOGLE_DOCS_PARAGRAPH_BREAK_RATIO = 0.5;
// biome-ignore lint/suspicious/noControlCharactersInRegex: Observed native Google Docs table separators, masked one code unit at a time.
const GOOGLE_DOCS_TABLE_SEPARATORS = /[\u0010\u0011\u0012\u001c]/gu;
// biome-ignore lint/suspicious/noControlCharactersInRegex: Native Shift+Enter becomes one space only in the lint projection.
const GOOGLE_DOCS_SOFT_BREAKS = /\u000b/gu;
// biome-ignore lint/suspicious/noControlCharactersInRegex: Native control characters cannot own visible source geometry.
const GOOGLE_DOCS_CONTROL_CHARACTERS = /[\u0000-\u001f]/u;

type LayoutRefreshFramework = LintFramework & {
	refreshLayout?: () => void;
};

type GoogleDocsRectSegment = {
	rectNode: SVGRectElement;
	page: Element | null;
	text: string;
	rect: GoogleDocsRectLayout;
};

type OrdinaryPiece = ['copy' | 'gap', number, number, number, number];
type OrdinaryMap = {
	format: 'ordinary-utf16-v1';
	source: 'logical' | 'rects';
	window: [number, number];
	pieces: OrdinaryPiece[];
	// Independent exact paragraphs when visual order cannot prove one window.
	regions?: Array<[number, number, number, number]>;
};

type GoogleDocsCloneSnapshot = {
	fragment: DocumentFragment;
	text: string;
	source: 'logical' | 'rects' | 'native';
	nativeSnapshot?: string;
	nativeRuns?: Array<[number, number, number]> | OrdinaryMap;
	segmentCount: number;
	signature: string;
};

export function isGoogleDocsPage(): boolean {
	return (
		window.location.hostname === 'docs.google.com' &&
		window.location.pathname.startsWith('/document/')
	);
}

export function createGoogleDocsBridgeSync(fw: LintFramework): () => Promise<void> {
	let bridgeClient: GoogleDocsBridgeClient | null = null;
	let bridgeAttached = false;
	let syncInFlight = false;
	let syncPending = false;
	let lastCloneSignature = '';
	let injectedMainWorldBridge = false;

	function ensureTarget(editor: HTMLElement): HTMLElement {
		let target = document.getElementById(GOOGLE_DOCS_TARGET_ID);

		if (!(target instanceof HTMLElement)) {
			target = document.createElement('div');
			target.id = GOOGLE_DOCS_TARGET_ID;
			target.setAttribute('data-harper-google-docs-target', 'true');
			target.setAttribute('aria-hidden', 'true');
			target.setAttribute('contenteditable', 'false');
			target.setAttribute('data-language', 'plaintext');
			target.style.position = 'absolute';
			target.style.top = '0';
			target.style.left = '0';
			target.style.width = '0';
			target.style.height = '0';
			target.style.overflow = 'visible';
			target.style.pointerEvents = 'none';
			target.style.opacity = '0';
			target.style.zIndex = '-2147483648';
			editor.appendChild(target);
		}

		if (target.parentElement !== editor) {
			editor.appendChild(target);
		}

		return target;
	}

	function ensureMainWorldBridge() {
		if (
			injectedMainWorldBridge ||
			document.getElementById(GOOGLE_DOCS_MAIN_WORLD_BRIDGE_ID) != null
		) {
			injectedMainWorldBridge = true;
			return;
		}

		const script = document.createElement('script');
		script.type = 'module';
		script.src = chrome.runtime.getURL('google-docs-bridge.js');
		script.onload = () => script.remove();
		(document.head || document.documentElement).appendChild(script);
		injectedMainWorldBridge = true;
	}

	function bindBridgeClient() {
		if (bridgeClient != null) {
			return;
		}

		bridgeClient = new GoogleDocsBridgeClient(document);
		window.__harperGoogleDocsBridgeClient = bridgeClient;

		bridgeClient.onTextUpdated(() => {
			void syncGoogleDocsBridge();
		});

		bridgeClient.onLayoutChanged((reason) => {
			if (!GOOGLE_DOCS_IGNORED_LAYOUT_REASONS.has(reason)) {
				(fw as LayoutRefreshFramework).refreshLayout?.();
			}
		});
	}

	function disposeBridgeClient() {
		bridgeClient?.dispose();
		bridgeClient = null;
		delete window.__harperGoogleDocsBridgeClient;
	}

	function normalizeGoogleDocsRectLabel(label: string): string {
		const parts = label.split(' ');
		let normalized = '';

		for (let index = 0; index < parts.length; index += 1) {
			const part = parts[index];
			if (part === '') {
				normalized += '\u00a0';
				continue;
			}

			normalized += part;
			if (index === parts.length - 1) {
				continue;
			}

			const keepTightRight = /[(["'“‘/_`-]$/u.test(part);
			const keepTightLeft = /^[)\]"'”’/_`—–-]/u.test(parts[index + 1] ?? '');

			if (!keepTightRight && !keepTightLeft) {
				normalized += ' ';
			}
		}

		return normalized;
	}

	function isStandaloneListMarker(text: string): boolean {
		return /^((\d+|[a-zA-Z]|[ivxlcdmIVXLCDM]+)[.)]|[-+*•◦▪‣●☐☑☒])$/u.test(text.trim());
	}

	function appendText(fragment: DocumentFragment, parts: string[], text: string) {
		if (text.length === 0) {
			return;
		}

		parts.push(text);
		fragment.appendChild(document.createTextNode(text));
	}

	function createCloneSpan(segment: GoogleDocsRectSegment, text: string): HTMLSpanElement {
		const span = document.createElement('span');
		span.textContent = text;
		span.style.position = 'absolute';
		span.style.whiteSpace = 'pre';
		span.style.overflow = 'hidden';
		span.style.left = `${segment.rect.left}px`;
		span.style.top = `${segment.rect.top}px`;
		span.style.width = `${Math.max(1, segment.rect.width)}px`;
		span.style.height = `${Math.max(1, segment.rect.height)}px`;
		span.style.lineHeight = `${Math.max(1, segment.rect.height)}px`;

		const fontCss = segment.rectNode.getAttribute('data-font-css');
		if (fontCss) {
			span.style.font = fontCss;
			// Docs zooms the SVG, but data-font-css remains in unscaled SVG units.
			// The mirror uses screen-space geometry, so its font must use the same scale.
			const svgWidth = segment.rectNode.width.baseVal.value;
			const fontSize = Number.parseFloat(span.style.fontSize);
			if (svgWidth > 0 && Number.isFinite(fontSize)) {
				span.style.fontSize = `${fontSize * (segment.rect.width / svgWidth)}px`;
			}
		}

		return span;
	}

	function canIgnoreLogicalGap(text: string): boolean {
		return /^\s*$/u.test(text);
	}

	function segmentsShareVisualLine(
		left: GoogleDocsRectSegment,
		right: GoogleDocsRectSegment,
	): boolean {
		return (
			rectSharesGoogleDocsLineBand(left.rect, createGoogleDocsLineBand(right.rect)) ||
			rectSharesGoogleDocsLineBand(right.rect, createGoogleDocsLineBand(left.rect))
		);
	}

	function compareSegments(left: GoogleDocsRectSegment, right: GoogleDocsRectSegment): number {
		if (segmentsShareVisualLine(left, right)) {
			const horizontalDelta = left.rect.left - right.rect.left;
			if (Math.abs(horizontalDelta) > 1) {
				return horizontalDelta;
			}
		}

		const verticalDelta = left.rect.top - right.rect.top;
		if (Math.abs(verticalDelta) > 1) {
			return verticalDelta;
		}

		const horizontalDelta = left.rect.left - right.rect.left;
		if (Math.abs(horizontalDelta) > 1) {
			return horizontalDelta;
		}

		return 0;
	}

	function collectRectSegments(editor: HTMLElement): GoogleDocsRectSegment[] {
		const editorRect = editor.getBoundingClientRect();
		const segments: GoogleDocsRectSegment[] = [];

		for (const rectNode of Array.from(
			editor.querySelectorAll<SVGRectElement>(GOOGLE_DOCS_RECT_SELECTOR),
		)) {
			const rawLabel = rectNode.getAttribute('aria-label');
			if (!rawLabel) {
				continue;
			}

			const text = normalizeGoogleDocsRectLabel(rawLabel);
			if (text.length === 0) {
				continue;
			}

			const rect = rectNode.getBoundingClientRect();
			if (!Number.isFinite(rect.top) || rect.width <= 0 || rect.height <= 0) {
				continue;
			}

			const top = rect.top - editorRect.top + editor.scrollTop;
			const left = rect.left - editorRect.left + editor.scrollLeft;
			if (!Number.isFinite(top) || !Number.isFinite(left)) {
				continue;
			}

			segments.push({
				rectNode,
				page: rectNode.closest('.kix-page-paginated'),
				text,
				rect: {
					top,
					left,
					width: rect.width,
					height: rect.height,
				},
			});
		}

		segments.sort(compareSegments);
		return segments;
	}

	function shouldRepairCollapsedGap(
		skippedText: string,
		previousText: string,
		nextText: string,
		sharesVisualLine: boolean,
	): boolean {
		return (
			skippedText.length === 0 &&
			!sharesVisualLine &&
			/[\p{L}\p{N}]$/u.test(previousText) &&
			/^[\p{L}\p{N}]/u.test(nextText)
		);
	}

	function normalizeLogicalGap(
		skippedText: string,
		previousText: string,
		nextText: string,
		sharesVisualLine: boolean,
		currentRect: GoogleDocsRectLayout,
		nextRect: GoogleDocsRectLayout | null,
	): string {
		if (shouldRepairCollapsedGap(skippedText, previousText, nextText, sharesVisualLine)) {
			return ' ';
		}

		if (!skippedText.includes('\n')) {
			return skippedText;
		}

		const startsNewTableColumn =
			nextRect != null &&
			rectSharesGoogleDocsLineBand(currentRect, createGoogleDocsLineBand(nextRect)) &&
			nextRect.left - currentRect.left > currentRect.width + 120;

		if (sharesVisualLine || startsNewTableColumn) {
			return skippedText.replace(/\n+/gu, '\n');
		}

		const shouldKeepParagraphBreak =
			!isStandaloneListMarker(previousText) && !isStandaloneListMarker(nextText);

		return skippedText.replace(/\n+/gu, shouldKeepParagraphBreak ? '\n\n' : '\n');
	}

	function shouldInsertSoftWrapSpace(
		previousText: string,
		nextText: string,
		lineGap: number,
		paragraphBreakThreshold: number,
	): boolean {
		return (
			lineGap < paragraphBreakThreshold &&
			/[\p{L}\p{N}]$/u.test(previousText) &&
			/^[\p{Ll}\p{N}]/u.test(nextText)
		);
	}

	function computeSignature(
		source: GoogleDocsCloneSnapshot['source'],
		text: string,
		segments: GoogleDocsRectSegment[],
		editor: HTMLElement,
	): string {
		const pages = Array.from(editor.querySelectorAll('.kix-page-paginated'));
		const paragraphs = Array.from(editor.querySelectorAll('g[role="paragraph"]'));
		return JSON.stringify([
			source,
			text,
			editor.scrollTop,
			editor.scrollLeft,
			segments.map((segment) => [
				segment.rect,
				segment.text,
				segment.rectNode.getAttribute('aria-label'),
				segment.rectNode.getAttribute('data-font-css'),
				pages.indexOf(segment.page!),
				paragraphs.indexOf(segment.rectNode.closest('g[role="paragraph"]')!),
			]),
		]);
	}

	function nativeOrdinaryBoundaries(native: string): number[] {
		// Trace UTF-16 boundaries through the existing CR conversion. Do not count
		// code points or recover offsets by looking for the diagnostic text later.
		const boundaries = [0];
		for (let offset = 0; offset < native.length; offset += 1) {
			if (native[offset] === '\r' && native[offset + 1] === '\n') offset += 1;
			boundaries.push(offset + 1);
		}
		return boundaries;
	}

	function buildLogicalSnapshot(
		editor: HTMLElement,
		segments: GoogleDocsRectSegment[],
		logicalText: string,
		nativeSnapshot: string,
	): GoogleDocsCloneSnapshot | null {
		if (logicalText.length === 0 || segments.length === 0) {
			return null;
		}

		const fragment = document.createDocumentFragment();
		const parts: string[] = [];
		const pieces: OrdinaryPiece[] = [];
		const nativeBoundaries = nativeOrdinaryBoundaries(nativeSnapshot);
		let projectionCursor = 0;
		let cursor = 0;
		let previousText = '';
		let currentLineBand: GoogleDocsLineBand | null = null;

		for (let index = 0; index < segments.length; index += 1) {
			const segment = segments[index];
			const startAtCursor = logicalText.startsWith(segment.text, cursor)
				? cursor
				: logicalText.indexOf(segment.text, cursor);

			if (startAtCursor < 0) {
				return null;
			}

			const skippedText = logicalText.slice(cursor, startAtCursor);
			if (!canIgnoreLogicalGap(skippedText)) {
				return null;
			}

			const sharesVisualLine: boolean =
				currentLineBand != null && rectSharesGoogleDocsLineBand(segment.rect, currentLineBand);
			const normalizedGap = /\n[^\S\n]*\n/u.test(skippedText)
				? skippedText
				: normalizeLogicalGap(
						skippedText,
						previousText,
						segment.text,
						sharesVisualLine,
						segment.rect,
						segments[index + 1]?.rect ?? null,
					);
			appendText(fragment, parts, normalizedGap);
			pieces.push([
				'gap',
				projectionCursor,
				projectionCursor + normalizedGap.length,
				nativeBoundaries[cursor],
				nativeBoundaries[startAtCursor],
			]);
			projectionCursor += normalizedGap.length;

			const span = createCloneSpan(segment, segment.text);
			span.setAttribute('data-harper-gdocs-native-start', String(nativeBoundaries[startAtCursor]));
			fragment.appendChild(span);
			pieces.push([
				'copy',
				projectionCursor,
				projectionCursor + segment.text.length,
				nativeBoundaries[startAtCursor],
				nativeBoundaries[startAtCursor + segment.text.length],
			]);
			projectionCursor += segment.text.length;
			parts.push(segment.text);
			cursor = startAtCursor + segment.text.length;
			previousText = segment.text;
			currentLineBand =
				currentLineBand == null || !sharesVisualLine
					? createGoogleDocsLineBand(segment.rect)
					: extendGoogleDocsLineBand(currentLineBand, segment.rect);
		}

		const trailingText = logicalText.slice(cursor);
		if (!canIgnoreLogicalGap(trailingText)) {
			return null;
		}

		appendText(fragment, parts, trailingText);
		pieces.push([
			'gap',
			projectionCursor,
			projectionCursor + trailingText.length,
			nativeBoundaries[cursor],
			nativeSnapshot.length,
		]);
		const text = parts.join('');

		return {
			fragment,
			text,
			source: 'logical',
			nativeSnapshot,
			nativeRuns: {
				format: 'ordinary-utf16-v1',
				source: 'logical',
				window: [0, nativeSnapshot.length],
				pieces,
			},
			segmentCount: segments.length,
			signature: computeSignature('logical', text, segments, editor),
		};
	}

	function getPageBoundarySeparator(
		previous: GoogleDocsRectSegment,
		current: GoogleDocsRectSegment,
		logicalText: string,
	): string {
		// A failed full-document alignment need not discard the logical gap here.
		// Repeated text is safe only when all occurrences are adjacent and agree.
		const currentContent = current.text.trimStart();
		const currentPrefix = current.text
			.slice(0, current.text.length - currentContent.length)
			.replace(/\u00a0/gu, ' ');
		let separator: string | null = null;
		let conflictingSeparators = false;
		let previousOccurrences = 0;
		let adjacentPairs = 0;
		let omittedProse = false;
		let cursor = 0;
		while (cursor < logicalText.length) {
			const start = logicalText.indexOf(previous.text, cursor);
			if (start < 0) break;
			previousOccurrences += 1;
			const end = start + previous.text.length;
			const nextStart = logicalText.indexOf(currentContent, end);
			if (nextStart >= 0 && !canIgnoreLogicalGap(logicalText.slice(end, nextStart))) {
				omittedProse = true;
			}
			const whitespace = /^\s*/u.exec(logicalText.slice(end))?.[0] ?? '';
			if (logicalText.startsWith(currentContent, end + whitespace.length)) {
				adjacentPairs += 1;
				// The rectangle already owns its prefix, even if Docs used regular spaces.
				const gap = whitespace.replace(/\u00a0/gu, ' ').endsWith(currentPrefix)
					? whitespace.slice(0, whitespace.length - currentPrefix.length)
					: whitespace;
				const normalized = normalizeLogicalGap(
					gap,
					previous.text,
					current.text,
					false,
					current.rect,
					null,
				);
				if (separator != null && separator !== normalized) {
					conflictingSeparators = true;
				}
				separator = normalized;
			}
			cursor = start + 1;
		}
		let currentOccurrences = 0;
		cursor = 0;
		while (currentContent.length > 0 && cursor < logicalText.length) {
			const start = logicalText.indexOf(currentContent, cursor);
			if (start < 0) break;
			currentOccurrences += 1;
			cursor = start + 1;
		}
		// Known missing prose is not an unknown gap. Isolate the visible regions
		// instead of manufacturing grammatical adjacency or choosing a repeated match.
		if (
			omittedProse ||
			(adjacentPairs > 0 &&
				currentContent.length > 0 &&
				(adjacentPairs !== previousOccurrences || adjacentPairs !== currentOccurrences))
		) {
			return '\n\n';
		}
		if (separator != null && !conflictingSeparators) return separator;

		// Page margins are layout, not paragraph semantics. Without a usable
		// logical gap, join conservatively rather than inventing a paragraph.
		if (/\s$/u.test(previous.text) || /^\s/u.test(current.text)) return '';
		// Straight quotes and apostrophes are ambiguous, not evidence for a tight join.
		if (/[([{“‘/_—–-]$/u.test(previous.text) || /^[,./:;!?%)\]}”’—–-]/u.test(current.text)) {
			return '';
		}
		return ' ';
	}

	function findUniqueRectWindow(
		logicalText: string,
		segments: GoogleDocsRectSegment[],
	): number[] | null {
		let unique: number[] | null = null;
		let search = 0;
		while (segments.length > 0 && search < logicalText.length) {
			const first = logicalText.indexOf(segments[0].text, search);
			if (first < 0) break;
			search = first + 1;
			const starts = [first];
			let end = first + segments[0].text.length;
			for (const segment of segments.slice(1)) {
				const start = logicalText.indexOf(segment.text, end);
				if (start < 0 || !canIgnoreLogicalGap(logicalText.slice(end, start))) break;
				starts.push(start);
				end = start + segment.text.length;
			}
			if (starts.length !== segments.length) continue;
			// Count embedded and overlapping matches before paragraph boundaries.
			// Synthesized spacing cannot distinguish two matching label sequences.
			if (unique != null) return null;
			unique = starts;
		}
		if (unique == null) return null;
		const first = unique[0];
		const end = unique[unique.length - 1] + segments[segments.length - 1].text.length;
		return (first === 0 || logicalText[first - 1] === '\n') &&
			(end === logicalText.length || logicalText[end] === '\n')
			? unique
			: null;
	}

	function buildRectSnapshot(
		editor: HTMLElement,
		segments: GoogleDocsRectSegment[],
		logicalText: string,
		nativeSnapshot: string,
	): GoogleDocsCloneSnapshot {
		const fragment = document.createDocumentFragment();
		const parts: string[] = [];
		const emitted: Array<{ start: number; end: number; span: HTMLSpanElement }> = [];
		let projectionCursor = 0;
		let previousText = '';
		let previousRect: GoogleDocsRectLayout | null = null;
		let previousSegment: GoogleDocsRectSegment | null = null;
		let currentLineBand: GoogleDocsLineBand | null = null;

		for (const segment of segments) {
			const sharesVisualLine: boolean =
				currentLineBand != null && rectSharesGoogleDocsLineBand(segment.rect, currentLineBand);
			const startsNewLine: boolean = currentLineBand != null && !sharesVisualLine;

			if (startsNewLine && currentLineBand != null) {
				const lineGap = Math.max(0, segment.rect.top - currentLineBand.bottom);
				const paragraphBreakThreshold = Math.max(
					GOOGLE_DOCS_MIN_PARAGRAPH_BREAK_GAP_PX,
					getGoogleDocsParagraphBreakThreshold(currentLineBand, segment.rect),
					Math.min(currentLineBand.height, segment.rect.height) * GOOGLE_DOCS_PARAGRAPH_BREAK_RATIO,
				);
				const changesPage =
					previousSegment?.page != null &&
					segment.page != null &&
					previousSegment.page !== segment.page;
				const breakText =
					changesPage && previousSegment != null
						? getPageBoundarySeparator(previousSegment, segment, logicalText)
						: shouldInsertSoftWrapSpace(
									previousText,
									segment.text,
									lineGap,
									paragraphBreakThreshold,
								)
							? ' '
							: lineGap >= paragraphBreakThreshold
								? '\n\n'
								: '\n';
				appendText(fragment, parts, breakText);
				projectionCursor += breakText.length;
			} else if (
				previousRect != null &&
				(isStandaloneListMarker(previousText) ||
					shouldInsertGoogleDocsSpace(previousRect, segment.rect, previousText, segment.text))
			) {
				appendText(fragment, parts, ' ');
				projectionCursor += 1;
			}

			const span = createCloneSpan(segment, segment.text);
			fragment.appendChild(span);
			emitted.push({ start: projectionCursor, end: projectionCursor + segment.text.length, span });
			projectionCursor += segment.text.length;
			parts.push(segment.text);
			previousText = segment.text;
			previousRect = segment.rect;
			previousSegment = segment;
			currentLineBand =
				currentLineBand == null || startsNewLine
					? createGoogleDocsLineBand(segment.rect)
					: extendGoogleDocsLineBand(currentLineBand, segment.rect);
		}

		let text = parts.join('');
		// A fallback may omit whole offscreen paragraphs, never text inside its
		// declared window. Prove occurrence identity with the actual labels/gaps.
		const starts = findUniqueRectWindow(logicalText, segments);
		const nativeRuns: OrdinaryMap = {
			format: 'ordinary-utf16-v1',
			source: 'rects',
			window: [0, 0],
			pieces: [],
		};
		if (starts != null) {
			const boundaries = nativeOrdinaryBoundaries(nativeSnapshot);
			let p = 0;
			let n = boundaries[starts[0]];
			nativeRuns.window[0] = n;
			for (let index = 0; index < emitted.length; index += 1) {
				const { start, end, span } = emitted[index];
				const nativeStart = boundaries[starts[index]];
				const nativeEnd = boundaries[starts[index] + segments[index].text.length];
				nativeRuns.pieces.push(['gap', p, start, n, nativeStart]);
				nativeRuns.pieces.push(['copy', start, end, nativeStart, nativeEnd]);
				span.setAttribute('data-harper-gdocs-native-start', String(nativeStart));
				p = end;
				n = nativeEnd;
			}
			nativeRuns.window[1] = n;
		} else {
			const boundaries = nativeOrdinaryBoundaries(nativeSnapshot);
			nativeRuns.regions = [];
			for (let index = 0; index < segments.length; index += 1) {
				// Retain the full-window label/gap contract here. Exact synthesized
				// paragraph text can hide another candidate with different whitespace.
				const first = index;
				const group = segments[index].rectNode.closest('g[role="paragraph"]');
				if (group != null) {
					while (
						index + 1 < segments.length &&
						segments[index + 1].rectNode.closest('g[role="paragraph"]') === group
					)
						index += 1;
				}
				const p0 = emitted[first].start;
				const p1 = emitted[index].end;
				const label = text.slice(p0, p1);
				const matches = findUniqueRectWindow(logicalText, segments.slice(first, index + 1));
				if (matches == null) continue;
				const match = matches[0];
				const matchEnd = matches[matches.length - 1] + segments[index].text.length;
				const start = boundaries[match];
				const end = boundaries[matchEnd];
				if (nativeSnapshot.slice(start, end) !== label) continue;
				nativeRuns.regions.push([p0, p1, start, end]);
				for (let part = first; part <= index; part += 1) {
					emitted[part].span.setAttribute(
						'data-harper-gdocs-native-start',
						String(start + emitted[part].start - p0),
					);
				}
			}
			// Only independently proven complete native paragraphs establish these
			// breaks. Do not infer them from physical line/page spacing or change
			// the existing projection of unproven text between other labels.
			const regionSpans = nativeRuns.regions.map((region) => ({
				region,
				first: emitted.find((part) => part.start === region[0])!.span,
				last: emitted.find((part) => part.end === region[1])!.span,
			}));
			for (const { first, last } of regionSpans) {
				let prefix = '';
				let suffix = '';
				for (let node = first.previousSibling; node != null; node = node.previousSibling)
					prefix = (node.textContent ?? '') + prefix;
				for (let node = last.nextSibling; node != null; node = node.nextSibling)
					suffix += node.textContent ?? '';
				if (prefix.length > 0 && !/\n[^\S\n]*\n\s*$/u.test(prefix))
					fragment.insertBefore(document.createTextNode('\n\n'), first);
				if (suffix.length > 0 && !/^\s*\n[^\S\n]*\n/u.test(suffix))
					fragment.insertBefore(document.createTextNode('\n\n'), last.nextSibling);
			}
			const offsets = new Map<Node, number>();
			let offset = 0;
			for (const node of Array.from(fragment.childNodes)) {
				offsets.set(node, offset);
				offset += node.textContent?.length ?? 0;
			}
			for (const { region, first, last } of regionSpans) {
				region[0] = offsets.get(first)!;
				region[1] = offsets.get(last)! + last.textContent!.length;
			}
			text = fragment.textContent ?? '';
		}

		return {
			fragment,
			text,
			source: 'rects',
			nativeSnapshot,
			nativeRuns,
			segmentCount: segments.length,
			signature: computeSignature('rects', text, segments, editor),
		};
	}

	function buildNativeTableSnapshot(
		editor: HTMLElement,
		segments: GoogleDocsRectSegment[],
		nativeSnapshot: string,
	): GoogleDocsCloneSnapshot {
		// Mask the observed controls without changing source characters. Confirmed
		// paragraph boundaries below can add LF, so lint offsets need explicit runs.
		// This is not a parser for the complete Google Docs control grammar.
		const masked = nativeSnapshot
			.replace(GOOGLE_DOCS_TABLE_SEPARATORS, '\n')
			.replace(GOOGLE_DOCS_SOFT_BREAKS, ' ');
		const comparable = nativeSnapshot.replace(/\u00a0/gu, ' ');
		const matchesBySegment = new Map<
			GoogleDocsRectSegment,
			{ start: number; end: number; segment: GoogleDocsRectSegment }
		>();
		const labels = new Map(
			segments.map((segment) => [
				segment,
				(segment.rectNode.getAttribute('aria-label') ?? '').replace(/\u00a0/gu, ' '),
			]),
		);
		for (const segment of segments) {
			// Preserve source characters. Only an equal-length space alias is used.
			const label = labels.get(segment)!;
			const start = comparable.indexOf(label);
			if (
				!label.trim() ||
				GOOGLE_DOCS_CONTROL_CHARACTERS.test(label) ||
				start < 0 ||
				comparable.indexOf(label, start + 1) >= 0
			)
				continue;
			matchesBySegment.set(segment, { start, end: start + label.length, segment });
		}
		// A paragraph's contiguous labels can uniquely anchor a repeated short word.
		// Screen order is used only within this group, never between native cells.
		// Multiple full matches are ambiguity, not permission to pick the nearest.
		const continuations = new Map<number, Set<Element>>();
		const groups = new Map<Element, GoogleDocsRectSegment[]>();
		for (const segment of segments) {
			const group = segment.rectNode.closest('g[role="paragraph"]');
			if (group) groups.set(group, [...(groups.get(group) ?? []), segment]);
		}
		for (const [group, groupSegments] of groups) {
			const ordered = groupSegments.toSorted(compareSegments);
			if (
				ordered.length < 2 ||
				ordered.some(
					(segment) =>
						!labels.get(segment)!.trim() ||
						GOOGLE_DOCS_CONTROL_CHARACTERS.test(labels.get(segment)!),
				)
			)
				continue;
			const firstLabel = labels.get(ordered[0])!;
			let cursor = 0;
			let unique: Array<{ start: number; end: number; segment: GoogleDocsRectSegment }> | null =
				null;
			while (cursor < comparable.length) {
				const first = comparable.indexOf(firstLabel, cursor);
				if (first < 0) break;
				const sequence = [{ start: first, end: first + firstLabel.length, segment: ordered[0] }];
				for (const segment of ordered.slice(1)) {
					const previousEnd = sequence[sequence.length - 1].end;
					const label = labels.get(segment)!;
					const start = comparable.indexOf(label, previousEnd);
					// biome-ignore lint/suspicious/noControlCharactersInRegex: Only ordinary whitespace may separate labels inside one native region.
					if (start < 0 || !/^[	\r\n ]*$/u.test(comparable.slice(previousEnd, start))) break;
					sequence.push({ start, end: start + label.length, segment });
				}
				if (sequence.length === ordered.length) {
					if (unique != null) {
						unique = null;
						break;
					}
					unique = sequence;
				}
				cursor = first + 1;
			}
			for (const match of unique ?? []) matchesBySegment.set(match.segment, match);
			// An aligned paragraph can identify LF as a wrap between its labels.
			// Keep this evidence separate from highlight resolution, which can
			// still reject overlapping boxes for the same native source range.
			for (let index = 1; unique != null && index < unique.length; index += 1) {
				const previous = unique[index - 1];
				const gap = nativeSnapshot.slice(previous.end, unique[index].start);
				const newline = gap.indexOf('\n');
				if (newline >= 0 && gap.indexOf('\n', newline + 1) < 0) {
					const offset = previous.end + newline;
					const agreeing = continuations.get(offset) ?? new Set<Element>();
					agreeing.add(group);
					continuations.set(offset, agreeing);
				}
			}
		}
		const matches = Array.from(matchesBySegment.values());
		const softLineBreaks = new Set<number>();
		for (const [newline, agreeing] of continuations) {
			// A separate anchored paragraph touching this LF contradicts a wrap.
			// Do not let conflicting SVG groups override the native hard boundary.
			const conflicting = matches.some(({ start, end, segment }) => {
				const group = segment.rectNode.closest('g[role="paragraph"]');
				if (group == null || agreeing.has(group)) return false;
				return (
					// biome-ignore lint/suspicious/noControlCharactersInRegex: Only non-line-breaking whitespace may touch this LF.
					(end <= newline && /^[	\r ]*$/u.test(comparable.slice(end, newline))) ||
					// biome-ignore lint/suspicious/noControlCharactersInRegex: Only non-line-breaking whitespace may touch this LF.
					(start > newline && /^[	\r ]*$/u.test(comparable.slice(newline + 1, start)))
				);
			});
			if (!conflicting) softLineBreaks.add(newline);
		}
		// Contradictory geometry is local ambiguity, never a reason to lint visual
		// table prose. Both overlapping assignments remain non-geometric gaps.
		const resolved = matches.filter(
			(match) =>
				!matches.some(
					(other) => other !== match && other.start < match.end && other.end > match.start,
				),
		);
		resolved.sort((left, right) => left.start - right.start);
		const paragraphBreaks = new Set<number>();
		// Native Enter is LF, even if either paragraph is repeated or unrendered.
		// Its linguistic meaning must not depend on a unique highlight anchor.
		// Keep positively identified same-paragraph wraps soft; page margins and
		// missing geometry are not evidence for a continuation. VT stays native.
		// biome-ignore lint/suspicious/noControlCharactersInRegex: Observed native paragraph/table boundaries plus adjacent whitespace.
		for (const gap of nativeSnapshot.matchAll(/[	\r\n \u0010\u0011\u0012\u001c]+/gu)) {
			const end = gap.index + gap[0].length;
			if (
				gap.index === 0 ||
				end === nativeSnapshot.length ||
				gap[0].replace(GOOGLE_DOCS_TABLE_SEPARATORS, '\n').includes('\n\n')
			)
				continue;
			const tableBoundary = gap[0].search(GOOGLE_DOCS_TABLE_SEPARATORS);
			const newline = gap[0].indexOf('\n');
			const boundary =
				tableBoundary >= 0
					? tableBoundary
					: newline >= 0 && !softLineBreaks.has(gap.index + newline)
						? newline
						: -1;
			if (boundary >= 0) paragraphBreaks.add(gap.index + boundary + 1);
		}
		const breaks = Array.from(paragraphBreaks).sort((left, right) => left - right);
		// Each run is [projection start, native start, UTF-16 length]. Inserted
		// separators are deliberately outside runs and cannot own an edit range.
		const nativeRuns: Array<[number, number, number]> = [];
		const parts: string[] = [];
		let nativeCursor = 0;
		let projectionCursor = 0;
		for (const end of [...breaks, nativeSnapshot.length]) {
			const slice = masked.slice(nativeCursor, end);
			nativeRuns.push([projectionCursor, nativeCursor, slice.length]);
			parts.push(slice);
			projectionCursor += slice.length;
			if (end < nativeSnapshot.length) {
				parts.push('\n');
				projectionCursor += 1;
			}
			nativeCursor = end;
		}
		const text = parts.join('');
		const projectOffset = (offset: number) => offset + breaks.filter((end) => end <= offset).length;
		const fragment = document.createDocumentFragment();
		let cursor = 0;
		for (const { start, end, segment } of resolved) {
			const projectedStart = projectOffset(start);
			const projectedEnd = projectOffset(end);
			fragment.appendChild(document.createTextNode(text.slice(cursor, projectedStart)));
			const span = createCloneSpan(segment, text.slice(projectedStart, projectedEnd));
			span.setAttribute('data-harper-gdocs-native-start', String(start));
			fragment.appendChild(span);
			cursor = projectedEnd;
		}
		fragment.appendChild(document.createTextNode(text.slice(cursor)));
		return {
			fragment,
			text,
			source: 'native',
			nativeSnapshot,
			nativeRuns,
			segmentCount: resolved.length,
			// Mapping identity includes exact ranges, geometry, and font. Legacy
			// normalized labels can stay equal when native matching changes.
			signature: JSON.stringify([
				editor.scrollTop,
				editor.scrollLeft,
				nativeRuns,
				resolved.map(({ start, end, segment }) => [
					start,
					end,
					segment.rect,
					segment.rectNode.getAttribute('data-font-css'),
				]),
			]),
		};
	}

	function buildSnapshot(editor: HTMLElement): GoogleDocsCloneSnapshot {
		const segments = collectRectSegments(editor);
		// The bridge removes only its leading sentinel and final newline. Keep the
		// exact remaining code units for mapped requests; CRLF conversion shifts them.
		const nativeText = document.getElementById(GOOGLE_DOCS_MAIN_WORLD_BRIDGE_ID)?.textContent ?? '';
		if (nativeText.search(GOOGLE_DOCS_TABLE_SEPARATORS) >= 0) {
			return buildNativeTableSnapshot(editor, segments, nativeText);
		}
		// Display normalization is lossy: it can turn a raw label into an exact
		// match for a different native paragraph, or hide known omitted prose.
		// Keep raw source labels throughout ordinary native matching/projection.
		// Without native text, retain the legacy display-only normalization.
		const ordinarySegments =
			nativeText.length > 0
				? segments.map((segment) => ({
						...segment,
						text: segment.rectNode.getAttribute('aria-label')!,
					}))
				: segments;
		const logicalText = nativeText.replace(/\r\n?/gu, '\n');
		return (
			buildLogicalSnapshot(editor, ordinarySegments, logicalText, nativeText) ??
			buildRectSnapshot(editor, ordinarySegments, logicalText, nativeText)
		);
	}

	function applySnapshot(target: HTMLElement, snapshot: GoogleDocsCloneSnapshot): boolean {
		const previousNative = target.getAttribute('data-harper-gdocs-native-snapshot');
		const serializedRuns =
			snapshot.nativeSnapshot != null ? JSON.stringify(snapshot.nativeRuns) : null;
		if (
			snapshot.signature === lastCloneSignature &&
			target.textContent === snapshot.text &&
			target.getAttribute('data-harper-gdocs-source') === snapshot.source &&
			target.getAttribute('data-harper-gdocs-native-runs') === serializedRuns &&
			previousNative === (snapshot.nativeSnapshot ?? null)
		) {
			return false;
		}

		target.replaceChildren(snapshot.fragment);
		if (snapshot.nativeSnapshot != null) {
			target.setAttribute('data-harper-gdocs-native-snapshot', snapshot.nativeSnapshot);
			target.setAttribute('data-harper-gdocs-native-runs', serializedRuns!);
		} else {
			target.removeAttribute('data-harper-gdocs-native-snapshot');
			target.removeAttribute('data-harper-gdocs-native-runs');
		}
		target.setAttribute('data-harper-gdocs-source', snapshot.source);
		target.setAttribute('data-harper-gdocs-segments', String(snapshot.segmentCount));
		lastCloneSignature = snapshot.signature;
		return true;
	}

	async function syncGoogleDocsBridge() {
		if (!isGoogleDocsPage()) {
			disposeBridgeClient();
			bridgeAttached = false;
			return;
		}

		if (syncInFlight) {
			syncPending = true;
			return;
		}

		syncInFlight = true;

		try {
			ensureMainWorldBridge();
			bindBridgeClient();

			const editor = document.querySelector(GOOGLE_DOCS_EDITOR_SELECTOR);
			if (!(editor instanceof HTMLElement)) {
				return;
			}

			const target = ensureTarget(editor);
			editor.setAttribute(GOOGLE_DOCS_SYNCING_ATTR, 'true');

			const changed = applySnapshot(target, buildSnapshot(editor));
			if (!bridgeAttached) {
				await fw.addTarget(target);
				bridgeAttached = true;
			}

			if (changed) {
				await fw.update();
			}
		} catch (error) {
			console.error('Failed to sync Google Docs bridge text', error);
		} finally {
			const editor = document.querySelector(GOOGLE_DOCS_EDITOR_SELECTOR);
			if (editor instanceof HTMLElement) {
				// Snapshot replacement is complete before the queued animation-frame render.
				// Keeping this flag set delays that render until an unrelated later update.
				editor.removeAttribute(GOOGLE_DOCS_SYNCING_ATTR);
			}

			syncInFlight = false;
			if (syncPending) {
				syncPending = false;
				void syncGoogleDocsBridge();
			}
		}
	}

	return syncGoogleDocsBridge;
}