drive comments create: anchor field results in 'Original content deleted' in Google Docs

[Om3rr]

Description

When creating a comment on a Google Docs file using gws drive comments create with an anchor field, the comment is posted successfully (HTTP 200) but appears in the Google Docs UI as "Original content deleted" instead of being anchored to the specified text.

Steps to Reproduce

gws drive comments create \
  --params '{"fileId": "<DOC_ID>", "fields": "id,content,anchor,quotedFileContent"}' \
  --json '{
    "content": "Hello",
    "quotedFileContent": {
      "mimeType": "text/plain",
      "value": "Overview"
    },
    "anchor": "{\"r\":\"head\",\"a\":[{\"lt\":\"b\",\"lv\":\"Overview\"}]}"
  }'

Expected Behavior

The comment should be anchored to the matching text in the document, or the CLI/docs should clearly indicate that anchored comments are not supported for Google Docs files via the API.

Actual Behavior

The API returns a 200 with the anchor saved, but the comment appears in the Google Docs UI as "Original content deleted" — no text is highlighted and the anchor has no visible effect.

Additional Context

• This appears to be a known Google Drive API limitation: for Google Workspace editor files (Docs, Sheets, Slides), the anchor field is saved but ignored by the editor UI. See the official docs: "The anchor is saved and returned when retrieving the comment, however Google Workspace editor apps treat these comments as un-anchored comments."
• It would be helpful if gws surfaced a warning when using anchor on a application/vnd.google-apps.kix (Google Docs) file, since the result is misleading.
• gws version: 0.4.4

[nadavof]

This is additional context for #169. The "Original content deleted" symptom is a surface manifestation of a deeper limitation: the Google Drive API has no way to obtain kix.PARAGRAPH_ID values needed for inline comment anchoring on Google Docs.

Root Cause Discovery

I tested all possible anchor formats for programmatically creating comments on Google Docs:

Anchor Format	Accepted by API	Inline highlight?	Notes
"anchor": "kix.PARAGRAPH_ID"	✅	✅	Works, but ID is unobtainable
"anchor": "h.HEADING_ID" (from Docs API)	✅	❌	Ignored by Docs editor
"anchor": {"region": {..., "line": N, ...}} (per API docs)	✅	❌	Ignored by Docs editor
"anchor": {"r":"head","a":[...]} (character range)	✅	❌	Ignored by Docs editor
"quotedFileContent": {"value": "text"}	✅	❌	Shows "Original content deleted"

The only format that produces inline highlighting is kix.PARAGRAPH_ID. These IDs are:

• Generated by Google's internal Kix editor engine
• Not returned by documents.get
• Not present in HTML exports
• Not computable from character indices or heading IDs
• Only visible when reading back a comment a human created via the UI

The Only Workaround

1. Manually create a comment on the target text via the Google Docs UI
2. Use comments.list() to read its anchor field (contains the kix ID)
3. Reuse that same kix ID for subsequent programmatic comments at that location
4. But there's no way to generate new kix IDs for new locations

Implication for gws

This is not a gws bug — it's a Google Drive API limitation. The options are:

1. Add a warning (as proposed in PR fix(drive): warn when anchor field targets Workspace editor files #487) when users try to anchor comments on Docs files, explaining the limitation
2. Document it clearly so users understand why programmatic anchoring doesn't work
3. File an issue with Google asking them to expose kix IDs in the Docs API (or provide a resolution mechanism)

The warning from PR #487 is a good interim solution, but it doesn't solve the fundamental problem. Google would need to expose these IDs or provide a way to obtain them.

Reproduction

DOC_ID="1D_ttRv-RsTa4qN0TXR_d3CGIRy0Fa_NWGO26S4m0I5I"
gws drive comments create 

--params '{"fileId": "'$DOC_ID'", "fields": "id,content,anchor"}' 

--json '{

"content": "Test comment",

"anchor": "{"region": {"kind": "drive#commentRegion", "line": 2, "rev": "head"}}"

}'

Result: Comment appears only in Comments panel, not inline.