athena-python-pptx 0.1.51__tar.gz → 0.1.56__tar.gz

athena_python_pptx-0.1.56/API_PARITY_REPORT.md

@@ -0,0 +1,51 @@
+# API Parity Report: athena-python-pptx vs python-pptx
+
+**Generated:** 2026-03-23
+**athena-python-pptx version:** 0.1.52
+**python-pptx version:** 1.0.2
+**Test script:** `tests/test_python_pptx_api_parity.py`
+**Classes tested:** 8
+
+---
+
+## Summary
+
+**0 unexpected missing, 0 unexpected extras, 0 param mismatches across all tested classes.**
+
+| Class | Standard Members | Missing | Extra | Status |
+|-------|---------|---------|-------|--------|
+| FillFormat | solid, background, gradient, patterned, fore_color, back_color, pattern, type | 1 (internal) | 2 (gradient props) | PASS |
+| LineFormat | color, dash_style, fill, width | 0 | 2 (is_dashed, is_solid) | PASS |
+| RGBColor | from_string, count, index, __iter__, __len__, __getitem__ | 0 | 0 | PASS |
+| ColorFormat | rgb, theme_color, brightness, type | 1 (internal) | 0 | PASS |
+| Font | bold, italic, underline, size, name, color | 2 (fill, language_id) | 0 | PASS |
+| TextFrame | text, paragraphs, margins, auto_size, word_wrap, add_paragraph, clear, fit_text | 1 (part) | 47 (convenience) | PASS |
+| Paragraph | alignment, font, level, line_spacing, runs, space_after/before, add_run, clear | 1 (part) | 30 (convenience) | PASS |
+| Run | text, font, hyperlink | 1 (part) | 20 (convenience) | PASS |
+
+## Intentionally Omitted
+
+| Member | Reason |
+|--------|--------|
+| `*.part` | Package part — REST SDK has no local XML packages |
+| `FillFormat.from_fill_parent()` | Internal XML constructor |
+| `ColorFormat.from_colorchoice_parent()` | Internal XML constructor |
+| `Font.fill` | Font fill format — not commonly used |
+| `Font.language_id` | Not yet implemented |
+
+## Non-Standard Extras (Candidates for Future Cleanup)
+
+**Core classes (FillFormat, LineFormat, RGBColor, ColorFormat, Font):** Fully cleaned — no non-standard methods.
+
+**TextFrame:** 47 convenience methods (to_html, to_markdown, word_count, capitalize, etc.)
+**Paragraph:** 30 convenience methods (bullet helpers, string ops, to_dict, etc.)
+**Run:** 20 convenience methods (string ops, is_bold, has_hyperlink, etc.)
+
+These extras are additive (don't break standard code) but should be removed in a future pass to match the same parity standard as the core classes.
+
+## How to Run
+
+```bash
+pip install python-pptx --target /tmp/pptx-standard
+python -m pytest tests/test_python_pptx_api_parity.py -v -s
+```

athena_python_pptx-0.1.56/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `athena-python-pptx` are documented in this file.
+
+## 0.1.56
+
+- **Charts: end-to-end author + edit support** for column / bar / line / area / pie / doughnut (including all stacked variants).
+  - `slide.shapes.add_chart(chart_type, left, top, width, height, chart_data)` now authors a fresh chart from scratch — previously raised `UnsupportedFeatureError`. Returns a `GraphicFrame` whose `.chart` property exposes the resulting `Chart` object. Supported types: `XL_CHART_TYPE.COLUMN_CLUSTERED`, `COLUMN_STACKED`, `COLUMN_STACKED_100`, `BAR_CLUSTERED`, `BAR_STACKED`, `BAR_STACKED_100`, `LINE`, `LINE_MARKERS`, `LINE_STACKED`, `LINE_STACKED_100`, `AREA`, `AREA_STACKED`, `AREA_STACKED_100`, `PIE`, `DOUGHNUT`. 3-D / scatter / bubble / radar / stock / surface / combo still raise `UnsupportedFeatureError` with a clearer message listing the supported set.
+  - `placeholder.insert_chart(chart_type, chart_data)` now wires up the same path — previously raised `NotImplementedError`.
+  - `Chart.replace_data(chart_data)` now emits `UpdateChartData` patches against an existing chart (ingested or just-authored) — previously raised `UnsupportedFeatureError`. Rewrites series values, series names, and category labels in place; embedded `.xlsx` workbook stays in sync.
+  - New `Chart.chart_title` setter and `Chart.has_legend` setter emit `SetChartTitle` and `SetLegendVisible` patches respectively.
+  - `CategoryChartData.add_series()` and `XyChartData` / `BubbleChartData` now capture data client-side instead of raising eagerly. (Authoring scatter / bubble charts still raises at `add_chart()` time.)
+  - `GraphicFrame` extended to host a `Chart` (in addition to `Table`), so `gf.chart` and `gf.has_chart` work.
+
+## 0.1.55
+
+- Internal: bumped version coordinated with the `Presentation.create()` server-side fix (#19270). No SDK API change.
+
+## 0.1.54
+
+- `RemoteError.__str__` now includes the HTTP status code (e.g., `[HTTP 400] Invalid request body: ...`) so the status is visible in tracebacks without unpacking `exc.status_code`.
+
+## 0.1.39
+
+- Added SDK support for `slide.shapes.add_table(...)` and table creation command wiring.
+- Added `slide.notes_slide.notes_text_frame.text` compatibility adapter for python-pptx style notes access.
+- Added support for auto-shape text frame access (`shape.text_frame`) to match python-pptx behavior.
+- Added smoke/integration tests for table creation/cell updates, notes slide adapter, and shape text-frame regression.
+- Updated README examples for notes slide adapter and auto-shape text support.

athena_python_pptx-0.1.56/CLAUDE.md

@@ -0,0 +1,73 @@
+# athena-python-pptx SDK — Claude Instructions
+
+## API Parity Rule (MANDATORY)
+
+**This SDK MUST be a 100% exact replica of the standard [python-pptx](https://python-pptx.readthedocs.io/) API.**
+
+Every class, method, property, and parameter name must match python-pptx exactly. The goal is that any code written for python-pptx works identically with this SDK — no surprises, no differences.
+
+### What this means in practice
+
+- **Do NOT add new methods** that don't exist in python-pptx (e.g., `fill.set_color()`, `line.no_fill()`, `fill.solid_fill()`)
+- **Do NOT add new properties** that don't exist in python-pptx (e.g., `fill.color_hex`, `line.color_hex`, `line.width_pt`)
+- **Do NOT rename parameters** — use the exact same parameter names as python-pptx (e.g., `autoshape_type_id`, not `autoshape_type`)
+- **Do NOT change method signatures** — if python-pptx's `fill.solid()` takes no arguments, ours must also take no arguments
+- **Do NOT change return types** — if python-pptx's `font.color` returns a `ColorFormat`, ours must too (never `None`)
+
+### How to verify parity
+
+Before adding or modifying any API surface:
+
+1. Check the [python-pptx documentation](https://python-pptx.readthedocs.io/)
+2. Check the [python-pptx source code](https://github.com/scanny/python-pptx)
+3. Confirm the method/property/parameter exists with the same name and signature
+4. If it doesn't exist in python-pptx, **do not add it** without explicit user approval
+
+### Current status (v0.1.52)
+
+**Core classes are at 1:1 parity** with python-pptx: FillFormat, LineFormat, RGBColor, ColorFormat, Font. All legacy convenience methods on these classes have been removed.
+
+**TextFrame, Paragraph, and Run** still have non-standard convenience extras (e.g., `to_dict()`, `word_count`, `capitalize()`, string helpers). These are candidates for removal in a future cleanup pass.
+
+Run `python -m pytest tests/test_python_pptx_api_parity.py -v -s` to verify parity across 8 classes.
+
+### Intentionally omitted (REST SDK limitations)
+
+These standard python-pptx members don't apply to a REST SDK:
+- `Shape.element`, `Shape.part` — XML element access (no local XML)
+- `TextFrame.part`, `Paragraph.part`, `Run.part` — package part access
+- `FillFormat.from_fill_parent()`, `ColorFormat.from_colorchoice_parent()` — internal constructors
+- `Font.fill` — font fill format (not supported)
+- `Font.language_id` — not yet implemented
+
+### If you need a deviation
+
+If there is a genuine technical reason why a deviation from python-pptx is necessary (e.g., the SDK is a REST client and cannot replicate XML-level behavior):
+
+1. **Stop and ask the user** before implementing
+2. Explain what the deviation is and why it's needed
+3. Get explicit confirmation that the deviation is acceptable
+4. Document the deviation in the table above
+
+**Do NOT silently add convenience methods, aliases, or "improved" APIs.** The value of this SDK is that it's a drop-in replacement — any divergence breaks that contract.
+
+## Development
+
+```bash
+# Install in editable mode
+pip install -e ".[dev]"
+
+# Run tests
+python -m pytest tests/ -x -q
+
+# Run specific test file
+python -m pytest tests/test_sdk_features.py -x -q
+```
+
+## Architecture
+
+This is a **REST API client** that mimics the python-pptx API. Instead of manipulating XML directly, method calls are translated to commands sent to the PPTX Studio API server. Key differences from python-pptx internals:
+
+- No `_element`, `_sp`, `_spTree` XML attributes — these don't exist
+- Operations are batched via `with prs.batch():` context manager
+- State is synchronized via the PPTX Studio collaboration layer (Yjs)

{athena_python_pptx-0.1.51 → athena_python_pptx-0.1.56}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.1.51
+Version: 0.1.56
 Summary: Drop-in replacement for python-pptx that connects to PPTX Studio for real-time collaboration
 Project-URL: Homepage, https://github.com/pptx-studio/python-sdk
 Project-URL: Documentation, https://docs.pptx-studio.com/sdk/python

athena_python_pptx-0.1.56/docs/API_PARITY_EXCEPTIONS.md

@@ -0,0 +1,110 @@
+# athena-python-pptx API Parity Exceptions
+
+This document lists all intentional deviations from the standard [python-pptx](https://python-pptx.readthedocs.io/) API in the athena-python-pptx SDK.
+
+The SDK's goal is 1:1 API parity with python-pptx. These exceptions exist because the SDK is a REST client (no local XML), or because LLM agents need ergonomic aliases for common patterns.
+
+---
+
+## REST SDK Limitations (python-pptx members that don't apply)
+
+These standard python-pptx members are omitted because a REST SDK has no access to the underlying XML or package structure:
+
+| Member | Reason |
+|--------|--------|
+| `Shape.element`, `Shape.part` | XML element access (no local XML) |
+| `TextFrame.part`, `Paragraph.part`, `Run.part` | Package part access |
+| `FillFormat.from_fill_parent()` | Internal constructor |
+| `ColorFormat.from_colorchoice_parent()` | Internal constructor |
+| `Font.fill` | Font fill format (not supported) |
+| `Font.language_id` | Not yet implemented |
+
+---
+
+## Agent-Friendly Additions (not in python-pptx)
+
+These properties/methods were added because LLM agents (Claude, GPT, etc.) frequently generate code using these patterns. Without them, agent-generated table code fails at runtime.
+
+### `TableCell` — RGB tuple aliases
+
+| Property | Type | Maps to | Why |
+|----------|------|---------|-----|
+| `cell.font_bold` | `bool` | `cell.bold` | Agents write `cell.font_bold = True` instead of `cell.bold = True` |
+| `cell.font_color_rgb` | `tuple(R,G,B)` | `cell.font_color_hex` | Agents write `cell.font_color_rgb = (255, 255, 255)` instead of `cell.font_color_hex = "FFFFFF"` |
+| `cell.fill_color_rgb` | `tuple(R,G,B)` | `cell.fill` (hex) | Agents write `cell.fill_color_rgb = (31, 57, 100)` instead of `cell.fill = "1F3964"` |
+
+**Example of the agent pattern these support:**
+
+```python
+# LLM agents commonly generate this pattern:
+cell = tbl.cell(0, 0)
+cell.text = "Header"
+cell.font_size_pt = 14
+cell.font_bold = True
+cell.font_color_rgb = (255, 255, 255)
+cell.fill_color_rgb = (31, 57, 100)
+```
+
+### `GraphicFrame` — Table passthrough methods
+
+In python-pptx, `add_table()` returns a `GraphicFrame` and the table is accessed via `.table`. However, agents frequently call `.cell()`, `.rows`, `.cols` directly on the return value. These passthroughs prevent `AttributeError`:
+
+| Member | Delegates to |
+|--------|-------------|
+| `graphic_frame.cell(row, col)` | `graphic_frame.table.cell(row, col)` |
+| `graphic_frame.rows` | `graphic_frame.table.rows` |
+| `graphic_frame.cols` | `graphic_frame.table.cols` |
+
+**Example:**
+
+```python
+# Both patterns work:
+tbl = slide.shapes.add_table(rows=3, cols=3, ...)
+
+# Pattern 1: python-pptx canonical
+tbl.table.cell(0, 0).text = "Header"
+
+# Pattern 2: agent shortcut (also works)
+tbl.cell(0, 0).text = "Header"
+```
+
+---
+
+## Structural Deviations (python-pptx behavior differs)
+
+### `Table.first_row` / `Table.last_row` — Boolean look flags, not cell lists
+
+In python-pptx, `Table.first_row` and `Table.last_row` are boolean properties controlling table style look flags (whether the first/last row gets special styling).
+
+In a prior version of this SDK, these were cell-list properties returning `list[TableCell]`. They have been changed to match python-pptx (boolean). The old cell-list accessors are available as methods:
+
+| Old (removed) | New (python-pptx parity) | Cell-list replacement |
+|---------------|-------------------------|----------------------|
+| `table.first_row` → `list[TableCell]` | `table.first_row` → `bool` | `table.get_first_row_cells()` |
+| `table.last_row` → `list[TableCell]` | `table.last_row` → `bool` | `table.get_last_row_cells()` |
+| `table.first_column` → `list[TableCell]` | (not a python-pptx property) | `table.get_first_column_cells()` |
+| `table.last_column` → `list[TableCell]` | (not a python-pptx property) | `table.get_last_column_cells()` |
+
+### `Shapes.add_table()` — Returns `GraphicFrame`, not `Table`
+
+Changed to match python-pptx semantics. `add_table()` returns a `GraphicFrame`. Access the `Table` via `.table`. The passthrough methods above ensure backward compatibility for code that calls `.cell()` directly.
+
+### `_Row` / `_Column` with height/width setters
+
+python-pptx's `_Row.height` and `_Column.width` are read/write EMU properties. This SDK matches that API, but setting them also emits SDK commands (`SetRowHeight`, `SetColWidth`) to the server.
+
+### `Table.rows` / `Table.columns` — Return `_RowCollection` / `_ColumnCollection`
+
+In python-pptx, `Table.rows` returns a `_RowCollection` of `_Row` objects (each with `.height`). This SDK matches that. In a prior version, `Table.rows` returned a flat collection of cell lists.
+
+---
+
+## Non-Standard Convenience Methods (candidates for future cleanup)
+
+These exist on `TextFrame`, `Paragraph`, `Run`, `TableCell`, and `Table` but are NOT in python-pptx:
+
+- `to_dict()`, `word_count`, `capitalize()`, `upper()`, `lower()`, `title()`, `strip()`, `is_empty`
+- `Table.to_csv()`, `Table.to_list()`, `Table.to_dict_list()`, `Table.all_text`, `Table.contains_text()`, `Table.find_cells()`
+- `TableCell.address` (A1 notation), `TableCell.copy_from()`, `TableCell.clear()`
+
+These are convenience methods for agents and don't conflict with python-pptx API (python-pptx doesn't have them, so there's no behavioral difference).

{athena_python_pptx-0.1.51 → athena_python_pptx-0.1.56}/pptx/__init__.py

@@ -126,7 +126,7 @@ def flush_all() -> None:
     _active_buffers[:] = alive
 
 
-__version__ = "0.1.51"
+__version__ = "0.1.56"
 
 __all__ = [
     # Main entry point

athena_python_pptx-0.1.56/pptx/chart/data.py

@@ -0,0 +1,117 @@
+"""
+Chart data classes matching python-pptx.
+
+These classes capture series data client-side. The actual server-side
+materialization happens via:
+
+  * `Shape.chart.replace_data(chart_data)` for ingested charts — emits
+    `UpdateSeriesValue` / `UpdateCategoryLabel` patches against the existing
+    chart part.
+  * `slide.shapes.add_chart(chart_type, ..., chart_data)` for SDK-authored
+    charts — sends an `AddChart` command that the export-worker
+    materializes via `@pptx/chart-ooxml/export/author.ts`.
+"""
+
+from __future__ import annotations
+from typing import Any, Sequence
+
+from ..errors import UnsupportedFeatureError
+
+
+class CategoryChartData:
+    """
+    Chart data for category-based charts (column, bar, line, area, pie,
+    doughnut). Matches python-pptx's `CategoryChartData` API.
+    """
+
+    def __init__(self) -> None:
+        self._categories: list[str] = []
+        self._series: list[tuple[str, list[float | None]]] = []
+
+    @property
+    def categories(self) -> list[str]:
+        """Category labels (x-axis tick labels)."""
+        return self._categories
+
+    @categories.setter
+    def categories(self, value: Sequence[str]) -> None:
+        """Set category labels."""
+        self._categories = [str(v) for v in value]
+
+    def add_series(
+        self,
+        name: str,
+        values: Sequence[float | None],
+        number_format: str = "",
+    ) -> None:
+        """Add a data series.
+
+        `number_format` is accepted for python-pptx parity but is not
+        currently propagated to the chart spec — the embedded workbook's
+        format string controls display formatting.
+        """
+        self._series.append((name, [None if v is None else float(v) for v in values]))
+
+    def to_series_payload(self) -> list[dict[str, Any]]:
+        """Internal: convert to the wire shape used by AddChart / patches."""
+        return [{"name": name, "values": list(values)} for name, values in self._series]
+
+    def __len__(self) -> int:
+        return len(self._series)
+
+
+# Alias for compatibility with python-pptx (which exposes both names).
+ChartData = CategoryChartData
+
+
+class _XySeries:
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.points: list[tuple[float, float]] = []
+
+    def add_data_point(self, x: float, y: float) -> None:
+        self.points.append((float(x), float(y)))
+
+
+class XyChartData:
+    """Chart data for XY (scatter) charts. Captured client-side; authoring
+    these via the SDK is gated on the chart-ooxml authoring path adding
+    scatter support — currently raises `UnsupportedFeatureError` from
+    `add_chart()` for scatter types. The data structure itself is
+    populated for parity with python-pptx code."""
+
+    def __init__(self) -> None:
+        self._series: list[_XySeries] = []
+
+    def add_series(self, name: str, values: Any = None) -> _XySeries:
+        series = _XySeries(name)
+        if values is not None:
+            for point in values:
+                if isinstance(point, (tuple, list)) and len(point) == 2:
+                    series.add_data_point(point[0], point[1])
+        self._series.append(series)
+        return series
+
+
+class _BubbleSeries(_XySeries):
+    def __init__(self, name: str) -> None:
+        super().__init__(name)
+        self.sizes: list[float] = []
+
+    def add_data_point(self, x: float, y: float, size: float = 1.0) -> None:  # type: ignore[override]
+        super().add_data_point(x, y)
+        self.sizes.append(float(size))
+
+
+class BubbleChartData:
+    """Chart data for bubble charts. Same status as `XyChartData` — captured
+    client-side, but `add_chart()` for bubble type is unsupported until the
+    chart-ooxml authoring path covers bubble plots."""
+
+    def __init__(self) -> None:
+        self._series: list[_BubbleSeries] = []
+
+    def add_series(self, name: str, values: Any = None) -> _BubbleSeries:
+        series = _BubbleSeries(name)
+        self._series.append(series)
+        return series

{athena_python_pptx-0.1.51 → athena_python_pptx-0.1.56}/pptx/client.py

@@ -108,6 +108,9 @@ class Client:
         }
         if self.api_key:
             headers["Authorization"] = f"Bearer {self.api_key}"
+        custom_attr = os.environ.get("ATHENA_PPTX_CUSTOM_ATTRIBUTIONS")
+        if custom_attr:
+            headers["X-Custom-Attributions"] = custom_attr
         return headers
 
     def _handle_response(self, response: requests.Response) -> Any:
@@ -128,13 +131,17 @@ class Client:
                 # Extract message from top-level or nested error object
                 msg = data.get("message")
                 error_obj = data.get("error")
+                details = data.get("details")
                 if not msg and isinstance(error_obj, dict):
                     msg = error_obj.get("message")
-                    details = error_obj.get("details")
-                    if details:
-                        msg = f"{msg}: {details}"
+                    if not details:
+                        details = error_obj.get("details")
                 elif not msg and isinstance(error_obj, str):
                     msg = error_obj
+
+                detail_message = self._format_error_details(details)
+                if detail_message:
+                    msg = f"{msg or 'Request failed'}: {detail_message}"
                 raise RemoteError(
                     message=msg or f"API error: {response.status_code}",
                     status_code=response.status_code,
@@ -152,12 +159,49 @@ class Client:
 
         return response.json()
 
+    def _format_error_details(self, details: Any) -> Optional[str]:
+        """Convert structured API validation errors into actionable text."""
+        if not details:
+            return None
+
+        if isinstance(details, list):
+            rendered: list[str] = []
+            for item in details:
+                if not isinstance(item, dict):
+                    rendered.append(str(item))
+                    continue
+
+                path = ".".join(str(part) for part in item.get("path", []))
+                message = item.get("message") or "Invalid value"
+                received = item.get("received")
+
+                if path.endswith("shapeType") and isinstance(received, str):
+                    suggestion = self._suggest_shape_alias(received)
+                    if suggestion and suggestion != received:
+                        message = f"{message} (did you mean '{suggestion}'?)"
+
+                rendered.append(f"{path}: {message}" if path else message)
+
+            return "; ".join(rendered)
+
+        return str(details)
+
+    def _suggest_shape_alias(self, value: str) -> Optional[str]:
+        """Suggest the canonical backend shape name for common aliases."""
+        from .enum.shapes import mso_shape_to_string
+
+        try:
+            return mso_shape_to_string(value)
+        except Exception:
+            return None
+
     def _request(
         self,
         method: str,
         path: str,
         json: Optional[dict] = None,
         params: Optional[dict] = None,
+        timeout: Optional[float] = None,
     ) -> Any:
         """Make an HTTP request."""
         url = urljoin(self.base_url + "/", path.lstrip("/"))
@@ -175,7 +219,7 @@ class Client:
                 json=json,
                 params=params,
                 headers=headers,
-                timeout=self.timeout,
+                timeout=timeout if timeout is not None else self.timeout,
             )
             return self._handle_response(response)
         except requests.ConnectionError as e:
@@ -217,21 +261,70 @@ class Client:
         payload = {"name": name} if name else None
         return self._request("POST", "/decks", json=payload)
 
-    def create_empty_deck(self, name: Optional[str] = None) -> dict[str, Any]:
+    def create_empty_deck(
+        self,
+        name: Optional[str] = None,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        max_attempts: int = 240,
+    ) -> dict[str, Any]:
         """
-        Create a new empty deck that's immediately ready.
+        Create a new empty deck and wait until it is ready.
 
         Unlike create_deck(), this creates a deck without requiring an upload.
-        The deck is immediately usable with no slides.
+        The server provisions a blank PPTX template and runs it through the
+        ingest pipeline; this method blocks until ingest is finished.
+
+        The server may return either:
+          * 201 with status="ready" if ingest finishes within its synchronous
+            poll window, or
+          * 202 with status="processing" if ingest is still in progress.
+
+        In the 202 case we poll GET /decks/:id at ``poll_interval`` until the
+        status flips to "ready" (or "error", in which case we raise). The
+        initial POST uses an extended timeout so it doesn't race the server's
+        own poll loop.
 
         Args:
             name: Optional name for the deck
+            poll_interval: Seconds between status polls
+            max_attempts: Maximum number of poll attempts (default 240 ≈ 2 min)
 
         Returns:
-            Dictionary with id, name, status, slideCount, createdAt
+            Dictionary with id, name, status="ready", slideCount, createdAt
+
+        Raises:
+            UploadError: If ingest reports an error or never reaches "ready".
         """
         payload = {"name": name} if name else None
-        return self._request("POST", "/decks/empty", json=payload)
+        # Use an extended timeout so we don't race the server's synchronous
+        # poll window (the server may hold the request open for up to ~30s
+        # waiting for ingest to complete before returning 202).
+        result = self._request("POST", "/decks/empty", json=payload, timeout=120)
+
+        deck_id = result.get("id")
+        status = result.get("status")
+        if status == "ready":
+            return result
+        if not deck_id:
+            raise UploadError(
+                "Server did not return a deck id from POST /decks/empty",
+                None,
+            )
+
+        # Poll until ingest finishes.
+        for _ in range(max_attempts):
+            deck = self.get_deck(deck_id)
+            current_status = deck.get("status")
+            if current_status == "ready":
+                return deck
+            if current_status == "error":
+                raise UploadError("Empty deck ingest failed", deck_id)
+            time.sleep(poll_interval)
+
+        raise UploadError(
+            "Empty deck ingest timed out before reaching 'ready'",
+            deck_id,
+        )
 
     def delete_deck(self, deck_id: str) -> None:
         """Delete a deck."""
@@ -465,7 +558,9 @@ class Client:
                     type=placeholder_data.get("type", "obj"),
                     idx=placeholder_data.get("idx", 0),
                     sz=placeholder_data.get("sz"),
+                    orient=placeholder_data.get("orient"),
                     has_custom_prompt=placeholder_data.get("hasCustomPrompt"),
+                    local_transform_override=placeholder_data.get("localTransformOverride"),
                 )
 
             elements[elem_id] = ElementSnapshot(