Google Docs Integration

Relevant source files

The following files were used as context for generating this wiki page:

• extension/src/content/google-docs.ts
• extension/src/content/gdocs-helpers.ts
• extension/src/content/gdocs-comments.ts
• extension/src/content/gdocs.ts
• extension/src/background/index.ts

Google Docs Integration enables AI-powered document analysis and writing assistance directly within the Google Docs editor. The system overcomes the technical challenges of the Google Docs canvas-based renderer to provide precise highlights, structural edits, and interactive comments.

The integration serves two primary roles:

1. Annotation and Analysis: Detecting document content to provide AI-driven insights, claims, and critiques via an overlay layer.
2. Writing Assistance: A comprehensive workflow involving multiple-choice questions (MCQ), outline planning, and "Cursor-style" surgical edits that the user can review and apply.

Sources: extension/src/content/gdocs.ts, extension/src/content/google-docs.ts

Document Detection and Text Extraction

The integration identifies Google Docs by monitoring the hostname and URL path. It extracts the unique docId to interact with Google APIs and maintain persistent sessions.

Extraction follows a prioritized hierarchy to ensure text accuracy:

1. API Export: The extension fetches document text via the Google Docs export URL (/export?format=txt). This provides the most reliable full-text representation.
2. DOM Scraping: If the API is unreachable, the system attempts to scrape paragraph elements (.kix-paragraphrenderer). This serves as a fallback for older Google Docs versions or restricted permissions.
3. Persistence: Extracted text is cached to assist with positioning logic when the document is edited.

Sources: extension/src/content/google-docs.ts:5-132, extension/src/content/gdocs-helpers.ts:11-49

Text Resolution Logic

The extraction pipeline ensures that AI features always have context, even if the primary Google API is unavailable.
Sources: extension/src/content/gdocs-helpers.ts:25-49

Positioning and Canvas Rendering Architecture

Google Docs uses a custom canvas engine to render text, which means standard DOM text nodes are often absent or invisible. Oddity1 implements a "Pretext" layout simulation and a "Cursor-based" correction system to place highlights accurately.

The Positioning Pipeline

1. Layout Simulation: The system uses a pretext engine to simulate how Google Docs wraps text based on page width, margins, and font metrics.
2. Rough Estimation: It calculates an approximate X/Y coordinate for an annotation's anchor text.
3. Native Highlight Correction: To achieve pixel perfection, the system programmatically triggers a native Google Docs highlight on the anchor text.
4. Canvas Scanning: It scans the document's <canvas> tiles for specific RGB pixel values matching the native highlight colors (Green/Red).
5. Refinement: Once the pixels are located, the Oddity overlay snaps to the detected pixel coordinates and stores the result.

Sources: extension/src/content/google-docs.ts:260-450, extension/src/background/index.ts:1040-1065

Coordinate Resolution Sequence

The correction system ensures that annotations track correctly even when users change font sizes or page zoom.
Sources: extension/src/content/google-docs.ts:503-535

AI Writing Assistant Workflow

The integration features a structured workflow for generating new content or modifying existing documents.

Phase	Description
Topic Entry	User provides a prompt or request (e.g., "Write an essay about AI ethics").
MCQ Clarification	The AI generates 5 multiple-choice questions to determine intent, tone, and audience.
Outline/Skeleton	For complex requests (PLAN mode), the AI provides a structural skeleton for approval.
Drafting	The AI generates the full content, wrapped in <<<ESSAY>>> tags for insertion.
Surgical Edits	For targeted changes (FAST mode), the AI provides specific replacements in <<<EDIT>>> blocks.

Sources: extension/src/content/gdocs.ts:117-210, extension/src/content/gdocs.ts:1100-1160

Edit Modes

The system routes requests into two modes based on complexity:

• FAST: Small, targeted changes like rephrasing a sentence or fixing word choice.
• PLAN: Large structural changes, such as reordering sections or drafting from scratch.

Sources: extension/src/content/gdocs.ts:1170-1200, extension/src/background/index.ts:1330-1345

Edit Application and Review Panel

When the AI suggests edits, they are not applied blindly. Oddity1 implements a "Review Panel" that allows users to inspect changes in the document before finalizing them.

Applying Edits

1. Tag Parsing: The system parses REPLACE, DELETE, and INSERT operations from the AI response.
2. Conflict Detection: It performs a "Cascading Edit Guard" to ensure a new edit doesn't conflict with a replacement made in the same batch.
3. Highlighting: Suggested changes are highlighted in Orange (deletion) and Blue (insertion) using the Google Docs API.
4. Review UI: A panel appears in the sidebar allowing the user to "Keep" or "Revert" individual changes or the entire batch.

Sources: extension/src/content/gdocs.ts:696-850, extension/src/background/index.ts:1068-1180

Edit Operations Table

Operation	Action	Color Code
REPLACE	Swaps existing text with new content.	Orange (Old) / Blue (New)
DELETE	Removes text entirely.	Orange
INSERT	Adds new text after a specific anchor.	Blue

Sources: extension/src/content/gdocs.ts:476-505, extension/src/background/index.ts:1105-1120

Comment Synchronization

The integration maps AI annotations to native Google Docs comments, allowing for a collaborative-style workflow.

• Generation: AI annotations (critiques, questions) are automatically inserted as comments at their relevant anchors.
• Reply Monitoring: The extension observes the Google Docs comment stream. When a user replies to an AI-generated comment, the text is extracted and stored in the session history.
• Contextual Awareness: These replies are fed back into subsequent AI prompts, ensuring the assistant "remembers" user feedback regarding specific sections.

Sources: extension/src/content/gdocs-comments.ts, extension/src/content/gdocs.ts:645-680

Conclusion

The Google Docs Integration provides a seamless bridge between a static editor and a dynamic AI writing environment. By combining low-level canvas scanning with high-level document manipulation APIs, it enables precise feedback and surgical document editing that maintains the user's intent and document structure.