Antigravity LaTeX Chat Patch 🚀

A lightweight, zero-dependency, and Trusted-Types compliant patch tool that brings rich mathematical typesetting (LaTeX / KaTeX) directly into the Antigravity IDE chat conversation panel.

---

🌐 Language Navigation / Chuyển đổi ngôn ngữ

• English Documentation
  • The Problem
  • Key Features
  • Quick Start
  • How It Works
  • Safety & Reliability
• Tài liệu Tiếng Việt
  • Vấn đề được giải quyết
  • Tính năng nổi bật
  • Hướng dẫn sử dụng
  • Cơ chế kỹ thuật
  • Bảo mật và an toàn
• License

---

🇬🇧 English Documentation

💡 The Problem

While Antigravity IDE natively renders LaTeX formulas in the built-in Markdown: Preview to the Side tab, its primary AI Agent conversation panel lacks native math parsing:

1. Mathematical expressions written in standard syntax ($...$ and $$...$$) remain raw, unformatted text.
2. Markdown parsing can break math formulas by turning subscripts like _{xx} into italic <em> tags.
3. Strict Chromium Trusted Types CSP (require-trusted-types-for 'script') prevents naive HTML injection methods (innerHTML).

Antigravity LaTeX Patch resolves all these problems by injecting a non-destructive, Trusted-Types safe observer into the Antigravity Workbench window.

---

✨ Key Features

• ⚡ Real-Time AI Streaming: Dynamically typesets formulas token-by-token as the AI generates mathematical responses.
• 🛡️ 100% Trusted-Types & CSP Compliant: Built strictly using W3C DOM Range & Node Manipulation APIs—zero innerHTML usage.
• 🔤 Math-Italic Un-mangler: Automatically prevents Markdown from corrupting LaTeX subscripts (_{xx}, _{xy}).
• 📐 Strict Block Scoping: Isolates equation parsing to individual paragraphs and list items, preventing formulas from swallowing headings, dividers, or text.
• 🌐 100% Offline: Leverages the KaTeX engine and web fonts already bundled with Antigravity IDE. No internet or external CDN required.
• 🔄 Safe & Reversible: Atomic 1-click install and 1-click rollback with automated clean backups.

---

📦 Quick Start

Requirements

• Node.js >= 16.0.0
• Antigravity IDE installed on Windows, macOS, or Linux.

1. Installation

Clone this repository and run the install command:

git clone https://github.com/dznpev/antigravity-latex-patch.git
cd antigravity-latex-patch
node bin/cli.js install

2. Reload Antigravity IDE

Press Ctrl + Shift + P (or Cmd + Shift + P on macOS) -> select Developer: Reload Window (or restart the IDE).

3. Verify

Open the developer console (Help -> Toggle Developer Tools), and you will see:

[Antigravity LaTeX Patch v1.0.0] Production AI Math Engine active.

4. Uninstallation (Restore original files)

To completely revert Antigravity IDE to its original state:

node bin/cli.js uninstall

Then reload the window.

---

🔬 How It Works Under The Hood

Antigravity IDE (workbench.html)
  ├── Loads ag-latex-style.css (KaTeX font styles)
  └── Loads ag-latex-script.js
        ├── KaTeX Engine (decapsulated factory)
        ├── Un-mangler (recovers LaTeX underscores from markdown <em>)
        ├── Strict Block Scoper (processes <p>, <li>, <blockquote> independently)
        ├── W3C DOM Range API (replaces math tokens without innerHTML)
        └── MutationObserver (debounced real-time wake on streaming tokens)

1. Workbench Injection: Injects standalone scripts directly into workbench.html, targeting the core Workbench process where the AI chat UI runs.
2. AST Protection: Before parsing, the un-mangler detects italic tags generated by Markdown between math subscripts and restores original LaTeX underscores.
3. W3C Range Replacement: Uses document.createRange() and range.insertNode(span) to insert KaTeX elements directly, ensuring zero violation of Chromium's require-trusted-types-for 'script'.

---

🔒 Safety & Reliability

• Idempotent: Running install multiple times will never duplicate code or corrupt files.
• Original Backup Preserved: The first clean backup (.bak) is permanently preserved and never overwritten by subsequent runs.
• Clean Console: Internal KaTeX font metric warnings for non-Latin characters (e.g. Vietnamese glyphs) and non-strict unicode warnings are filtered.

