athena-python-docx 0.15.5__tar.gz → 0.16.1__tar.gz

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.15.5
+Version: 0.16.1
 Summary: Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/docx/__init__.py

@@ -6,7 +6,7 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.15.5"
+__version__ = "0.16.1"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/docx/_buffer.py

@@ -21,9 +21,9 @@ best-effort coalesce — if the loop thread races us we just flush twice
 (or zero times; the next loop-thread call drains it).
 
 `flush_all` is a process-wide hook used by the Daytona sandbox prelude to
-make sure pending writes hit Keryx and server-side edit sessions are
-checkpointed before the sandbox is suspended. It walks a weak-ref registry
-so dead Document instances don't keep their buffers alive.
+make sure pending writes hit Keryx before the sandbox is suspended. It walks
+a weak-ref registry so dead Workbook instances don't keep their buffers
+alive.
 """
 
 from __future__ import annotations
@@ -124,10 +124,25 @@ if TYPE_CHECKING:
 # HTTP POST to agora (see ``_ptc._send``), so emitting one card per low-level
 # mutation produces hundreds of sub-cards per script and pays full network
 # RTT on every one. The allow-list keeps the per-action signal — one card
-# per logical paragraph creation — without the spam or the cumulative
-# latency. Asset-level creation events (``CreateDocument``) are emitted
-# from ``Document.create`` directly, not through this buffer path.
-_PTC_EMIT_TOOLS: frozenset[str] = frozenset({"CreateParagraph"})
+# per logical block creation (paragraph, heading, table) — without the spam
+# or the cumulative latency. Asset-level creation events (``CreateDocument``)
+# are emitted from ``Document.create`` directly, not through this buffer path.
+_PTC_EMIT_TOOLS: frozenset[str] = frozenset({"CreateParagraph", "CreateHeading", "CreateTable"})
+
+
+def _should_emit_ptc(cmd: Command) -> bool:
+    """Whether ``cmd`` should produce a PTC sub-tool-card.
+
+    Only allow-listed block creates emit, and only when they target the
+    **body** story. Creates carrying an ``in_`` story locator (header,
+    footer, footnote, …) are skipped: the frontend locate affordance
+    scans the body editor only, so a header/footer card would highlight
+    an unrelated body block or nothing at all. Skip until the frontend
+    can route by ``args.in``.
+    """
+    if type(cmd).__name__ not in _PTC_EMIT_TOOLS:
+        return False
+    return getattr(cmd, "in_", None) is None
 
 
 def _ptc_emit_end_batch(cmds: list[Command], *, is_error: bool) -> None:
@@ -180,12 +195,11 @@ def _unregister(buffer: "CommandBuffer") -> None:
 
 
 def flush_all(*, strict: bool = False) -> None:
-    """Flush and checkpoint every live CommandBuffer in this process.
+    """Flush every live CommandBuffer in this process.
 
     Used by the Daytona sandbox prelude after user code returns, so
-    buffered mutations make it to Keryx and server-side edit sessions are
-    durably released before the sandbox is suspended. Safe to call when no
-    Buffers exist (no-op).
+    buffered mutations make it to Keryx before the sandbox is suspended.
+    Safe to call when no Buffers exist (no-op).
 
     By default, failures are logged and swallowed for backwards
     compatibility with existing local scripts. The executor calls
@@ -217,9 +231,9 @@ def flush_all(*, strict: bool = False) -> None:
                     sys.stderr.write(f"[docx-sdk] flush_all: {msg}\n")
             continue
         try:
-            buf.commit()
+            buf.flush()
         except Exception as e:  # noqa: BLE001
-            msg = f"buffer {buf.asset_id} flush/commit failed: {e}"
+            msg = f"buffer {buf.asset_id} flush failed: {e}"
             if strict:
                 failures.append(msg)
             else:
@@ -415,7 +429,7 @@ class CommandBuffer:
         # commands still flow through the buffer (and through the batched
         # HTTP POST), they just don't produce a sub-tool-card. ``emit_end``
         # is automatically skipped because no ``_ptc_call_id`` was set.
-        if type(cmd).__name__ in _PTC_EMIT_TOOLS:
+        if _should_emit_ptc(cmd):
             try:
                 cmd._ptc_call_id = _ptc.emit_begin(  # type: ignore[attr-defined]
                     type(cmd).__name__,
@@ -500,20 +514,6 @@ class CommandBuffer:
         _apply_proxy_id_rewrites(results, proxy_id_refs)
         return results
 
-    def commit(self) -> None:
-        """Flush pending commands and release the server-side edit session.
-
-        The HTTP command response tells us docx-studio applied the batch to its
-        pooled SuperDoc handle. Releasing the handle closes the collaboration
-        session without discard on the server, which is the durability
-        checkpoint for asset-backed document edits.
-        """
-        self._assert_current_execution()
-        self.flush()
-        release_asset = getattr(self._client, "release_asset", None)
-        if callable(release_asset):
-            release_asset(self._asset_id)
-
     def close(self) -> None:
         """Flush and disable. Idempotent."""
         if self._closed:
@@ -528,7 +528,7 @@ class CommandBuffer:
                     self._proxy_id_refs = {}
                 _ptc_emit_end_batch(pending, is_error=True)
             else:
-                self.commit()
+                self.flush()
         finally:
             self._closed = True
             _unregister(self)

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/docx/_http_doc.py

@@ -699,24 +699,6 @@ class HttpClient:
         except Exception:  # noqa: BLE001
             pass
 
-    def release_asset(self, asset_id: str) -> None:
-        """Ask docx-studio to close its pooled SuperDoc session for ``asset_id``.
-
-        Command POSTs only prove that the server accepted and applied the
-        mutation batch to its live SuperDoc handle. The durable checkpoint for
-        collaborative sessions happens when that handle is closed without
-        discard, so ``Document.save()`` and the Daytona ``flush_all`` cleanup
-        call this endpoint after draining the command buffer.
-        """
-        url: str = f"{self._base_url}/docs/{asset_id}/session/release"
-        _http_post_json(
-            session=self._session,
-            url=url,
-            api_key=self._api_key,
-            body={},
-            timeout=30.0,
-        )
-
     def execute_batch(
         self,
         asset_id: str,

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/docx/_timeouts.py

@@ -13,13 +13,6 @@ LONG_RUNNING_COMMAND_TIMEOUT_SECONDS: float = 300.0
 
 _LONG_RUNNING_COMMAND_TYPES: frozenset[str] = frozenset(
     {
-        # The first write to a large imported document can spend close to a
-        # minute opening/syncing the server-side SuperDoc session before the
-        # block creation itself is applied. These are ordinary agent primitives
-        # for "append a summary/TLDR", so give the first batch enough room.
-        "CreateHeading",
-        "CreateParagraph",
-        "CreateSectionBreak",
         "FindReplace",
         # Plain ``cell.text = value`` table fills are buffered as TableSetCell
         # commands. On dense legal documents, SuperDoc can spend well over the

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/docx/client.py

@@ -231,8 +231,8 @@ class Session:
         handle = self._doc_handle
         buffer = getattr(handle, "buffer", None) if handle is not None else None
         if buffer is not None:
-            buffer.commit()
-        _log_info(f"Saved {self._asset_id} (buffer drained and session released)")
+            buffer.flush()
+        _log_info(f"Saved {self._asset_id} (buffer drained)")
 
     async def close(self) -> None:
         """Close the session. Idempotent."""

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/docx/commands.py

@@ -519,6 +519,11 @@ class ImagesGet(Command):
 class BlocksList(Command):
     node_types: list[str] | None = None
     include_text: bool | None = None
+    # Ask the server to inline each paragraph/heading block's run breakdown
+    # (``paragraph.inlines``) so ``Document.paragraphs`` can hydrate
+    # ``Paragraph.text``/``.runs``/``.style`` from one list instead of a
+    # ``get_node_by_id`` per paragraph. Serialized to ``includeRuns`` on the wire.
+    include_runs: bool | None = None
 
 
 @dataclass

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/docx/document.py

@@ -359,12 +359,23 @@ class Document:
         # Include "heading" too so iterating over paragraphs covers both —
         # python-docx does not distinguish headings from paragraphs at the
         # Document.paragraphs level either (they're all Paragraph instances).
+        # ``includeRuns`` asks the server to inline each block's run breakdown
+        # (``paragraph.inlines``) so we can hydrate every returned proxy's
+        # ``.text`` / ``.runs`` / ``.style`` from this single list — instead of
+        # one ``get_node_by_id`` round-trip per paragraph per property. A
+        # read-heavy restyle loop over a large doc drops from ~N×3 round-trips
+        # to 1. See ``docx-studio/PERFORMANCE_BATCHING_ANALYSIS.md``.
         raw: object = run_sync(
             self._session.doc.blocks.list(
-                {"nodeTypes": ["paragraph", "heading"], "includeText": False},
+                {
+                    "nodeTypes": ["paragraph", "heading"],
+                    "includeText": True,
+                    "includeRuns": True,
+                },
             ),
         )
-        # Real shape: {"blocks": [{"kind":"block","nodeType":..,"nodeId":..}], ...}
+        # Real shape: {"blocks": [{"kind":"block","nodeType":..,"nodeId":..,
+        # "styleId":..,"text":..,"paragraph":{"inlines":[..]}}], ...}
         if isinstance(raw, dict):
             blocks_obj: object = raw.get("blocks", [])
             blocks: list = blocks_obj if isinstance(blocks_obj, list) else []
@@ -380,11 +391,20 @@ class Document:
             if node_id:
                 nt_raw = b.get("nodeType")
                 nt: str = nt_raw if isinstance(nt_raw, str) and nt_raw else "paragraph"
+                # Seed the read cache when the server inlined this block's runs.
+                # The snapshot is ``get_node_by_id``-shaped so
+                # ``Paragraph._node_info`` and the text/runs/style getters consume
+                # it unchanged. Blocks without an ``inlines`` payload (e.g.
+                # tables) fall back to live queries.
+                snapshot: dict | None = (
+                    {"node": b} if isinstance(b.get("paragraph"), dict) else None
+                )
                 out.append(
                     Paragraph(
                         session=self._session,
                         node_id=node_id,
                         node_type=nt,
+                        node_info_snapshot=snapshot,
                     ),
                 )
         return out

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/docx/text/paragraph.py

@@ -226,6 +226,7 @@ class Paragraph:
         in_cell: bool = False,
         cell_ooxml_address: "tuple[str | None, int, int, int, int] | None" = None,
         cell: "object | None" = None,
+        node_info_snapshot: dict | None = None,
     ) -> None:
         self._session: "Session" = session
         self._node_id: str = node_id
@@ -272,6 +273,36 @@ class Paragraph:
         # — defensive for paragraph proxies built outside the _Cell
         # construction paths.
         self._cell: object | None = cell
+        # Prefetched ``get_node_by_id``-shaped snapshot
+        # (``{"node": {..., "paragraph": {"inlines": [...]}}}``) seeded by
+        # ``Document.paragraphs`` via the bulk ``blocks.list(includeRuns=True)``
+        # read. When present, ``text`` / ``runs`` / ``style`` read it instead of
+        # issuing a per-property ``get_node_by_id`` round-trip. It is a
+        # point-in-time snapshot (consistent with ``Document.paragraphs`` already
+        # returning a snapshot list) and is dropped by ``_invalidate_node_info``
+        # the moment this proxy mutates its own content.
+        self._node_info_snapshot: dict | None = node_info_snapshot
+
+    def _node_info(self) -> object:
+        """Return this paragraph's ``get_node_by_id``-shaped node info.
+
+        Served from the prefetch snapshot when one was seeded (one bulk
+        ``blocks.list`` for the whole document instead of one
+        ``get_node_by_id`` per ``.text`` / ``.runs`` / ``.style`` access);
+        otherwise a live query. ``_invalidate_node_info`` clears the snapshot
+        after a content mutation so the next read re-queries.
+        """
+        snapshot = self._node_info_snapshot
+        if snapshot is not None:
+            return snapshot
+        return run_sync(
+            self._session.doc.get_node_by_id({"id": self._node_id}),
+        )
+
+    def _invalidate_node_info(self) -> None:
+        """Drop the prefetched node snapshot after a content mutation, so the
+        next ``text`` / ``runs`` / ``style`` read reflects the new state."""
+        self._node_info_snapshot = None
 
     def _check_cell_inner(self, op: str, **format_props: Any) -> bool:
         """Return ``True`` if this paragraph is inside a table cell and
