From 0430d4954982a2e91412fc22c79f89a8b06ef181 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 28 Jul 2026 08:01:19 +0000
Subject: [PATCH 1/4] Add CODE_REVIEW.md and LIGHTNING_TALK.md

Co-authored-by: lucasrangit <701818+lucasrangit@users.noreply.github.com>
---
 CODE_REVIEW.md    | 40 ++++++++++++++++++++++++++++++++++++
 LIGHTNING_TALK.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)
 create mode 100644 CODE_REVIEW.md
 create mode 100644 LIGHTNING_TALK.md

diff --git a/CODE_REVIEW.md b/CODE_REVIEW.md
new file mode 100644
index 0000000..b54af85
--- /dev/null
+++ b/CODE_REVIEW.md
@@ -0,0 +1,40 @@
+# Code Review: Plotline Google Docs Add-on
+
+## Summary
+The codebase is logically organized into frontend (`Sidebar.html`, `PickerModal.html`) and backend components (`Code.js`, `Data.js`, `Library.js`). The separation of Google Docs context vs standard Apps Script logic is solid. However, following the `AGENTS.md` guidelines and general best practices, the following architectural and stylistic improvements would elevate the project.
+
+## 1. Modern JavaScript & V8 Engine Support
+
+Google Apps Script now runs on the V8 engine, which supports ES2017 syntax. Several files use older syntax that can be modernized for readability and performance.
+
+### Suggestions:
+- **`var` vs `let`/`const`:** In frontend scripts (e.g., `Sidebar.html` and `PickerModal.html`), variables are extensively declared using `var` (e.g., `var html`, `var appData`). Use `let` and `const` for proper block-scoping.
+- **Loops:** You rely heavily on C-style `for` loops (e.g., `for (let i = 0; i < paragraphs.length; i++)` in `Data.js`). Utilize `for...of` loops, or higher-order array methods like `.map()`, `.filter()`, and `.reduce()` for cleaner iteration.
+- **Object Iteration:** In `Data.js` (`migrateRevisionLegacyCachedWordCounts`, `getRevisionCachedWordCounts`), loops are driven by `Object.keys()`. You can streamline these blocks using `Object.entries()` or modern iteration directly on Maps if you refactor the caching logic.
+- **String Interpolation:** Update string concatenations (e.g., `"Revision " + rev.id + " Date: " + new Date(rev.date).toLocaleString()`) to template literals (e.g., `` `Revision ${rev.id} Date: ${new Date(rev.date).toLocaleString()}` ``).
+
+## 2. Magic Strings and Centralized Constants
+
+Strings used for property keys, DOM IDs, and error messages are hardcoded across multiple functions, which increases the likelihood of typos and complicates future refactors.
+
+### Suggestions:
+- Extract property keys (e.g., `'WORD_COUNT_GOAL'`, `'SIMULATE_FILE_NOT_FOUND'`) into a central `Constants` object at the top of your scripts.
+- Extract common error string matchers in `showError()` (`Sidebar.html`) to well-named constant arrays or objects.
+- Centralize cache keys and prefixes (e.g., `"REV_WC_"`, `"ALL_REVISIONS_CACHE"`) into the same module/scope to prevent drift.
+
+## 3. Frontend Architecture (Separation of Concerns)
+
+The HTML files (`Sidebar.html`, `PickerModal.html`) contain a dense mixture of HTML markup, inline CSS styles, and client-side JavaScript logic.
+
+### Suggestions:
+- **Componentization:** Move styles into a separate `Stylesheet.html` and scripts into a `JavaScript.html` file. You can then include these dynamically in your main HTML files using `HtmlService.createTemplateFromFile()` and `<?!= include('Stylesheet'); ?>` scriptlets.
+- **Inline Event Handlers:** Remove inline HTML event handlers (e.g., `onload="onLoad()"`, `onclick="refreshOutline()"`) in favor of standard event listeners attached within your client-side JavaScript block (e.g., `document.getElementById('refreshBtn').addEventListener('click', refreshOutline)`).
+- **DOM Manipulations:** The frequent string concatenation to build HTML nodes (e.g., `var html = '<div class="outline-item"...`) is verbose and prone to XSS risks (though you have an `escapeHtml` function, manual concatenation is still brittle). Consider using standard DOM methods (`document.createElement`) or a lightweight UI templating system to generate complex dynamic lists.
+
+## 4. General Best Practices
+
+- **Configuration:** Configuration options in `PickerModal.html` refer directly to `GOOGLE_CLOUD_API_KEY` and `GOOGLE_CLOUD_PROJECT_NUMBER`. Ensure proper fallback defaults and validation in your backend configuration getters.
+- **Error Handling:** The backoff retry wrapper in `Library.js` is great, but ensure you properly handle non-fatal transient Drive API errors explicitly before resorting to random backoffs. Wait explicitly on `429` retry-after headers if they are provided.
+
+---
+*Overall, the integration logic is sound and the backend is well-structured for Apps Script execution.*
diff --git a/LIGHTNING_TALK.md b/LIGHTNING_TALK.md
new file mode 100644
index 0000000..905301e
--- /dev/null
+++ b/LIGHTNING_TALK.md
@@ -0,0 +1,52 @@
+# Lightning Talk: Inside Plotline
+
+**Duration:** ~5 Minutes
+
+---
+
+## 0:00 - Introduction (1 minute)
+
+**Presenter:**
+"Hi everyone. Today I'm going to give you a quick look under the hood of **Plotline**, a Google Docs Add-on.
+
+For those who haven't used it, Plotline tracks your writing productivity. It sits right inside Google Docs in a sidebar and gives you visualizations of your word count progress over time. You can set goals, track your average daily words, and see when you'll likely hit your target.
+
+The interesting part, from a development perspective, is how this is built purely using Google Apps Script running on Google's servers. Let's dive into the architecture."
+
+---
+
+## 1:00 - Architecture and API Integration (1.5 minutes)
+
+**Presenter:**
+"Plotline is divided into two main environments: the frontend HTML/JS that renders the Sidebar, and the backend Apps Script code that hooks into the Document and Drive APIs.
+
+To get a historical word count timeline, we need to inspect past revisions of a document. We use the Google Drive `Revisions.list` API to get the revision timestamps. However, the Revisions API doesn't just hand us the plain text. Instead, it provides `exportLinks`.
+
+Our backend code makes a separate HTTP request using `UrlFetchApp` to download the `text/plain` export of each revision. We parse the downloaded snapshot to count the words at that exact moment in time."
+
+---
+
+## 2:30 - Exponential Backoff (1 minute)
+
+**Presenter:**
+"When you have a document with dozens or hundreds of revisions, fetching export links sequentially can trigger Google's rate limits—specifically HTTP 429 'Too Many Requests'.
+
+To handle this gracefully, we implemented a custom wrapper for `UrlFetchApp`. If it detects a 429 or a 5xx error, it doesn't crash the sidebar. Instead, it applies an **exponential backoff algorithm**. It pauses execution—multiplying the wait time on each subsequent attempt—and adds a little random 'jitter' so concurrent requests don't retry at the exact same millisecond. This ensures the add-on recovers automatically from transient load issues."
+
+---
+
+## 3:30 - Caching Strategy (1 minute)
+
+**Presenter:**
+"Of course, re-fetching old revisions over and over would be incredibly slow. So, we heavily utilize `PropertiesService.getDocumentProperties()`.
+
+Once a revision's word count is calculated, it's permanently stored as a key-value pair tied directly to that document (e.g., `REV_WC_12345` -> `Date,WordCount`). The next time the user opens the sidebar or refreshes, Plotline pulls everything from the cache instantly, and only queries the Drive API for *new* revisions that happened since the last check. It dramatically speeds up the UI."
+
+---
+
+## 4:30 - UI Implementation & Wrap Up (30 seconds)
+
+**Presenter:**
+"Finally, the UI itself. We use `HtmlService` to serve the sidebar, and client-side JavaScript talks to our backend functions using `google.script.run`. Because Apps Script calls are asynchronous, we use success and failure handlers to update the DOM—like rendering our Chart.js timeline or showing error messages—without freezing the Docs interface.
+
+And that's Plotline! A serverless add-on turning raw revision data into actionable insights for writers. Thanks!"

From 57d0f7fdfeceb991495263ab90c09d1857955073 Mon Sep 17 00:00:00 2001
From: Lucas Rangit MAGASWERAN <lucasrangit@gmail.com>
Date: Tue, 28 Jul 2026 10:36:20 +0200
Subject: [PATCH 2/4] Update CODE_REVIEW.md

---
 CODE_REVIEW.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/CODE_REVIEW.md b/CODE_REVIEW.md
index b54af85..dbe63c5 100644
--- a/CODE_REVIEW.md
+++ b/CODE_REVIEW.md
@@ -11,7 +11,6 @@ Google Apps Script now runs on the V8 engine, which supports ES2017 syntax. Seve
 - **`var` vs `let`/`const`:** In frontend scripts (e.g., `Sidebar.html` and `PickerModal.html`), variables are extensively declared using `var` (e.g., `var html`, `var appData`). Use `let` and `const` for proper block-scoping.
 - **Loops:** You rely heavily on C-style `for` loops (e.g., `for (let i = 0; i < paragraphs.length; i++)` in `Data.js`). Utilize `for...of` loops, or higher-order array methods like `.map()`, `.filter()`, and `.reduce()` for cleaner iteration.
 - **Object Iteration:** In `Data.js` (`migrateRevisionLegacyCachedWordCounts`, `getRevisionCachedWordCounts`), loops are driven by `Object.keys()`. You can streamline these blocks using `Object.entries()` or modern iteration directly on Maps if you refactor the caching logic.
