athena-python-pptx 0.9.1__tar.gz → 0.13.0__tar.gz

{athena_python_pptx-0.9.1 → athena_python_pptx-0.13.0}/CHANGELOG.md

@@ -2,6 +2,208 @@
 
 All notable changes to `athena-python-pptx` are documented in this file.
 
+## Unreleased — `pptx.kit` composition kit
+
+- New Athena-only module `pptx.kit` (`from pptx.kit import Kit, Palette,
+  Fonts, Region`; also re-exported from `pptx`). `Kit(prs)` composes slides
+  from regions derived from the slide size: `header` (small-caps kicker,
+  action title auto-fit to a two-line band, footer rule + page number +
+  `kit.footer_text`), `footer`, `takeaway` (full-width bar one gap above the
+  footer band), `content_region`, `columns`, `grid`, `kpi_row` / `kpi_card`
+  (surface card, accent stripe, big auto-fit value, auto-fit label), `card`,
+  `text` and `bullets`.
+- Text asked to fit is sized to its box by the studio's `/measure-text-fit`
+  layouter (same client pattern as `TextFitter.best_fit_font_size`, result
+  floored and cached per kit, one failed probe latches the fallback) or, when
+  the studio is unreachable, by a conservative greedy wrap on the
+  `_estimate_text_width_emu` glyph table at 1.2 line height. It never grows
+  past the requested size; when nothing fits even at the minimum size the kit
+  uses the minimum and emits a `RuntimeWarning` naming the text; `fit=False`
+  keeps the size as given.
+- Regions are clamped to the slide and the footer band is reserved, so
+  nothing lands outside the slide or under the footer; a region with nothing
+  left raises instead of silently placing nothing. `content_region` keeps the
+  takeaway band free by default so a bar added after the body cannot hide it,
+  and the `y` / `h` overrides of `columns` / `grid` / `kpi_row` are clamped to
+  the content region. Per-slide state is keyed by the stable `slide.slide_id`.
+- Pure python-pptx public API underneath (`add_shape` / `add_textbox` /
+  `fill` / `line` / `text_frame` / `font`), emitted through the
+  presentation's command buffer — build each slide inside `with prs.batch():`
+  for one round-trip. Reaches agents with the next `athena-python-pptx` bump.
+  Documented in `docs/API_PARITY_EXCEPTIONS.md`; demo in
+  `examples/kit_demo.py`.
+
+## Unreleased — validate() finds overflow and hidden text, drops containment noise
+
+Reworks `Slide.validate()` around the defects that actually ship in agent
+decks (verified 2026-09-14 against two 8-slide agent builds: 167 and 127
+warnings, ~75% of them a background card behind its own label). Same
+signature; an empty list is once again reachable by a designed slide.
+
+- **Containment overlaps are no longer reported** unless both shapes carry
+  text (text on text is always reported). Partial overlaps are reported
+  only when at least one shape carries text; hairline overlaps thinner
+  than a text-frame inset (0.05in) and overlaps between two text-less
+  shapes are ignored. Tables count as text-bearing.
+- **New: text overflow for non-table shapes** — per-paragraph font-metric
+  estimate (`_estimate_text_width_emu`, run size → paragraph default →
+  shape default → 18pt; word wrap on → `ceil(width / inner_width)` lines,
+  off → horizontal check; `lines × font × 1.2 × line_spacing` + spacing vs
+  box height minus margins). Frames set to auto-fit are skipped. When the
+  presentation has a studio client each hit whose paragraphs share one
+  font size and weight is confirmed with one `MeasureTextFit` round-trip
+  pinned at that size (`fits: true` drops it; capped at 12 per call; every
+  network error falls back to the heuristic verdict); mixed-font frames keep
+  the heuristic verdict since the server measures at a single font.
+- **New: hidden text (occlusion)** — a text shape at least half covered by
+  a later (higher z-order) shape with a solid, non-transparent fill and no
+  text: `"text in 'X' is covered by 'Y'"`. Unknown fills (none, gradient,
+  pattern, pictures) count as not opaque; any transparency on the proxy or
+  a snapshot `fillTransparency` disables the rule for that shape.
+- Warnings are deduplicated, ordered overflow → occlusion → text-on-text →
+  other (off-slide, one-text partial overlaps, empty placeholders), capped
+  at 15 per slide with a trailing `"… and N more (M containment overlaps
+  ignored)"` line. Rotated shapes near 90°/270° use their swapped visual
+  bbox in the pairwise rules.
+- `bring_to_front()` / `send_to_back()` / `bring_forward()` /
+  `send_backward()` now mirror the move on the local `slide.shapes` order
+  (previously only the server saw it), so `validate()` reads the intended
+  stack without a refresh.
+- New module-level `pptx.validate_all_touched() -> dict[int, list[str]]`
+  (Athena extension) for the executor postamble: `CommandBuffer` records
+  the slide indexes / slide ids / shape ids of every command the server
+  applied (`CommandBuffer.take_touched()` returns and clears them);
+  `validate_all_touched()` resolves them to slides on every live
+  `Presentation`, validates only those, and returns the slides with
+  warnings. Recorded indexes are shifted for slide insertions, deletions
+  and reorders applied later in the run; destination-bearing commands
+  (`CloneShape`, `CopySlideFromDeck`, `ReplaceText`) record their
+  destination; `SetPresentationSize` and a deck-wide `ReplaceText` validate
+  every slide. Commands that cannot change a layout (notes, names,
+  citations, deck metadata) never mark a slide; never raises for
+  validation reasons.
+
+## 0.12.0 — snapshot hydration, ReplaceChartData emission, level dirty-flag, discard_all
+
+SDK halves of the issue #30178 Cluster D server work (#30204 / #30211 /
+#30212 / #30213).
+
+**⚠️ Server ordering:** `Chart.replace_data` now emits a single
+`ReplaceChartData` patch, which servers without #30211 reject (400) — the
+`presentation-exec` snapshot bump to 0.12.0 must wait for the pptx-studio
+deploy that ships the op.
+
+- `Shape.shadow` hydrates from the snapshot's `shadow` bag: a partial edit
+  like `shadow.blur_radius = Pt(6)` re-emits the ingested shadow's
+  `visible=True` / type / distance / direction / color / transparency
+  instead of the un-hydrated defaults (`visible=False` used to DELETE the
+  ingested shadow server-side). Hydrated shadows read back
+  `inherit == False`.
+- `Shape.click_action` hydrates from the snapshot's `clickAction` bag —
+  same deletion-bug class (`click_action.tooltip = ...` used to emit
+  `action_type='none'` and delete the ingested link).
+- `Presentation.core_properties` hydrates from the snapshot's
+  `coreProperties` (server #30204): setting one property no longer wipes
+  the deck's other metadata to `None`. `refresh()` re-hydrates.
+- `Chart.replace_data` emits ONE `ReplaceChartData` patch carrying the
+  full categories + series matrix (python-pptx semantics: shrink drops
+  trailing points, grow adds them, extra series are removed) instead of
+  per-index `UpdateSeries*` / `UpdateCategoryLabel` patches that couldn't
+  change the data's shape. The local `chartSpec` mirror still updates,
+  preserving server series ids by index. A zero-series `chart_data`
+  raises `ValidationError` before touching the local mirror (the op
+  requires at least one series; silently returning would desync local
+  reads from the server).
+- `run.hyperlink.target_slide = n` no longer rides with `address=''` (the
+  clear convention) — exactly one of address / targetSlideIndex is sent,
+  aligning with server #30212. The SetText re-emit carries
+  `hyperlinkTargetSlideIndex`, and snapshot rich content hydrates it back.
+  `SetRunHyperlinkTarget.validate()` rejects setting both.
+- `paragraph.level` is sent only when the paragraph is indented or the
+  caller explicitly assigned it (explicit `level = 0` still reaches the
+  wire); an untouched level-0 paragraph omits the field so unrelated style
+  edits don't stomp the server-side outline level (belt-and-suspenders
+  with the server-side lvl=0 canonicalization in #30213).
+- New module-level `pptx.discard_all()` (mirrors athena-python-docx):
+  drops all buffered, un-flushed commands across open decks without
+  posting and returns the dropped count. The agora executor postamble
+  calls it when user code raised, so failed scripts discard their
+  half-buffered tail instead of posting it.
+
+## 0.11.0 — silent no-op & data-loss fixes (deep-dive remediation)
+
+Eliminates a cluster of silent no-ops, read-after-write desyncs, and
+buffer-poisoning bugs found in the 2026-08 presentation-asset deep dive.
+All fixes preserve python-pptx API parity (behavior, not surface, changes).
+
+- `paragraph.level = 0` now reaches the wire (was dropped by the None-drop),
+  so resetting an indented paragraph works.
+- `font.subscript = False` / `font.superscript = False` now send `baseline: 0`
+  (the server's clear signal) instead of omitting the field, so they actually
+  un-sub/superscript existing text.
+- A bare `shape.fill.solid()` now emits, matching `gradient()`/`patterned()`.
+- Chart `has_legend` / `has_title` / `chart_title` now update the local
+  snapshot on write, so reads after a write return the new value.
+- `rows.insert()` / `columns.insert()` now shift the cached row-height /
+  column-width lists, fixing corrupted height/width reads after an insert.
+- `GroupShape.shapes` now resolves child shapes via `childIds` (was hardcoded
+  to `[]`).
+- `PicturePlaceholder.insert_picture` converts WebP/SVG/AVIF to PNG (was
+  mislabeling them `png`) and honors its `width`/`height` params.
+- `batch()` discards the buffer when its body raises (was committing the
+  partial prefix).
+- A server-rejected command in a batch is dropped (not re-queued), ending the
+  permanent buffer-poison loop; the rest of the rolled-back chunk is restored.
+- Command chunks carry a stable `txn.id` across retries so an ambiguous-timeout
+  resend dedups server-side instead of double-applying.
+- `flush_all(strict=True)` raises `FlushAllError` on a per-buffer flush failure
+  (the sandbox executor opts in) instead of silently swallowing it.
+- `Presentation` no longer pins its buffer/client/session via the atexit hook
+  (weakref closure); `close()`/`__del__` release the HTTP session.
+- Export 404s fail fast for a deck this client already read (deleted deck),
+  instead of burning the ~85s post-upload retry budget.
+- `XyChartData` / `BubbleChartData` `add_series` raise on malformed inline
+  points instead of silently dropping them.
+- `mso_shape_to_string` raises on an unmapped autoshape id instead of silently
+  authoring a rectangle.
+- `AddMovie` emits `posterBase64` (the key the server reads) and always sends a
+  poster (a 1x1 placeholder when none is supplied), so `add_movie`/`add_video`
+  no longer fail the whole batch.
+
+## 0.10.1 — unnamed-shape parity, browser UA on image fetches, honest SVG errors
+
+Fixes the three `execute_presentation_code` failures observed in the
+2026-08-12 production deck-build session (thread_d7eb9dd6).
+
+- `Shape.name` now always returns a `str` (python-pptx parity —
+  `cNvPr@name` is a schema-required attribute upstream). Elements
+  persisted before names were stored (e.g. pictures added by pre-0.10
+  SDKs) read back as `""` instead of `None`, so idioms like
+  `'Picture' in shape.name` no longer raise `TypeError`.
+- `add_picture(url)` fetches now send browser-equivalent
+  `User-Agent`/`Accept` headers. Image hosts and proxies behind bot
+  rules (e.g. `wsrv.nl`, Cloudflare-fronted CDNs) 403 the default
+  `python-requests/x.y` UA while serving the identical URL to a browser
+  UA. The Accept header advertises only formats the deck pipeline
+  handles (PNG/JPEG native, WebP via Pillow) so format-negotiating CDNs
+  don't switch the body to AVIF or SVG.
+- AVIF is now detected explicitly (any `avif`/`avis` brand in the
+  ISO-BMFF `ftyp` box — major or compatible, so `mif1`-major HEIF
+  containers are covered) instead of falling through the sniffer as
+  `png` — it converts via Pillow where the build supports AVIF, and
+  otherwise raises the actionable convert-or-fail error rather than
+  shipping undecodable bytes that render as a silent broken-image
+  placeholder.
+- `Shapes.by_name("")` / `get_by_name("")` no longer match unnamed
+  legacy shapes — `""` is the no-name sentinel, not an addressable
+  name.
+- The SVG `add_picture` error no longer recommends `pip install svglib`
+  (rasterization also needs the `rlPyCairo` backend and the native cairo
+  library, so that advice cannot work in a stock sandbox). WebP and SVG
+  now get separate, accurate remediation hints. Pairs with the
+  presentation-exec v59 snapshot, which bundles `svglib` + `rlPyCairo`
+  so SVG→PNG conversion works in-sandbox.
+
 ## 0.9.0 — eager validation, table overflow diagnostics, and text caps
 
 Publishes the SDK changes already deployed with PPTX Studio after 0.8.1.

athena_python_pptx-0.13.0/CLAUDE.md

@@ -0,0 +1,5 @@
+@AGENTS.md
+
+<!-- AGENTS.md next to this file is the single source of truth for agent
+     instructions. Claude Code does not read AGENTS.md natively, so this file
+     imports it. Add Claude-Code-only rules below this line. -->

{athena_python_pptx-0.9.1 → athena_python_pptx-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: athena-python-pptx
-Version: 0.9.1
+Version: 0.13.0
 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
@@ -31,7 +31,6 @@ Requires-Dist: responses>=0.23; extra == 'dev'
 Requires-Dist: ruff>=0.1; extra == 'dev'
 Provides-Extra: e2e
 Requires-Dist: pytest>=7.0; extra == 'e2e'
-Requires-Dist: python-pptx>=0.6.21; extra == 'e2e'
 Provides-Extra: visual
 Requires-Dist: numpy>=1.24; extra == 'visual'
 Requires-Dist: pillow>=10.0; extra == 'visual'

{athena_python_pptx-0.9.1 → athena_python_pptx-0.13.0}/docs/API_PARITY_EXCEPTIONS.md

@@ -158,6 +158,119 @@ very large inline image) cannot be split — it is sent alone and may still
 be rejected with a teaching `IMAGE_TOO_LARGE` error, but it no longer
 takes the rest of the queued edits down with it.
 
+### `Chart.replace_data()` emits one `ReplaceChartData` op (v0.12.0 — requires a server with ReplaceChartData support)
+
+python-pptx's `chart.replace_data(chart_data)` rewrites the chart's whole
+data matrix. Before v0.12.0 the SDK approximated that with per-index
+`UpdateSeries*` / `UpdateCategoryLabel` patches, which could neither shrink
+nor grow the data (stale trailing `c:pt` entries and orphaned series
+corrupted the chart part). As of v0.12.0 each `replace_data` call emits
+exactly **one** `ReplaceChartData` patch carrying the full
+`categories` + `series` matrix, so shrinking drops trailing points, growing
+adds them, and extra series are removed — matching python-pptx semantics.
+
+**Deployment note:** a pptx-studio server without the `ReplaceChartData`
+patch op (pre-#30211) rejects the whole command batch with a Zod validation
+error. SDK 0.12.0 must only be rolled into sandbox snapshots after the
+studio deploy that ships the op.
+
+### `pptx.flush_all()` / `pptx.discard_all()` — module-level buffer drains (Athena-only)
+
+The sandbox executor postamble ends every `execute_presentation_code` run
+with one of these:
+
+- `flush_all(strict=False)` — flush every live presentation's buffered
+  commands. `strict=True` (used by the executor) raises `FlushAllError`
+  when any buffer's flush is rejected instead of silently swallowing it.
+- `discard_all()` (v0.12.0) — drop all buffered, un-flushed commands
+  across open decks **without posting them** and return the dropped count.
+  Called when user code raised: posting a dead script's half-buffered tail
+  would write content whose prerequisites failed (and duplicate it when
+  the agent retries the whole script). Best-effort — a batch already
+  handed to an in-flight background flush cannot be recalled.
+
+```python
+import pptx
+dropped = pptx.discard_all()   # -> int, 0 when nothing was buffered
+```
+
+Stock python-pptx has no equivalent; local scripts normally never need
+either function (buffers auto-flush on idle and at interpreter exit).
+
+### `pptx.validate_all_touched() -> dict[int, list[str]]` — validate the slides a run edited (Athena-only)
+
+The third executor hook, called after `flush_all(strict=True)`. Every
+`CommandBuffer` remembers the slide indexes, slide ids (including the
+`sld_…` client ids of slides added in the run) and shape ids of the commands
+the server **applied** since the last call (`CommandBuffer.take_touched()`);
+`validate_all_touched()` resolves them against each live `Presentation`'s
+slide proxies, runs [`slide.validate()`](#slidevalidate---liststr) on exactly
+those slides, and returns `{slide_index: warnings}` for the slides that had
+warnings — `{}` means every touched slide is clean.
+
+- Only flushed commands count — buffered edits are not yet "touched".
+- The touched set is consumed by the call; a second call with no flush in
+  between returns `{}`.
+- Commands that cannot change a layout (notes, names, citations, deck
+  metadata) never mark a slide. `DeleteSlide` and `ReorderSlides` mark
+  nothing but shift the indexes recorded before them, as do slide
+  insertions (`AddSlide`, `CloneSlide`, `CopySlideFromDeck`), so an index
+  recorded early in a batch still names the same slide at the end.
+- Destination-bearing commands record their destination: `CloneShape`
+  marks `target_slide_index` (the source shape only when cloning in place),
+  `CopySlideFromDeck` its `destination_index`, `UngroupShapes` the group
+  shape's slide, `ReplaceText` its shape or slide. `SetPresentationSize`
+  and a deck-wide `ReplaceText` set `all_slides` and validate every slide.
+- Never raises for validation reasons: a slide whose `validate()` fails
+  contributes a single `"validate() failed: …"` line.
+
+```python
+import pptx
+pptx.flush_all(strict=True)
+for index, warnings in pptx.validate_all_touched().items():
+    print(f"slide {index + 1}:", *warnings, sep="\n  ")
+```
+
+Stock python-pptx has no equivalent.
+
+### Snapshot-hydrated full-state setters (v0.12.0)
+
+`Shape.shadow`, `Shape.click_action`, and `Presentation.core_properties`
+re-emit their **full** state on every partial write (their wire commands
+have no partial form). As of v0.12.0 they hydrate that state from the
+snapshot at construction, so a partial edit preserves what was ingested:
+
+- `shape.shadow.blur_radius = Pt(6)` keeps the ingested shadow's
+  `visible=True` / type / distance / direction / color / transparency
+  (previously it emitted the un-hydrated `visible=False` default, deleting
+  the shadow server-side). A hydrated shadow also reads back
+  `shadow.inherit == False`.
+- `shape.click_action.tooltip = "..."` keeps the ingested link's action
+  type / URL / slide target (previously it emitted `action_type='none'`,
+  deleting the link).
+- `prs.core_properties.author = "..."` keeps the deck's existing title /
+  subject / keywords / comments / category (previously they were wiped to
+  `None`). `Presentation.refresh()` re-hydrates from the fresh snapshot.
+
+### `paragraph.level` rides the wire only when meaningful (v0.12.0)
+
+`SetParagraphStyle` re-emits the paragraph's full style on every setter.
+`level` is now included only when the paragraph is indented (`level > 0`)
+or the caller explicitly assigned `paragraph.level` (including an explicit
+reset to `0`, which must reach the wire). An untouched level-0 paragraph
+omits the field so unrelated style edits (alignment, spacing, …) don't
+stomp the server-side outline level.
+
+### Run-level slide jumps send exactly one of address / targetSlideIndex (v0.12.0)
+
+`run.hyperlink.target_slide = n` emits `SetRunHyperlinkTarget` with
+`targetSlideIndex` only — it no longer rides with `address=''` (the
+clear-the-link convention), which servers interpret as "clear". An
+explicit `run.hyperlink.address = None` with no slide target still sends
+`address=''` to clear. The rich-content re-emit carries the jump as
+`hyperlinkTargetSlideIndex` on the run, and snapshot rich content with
+that key hydrates back into `run.hyperlink`.
+
 ---
 
 ## Agent-Friendly Additions (not in python-pptx)
@@ -288,12 +401,18 @@ the iterate-and-rebuild pattern in the v0.1.77 retrospective. None of them
 exist in upstream python-pptx — they're Athena additions and code that uses
 them is *not* portable to stock python-pptx.
 
-### `slide.clear_shapes() -> int`
+### `slide.clear_shapes(*, delete_unmodeled_source_content=False) -> int`
 
-Delete every slide-local shape in one batched `post_commands` call. Returns
-the number of shapes queued for deletion. Targets only slide-local shapes
-(what `slide.shapes` iterates); inherited layout / master placeholders are
-left alone.
+Delete every slide-local shape with one slide-scoped command. Returns the
+number of modeled shapes removed. Unmodeled visual OOXML from the imported
+slide is preserved by default, because Athena not rendering an object is not
+authorization to delete it. Inherited layout / master placeholders and
+slide-level background/notes are left alone.
+
+Pass `delete_unmodeled_source_content=True` only after the user explicitly
+authorizes replacing the complete imported visual layer. That option can
+delete text boxes, SmartArt, controls, and other PowerPoint content that is
+not visible in Athena.
 
 **Why we added it:** the previous workaround was a manual
 `for shape in slide.shapes: shape.delete()` loop. Combined with the silent
@@ -308,12 +427,47 @@ slide.shapes.add_textbox(Inches(1), Inches(1), Inches(8), Inches(2))
 
 ### `slide.validate() -> list[str]`
 
-Report layout issues without rendering. Returns warnings for:
-
-* Off-slide shapes (bbox extends outside the slide rectangle).
-* Overlapping slide-local shapes (>0.01% of slide area overlap).
-
-Does **not** detect text overflow — for that, render the slide to PNG.
+Report the layout defects a reader would notice, without rendering. An
+empty list means the slide is clean — and a designed slide (cards behind
+their labels, icons inside tiles) reaches it. Warnings come back in this
+order, at most 15 per slide, then a count line
+`"… and N more (M containment overlaps ignored)"`:
+
+1. **Text overflow** — `"text in 'X' likely overflows its box (needs ~N
+   lines of ~M at Spt; …)"` for non-table text whose estimated height
+   (per-paragraph font-metric width → wrapped lines → lines × font × 1.2 +
+   spacing) exceeds the box minus its text-frame margins. Word-wrap-off
+   frames are checked horizontally; auto-fit frames are skipped. When the
+   presentation has a studio client, each hit whose paragraphs share one
+   font size and weight is confirmed with one `POST /measure-text-fit`
+   pinned at that size (`fits: true` drops the warning, at most 12
+   round-trips per call, network errors keep the heuristic verdict); a
+   mixed-font frame (60pt heading over 12pt body) keeps the heuristic
+   verdict because the server lays the frame out at a single font. Table
+   cells whose single-line text is wider than the column are reported here
+   too.
+2. **Hidden text** — `"text in 'X' is covered by 'Y'"`: a text shape at
+   least half covered by a *later* (higher z-order) shape with a solid fill,
+   no transparency and no text. A solid fill the snapshot reports without
+   transparency data is taken as opaque (PowerPoint's default); any
+   transparency set on the proxy or carried as `fillTransparency` disables
+   the rule for that shape. `send_to_back()` / `bring_to_front()` now mirror
+   the move on `slide.shapes` order so the rule sees the intended stack
+   without a refresh.
+3. **Text on text** — two text-bearing shapes (tables count) whose bboxes
+   overlap or nest.
+4. **Other** — off-slide shapes; partial overlaps where exactly one shape
+   carries text (a title running under a card); empty slide-level
+   placeholders.
+
+Not reported: one shape fully inside another unless both carry text,
+overlaps between two text-less shapes, and hairline overlaps thinner than
+a text-frame inset (0.05in). Rotated shapes near 90°/270° use their swapped
+visual bbox.
+
+The overflow estimate uses average glyph widths, so offline it can be off
+by a line either way; render the slide before rebuilding a layout around a
+single warning.
 
 ```python
 warnings = slide.validate()
@@ -390,6 +544,15 @@ upstream auto-assigns names like `"Rectangle 47"` and only exposes
 construction. **Portable code that needs to run against stock python-pptx
 should omit `name=` and assign after the fact.**
 
+When `name=` is omitted, Athena's generated name skips any identical name in
+the slide's current SDK snapshot. This matters after clone/delete workflows
+where the simple shape-count candidate can already exist. The selected name is
+also available immediately on the returned proxy, before a snapshot refresh.
+This is snapshot-local rather than a distributed uniqueness guarantee: a
+concurrent collaborator can add the same name after the snapshot was loaded.
+Keep the returned proxy or `shape_id` for cross-client-safe follow-up edits;
+use names as human-readable selectors after refreshing the deck.
+
 ```python
 card = slide.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE,
                               Inches(1), Inches(1), Inches(4), Inches(2),
@@ -1049,6 +1212,14 @@ work in addition to SDK surface and are tracked separately.
 
 ### Shape-level additions
 
+- **`Shape.z_order = "to_back" | "to_front" | "backward" | "forward"`**
+  is a write-only convenience alias for `send_to_back()`,
+  `bring_to_front()`, `send_backward()`, and `bring_forward()`. Assignment
+  emits the same `SetShapeZOrder` command as the method form; unsupported
+  strings raise `ValueError` instead of creating a misleading local
+  attribute. Reading `shape.z_order` raises `AttributeError` because deck
+  snapshots do not expose a stable numeric z-order value.
+
 - **`Shape.duplicate(target_slide=None, offset_x=None, offset_y=None)`**
   (closes python-pptx#533, #620, 10-comment thread requesting a public
   duplicate API). Alias for the existing `Shape.clone()` — both verbs
@@ -1503,3 +1674,75 @@ prior in-module definitions. `AssetReference` remains a thin in-module wrapper
 that additionally accepts a plain `dict` `meta` (the historical SDK shape) and
 serializes it verbatim, preserving byte-identical `to_dict()` output for
 existing callers.
+
+---
+
+## `pptx.kit` — composition kit (Athena-only, unreleased)
+
+`from pptx.kit import Kit, Palette, Fonts, Region` (also re-exported from the
+`pptx` package). No upstream counterpart — python-pptx has no layout layer.
+The module carries the module-level `__athena_extension_module__` marker and
+each of the four classes is decorated `@athena_extension`, so the whole
+surface walks through `iter_athena_extensions`.
+
+**Why.** Two agent-built 8-slide decks (2026-09-14) each hand-placed 200+
+shapes with EMU arithmetic and both agents wrote the same six helpers
+(`rect`, `text`, `header`, `kpi`, `card`, `takeaway`) from scratch. Every
+visual defect was placement maths: text wrapping in a too-narrow box, a title
+under the KPI cards, body text hidden under a takeaway bar added later. The
+model should compose, not compute EMUs.
+
+**Surface.**
+
+| Member | Purpose |
+|--------|---------|
+| `Kit(prs, palette=None, fonts=None)` | Reads slide size, layouts and the command buffer from `prs`. `kit.footer_text` is the footer text `header()` places on every slide; `kit.reserve_takeaway` (default `True`) keeps the takeaway band free in `content_region()` before a bar exists. |
+| `Palette(...)` | `RRGGBB` hex fields (`#` / lowercase normalised). Athena defaults: primary `0B1F3A`, accent `00A6A6`, highlight `F2A900`, ink `1F2937`, muted `6B7280`, surface `F4F6FA`, line `D9DEE7`, on_dark `FFFFFF`. Any `color=` / `accent=` argument may name a field (`"accent"`) or pass hex / `RGBColor`. |
+| `Fonts(heading=None, body=None, …)` | Family names (`None` inherits the deck theme) plus the point-size scale each helper starts from (`title_pt=30`, `title_min_pt=18`, `kicker_pt=11`, `body_pt=14`, `small_pt=11`, `kpi_value_pt=36`, `card_title_pt=14`, `card_body_pt=12`, `takeaway_pt=14`, `footer_pt=9`, `min_pt=8`). Auto-fit only ever shrinks. |
+| `Region(x, y, w, h)` | Frozen EMU rectangle (accepts `Length`); `.right`, `.bottom`, `.inset(dx, dy=None)`, `.split_h(n_or_weights, gap=None)`, `.split_v(...)`, `.contains`, `.overlaps`, `.intersect`. |
+| `kit.new_slide(layout_name="Blank") -> Slide` | `slide_layouts.by_name(...)`, falling back to the first layout without body placeholders, then the first layout. |
+| `kit.header(slide, title, kicker=None, page=None) -> Region` | Small-caps accent kicker, action title auto-fit to a two-line band, footer rule + `footer_text` + page number. Returns the title band. |
+| `kit.footer(slide, text, page=None) -> Region` | Rule, `text` (left) and `page` (right) inside the reserved footer band; idempotent per slide. |
+| `kit.takeaway(slide, text) -> Region` | Full-width primary bar with an accent stripe, one gap above the footer band; text auto-fit, `on_dark`. |
+| `kit.content_region(slide, *, takeaway=None) -> Region` | Between the title band (if a header was placed) and the takeaway band / footer band. |
+| `kit.columns(slide, n, y=None, h=None, gap=None)` / `kit.grid(slide, rows, cols, y=None, h=None, gap=None)` | Partition the content region; `n` / `rows` / `cols` may be weights. |
+| `kit.kpi_row(slide, items, y=None, h=None, accents=None)` / `kit.kpi_card(slide, region, value, label, accent=None)` | Surface cards with an accent stripe, a big auto-fit value and an auto-fit label; `kpi_row` returns the card regions. |
+| `kit.card(slide, region, title=None, body=None, accent=None)` | Card with a bold title and a body (a string = paragraphs, a list = bullets). |
+| `kit.text(slide, region, text_or_paragraphs, size=None, bold=False, color=None, align=None, anchor=None, fit=True)` / `kit.bullets(slide, region, items, size=None, fit=True)` | A text box filling the region; returns the shape. Bullet items may be `(text, level)` tuples. |
+| `kit.fit_size(paragraphs, region, max_size, *, min_size=None, bold=False, family=None)` | The fitting size the helpers use, exposed for custom boxes. |
+
+**Rules the kit enforces.**
+
+- Every position derives from `prs.slide_width` / `prs.slide_height`: margin
+  5% of the width, gutter 1.5%, top margin 6% of the height, title band 15%,
+  footer band 6%, takeaway bar 10%, KPI row 20%.
+- Regions are clamped to the slide and to the canvas above the footer band;
+  a region with nothing left raises `ValueError` rather than placing nothing.
+  The `y` / `h` overrides of `columns`, `grid` and `kpi_row` only ever narrow
+  the content region — they are clamped to it, so they cannot reach the title
+  band or the reserved takeaway band. Header, takeaway and footer bands never
+  overlap each other; footer text always leaves the page-number column free.
+- With `fit=True` the largest size ≤ the requested size that fits is used.
+  When the presentation's client has a base URL the kit POSTs a
+  `MeasureTextFit` query to `/measure-text-fit` (the same client pattern as
+  `TextFitter.best_fit_font_size`; result floored, cached per kit; one failed
+  probe latches the fallback for the kit's lifetime). Offline it greedy-wraps
+  on the `_estimate_text_width_emu` glyph table at 1.2 line height. When
+  nothing fits even at the minimum size (the server's `fits: false`, or the
+  estimate) the kit uses the minimum and emits a `RuntimeWarning` naming the
+  text, so the author can shorten it or enlarge the region. Fitted boxes also
+  get `auto_size = TEXT_TO_FIT_SHAPE` as a render-time safety net;
+  `fit=False` keeps the requested size and touches no auto-size.
+- Pure python-pptx public API underneath — `add_shape(MSO_SHAPE.RECTANGLE, …)`,
+  `add_textbox`, `fill.solid()` / `fore_color.rgb`, `line.fill.background()`,
+  `text_frame`, `font` — so the deck is an ordinary deck and every command
+  rides the presentation's `CommandBuffer`; build each slide inside
+  `with prs.batch():` for one round-trip.
+
+Per-slide state (header bottom, takeaway top, footer parts) is keyed by
+`slide.slide_id` — the SDK's stable slide identity, so it survives reorders,
+inserts and deletes — for the life of the `Kit`. Compose a slide through one
+`Slide` proxy (normally inside one `with prs.batch():`); a batch-created slide
+re-fetched after a refresh carries its server id and starts with fresh state.
+Reaches agents with the next `athena-python-pptx` bump. Demo:
+`examples/kit_demo.py`; tests: `tests/test_kit.py`.