---

🇻🇳 Tài liệu Tiếng Việt

💡 Vấn đề được giải quyết

Khi trò chuyện với AI Agent trên Antigravity IDE, các công thức toán học ($...$ và $$...$$) thường chỉ hiển thị dưới dạng văn bản thô khó nhìn. Trong khi đó, tính năng Preview to the Side lại hiển thị rất đẹp.

Antigravity LaTeX Patch mang trọn vẹn khả năng hiển thị toán học KaTeX chất lượng cao vào ngay trong khung chat, hoạt động mượt mà với cả quá trình AI đang sinh câu trả lời (streaming).

---

✨ Tính năng nổi bật

• ⚡ Hỗ trợ Streaming thời gian thực: Render mượt mà từng ký hiệu toán học khi Agent đang gõ câu trả lời theo thời gian thực.
• 🛡️ Bảo mật tuyệt đối (Trusted Types Compliant): 100% sử dụng W3C DOM Range & Node Manipulation API, không bao giờ vi phạm chính sách bảo mật CSP TrustedHTML của Chromium.
• 🔤 Bộ giải cứu chỉ số dưới (Un-mangler): Tự động ngăn chặn Markdown hiểu nhầm các ký tự gạch dưới (_{xx}, _{xy}) thành thẻ in nghiêng <em>.
• 📐 Khóa ranh giới khối (Strict Block Scoping): Cô lập từng khối văn bản (<p>, <li>), ngăn chặn triệt để hiện tượng công thức nuốt chửng tiêu đề, thẻ kẻ ngang <hr> hoặc nhân bản văn bản.
• 🌐 Hoàn toàn Offline: Sử dụng trực tiếp bộ thư viện KaTeX và font toán học tích hợp sẵn bên trong Antigravity IDE, không cần kết nối mạng hay tải từ CDN.
• 🔄 Cài đặt & Gỡ bỏ 1 chạm: Tự động sao lưu file gốc và khôi phục nguyên trạng 100% chỉ bằng một dòng lệnh.

---

📦 Hướng dẫn sử dụng

Yêu cầu

• Đã cài đặt Node.js >= 16.0.0
• Antigravity IDE trên Windows, macOS hoặc Linux.

1. Cài đặt Patch

Mở terminal và thực thi:

git clone https://github.com/dznpev/antigravity-latex-patch.git
cd antigravity-latex-patch
node bin/cli.js install

2. Tải lại Antigravity IDE

Nhấn tổ hợp phím Ctrl + Shift + P -> gõ và chọn Developer: Reload Window (hoặc khởi động lại IDE).

3. Kiểm tra trạng thái

node bin/cli.js status

4. Gỡ bỏ Patch (Khôi phục nguyên bản)

Khi muốn gỡ bỏ hoàn toàn và trả IDE về trạng thái xuất xưởng:

node bin/cli.js uninstall

Sau đó Reload Window để hoàn tất.

---

🔬 Cơ chế kỹ thuật chuyên sâu

1. Vị trí can thiệp: Script được nạp trực tiếp qua workbench.html của Antigravity Workbench, nơi giao diện chat chính thức được render.
2. Thao tác DOM tuân thủ Trusted Types: Thay vì dùng innerHTML (vốn bị Chromium chặn đứng), công cụ sử dụng document.createRange() và window.katex.render() để tạo DOM node toán học trực tiếp.
3. Khử cảnh báo Console: Tự động tắt cảnh báo strict mode, khử các ký tự unicode lạ từ AI (như dấu phẩy trên ′, khoảng trắng vô hình \u200B) và lọc cảnh báo font metrics cho tiếng Việt.

---

📂 Cấu trúc thư mục

antigravity-latex-patch/
├── package.json          # Package manifest & npm scripts
├── LICENSE               # MIT License
├── README.md             # Song ngữ EN / VI documentation
├── .gitignore            # Git exclusion rules
├── bin/
│   └── cli.js            # Giao diện dòng lệnh CLI (install, uninstall, status)
└── src/
    ├── index.js          # Main programmatic API (AntigravityLatexPatcher)
    ├── detector.js       # Auto-discovery for Antigravity IDE paths
    ├── backup.js         # Safe atomic file backup & restore manager
    └── injector.js       # Client script builder & HTML injector

---

📄 License

This project is licensed under the MIT License - feel free to use, modify, and contribute.