@@ -356,7 +387,7 @@ class Paragraph:
     @property
     def text(self) -> str:
         """Return the plain-text content of this paragraph."""
-        return _node_text(self._session, self._node_id)
+        return _extract_text(self._node_info())
 
     @text.setter
     def text(self, value: str) -> None:
@@ -399,6 +430,9 @@ class Paragraph:
         # We just replaced the entire paragraph contents with ``value``;
         # the new text-address length is simply ``len(value)``.
         self._text_len = len(value)
+        # Content changed — drop the prefetched snapshot so a follow-up
+        # ``.text`` / ``.runs`` read reflects the replacement.
+        self._invalidate_node_info()
 
     @property
     def runs(self) -> list["Run"]:
@@ -413,9 +447,7 @@ class Paragraph:
         """
         from docx.text.run import Run
 
-        info: object = run_sync(
-            self._session.doc.get_node_by_id({"id": self._node_id}),
-        )
+        info: object = self._node_info()
         inlines: list[dict] = _walk_inlines(info)
         runs: list["Run"] = []
         offset: int = 0
@@ -479,9 +511,7 @@ class Paragraph:
         from docx.styles.style import ParagraphStyle
         from docx.enum.style import WD_STYLE_TYPE
 
-        info: object = run_sync(
-            self._session.doc.get_node_by_id({"id": self._node_id}),
-        )
+        info: object = self._node_info()
         if not isinstance(info, dict):
             return None
         node: object = info.get("node")
@@ -537,6 +567,10 @@ class Paragraph:
                 },
             ),
         )
+        # Style changed — drop the prefetched snapshot so a follow-up ``.style``
+        # read reflects the new style instead of the stale prefetched value
+        # (the restyle-loop read-after-write this PR's prefetch targets).
+        self._invalidate_node_info()
 
     @property
     def alignment(self) -> "WD_ALIGN_PARAGRAPH | None":
@@ -1227,6 +1261,9 @@ class Paragraph:
                 )
             offset += 1
             i = j + 1
+        # Inserted content — drop the prefetched node snapshot so a follow-up
+        # ``.text`` / ``.runs`` read on this proxy reflects the new runs.
+        self._invalidate_node_info()
 
     @athena_extension(
         issue=74,
@@ -1397,6 +1434,11 @@ class Paragraph:
         )
         run_sync(self._session.send_command(cmd))
         self._text_len = end_offset
+        # Appended a hyperlink run — drop the prefetched snapshot so a follow-up
+        # ``.text`` / ``.runs`` read reflects the new content. This path fires
+        # ``CreateHyperlink`` directly via ``send_command`` (it bypasses
+        # ``_insert_run_text_segments``), so it needs its own invalidation.
+        self._invalidate_node_info()
 
         run_dict = {"text": text, "hyperlink": {"url": url, "target": url}}
         return Hyperlink(

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.15.5"
+version = "0.16.1"
 description = "Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack"
 readme = "README.md"
 license = "MIT"

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/tests/fidelity/fake_session.py

@@ -296,6 +296,7 @@ class FakeDocState:
 
         if op == "blocks.list":
             types = params.get("nodeTypes") or None
+            include_runs = bool(params.get("includeRuns"))
             out_blocks: list[dict] = []
             for b in self.blocks:
                 if types and b.node_type not in types:
@@ -307,6 +308,12 @@ class FakeDocState:
                     "styleId": b.style_id,
                     "alignment": b.alignment,
                 }
+                # Mirror the real server: when runs are requested, inline each
+                # paragraph/heading block's run breakdown so the SDK hydrates
+                # Paragraph.text/.runs/.style from this one list (no per-node read).
+                if include_runs and b.node_type in ("paragraph", "heading"):
+                    entry["text"] = b.text
+                    entry["paragraph"] = {"inlines": list(b.inlines)}
                 out_blocks.append(entry)
             # Mirror real SuperDoc: when "table" is in the requested
             # nodeTypes, top-level tables come back too. The fake doesn't

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/tests/test_buffer.py

@@ -7,9 +7,8 @@ Verifies that:
 - Creates WITH a client id (the transparent-batching path) defer,
 - pending mutations drain in the same batch as an eager call,
 - ``flush()`` drains explicitly,
-- ``commit()`` drains and releases the server-side session,
 - the idle timer auto-flushes after a configurable window,
-- the process-wide ``flush_all`` walks every live buffer and commits it.
+- the process-wide ``flush_all`` walks every live buffer.
 """
 
 from __future__ import annotations
