mcp-gee-sweet 0.9.2.dev315__tar.gz → 0.9.2.dev321__tar.gz

{mcp_gee_sweet-0.9.2.dev315 → mcp_gee_sweet-0.9.2.dev321}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-gee-sweet
-Version: 0.9.2.dev315
+Version: 0.9.2.dev321
 Summary: MCP server for Google Workspace — Sheets, Drive, Docs (HTML or Markdown), and Calendar.
 Project-URL: Homepage, https://github.com/khuisman/mcp-gee-sweet
 Project-URL: Bug Tracker, https://github.com/khuisman/mcp-gee-sweet/issues

{mcp_gee_sweet-0.9.2.dev315 → mcp_gee_sweet-0.9.2.dev321}/docs/design/doc-to-markdown.md

@@ -128,8 +128,9 @@ Three gaps were kept **as documented limitations, not implementation shortcuts**
 - **Linked images** (#951): Docs puts an image's link on its `inlineObjectElement`'s own
   `textStyle.link`, the same as a text run (confirmed live). `doc_to_ast` reads it into
   `Image.link_url`, and every image renders through `_render_image` as `[![alt](src)](url)`, in
-  ordinary text, a code paragraph, and a table cell alike. The write side doesn't set
-  `Image.link_url` yet (#977).
+  ordinary text, a code paragraph, and a table cell alike. The write side sets it too (#977;
+  see [image-conversion.md](image-conversion.md#linked-images-977)), so a linked image
+  round-trips.
 - **Same-document links** (PR #976 QA round 1): Docs reports a link to a heading or bookmark by
   ID with no `url` (confirmed live for a heading: `{"headingId": "h.x"}`, on a text run and an
   image alike). `doc_to_ast._link_url`, shared by both, rebuilds it as

{mcp_gee_sweet-0.9.2.dev315 → mcp_gee_sweet-0.9.2.dev321}/docs/design/image-conversion.md

@@ -103,6 +103,39 @@ need K retries. Resending the whole document each time would be K+1 full-size ro
 Confirmed live that the split produces a document structurally identical to the old
 whole-list retry (text, bullets, table, and the surviving image all in place).
 
+## Linked images (#977)
+
+An `<img>` inside `<a href>` (markdown `[![alt](src)](url)`) keeps its link: `html_parser.py`
+copies the open `<a>`'s href onto `Image.link_url`. That includes raw HTML with no enclosing
+block: a top-level `<img>` gets an implicit paragraph even when it's wrapped in inline tags (unlike
+bare text or `<hr>` in that position), and reads its link from `_bare_link_url`, a stack separate
+from `_link_url` so text handling and an unclosed top-level `<a>` are unaffected. Each open `<a>`
+records which of the two stacks it pushed onto, or that it pushed nothing (`_anchor_pushes`), and
+its `</a>` pops only that: an href-less `<a name>` nested in a linked anchor used to pop the outer
+link (#994, PR #992 QA round 2). Docs stores an image's link on its
+`inlineObjectElement`'s own `textStyle.link`, so `emitter.py` follows the image's
+`insertInlineImage` with an `updateTextStyle` over its one-character range
+`[position, position + 1)`. The link has to come right after its own insert, inside the
+descending-position tail: at that point nothing before `position` has shifted yet. An inserted
+image never inherits a neighboring run's link (confirmed live, both directions), so an unlinked
+image gets no clearing request.
+
+Inserts that share a position, such as adjacent images with nothing between them, each land in
+front of whatever is already there, so the later one in the document has to be inserted first.
+The descending pass sorts on `(position, node order, item order)`, all descending; sorting by
+position alone kept source order within a tie and wrote adjacent images reversed (PR #992 QA
+round 1). A table and the image right after it share a position the same way, and still come out
+table first.
+
+The retry treats the pair as one unit. `ast_to_requests(image_links=...)` records each
+`id(insert request) -> link request` as it builds them, and `_apply_doc_content` uses that record
+rather than matching request shapes. `_drop_failed_image` pops the link request with its failed
+insert, since a stranded link would land on whatever character now sits at that position.
+`_positional_insert_tail_start` counts a recorded link request as part of the tail, so the K≥2
+split still applies. A `#slug` image link goes
+through the heading-anchor pass like a text link: `_walk_headings_and_anchor_runs` reads the
+`inlineObjectElement`'s link too, so it's resolved or stripped.
+
 ## Known, deliberate gap: table-cell images
 
 `html_parser.py`'s img-handling only fires when a block context is open at the body level

{mcp_gee_sweet-0.9.2.dev315 → mcp_gee_sweet-0.9.2.dev321}/docs/design/markdown-support.md

@@ -173,6 +173,7 @@ another registered tool), passing `content_format` through to `_to_doc_requests`
 | `~~strikethrough~~` | `<del>` | `Run(strikethrough=True)` | strikethrough |
 | `[text](url)` | `<a href=...>` | `Run(link_url=...)` | hyperlink |
 | bare `https://url` | `<a href=...>` (autolink extension) | `Run(link_url=...)` | hyperlink — disable via `autolink_urls=False` |
+| `[![alt](src)](url)` | `<a href=...><img ...></a>` | `Image(link_url=...)` | linked inline image (#977) |
 | `- item` | `<ul><li>` | `BulletItem(ordered=False)` | disc bullet list |
 | `1. item` | `<ol><li>` | `BulletItem(ordered=True)` | numbered list |
 | `- [x] item` | `<input type="checkbox" checked>` | `BulletItem(checked=True)` | bullet with a `☑`/`☐` glyph prefix |

{mcp_gee_sweet-0.9.2.dev315 → mcp_gee_sweet-0.9.2.dev321}/docs/qa/tests/docs_content.md

@@ -3716,6 +3716,64 @@ Not covered live: a soft break (Shift+Enter) inside an inline code run in a para
 
 **Result (2026-10-10) ✅ PASS — Kit, PR #981 round 2 (`b2bfafe`).** Ran on a scratch doc (created with `create_doc` from the step 1 HTML, trashed afterwards) instead of `{DOC_ID}`. Step 2 used one `find_in_doc(regex=True)` call for all three queries: matches at 4–11, 15–20 and 26–39. After step 3, `get_doc_structure` showed each of the first three paragraphs as two runs split at the `<`/`&` (`a <` | `b> text`, `AT&` | `amp;T`, `see <` | `https://x.io>`). `get_doc_as_markdown` returned `a \<b> text`, `AT\&amp;T`, `see \<https://x.io>`, and `a < b and AT&T` unchanged. markdown-it-py `commonmark` rendered `a &lt;b&gt; text`, `AT&amp;amp;T`, `see &lt;https://x.io&gt;`, and `a &lt; b and AT&amp;T`, with no `<b>` and no `<a>`. Round 1 got `a <b> text` and `AT&amp;T` unescaped from the same kind of split, on pre-fix code (`307e47c`).
 
+
+### TC-DOC216: A linked image written as Markdown or HTML keeps its link and round-trips (#977) ⚠️ requires-oauth
+**Background:** the write side built a linked image with no link, so `[![alt](src)](url)` and `<a href><img></a>` imported as a plain image and didn't round-trip with TC-DOC209's export. The image now gets its link through an `updateTextStyle` over its one-character range, right after its insert. That request has to stay paired with the image when an unreachable image is dropped and retried, and a `#slug` image link goes through the heading-anchor pass.
+
+**Setup:** none. Each step uses a scratch doc.
+
+**Prompt**
+**Playwright: required** (each linked image is clickable to its URL in the rendered doc; the unlinked one isn't)
+1. `create_doc(title="TC-DOC216 md", folder_id={FOLDER_ID}, content_format='markdown', content=...)` with:
+   ```markdown
+   # Overview
+
+   Before [![Logo](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)](https://example.com/one) and [linked text](https://example.com/t)![Plain](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)
+
+   Jump: [![A](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)](#overview) and [![B](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)](#missing)
+
+   | a | b |
+   |---|---|
+   | 1 | 2 |
+
+   [![C](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)](https://example.com/after-table)
+   ```
+2. `get_doc_as_markdown(doc_id=<step 1 docId>)`
+3. `create_doc(title="TC-DOC216 retry", folder_id={FOLDER_ID}, content_format='html', content=...)` with:
+   ```html
+   <p><a href="https://example.com/b1"><img src="https://example.invalid/nope.png?1"></a></p><p>x <a href="https://example.com/good"><img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"></a> y</p><p><a href="https://example.com/b2"><img src="https://example.invalid/nope.png?2"></a></p>
+   ```
+4. `get_doc_as_markdown(doc_id=<step 3 docId>)`
+5. `create_doc(title="TC-DOC216 adjacent", folder_id={FOLDER_ID}, content_format='html', content=...)` with (raw HTML, the first image wrapped in a top-level `<a>` with no `<p>`):
+   ```html
+   <a href="https://example.com/top"><img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png" width="100"></a><p>x <a href="https://example.com/first"><img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png" width="40"></a><a href="https://example.com/second"><img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png" width="80"></a><img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png" width="120"> y</p>
+   ```
+6. `get_doc_as_markdown(doc_id=<step 5 docId>)`
+7. `create_doc(title="TC-DOC216 nested anchor", folder_id={FOLDER_ID}, content_format='html', content=...)` with an href-less `<a name>` nested inside each linked anchor (#994):
+   ```html
+   <a href="https://example.com/bare"><a name="n1"></a><img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"></a><p><a href="https://example.com/block"><a name="n2"></a>tail<img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"></a> after</p>
+   ```
+8. `get_doc_as_markdown(doc_id=<step 7 docId>)`
+
+**Checks**
+- Step 2: `[![](<contentUri>)](https://example.com/one)`
+- Step 2: `[linked text](https://example.com/t)` is followed by an unlinked `![](<contentUri>)`, not one inside the link
+- Step 2: image `A` links to `https://docs.google.com/document/d/<docId>/edit?tab=t.0#heading=<headingId>`, the `Overview` heading. Image `B` is unlinked, its `#missing` link stripped
+- Step 2: the image after the table is `[![](<contentUri>)](https://example.com/after-table)`
+- Step 3: `images` reports an `error` for both `example.invalid` sources and none for the Google logo
+- Step 4: the only image is `[![](<contentUri>)](https://example.com/good)`, between `x` and `y`. No text character carries `b1`'s or `b2`'s link
+- Step 6: the first paragraph is the top-level image alone, as `[![](<contentUri>)](https://example.com/top)`
+- Step 6: the second paragraph is `x `, `[![](<contentUri>)](https://example.com/first)`, `[![](<contentUri>)](https://example.com/second)`, an unlinked `![](<contentUri>)`, then ` y`, in that order. Playwright: in the step 5 doc's editor the three inline images get wider left to right (40, 80, 120px source widths), which confirms the order independently of the links
+- Step 8: the first paragraph is `[![](<contentUri>)](https://example.com/bare)`. The second is `[tail](https://example.com/block)`, then `[![](<contentUri>)](https://example.com/block)`, then an unlinked ` after`: the nested `<a name>` doesn't end the outer link
+
+**Cleanup:** `delete_file` all four scratch docs
+
+**Result (2026-10-11) ✅ PASS — Sky, PR #992 round 1 (`6aa4dac`).** Step 2: `Logo` came back as `[![](<contentUri>)](https://example.com/one)`. `[linked text](https://example.com/t)` was followed by an unlinked `![](<contentUri>)`. `A` linked to `.../edit?tab=t.0#heading=h.…` (the `Overview` heading), and `B` was unlinked. The image after the table kept `https://example.com/after-table`. Step 3: `images` reported an `error` for both `example.invalid` sources and none for the logo. Step 4: the only image was `[![](<contentUri>)](https://example.com/good)` between `x` and `y`, and no text carried `b1`'s or `b2`'s link. Playwright, clicking each image in the step 1 doc's editor: `Logo` and the after-table image each showed a link chip for `https://example.com/…`, and `A`'s chip showed `Overview`. The unlinked image and `B` showed no link chip. The `/mobilebasic` HTML view isn't a substitute: it renders the text link but never wraps an image in `<a>`. A separate probe, `[![first](…)](https://example.com/first)[![second](…)](https://example.com/second)`, exported as `second` then `first`: adjacent images are written in reverse order. Each kept its own link.
+
+**Result (2026-10-11) ✅ PASS — Sky, PR #992 round 2 (`3a506f4`).** Re-ran step 3 (the retry, now pairing each image with its link by identity) and the new step 5. Step 4: the only image was `[![](<contentUri>)](https://example.com/good)` between `x` and `y`, and no text carried `b1`'s or `b2`'s link. Step 6: the first paragraph was the top-level image alone, as `[![](<contentUri>)](https://example.com/top)`. The second paragraph was `x `, `…(https://example.com/first)`, `…(https://example.com/second)`, an unlinked image, then ` y`. Playwright: in the step 5 doc's editor the three inline images got wider left to right, and the top image's link chip showed `https://example.com/…`. Steps 1–2 weren't re-run: the fix commit doesn't change that path beyond the sort, which step 5 covers.
+
+**Result (2026-10-11) ✅ PASS — Sky, PR #992 round 3 (`9271dfe`).** Ran the new step 7. Step 8: the first paragraph was `[![](<contentUri>)](https://example.com/bare)`, and the second was `[tail](https://example.com/block)`, then `[![](<contentUri>)](https://example.com/block)`, then an unlinked ` after`. The fix commit only touches `html_parser.py`'s anchor handling, so steps 1–6 weren't re-run.
+
 ---
 
 ## Orphan fileId on inline-image sharing failure (#649)

{mcp_gee_sweet-0.9.2.dev315 → mcp_gee_sweet-0.9.2.dev321}/docs/roadmap.md

@@ -223,9 +223,8 @@ Same shape as v0.8.1 — stabilize on defects that surfaced since v0.9.0 shipped
 - [x] `get_doc_as_markdown(local_path=…)` writes the JSON result envelope, not the markdown: `markdown_export.py` routes through the generic JSON-to-disk helper — lane B, after #938 (same read-side area) (PR #982) ([#958](https://github.com/khuisman/mcp-gee-sweet/issues/958))
 - [x] `add_chart`: a cell-to-row (`B2:5`) or row-only (`1:5`) range silently charts one column — `_per_column_ranges` defaults `endColumnIndex` to start+1. Found reviewing #931 — lane A, after #917 (PR #983) ([#954](https://github.com/khuisman/mcp-gee-sweet/issues/954))
 - [x] `_parse_a1_notation` hardening: one compiled grammar, index bounds, validate before the sheet-ID fetch. #931 review follow-ups, no behavior change for valid input — lane A, after #954 (same A1 area); its QA also runs #953's live checks for #931 (folded in) (PR #986) ([#955](https://github.com/khuisman/mcp-gee-sweet/issues/955))
-- [ ] Write side drops image links: `[![alt](src)](url)` (or `<a href><img></a>`) imports through `create_doc`/`create_doc_from_file`/`write_doc_content` without its URL, so it doesn't round-trip with #951's export. Found in PR #976 — lane A, after #955 ([#977](https://github.com/khuisman/mcp-gee-sweet/issues/977))
-- [ ] `_parse_a1_notation` rejects `A:B5`, which the Sheets values API accepts as `A5:B` — decided 2026-10-11: keep rejecting (a destructive GridRange tool acting on "row 5 onward" is worse than an error); document in the docstring that this is deliberately stricter than Sheets. Found in PR #986 — lane A, after #977 ([#987](https://github.com/khuisman/mcp-gee-sweet/issues/987))
-- [ ] Comment quoted text comes back HTML-escaped (`Caf&#233;`) from `add_doc_comment`, `list_doc_comments`, and `get_doc_as_markdown(include_comments=True)`: `comments.py` passes Drive's escaped `quotedFileContent.value` through unchanged. Found reviewing #958 — lane B, after #959 (defect, next pick) ([#984](https://github.com/khuisman/mcp-gee-sweet/issues/984))
+- [x] Write side drops image links: `[![alt](src)](url)` (or `<a href><img></a>`) imports through `create_doc`/`create_doc_from_file`/`write_doc_content` without its URL, so it doesn't round-trip with #951's export. Found in PR #976 — lane A, after #955 (PR #992) ([#977](https://github.com/khuisman/mcp-gee-sweet/issues/977))
+- [x] Comment quoted text comes back HTML-escaped (`Caf&#233;`) from `add_doc_comment`, `list_doc_comments`, and `get_doc_as_markdown(include_comments=True)`: `comments.py` passes Drive's escaped `quotedFileContent.value` through unchanged. Found reviewing #958 — lane B, after #959 (defect, next pick) (PR #991) ([#984](https://github.com/khuisman/mcp-gee-sweet/issues/984))
 - [ ] `write_capped_result_to_disk` writes `dir/` as a file when the directory doesn't exist: a trailing separator should mean "directory" (create it, append `default_filename`). Shared by every `local_path` writer. Found in PR #988 — lane B, after #984 (defect) ([#990](https://github.com/khuisman/mcp-gee-sweet/issues/990))
 
 **Sheets hardening** _(triaged out of `backlog` 2026-09-11 — see the "Backlog triage" note below)_
@@ -380,6 +379,8 @@ Follows the design in [`docs/decisions/decision-comments-first-class.md`](decisi
 
 - [ ] `sync_folder(export_format=...)`: converted Sheets/Slides probably have #814's `modifiedTime` lag and restamp race too. Suspected, not yet observed ([#818](https://github.com/khuisman/mcp-gee-sweet/issues/818))
 - [ ] Add a tool to set (and read back) Google Docs table column widths — `tableColumnProperties` isn't reachable through any tool today ([#809](https://github.com/khuisman/mcp-gee-sweet/issues/809))
+- [ ] `_parse_a1_notation` rejects `A:B5`, which the Sheets values API accepts as `A5:B` — decided 2026-10-11: keep rejecting (a destructive GridRange tool acting on "row 5 onward" is worse than an error); document in the docstring that this is deliberately stricter than Sheets. Found in PR #986 — lane A; moved from v0.9.2 2026-10-11 (docstring only, current behavior is the safe one) ([#987](https://github.com/khuisman/mcp-gee-sweet/issues/987))
+- [x] `html_parser`: the `</a>` of an href-less anchor nested in a linked one pops the outer link, so text or an image after it is written unlinked. Found in PR #992's QA, which sent back the same bug in its new `_bare_link_url` stack; may close with PR #992 — lane A; moved from v0.9.2 2026-10-11 (pre-existing, invalid nested HTML only) (PR #992) ([#994](https://github.com/khuisman/mcp-gee-sweet/issues/994))
 
 **Code structure & typing (Joy)** _(slotted into v0.9.2 (now v0.9.3) 2026-09-09 so Joy's architecture initiative carries release deadlines instead of staying open-ended)_
 

{mcp_gee_sweet-0.9.2.dev315 → mcp_gee_sweet-0.9.2.dev321}/src/mcp_gee_sweet/tools/docs/ast.py

@@ -49,8 +49,8 @@ class Image:
     alt: str | None = None
     width: float | None = None  # pt
     height: float | None = None  # pt
-    # Read side only (doc_to_ast.py): the image element's own textStyle.link.
-    # The write side doesn't set it yet.
+    # The image element's own textStyle.link: read by doc_to_ast.py, and written
+    # by emitter.py as an updateTextStyle over the image's one-character range (#977).
     link_url: str | None = None
 
 

{mcp_gee_sweet-0.9.2.dev315 → mcp_gee_sweet-0.9.2.dev321}/src/mcp_gee_sweet/tools/docs/content.py

@@ -162,12 +162,20 @@ def _failed_insert_image_message(error: HttpError) -> str:
 _POSITIONAL_INSERT_KEYS = ("insertTable", "insertInlineImage")
 
 
-def _positional_insert_tail_start(requests: list[dict]) -> int:
+def _positional_insert_tail_start(
+    requests: list[dict], image_links: dict[int, dict] | None = None
+) -> int:
     """Index where ast_to_requests's trailing stage-3 pass (the descending-position
     insertTable + insertInlineImage requests — see its docstring) begins: the start
-    of the maximal suffix made up only of those two request kinds."""
+    of the maximal suffix made up only of those two request kinds, plus each linked
+    image's own link request (#977). `image_links` is the id(insert) -> link
+    request map ast_to_requests filled; a link request counts by identity."""
+    link_ids = {id(link) for link in (image_links or {}).values()}
     start = len(requests)
-    while start > 0 and any(key in requests[start - 1] for key in _POSITIONAL_INSERT_KEYS):
+    while start > 0 and (
+        id(requests[start - 1]) in link_ids
+        or any(key in requests[start - 1] for key in _POSITIONAL_INSERT_KEYS)
+    ):
         start -= 1
     return start
 
@@ -553,8 +561,9 @@ async def _apply_doc_content(
     # (#789): revoking after a failed edit is harmless, since a doc that did embed
     # an image holds its own copy and one that didn't never needed the share.
     try:
+        image_links: dict[int, dict] = {}
         content_requests, tables = ast_to_requests(
-            nodes, start_index=1, image_uris=placeholder_uris
+            nodes, start_index=1, image_uris=placeholder_uris, image_links=image_links
         )
 
         # Swap each request's placeholder URI for the real one, recording which
@@ -626,13 +635,21 @@ async def _apply_doc_content(
 
             def _drop_failed_image(requests: list[dict], e: HttpError) -> bool:
                 """Pop the insertInlineImage request `e` names from `requests` (the
-                batch that raised `e`), recording the failure on its image's outcome
+                batch that raised `e`), plus its link request if the image was
+                linked (#977), recording the failure on its image's outcome
                 entry. False if `e` isn't an image-fetch failure, so the caller
                 re-raises."""
                 bad_index = _failed_insert_image_request_index(e)
                 if bad_index is None or bad_index >= len(requests):
                     return False
                 bad_request = requests.pop(bad_index)
+                # Left in place, the link would land on whatever character now
+                # sits at the image's position. Matched by identity: the list
+                # holds the same dict objects ast_to_requests recorded.
+                link = image_links.get(id(bad_request))
+                if link is not None:
+                    link_index = next(i for i, r in enumerate(requests) if r is link)
+                    requests.pop(link_index)
                 img_id = request_id_to_img_id.get(id(bad_request))
                 entry = entry_by_id.get(img_id) if img_id is not None else None
                 if entry is not None:
@@ -660,7 +677,7 @@ async def _apply_doc_content(
                     image_failures += 1
                     if image_failures != 2:
                         continue
-                    tail_start = _positional_insert_tail_start(remaining)
+                    tail_start = _positional_insert_tail_start(remaining, image_links)
                     # Fail-safe: split only if every image request really is in the
                     # tail. If ast_to_requests ever emits something after its
                     # positional-insert pass, the boundary scan comes up short —
@@ -728,7 +745,7 @@ def _walk_headings_and_anchor_runs(
 ) -> tuple[list[tuple[str, str]], list[tuple[str, int, int]]]:
     """Recursively walk document body content, including table cells,
     collecting (heading_text, heading_id) pairs and (anchor_url, start, end)
-    runs for any run whose link_url starts with '#'.
+    runs for any run or inline image whose link_url starts with '#'.
 
     Mirrors _collect_doc_paragraphs's two correctness properties: it recurses
     into table cells (a heading or an anchor link living inside a table cell
@@ -767,6 +784,16 @@ def _walk_headings_and_anchor_runs(
                     end = pe.get("endIndex")
                     if end is not None:
                         offset = end
+                    # A linked image carries its link on the inlineObjectElement's
+                    # own textStyle (#977).
+                    link_url = (
+                        pe.get("inlineObjectElement", {})
+                        .get("textStyle", {})
+                        .get("link", {})
+                        .get("url", "")
+                    )
+                    if link_url.startswith("#") and end is not None:
+                        anchor_runs.append((link_url, run_start, end))
 
             if is_heading and heading_id:
                 headings.append(("".join(text_parts).strip(), heading_id))

{mcp_gee_sweet-0.9.2.dev315 → mcp_gee_sweet-0.9.2.dev321}/src/mcp_gee_sweet/tools/docs/emitter.py

@@ -23,6 +23,7 @@ class _PendingTable:
     node: Table
     position: int  # doc index where this table starts, before tab-consumption adjustment
     tab_offset: int  # cumulative synthetic bullet-tabs consumed ahead of it by insertTable time
+    order: int  # index in the top-level node list; breaks same-position ties (see below)
 
 
 @dataclass
@@ -46,6 +47,7 @@ class _SegmentMeta:
     skip_len: int
     tabs_through: int
     runs: list[Run | Image]
+    order: int  # index in the top-level node list, as _PendingTable.order
 
 
 def _strip_bullet_leading_tabs(runs: list[Run | Image]) -> list[Run | Image]:
@@ -119,6 +121,8 @@ def ast_to_requests(
     nodes: list[DocNode],
     start_index: int = 1,
     image_uris: dict[int, str] | None = None,
+    *,
+    image_links: dict[int, dict] | None = None,
 ) -> tuple[list[dict], list[Table]]:
     """Convert AST nodes to phase-1 batchUpdate requests and a list of Table nodes.
 
@@ -149,6 +153,11 @@ def ast_to_requests(
     insertInlineImage has no notion of "insert later"; the caller is expected to have
     already recorded why that image failed via extract_images's own resolution pass.
 
+    image_links: if given, filled with id(insertInlineImage request) -> the
+    updateTextStyle request that links that image (#977), so a caller that drops a
+    failed image request can drop its link request too, by identity rather than by
+    matching request shapes.
+
     Returns (requests, tables) where tables is the list of Table AST nodes in document
     order.
     """
@@ -166,7 +175,7 @@ def ast_to_requests(
     pending_tables: list[_PendingTable] = []
     cumulative_tabs = 0
 
-    for node in nodes:
+    for order, node in enumerate(nodes):
         if isinstance(node, Table):
             num_rows = len(node.rows)
             num_cols = max((sum(c.colspan for c in row.cells) for row in node.rows), default=0)
@@ -176,7 +185,9 @@ def ast_to_requests(
                 # tables list positionally against the tables actually present in the live
                 # doc, and a table with no insertTable request never shows up there.
                 continue
-            pending_tables.append(_PendingTable(node, start_index + utf16_offset, cumulative_tabs))
+            pending_tables.append(
+                _PendingTable(node, start_index + utf16_offset, cumulative_tabs, order)
+            )
         else:
             doc_start = start_index + utf16_offset
             # Leading tab characters encode a bullet's nesting depth for
@@ -278,6 +289,7 @@ def ast_to_requests(
                     skip_len=utf16_len(tabs) + utf16_len(prefix),
                     tabs_through=cumulative_tabs,
                     runs=offset_runs,
+                    order=order,
                 )
             )
 
@@ -293,8 +305,10 @@ def ast_to_requests(
     # Combined descending-position insertion pass (tables + images, #333): both shift
     # every later, not-yet-processed position, so they must be interleaved by their true
     # final position rather than processed as two separate blocks — see ast_to_requests's
-    # docstring. Each entry is (final_position, request_dict).
-    positional_inserts: list[tuple[int, dict]] = []
+    # docstring. Each entry is (sort_key, requests): an insert request, followed for a
+    # linked image by the updateTextStyle that links it (#977). sort_key is
+    # (final_position, node order, item order) — see the sort at the end.
+    positional_inserts: list[tuple[tuple[int, int, int], list[dict]]] = []
 
     if full_text:
         requests.append({"insertText": {"location": {"index": start_index}, "text": full_text}})
@@ -348,13 +362,16 @@ def ast_to_requests(
             # many tab characters were stripped but never actually inserted (the
             # regression PR #768's QA round 2 caught in finding 1's own first version).
             offset = seg.skip_len
-            for item in seg.runs:
+            for item_order, item in enumerate(seg.runs, start=1):
                 if isinstance(item, Image):
                     uri = image_uris.get(id(item))
                     if uri is not None:
                         image_position = doc_start + offset - seg.tabs_through
+                        image_requests = _image_insert_requests(item, uri, image_position)
+                        if image_links is not None and len(image_requests) == 2:
+                            image_links[id(image_requests[0])] = image_requests[1]
                         positional_inserts.append(
-                            (image_position, _image_insert_request(item, uri, image_position))
+                            ((image_position, seg.order, item_order), image_requests)
                         )
                     continue
                 run_len = utf16_len(item.text)
@@ -454,14 +471,16 @@ def ast_to_requests(
         position = pending.position - pending.tab_offset
         positional_inserts.append(
             (
-                position,
-                {
-                    "insertTable": {
-                        "rows": num_rows,
-                        "columns": num_cols,
-                        "location": {"index": position},
+                (position, pending.order, 0),
+                [
+                    {
+                        "insertTable": {
+                            "rows": num_rows,
+                            "columns": num_cols,
+                            "location": {"index": position},
+                        }
                     }
-                },
+                ],
             )
         )
 
@@ -471,8 +490,14 @@ def ast_to_requests(
     # and processing this way means an earlier, not-yet-processed insertion's position is
     # never invalidated by a later one's own content (#333 generalizes this from the
     # table-only version of the same pattern).
-    for _, insert_request in sorted(positional_inserts, key=lambda item: item[0], reverse=True):
-        requests.append(insert_request)
+    #
+    # Inserts that share a position (adjacent images with no text between them, or a
+    # table and the image right after it) are each inserted *in front of* whatever is
+    # already at that position, so the later one in the document must go first. The
+    # node/item order in the key does that; sorting by position alone kept source order
+    # within a tie and wrote adjacent images reversed (PR #992 QA round 1).
+    for _, insert_requests in sorted(positional_inserts, key=lambda item: item[0], reverse=True):
+        requests.extend(insert_requests)
 
     return requests, [pending.node for pending in pending_tables]
 
@@ -510,8 +535,18 @@ def _blockquote_style_request(rng: dict, depth: int) -> dict:
     }
 
 
-def _image_insert_request(image: Image, uri: str, position: int) -> dict:
-    """Build an insertInlineImage request for an already-resolved image at `position`."""
+def _image_insert_requests(image: Image, uri: str, position: int) -> list[dict]:
+    """Build the insertInlineImage request for an already-resolved image at `position`,
+    followed, for a linked image, by the updateTextStyle that links it (#977).
+
+    Docs stores an image's link on its inlineObjectElement's own textStyle, so the link
+    goes over the image's one-character range [position, position + 1). It must run
+    right after this insert: the descending-position pass guarantees nothing before
+    `position` has shifted yet at that point. An image never inherits a neighboring
+    run's link on insert (confirmed live), so an unlinked image needs no clearing
+    request. content.py's retry drops the pair together when the insert fails
+    (_drop_failed_image, through ast_to_requests's image_links); otherwise the link
+    would land on whatever character sits at `position`."""
     request: dict = {"insertInlineImage": {"uri": uri, "location": {"index": position}}}
     if image.width is not None or image.height is not None:
         object_size: dict = {}
@@ -520,7 +555,20 @@ def _image_insert_request(image: Image, uri: str, position: int) -> dict:
         if image.height is not None:
             object_size["height"] = {"magnitude": image.height, "unit": "PT"}
         request["insertInlineImage"]["objectSize"] = object_size
-    return request
+    if image.link_url is None:
+        return [request]
+    return [request, _image_link_request(image.link_url, position)]
+
+
+def _image_link_request(link_url: str, position: int) -> dict:
+    """updateTextStyle linking the image just inserted at `position` (#977)."""
+    return {
+        "updateTextStyle": {
+            "range": {"startIndex": position, "endIndex": position + 1},
+            "textStyle": {"link": {"url": link_url}},
+            "fields": "link",
+        }
+    }
 
 
 def _run_style_requests(run: Run, start: int, end: int) -> list[dict]:

{mcp_gee_sweet-0.9.2.dev315 → mcp_gee_sweet-0.9.2.dev321}/src/mcp_gee_sweet/tools/docs/html_parser.py

@@ -138,15 +138,18 @@ def _px_to_pt(value: str) -> float | None:
         return None
 
 
-def _make_image(attr_dict: dict, src: str) -> Image:
+def _make_image(attr_dict: dict, src: str, link_url: str | None = None) -> Image:
     """Build an Image node from an <img> tag's attributes. width/height are
     only ever present on raw HTML <img> tags (content_format="html") — plain
-    markdown "![alt](src)" has no syntax for them, so they're None there."""
+    markdown "![alt](src)" has no syntax for them, so they're None there.
+    link_url is the enclosing <a href>, if any (markdown "[![alt](src)](url)",
+    #977)."""
     return Image(
         src=src,
         alt=attr_dict.get("alt") or None,
         width=_px_to_pt(attr_dict.get("width") or ""),
         height=_px_to_pt(attr_dict.get("height") or ""),
+        link_url=link_url,
     )
 
 
@@ -209,6 +212,17 @@ class _AstParser(HTMLParser):
         self._strike_depth = 0
         self._code_depth = 0  # inline <code> nesting; ignored inside <pre>
         self._link_url: list[str] = []  # stack of href values
+        # href values of <a> tags opened with no block or table cell around them.
+        # Read only by the bare top-level <img> branch (#977), so a top-level
+        # "<a href><img></a>" keeps its link; kept apart from _link_url so text
+        # handling, and an unclosed top-level <a>, are unaffected.
+        self._bare_link_url: list[str] = []
+        # One entry per open <a>: which of the two stacks above its start tag
+        # pushed an href onto ("block" or "bare"), or None if it pushed nothing
+        # (no href, e.g. <a name>). </a> pops only what its own start tag pushed,
+        # so an href-less anchor nested in a linked one can't pop the outer
+        # link (#994).
+        self._anchor_pushes: list[str | None] = []
 
         # --- current run buffer ---
         self._run_buf: list[str] = []
@@ -324,6 +338,10 @@ class _AstParser(HTMLParser):
         self._strike_depth = 0
         self._code_depth = 0
         self._link_url = []
+        # The cleared hrefs' anchors no longer own an entry to pop.
+        self._anchor_pushes = [
+            None if pushed == "block" else pushed for pushed in self._anchor_pushes
+        ]
 
     def _emit_block_node(
         self, tag: str, runs: list[Run | Image], *, preserve_if_empty: bool = False
@@ -686,18 +704,17 @@ class _AstParser(HTMLParser):
         # Same rationale as <hr> just above: markdown's own "![]()" syntax
         # always renders wrapped in a <p>, so this only matters for raw HTML
         # (content_format="html") supplying a top-level <img> with no
-        # wrapping tag at all.
-        if (
-            tag == "img"
-            and self._block_tag is None
-            and self._table_depth == 0
-            and self._tag_depth == 0
-        ):
+        # wrapping block at all. Unlike <hr> and bare text, an <img> wrapped
+        # only in inline tags still gets its implicit paragraph: a raw-HTML
+        # "<a href><img></a>" (a linked badge, say) is real content, and
+        # dropping it loses the image along with its link (PR #992 QA round 1).
+        if tag == "img" and self._block_tag is None and self._table_depth == 0:
             src = attr_dict.get("src")
             if src:
+                link_url = self._bare_link_url[-1] if self._bare_link_url else None
                 self._nodes.append(
                     Paragraph(
-                        runs=[_make_image(attr_dict, src)],
+                        runs=[_make_image(attr_dict, src, link_url)],
                         blockquote_depth=self._blockquote_depth,
                     )
                 )
@@ -724,6 +741,7 @@ class _AstParser(HTMLParser):
                 href = attr_dict.get("href", "")
                 if href:
                     self._link_url.append(href)
+                self._anchor_pushes.append("block" if href else None)
             elif tag == "code" and not self._in_pre:
                 self._code_depth += 1
             elif tag == "br":
@@ -739,7 +757,9 @@ class _AstParser(HTMLParser):
                 # already gets in a cell.
                 src = attr_dict.get("src")
                 if src:
-                    self._pending_runs.append(_make_image(attr_dict, src))
+                    self._pending_runs.append(
+                        _make_image(attr_dict, src, self._link_url[-1] if self._link_url else None)
+                    )
                 else:
                     self._block_had_unsupported_content = True
             elif self._block_tag:
@@ -749,6 +769,11 @@ class _AstParser(HTMLParser):
                 # silently dropped rather than contributing a run — see
                 # self._block_had_unsupported_content.
                 self._block_had_unsupported_content = True
+        elif tag == "a":
+            href = attr_dict.get("href", "") if self._table_depth == 0 else ""
+            if href:
+                self._bare_link_url.append(href)
+            self._anchor_pushes.append("bare" if href else None)
 
     def handle_endtag(self, tag):
         # --- table structure ---
@@ -911,10 +936,23 @@ class _AstParser(HTMLParser):
                 self._underline_depth = max(0, self._underline_depth - 1)
             elif tag in _INLINE_STRIKE:
                 self._strike_depth = max(0, self._strike_depth - 1)
-            elif tag == "a" and self._link_url:
-                self._link_url.pop()
+            elif tag == "a":
+                self._close_anchor()
             elif tag == "code" and not self._in_pre:
                 self._code_depth = max(0, self._code_depth - 1)
+        elif tag == "a":
+            self._close_anchor()
+
+    def _close_anchor(self):
+        """Pop whatever href the matching <a> start tag pushed, and nothing
+        else (#994)."""
+        if not self._anchor_pushes:
+            return
+        pushed = self._anchor_pushes.pop()
+        if pushed == "block" and self._link_url:
+            self._link_url.pop()
+        elif pushed == "bare" and self._bare_link_url:
+            self._bare_link_url.pop()
 
     def handle_data(self, data):
         # Table-cell text and open-block text are independent triggers that happen