-- **String Interpolation:** Update string concatenations (e.g., `"Revision " + rev.id + " Date: " + new Date(rev.date).toLocaleString()`) to template literals (e.g., `` `Revision ${rev.id} Date: ${new Date(rev.date).toLocaleString()}` ``).
 
 ## 2. Magic Strings and Centralized Constants
 

From 45919c0e3f7dd79a4c494f23cc5643cb464a102d Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Wed, 29 Jul 2026 07:27:52 +0000
Subject: [PATCH 3/4] Update CODE_REVIEW.md with best practices

Co-authored-by: lucasrangit <701818+lucasrangit@users.noreply.github.com>
---
 CODE_REVIEW.md | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/CODE_REVIEW.md b/CODE_REVIEW.md
index dbe63c5..ca750dc 100644
--- a/CODE_REVIEW.md
+++ b/CODE_REVIEW.md
@@ -11,6 +11,7 @@ Google Apps Script now runs on the V8 engine, which supports ES2017 syntax. Seve
 - **`var` vs `let`/`const`:** In frontend scripts (e.g., `Sidebar.html` and `PickerModal.html`), variables are extensively declared using `var` (e.g., `var html`, `var appData`). Use `let` and `const` for proper block-scoping.
 - **Loops:** You rely heavily on C-style `for` loops (e.g., `for (let i = 0; i < paragraphs.length; i++)` in `Data.js`). Utilize `for...of` loops, or higher-order array methods like `.map()`, `.filter()`, and `.reduce()` for cleaner iteration.
 - **Object Iteration:** In `Data.js` (`migrateRevisionLegacyCachedWordCounts`, `getRevisionCachedWordCounts`), loops are driven by `Object.keys()`. You can streamline these blocks using `Object.entries()` or modern iteration directly on Maps if you refactor the caching logic.
+- **String Interpolation:** Update string concatenations (e.g., `"Revision " + rev.id + " Date: " + new Date(rev.date).toLocaleString()`) to template literals (e.g., `` `Revision ${rev.id} Date: ${new Date(rev.date).toLocaleString()}` ``).
 
 ## 2. Magic Strings and Centralized Constants
 
@@ -30,10 +31,13 @@ The HTML files (`Sidebar.html`, `PickerModal.html`) contain a dense mixture of H
 - **Inline Event Handlers:** Remove inline HTML event handlers (e.g., `onload="onLoad()"`, `onclick="refreshOutline()"`) in favor of standard event listeners attached within your client-side JavaScript block (e.g., `document.getElementById('refreshBtn').addEventListener('click', refreshOutline)`).
 - **DOM Manipulations:** The frequent string concatenation to build HTML nodes (e.g., `var html = '<div class="outline-item"...`) is verbose and prone to XSS risks (though you have an `escapeHtml` function, manual concatenation is still brittle). Consider using standard DOM methods (`document.createElement`) or a lightweight UI templating system to generate complex dynamic lists.
 