@@ -27,7 +26,6 @@ from docx._timeouts import DEFAULT_OP_TIMEOUT_SECONDS, LONG_RUNNING_COMMAND_TIME
 from docx.commands import (
     BlocksList,
     Command,
-    CreateHeading,
     CreateParagraph,
     FormatApply,
     Replace,
@@ -46,7 +44,6 @@ class _FakeClient:
         # Envelope-level fields recorded per batch — used by
         # track-changes tests to verify changeMode / user propagation.
         self.envelopes: list[dict[str, Any]] = []
-        self.releases: list[str] = []
         self._lock = threading.Lock()
 
     def execute_batch(
@@ -65,10 +62,6 @@ class _FakeClient:
         # Mimic per-command result envelope.
         return [{"index": i, "ok": True} for i, _ in enumerate(commands)]
 
-    def release_asset(self, asset_id: str) -> None:
-        with self._lock:
-            self.releases.append(asset_id)
-
 
 class _FakeDocHandle:
     def __init__(self, buffer: CommandBuffer) -> None:
@@ -116,23 +109,6 @@ def test_pending_timeout_extends_for_table_set_cell_batches() -> None:
     buf.close()
 
 
-def test_pending_timeout_extends_for_block_creation_batches() -> None:
-    fake = _FakeClient()
-    buf = CommandBuffer(fake, "asset_1", auto_flush_seconds=0.0)
-
-    buf.call(
-        CreateHeading(
-            text="TLDR",
-            level=1,
-            at={"kind": "documentEnd"},
-            client_node_id="h_test",
-        )
-    )
-
-    assert buf.pending_timeout_seconds == LONG_RUNNING_COMMAND_TIMEOUT_SECONDS
-    buf.close()
-
-
 def test_session_pending_timeout_reads_command_buffer_budget() -> None:
     from docx.client import Session
 
@@ -213,19 +189,6 @@ def test_flush_with_empty_queue_is_noop() -> None:
     buf.close()
 
 
-def test_commit_drains_pending_and_releases_server_session() -> None:
-    fake = _FakeClient()
-    buf = CommandBuffer(fake, "asset_1", auto_flush_seconds=0.0)
-
-    buf.call(FormatApply(target={"kind": "block"}, inline={"bold": True}))
-    buf.commit()
-
-    assert len(fake.batches) == 1
-    assert _types(fake.batches[0]) == ["FormatApply"]
-    assert fake.releases == ["asset_1"]
-    buf.close()
-
-
 def test_idle_timer_auto_flushes() -> None:
     """A non-zero idle window should flush after inactivity.
 
@@ -319,8 +282,6 @@ def test_flush_all_walks_every_live_buffer() -> None:
     flush_all()
     assert len(fake_a.batches) == 1
     assert len(fake_b.batches) == 1
-    assert fake_a.releases == ["asset_a"]
-    assert fake_b.releases == ["asset_b"]
     buf_a.close()
     buf_b.close()
 

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/tests/test_http_transport.py

@@ -17,7 +17,7 @@ import requests
 from docx import __version__ as SDK_VERSION
 from docx._http_doc import HttpClient, HttpDocHandle
 from docx._timeouts import LONG_RUNNING_COMMAND_TIMEOUT_SECONDS
-from docx.commands import CreateParagraph, FindReplace, TableSetCell
+from docx.commands import FindReplace, TableSetCell
 from docx.errors import AuthenticationError, DocxError, SessionError
 
 
@@ -145,73 +145,6 @@ def test_table_set_cell_batch_uses_long_running_http_timeout() -> None:
     assert captured["timeout"] == LONG_RUNNING_COMMAND_TIMEOUT_SECONDS
 
 
-def test_block_creation_batch_uses_long_running_http_timeout() -> None:
-    captured: dict[str, Any] = {}
-
-    def _capture(url: str, **kwargs: Any) -> _FakeResponse:  # noqa: ARG001
-        captured["timeout"] = kwargs["timeout"]
-        return _FakeResponse(
-            status_code=200,
-            body=_ok_body(
-                [
-                    {
-                        "index": 0,
-                        "type": "CreateParagraph",
-                        "result": {
-                            "client_node_id": "p_test",
-                            "real_node_id": "paragraph_real",
-                        },
-                    }
-                ],
-            ),
-        )
-
-    client = HttpClient(base_url="https://example.com", api_key="bg_key")
-
-    with patch.object(client._session, "post", side_effect=_capture):
-        result = client.execute_batch(
-            "asset_test",
-            [
-                CreateParagraph(
-                    text="DLDR",
-                    at={"kind": "documentEnd"},
-                    client_node_id="p_test",
-                )
-            ],
-        )
-
-    assert result == [
-        {"client_node_id": "p_test", "real_node_id": "paragraph_real"}
-    ]
-    assert captured["timeout"] == LONG_RUNNING_COMMAND_TIMEOUT_SECONDS
-
-
-def test_release_asset_posts_to_session_release_endpoint() -> None:
-    captured: dict[str, Any] = {}
-
-    def _capture(url: str, **kwargs: Any) -> _FakeResponse:
-        captured["url"] = url
-        captured["body"] = json.loads(kwargs["data"].decode("utf-8"))
-        captured["auth"] = kwargs["headers"].get("Authorization")
-        captured["timeout"] = kwargs["timeout"]
-        return _FakeResponse(
-            status_code=200,
-            body=b'{"assetId":"asset_test","released":true}',
-        )
-
-    client = HttpClient(base_url="https://example.com", api_key="bg_key")
-
-    with patch.object(client._session, "post", side_effect=_capture):
-        client.release_asset("asset_test")
-
-    assert captured == {
-        "url": "https://example.com/docs/asset_test/session/release",
-        "body": {},
-        "auth": "Bearer bg_key",
-        "timeout": 30.0,
-    }
-
-
 def test_deeply_nested_paths() -> None:
     """``doc.format.paragraph.set_alignment(p)`` walks three levels and
     serializes as ``SetParagraphAlignment``. It's a pure mutation, so it

{athena_python_docx-0.15.5 → athena_python_docx-0.16.1}/tests/test_iter_inner_content.py

@@ -35,15 +35,22 @@ def test_document_iter_inner_content_yields_paragraphs_then_table() -> None:
     assert all(isinstance(i, (Paragraph, Table)) for i in items)
 
 
-def test_document_paragraphs_uses_lightweight_block_listing() -> None:
+def test_document_paragraphs_prefetches_runs_in_one_listing() -> None:
+    """``Document.paragraphs`` issues ONE rich ``blocks.list(includeRuns=True)``
+    and hydrates every proxy's text/style/runs from it — so iterating and reading
+    per-paragraph properties costs no extra ``getNodeById`` round-trips (the old
+    hot path was one query per property per paragraph). See
+    ``docx-studio/PERFORMANCE_BATCHING_ANALYSIS.md``."""
     install_fake_session()
     from docx import Document
 
     doc = Document("asset_fake")
     doc.add_paragraph("Intro")
+    doc.add_heading("Section A", level=1)
 
-    _ = doc.paragraphs
+    paras = doc.paragraphs
 
+    # paragraphs() asked the server to inline the run breakdown.
     block_list_calls = [
         params
         for op, params in doc._session.calls()
@@ -51,7 +58,62 @@ def test_document_paragraphs_uses_lightweight_block_listing() -> None:
         and params.get("nodeTypes") == ["paragraph", "heading"]
     ]
     assert block_list_calls
-    assert block_list_calls[-1]["includeText"] is False
+    assert block_list_calls[-1]["includeRuns"] is True
+
+    # Reading text/style/runs off the prefetched proxies issues NO per-paragraph
+    # getNodeById round-trips.
+    calls_before: int = len(doc._session.calls())
+    for p in paras:
+        _ = p.text
+        _ = p.style
+        _ = list(p.runs)
+    extra_node_reads = [
+        op for op, _ in doc._session.calls()[calls_before:] if op == "getNodeById"
+    ]
+    assert extra_node_reads == []
+
+
+def test_paragraph_text_mutation_invalidates_prefetch_snapshot() -> None:
+    """A content mutation on a prefetched paragraph drops its snapshot, so the
+    next read reflects the new state instead of the stale prefetched value."""
+    install_fake_session()
+    from docx import Document
+
+    doc = Document("asset_fake")
+    doc.add_paragraph("Original")
+
+    p = doc.paragraphs[0]
+    assert p.text == "Original"  # served from the prefetch snapshot
+
+    p.text = "Replaced"  # content mutation → snapshot invalidated
+
+    calls_before: int = len(doc._session.calls())
+    assert p.text == "Replaced"  # re-read reflects the mutation
+    # The fresh read went back to the server (the stale snapshot was dropped).
+    assert any(
+        op == "getNodeById" for op, _ in doc._session.calls()[calls_before:]
+    )
+
+
+def test_paragraph_style_set_invalidates_prefetch_snapshot() -> None:
+    """Setting ``.style`` on a prefetched paragraph drops its snapshot, so the
+    next ``.style`` read returns the new style — the restyle-loop read-after-write
+    (``for p in doc.paragraphs: p.style = ...``) the prefetch optimizes for."""
+    install_fake_session()
+    from docx import Document
+
+    doc = Document("asset_fake")
+    doc.add_paragraph("Body")
+
+    p = doc.paragraphs[0]
+    _ = p.style  # prime the prefetch snapshot
+
+    p.style = "Heading1"  # style mutation → snapshot must be invalidated
+
+    style_after = p.style
+    assert style_after is not None
+    # Re-read reflects the new style instead of the stale prefetched value.
+    assert style_after.name == "Heading1"
 
 
 def test_document_tables_uses_lightweight_block_listing() -> None: