slidesync 0.2.0__tar.gz → 0.3.0__tar.gz

{slidesync-0.2.0/slidesync.egg-info → slidesync-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slidesync
-Version: 0.2.0
+Version: 0.3.0
 Summary: Bidirectional sync between a Slidev markdown deck and Google Slides as native, editable objects
 Author-email: Daniel Hails <slidesync@hails.info>
 License: MIT
@@ -22,7 +22,7 @@ Bidirectional sync between a [Slidev](https://sli.dev) markdown deck and **Googl
 Slides** — as native, editable objects (title/body/bullets/tables/positioned
 images, brand-styled text boxes), not pasted screenshots.
 
-Version: 0.2.0
+Version: 0.3.0
 
 ```bash
 uvx slidesync --help            # run without installing
@@ -63,6 +63,8 @@ Support path.)
 | `slidesync roundtrip [--keep]` | self-test: push a sample, pull, assert identical |
 | `slidesync layouts <deckId>` | list a deck's theme layouts + placeholders |
 | `slidesync make-templates <deckId>` | inject branded `{{token}}` template slides |
+| `slidesync comments <deckId>` | list comment threads as JSON (page anchor, author, content, replies) |
+| `slidesync sync <file.slidev.md> [--deck ID]` | report drift vs the live deck — comments, live edits, conflicts (exit 1 on drift) |
 
 `push` resolves the target deck from (in order) `--deck`, `--new`, or a top-level
 `deck:` frontmatter key. Relative image paths resolve against the markdown file's
@@ -87,6 +89,25 @@ hidden `<!-- s2g {...} -->` marker in speaker notes carries the human id, image
 path, template vars — and, for template slides, the authored body markdown
 (base64) — so `pull` recovers the source verbatim.
 
+## Sync & drift (detection, not resolution)
+
+The marker's last-pushed source is a true per-slide **merge base**, so `sync`
+classifies each slide three-way without timestamps (the Slides API has no
+per-slide edit times — only file-level `modifiedTime`; the marker's `at` stamp
+records when *we* last pushed each slide):
+
+| status | meaning | action |
+|--------|---------|--------|
+| `clean` / `converged` | nothing changed, or both sides made the same change | — |
+| `local-edit` | markdown changed, deck untouched | `push` (normal) |
+| `live-drift` | slide edited in Google Slides | fold the printed diff into the markdown, or `push --force` to clobber |
+| `conflict` | both changed since last push | resolve the two printed diffs by hand/LLM, then `push` |
+
+Unresolved comment threads print as ready-to-paste `<!-- @Author: text -->`
+blocks on their slide (replies as extra `@Author:` lines) — paste them into the
+source, where they round-trip from then on. Threads anchor to slide objectIds,
+so a re-render orphans them: `sync` reports those too. Capture before you push.
+
 ## Markdown dialect
 
 Top-level frontmatter: `theme:`, `deck:`. Slides separated by `---`; each slide

{slidesync-0.2.0 → slidesync-0.3.0}/README.md

@@ -4,7 +4,7 @@ Bidirectional sync between a [Slidev](https://sli.dev) markdown deck and **Googl
 Slides** — as native, editable objects (title/body/bullets/tables/positioned
 images, brand-styled text boxes), not pasted screenshots.
 
-Version: 0.2.0
+Version: 0.3.0
 
 ```bash
 uvx slidesync --help            # run without installing
@@ -45,6 +45,8 @@ Support path.)
 | `slidesync roundtrip [--keep]` | self-test: push a sample, pull, assert identical |
 | `slidesync layouts <deckId>` | list a deck's theme layouts + placeholders |
 | `slidesync make-templates <deckId>` | inject branded `{{token}}` template slides |
+| `slidesync comments <deckId>` | list comment threads as JSON (page anchor, author, content, replies) |
+| `slidesync sync <file.slidev.md> [--deck ID]` | report drift vs the live deck — comments, live edits, conflicts (exit 1 on drift) |
 
 `push` resolves the target deck from (in order) `--deck`, `--new`, or a top-level
 `deck:` frontmatter key. Relative image paths resolve against the markdown file's
@@ -69,6 +71,25 @@ hidden `<!-- s2g {...} -->` marker in speaker notes carries the human id, image
 path, template vars — and, for template slides, the authored body markdown
 (base64) — so `pull` recovers the source verbatim.
 
+## Sync & drift (detection, not resolution)
+
+The marker's last-pushed source is a true per-slide **merge base**, so `sync`
+classifies each slide three-way without timestamps (the Slides API has no
+per-slide edit times — only file-level `modifiedTime`; the marker's `at` stamp
+records when *we* last pushed each slide):
+
+| status | meaning | action |
+|--------|---------|--------|
+| `clean` / `converged` | nothing changed, or both sides made the same change | — |
+| `local-edit` | markdown changed, deck untouched | `push` (normal) |
+| `live-drift` | slide edited in Google Slides | fold the printed diff into the markdown, or `push --force` to clobber |
+| `conflict` | both changed since last push | resolve the two printed diffs by hand/LLM, then `push` |
+
+Unresolved comment threads print as ready-to-paste `<!-- @Author: text -->`
+blocks on their slide (replies as extra `@Author:` lines) — paste them into the
+source, where they round-trip from then on. Threads anchor to slide objectIds,
+so a re-render orphans them: `sync` reports those too. Capture before you push.
+
 ## Markdown dialect
 
 Top-level frontmatter: `theme:`, `deck:`. Slides separated by `---`; each slide

{slidesync-0.2.0 → slidesync-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "slidesync"
-version = "0.2.0"
+version = "0.3.0"
 authors = [
     { name = "Daniel Hails", email = "slidesync@hails.info" },
 ]
@@ -32,7 +32,7 @@ include = ["slidesync*"]
 dev = ["pytest>=8"]
 
 [tool.bumpver]
-current_version = "0.2.0"
+current_version = "0.3.0"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit_message = "bump version {old_version} -> {new_version}"
 commit = true

{slidesync-0.2.0 → slidesync-0.3.0}/slidesync/__init__.py

@@ -30,7 +30,7 @@ from slidesync._sync import (
     write_slidev,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "Para",

{slidesync-0.2.0 → slidesync-0.3.0}/slidesync/_sync.py

@@ -36,6 +36,8 @@ from __future__ import annotations
 
 import argparse
 import base64
+import datetime
+import difflib
 import hashlib
 import html
 import json
@@ -580,6 +582,10 @@ def _marker(slide: Slide) -> str:
             data["src"] = base64.b64encode(slide.src.encode()).decode()
     elif slide.layout_name and slide.layout_name not in SECTION_LAYOUTS:
         data["tpl"] = slide.layout_name
+    # Last-push stamp: `sync` reports it alongside drift. The Slides/Drive APIs
+    # have no per-slide edit times (file-level modifiedTime only), so this is
+    # the only per-slide timestamp that exists.
+    data["at"] = datetime.datetime.now(datetime.UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
     return f"<!-- s2g {json.dumps(data, separators=(',', ':'))} -->"
 
 
@@ -1890,6 +1896,192 @@ def cmd_layouts(args):
         logger.info(f"{name:<24} {', '.join(phs) or '(no placeholders)'}")
 
 
+# ---------------------------------------------------------------------------
+# Comments + sync (drift detection)
+# ---------------------------------------------------------------------------
+
+
+def shape_comments(raw: list[dict]) -> list[dict]:
+    """Drive comment threads -> [{id, page, author, content, resolved, replies}].
+
+    `page` is the anchored slide objectId (None for file-level comments) —
+    note an objectId outlives its slide, so the anchor may point at a deleted
+    page after a re-render. Resolve-action replies with no text are dropped.
+    """
+    out = []
+    for c in raw:
+        try:
+            anchor = json.loads(c.get("anchor") or "{}")
+        except json.JSONDecodeError:
+            anchor = {}
+        pages = anchor.get("pages") or []
+        out.append({
+            "id": c.get("id", ""),
+            "page": pages[0] if pages else None,
+            "author": (c.get("author") or {}).get("displayName", ""),
+            "content": (c.get("content") or "").strip(),
+            "resolved": bool(c.get("resolved")),
+            "modified": c.get("modifiedTime", ""),
+            "replies": [
+                {"author": (r.get("author") or {}).get("displayName", ""),
+                 "content": (r.get("content") or "").strip()}
+                for r in c.get("replies", []) if (r.get("content") or "").strip()
+            ],
+        })
+    return out
+
+
+_COMMENT_FIELDS = ("nextPageToken,comments(id,content,author(displayName),"
+                   "anchor,resolved,modifiedTime,replies(content,author(displayName)))")
+
+
+def list_comments(drive, deck: str) -> list[dict]:
+    raw, token = [], None
+    while True:
+        resp = drive.comments().list(fileId=deck, pageSize=100, pageToken=token,
+                                     fields=_COMMENT_FIELDS).execute()
+        raw += resp.get("comments", [])
+        token = resp.get("nextPageToken")
+        if not token:
+            return raw
+
+
+def cmd_comments(args):
+    _, drive = get_services(args.account)
+    print(json.dumps(shape_comments(list_comments(drive, args.deck)), indent=2))
+
+
+def text_lines_md(src: str) -> list[str]:
+    """Markdown slide body -> normalised visible text lines (comments excluded)."""
+    fences = [m.group("text") for m in VERBATIM_RE.finditer(src)]
+    headings, paras, _img, _alt, table, _ = parse_body(VERBATIM_RE.sub("", src))
+    lines = [headings[k] for k in sorted(headings)]
+    lines += [p.text for p in paras]
+    if table:
+        lines += [" | ".join(row) for row in table]
+    for f in fences:
+        lines += f.splitlines()
+    return _norm_lines(lines)
+
+
+def text_lines_native(s: dict) -> list[str]:
+    """Native slide JSON -> normalised visible text lines (notes excluded)."""
+    boxes = []
+    for el in s.get("pageElements", []):
+        if el.get("shape", {}).get("text"):
+            paras = _paras_from_shape(el["shape"])
+            if paras:
+                boxes.append((_el_y(el), _el_x(el), paras))
+        elif el.get("table"):
+            rows = _table_from_native(el["table"])
+            boxes.append((_el_y(el), _el_x(el),
+                          [Para(" | ".join(r)) for r in rows]))
+    boxes.sort(key=lambda t: (t[0], t[1]))
+    return _norm_lines([p.text for _, _, paras in boxes for p in paras])
+
+
+def _norm_lines(lines: list[str]) -> list[str]:
+    # Sorted: box reading-order vs markdown order differ legitimately (e.g. a
+    # kicker renders above the headline but is written below it).
+    return sorted(" ".join(line.split()) for line in lines if line.strip())
+
+
+def classify_drift(base: list[str] | None, local: list[str],
+                   live: list[str]) -> str:
+    """Three-way status for one slide; base is the last-pushed source (marker)."""
+    if base is None:
+        return "clean" if local == live else "drift-no-base"
+    if local == base and live == base:
+        return "clean"
+    if local != base and live == base:
+        return "local-edit"
+    if local == base and live != base:
+        return "live-drift"
+    return "converged" if local == live else "conflict"
+
+
+def _diff(a: list[str], b: list[str], a_name: str, b_name: str) -> str:
+    return "\n".join(difflib.unified_diff(a, b, a_name, b_name, lineterm=""))
+
+
+def cmd_sync(args):
+    """Report per-slide drift between a markdown deck and its live Slides copy.
+
+    Detection, not resolution: each slide is classified against the marker's
+    last-pushed source (the merge base). Additive changes (comments, notes-pane
+    edits) are printed as ready-to-paste `<!-- @Author: ... -->` blocks; text
+    conflicts are printed as unified diffs for a human/LLM to fold into the
+    markdown, after which a normal `push` (or `push --force` to clobber
+    live-only drift) makes the file authoritative again. Exits 1 if anything
+    drifted.
+    """
+    slides_api, drive = get_services(args.account)
+    source = load_slides(args.source)
+    deck = args.deck or deck_from_source(args.source)
+    if not deck:
+        sys.exit("no target deck: pass --deck or add `deck:` frontmatter")
+    pres = slides_api.presentations().get(presentationId=deck).execute()
+    live = {s["objectId"].split("_")[1]: s for s in pres.get("slides", [])
+            if MANAGED_RE.match(s["objectId"])}
+    by_page = {}
+    for c in shape_comments(list_comments(drive, deck)):
+        if not c["resolved"] and c["page"]:
+            by_page.setdefault(c["page"], []).append(c)
+    drifted = 0
+    for sl in source:
+        s = live.pop(sl.key_hash, None)
+        if s is None:
+            logger.warning(f"[missing   ] {sl.key} — not in deck; push will create it")
+            drifted += 1
+            continue
+        for c in by_page.pop(s["objectId"], []):
+            drifted += 1
+            lines = [f"@{c['author']}: {c['content']}"]
+            lines += [f"@{r['author']}: {r['content']}" for r in c["replies"]]
+            logger.info(f"[comment   ] {sl.key} ({c['modified']}):\n"
+                        + "<!-- " + "\n".join(lines) + " -->")
+        if sl.custom is not None:
+            continue  # pull-authoritative; drawings are captured, not diffed
+        notes_raw = _read_notes(s)
+        marker = _read_marker(notes_raw)
+        base_src = (base64.b64decode(marker["src"]).decode()
+                    if "src" in marker else None)
+        base = text_lines_md(base_src) if base_src is not None else None
+        local = text_lines_md(sl.src or "")
+        live_lines = text_lines_native(s)
+        status = classify_drift(base, local, live_lines)
+        pushed_at = marker.get("at", "?")
+        if status in ("clean", "converged"):
+            continue
+        drifted += 1
+        if status == "local-edit":
+            logger.info(f"[local-edit] {sl.key} — push will update it")
+        elif status in ("live-drift", "drift-no-base"):
+            logger.warning(f"[live-drift] {sl.key} (pushed {pushed_at}) — edited in "
+                           f"Slides; fold into the markdown or `push --force` to clobber:\n"
+                           + _diff(base if base is not None else local, live_lines,
+                                   "last-pushed" if base is not None else "local", "live"))
+        else:  # conflict
+            logger.error(f"[conflict  ] {sl.key} (pushed {pushed_at}) — both sides "
+                         f"changed since last push:\n"
+                         + _diff(base, local, "last-pushed", "local") + "\n"
+                         + _diff(base, live_lines, "last-pushed", "live"))
+        live_notes = " ".join(MARKER_RE.sub("", notes_raw).split())
+        base_notes = " ".join(_extract_notes(base_src).split()) if base_src else ""
+        if base_src is not None and live_notes != base_notes:
+            logger.info(f"[notes     ] {sl.key} — notes pane edited live:\n{live_notes}")
+    for kh, s in live.items():
+        logger.warning(f"[unmanaged ] {s['objectId']} in deck has no local slide "
+                       "(--prune on push would delete it)")
+    for page, cs in by_page.items():
+        for c in cs:
+            logger.warning(f"[orphaned  ] comment by {c['author']} anchored to deleted "
+                           f"slide {page}: {c['content']!r}")
+    logger.log("WARNING" if drifted else "SUCCESS",
+               f"{drifted} drifted item(s)" if drifted else "deck matches source")
+    sys.exit(1 if drifted else 0)
+
+
 def _loop_hop(slides_api, drive, title, slides):
     """One md->slides hop: build a deck, push, pull back."""
     deck = new_deck(slides_api, title)
@@ -1966,6 +2158,17 @@ def main():
     p.add_argument("deck")
     p.set_defaults(func=cmd_layouts)
 
+    p = sub.add_parser("comments",
+                       help="list comment threads as JSON (page anchor, author, replies)")
+    p.add_argument("deck")
+    p.set_defaults(func=cmd_comments)
+
+    p = sub.add_parser("sync",
+                       help="report drift vs the live deck (comments, live edits, conflicts)")
+    p.add_argument("source", type=Path)
+    p.add_argument("--deck")
+    p.set_defaults(func=cmd_sync)
+
     p = sub.add_parser("make-templates",
                        help="add branded tagged template slides to a deck")
     p.add_argument("deck")

{slidesync-0.2.0 → slidesync-0.3.0/slidesync.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slidesync
-Version: 0.2.0
+Version: 0.3.0
 Summary: Bidirectional sync between a Slidev markdown deck and Google Slides as native, editable objects
 Author-email: Daniel Hails <slidesync@hails.info>
 License: MIT
@@ -22,7 +22,7 @@ Bidirectional sync between a [Slidev](https://sli.dev) markdown deck and **Googl
 Slides** — as native, editable objects (title/body/bullets/tables/positioned
 images, brand-styled text boxes), not pasted screenshots.
 
-Version: 0.2.0
+Version: 0.3.0
 
 ```bash
 uvx slidesync --help            # run without installing
@@ -63,6 +63,8 @@ Support path.)
 | `slidesync roundtrip [--keep]` | self-test: push a sample, pull, assert identical |
 | `slidesync layouts <deckId>` | list a deck's theme layouts + placeholders |
 | `slidesync make-templates <deckId>` | inject branded `{{token}}` template slides |
+| `slidesync comments <deckId>` | list comment threads as JSON (page anchor, author, content, replies) |
+| `slidesync sync <file.slidev.md> [--deck ID]` | report drift vs the live deck — comments, live edits, conflicts (exit 1 on drift) |
 
 `push` resolves the target deck from (in order) `--deck`, `--new`, or a top-level
 `deck:` frontmatter key. Relative image paths resolve against the markdown file's
@@ -87,6 +89,25 @@ hidden `<!-- s2g {...} -->` marker in speaker notes carries the human id, image
 path, template vars — and, for template slides, the authored body markdown
 (base64) — so `pull` recovers the source verbatim.
 
+## Sync & drift (detection, not resolution)
+
+The marker's last-pushed source is a true per-slide **merge base**, so `sync`
+classifies each slide three-way without timestamps (the Slides API has no
+per-slide edit times — only file-level `modifiedTime`; the marker's `at` stamp
+records when *we* last pushed each slide):
+
+| status | meaning | action |
+|--------|---------|--------|
+| `clean` / `converged` | nothing changed, or both sides made the same change | — |
+| `local-edit` | markdown changed, deck untouched | `push` (normal) |
+| `live-drift` | slide edited in Google Slides | fold the printed diff into the markdown, or `push --force` to clobber |
+| `conflict` | both changed since last push | resolve the two printed diffs by hand/LLM, then `push` |
+
+Unresolved comment threads print as ready-to-paste `<!-- @Author: text -->`
+blocks on their slide (replies as extra `@Author:` lines) — paste them into the
+source, where they round-trip from then on. Threads anchor to slide objectIds,
+so a re-render orphans them: `sync` reports those too. Capture before you push.
+
 ## Markdown dialect
 
 Top-level frontmatter: `theme:`, `deck:`. Slides separated by `---`; each slide

{slidesync-0.2.0 → slidesync-0.3.0}/slidesync.egg-info/SOURCES.txt

@@ -12,4 +12,5 @@ slidesync.egg-info/requires.txt
 slidesync.egg-info/top_level.txt
 tests/test_comment_preservation.py
 tests/test_markdown.py
-tests/test_pull.py
+tests/test_pull.py
+tests/test_sync_drift.py

slidesync-0.3.0/tests/test_sync_drift.py

@@ -0,0 +1,67 @@
+"""Offline tests for drift detection: comment shaping, text-line extraction
+parity (markdown vs native), and the three-way classification."""
+
+from slidesync._sync import (
+    classify_drift,
+    shape_comments,
+    text_lines_md,
+    text_lines_native,
+)
+
+RAW_COMMENTS = [
+    {"id": "c1",
+     "anchor": '{"type":"page","uid":1,"pages":["s2g_aaaaaaaaaa_bbbbbbbbbb"]}',
+     "author": {"displayName": "Daniel Hails"},
+     "content": "This is obviously dodgy. To debug",
+     "modifiedTime": "2026-06-12T15:00:00Z",
+     "replies": [
+         {"author": {"displayName": "Ted"}, "content": "agree"},
+         {"author": {"displayName": "Daniel Hails"}, "content": ""},  # resolve action
+     ]},
+    {"id": "c2", "anchor": "not json", "author": {}, "content": "file-level",
+     "resolved": True},
+]
+
+
+def test_shape_comments_extracts_page_author_replies():
+    a, b = shape_comments(RAW_COMMENTS)
+    assert a["page"] == "s2g_aaaaaaaaaa_bbbbbbbbbb"
+    assert a["author"] == "Daniel Hails" and not a["resolved"]
+    assert a["replies"] == [{"author": "Ted", "content": "agree"}]
+    assert b["page"] is None and b["resolved"] is True
+
+
+def _native(texts):
+    """A native slide with one text box per entry, stacked top to bottom."""
+    els = []
+    for i, text in enumerate(texts):
+        els.append({"transform": {"translateY": i * 914400, "translateX": 0},
+                    "shape": {"text": {"textElements": [
+                        {"paragraphMarker": {}},
+                        {"textRun": {"content": text, "style": {}}}]}}})
+    return {"objectId": "s", "pageElements": els}
+
+
+def test_md_and_native_text_lines_agree_for_a_styled_slide():
+    md = "# 2026/06/15\n## RELIABLE MONITORS\n\nWeekly Update\n<!-- a note -->"
+    # live render stacks kicker above headline — order differs, content matches
+    native = _native(["RELIABLE MONITORS", "2026/06/15", "Weekly Update"])
+    assert text_lines_md(md) == text_lines_native(native)
+
+
+def test_md_text_lines_include_verbatim_fences_and_skip_comments():
+    md = "## PROMPT\n```text\nYou are a monitor.\n```\n<!-- hidden -->"
+    lines = text_lines_md(md)
+    assert "You are a monitor." in lines
+    assert not any("hidden" in line for line in lines)
+
+
+def test_classify_drift_three_way():
+    base, local, live = ["a"], ["a"], ["a"]
+    assert classify_drift(base, local, live) == "clean"
+    assert classify_drift(base, ["b"], live) == "local-edit"
+    assert classify_drift(base, local, ["b"]) == "live-drift"
+    assert classify_drift(base, ["b"], ["c"]) == "conflict"
+    assert classify_drift(base, ["b"], ["b"]) == "converged"
+    assert classify_drift(None, ["a"], ["a"]) == "clean"
+    assert classify_drift(None, ["a"], ["b"]) == "drift-no-base"