-## 4. General Best Practices
+## 4. Apps Script Production & General Best Practices
 
-- **Configuration:** Configuration options in `PickerModal.html` refer directly to `GOOGLE_CLOUD_API_KEY` and `GOOGLE_CLOUD_PROJECT_NUMBER`. Ensure proper fallback defaults and validation in your backend configuration getters.
-- **Error Handling:** The backoff retry wrapper in `Library.js` is great, but ensure you properly handle non-fatal transient Drive API errors explicitly before resorting to random backoffs. Wait explicitly on `429` retry-after headers if they are provided.
+- **Missing License:** The repository does not include a `LICENSE` file. For an open-source or publicly distributed project, adding a clear license (e.g., MIT, Apache 2.0) is crucial to clarify usage and distribution rights.
+- **Automated Testing Suite:** The project currently relies on manual end-to-end browser tests (`TESTS.md`, `browser-test` skill). There is no automated unit testing suite (e.g., using Jest or Mocha with Clasp) for backend utility functions like heading parsing or math calculations. Adding unit tests will drastically improve maintainability.
+- **Configuration & Secrets:** Configuration options in `PickerModal.html` refer directly to `GOOGLE_CLOUD_API_KEY` and `GOOGLE_CLOUD_PROJECT_NUMBER`. Ensure proper fallback defaults and validation in your backend configuration getters. Avoid checking any real keys into the codebase.
+- **Error Handling & Quotas:** The backoff retry wrapper in `Library.js` is excellent for handling 429s. However, ensure you properly wait explicitly on `429` retry-after headers if they are provided by the Drive API, rather than purely relying on exponential backoff, to better respect Google's quota limits.
+- **Manifest Permissions (`appsscript.json`):** You have defined narrow scopes like `documents.currentonly` which is great for security. Ensure that the Stackdriver exception logging (`"exceptionLogging": "STACKDRIVER"`) does not inadvertently log PII from document text when an error is thrown.
 
 ---
 *Overall, the integration logic is sound and the backend is well-structured for Apps Script execution.*

From a901cd91c798162c1f23925c208881663b7c2b7c Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:37:35 +0000
Subject: [PATCH 4/4] Add production monitoring suggestion to CODE_REVIEW.md

Co-authored-by: lucasrangit <701818+lucasrangit@users.noreply.github.com>
---
 CODE_REVIEW.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CODE_REVIEW.md b/CODE_REVIEW.md
index ca750dc..f7ff7ee 100644
--- a/CODE_REVIEW.md
+++ b/CODE_REVIEW.md
@@ -38,6 +38,7 @@ The HTML files (`Sidebar.html`, `PickerModal.html`) contain a dense mixture of H
 - **Configuration & Secrets:** Configuration options in `PickerModal.html` refer directly to `GOOGLE_CLOUD_API_KEY` and `GOOGLE_CLOUD_PROJECT_NUMBER`. Ensure proper fallback defaults and validation in your backend configuration getters. Avoid checking any real keys into the codebase.
 - **Error Handling & Quotas:** The backoff retry wrapper in `Library.js` is excellent for handling 429s. However, ensure you properly wait explicitly on `429` retry-after headers if they are provided by the Drive API, rather than purely relying on exponential backoff, to better respect Google's quota limits.
 - **Manifest Permissions (`appsscript.json`):** You have defined narrow scopes like `documents.currentonly` which is great for security. Ensure that the Stackdriver exception logging (`"exceptionLogging": "STACKDRIVER"`) does not inadvertently log PII from document text when an error is thrown.
+- **Production Monitoring:** Since the add-on is distributed to end users, set up robust monitoring using Google Cloud operations suite (formerly Stackdriver) or a third-party service. Actively track error rates (especially `429` rate limits and permissions errors), API latency, and quota exhaustion to proactively address performance regressions or scale issues before users report them.
 
 ---
 *Overall, the integration logic is sound and the backend is well-structured for Apps Script execution.*