Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs(roundtrip): define the source-proxy authoring contract

hugohe3df0c3c23276d
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 19992cf0..7f1bd455 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -808,6 +808,17 @@ These direct routes share some analysis primitives with the main pipeline, but a
**Why PPTX round-trip uses a semantic workspace rather than a ZIP-shaped tree.** The editable page source is `authoring-svg-flat/`; PowerPoint image media, imported reusable vectors, cues, audio, video, notes, and opaque payloads live under `images/`, `icons/imported/`, `sounds/`, `audio/`, `video/`, `notes/`, and `native-payloads/`. The exact backing package stays at `sources/source.pptx`, structural and ownership contracts stay under `analysis/`, diagnostics stay under `validation/`, and published decks stay under `exports/`. This keeps authoring paths aligned with normal projects while `analysis/roundtrip_manifest.json` maps semantic files back to package ownership. Import and export use this one contract: root `source_template.pptx`, `native_structure.json`, `conversion-report.json`, and `assets/` are invalid rather than compatibility inputs.
+Large imported tables and complex groups are source-backed atoms rather than
+thousands of model-facing SVG nodes. Their exact browser previews are hashed
+under `images/source-object-previews/`, and `authoring-svg-flat/` keeps one
+compact `native-restore` image proxy plus the outer source reference. An
+unchanged proxy rehydrates the complete native OOXML object, including a native
+PowerPoint table; deleting a Slide-local proxy deletes that object. Inherited
+Master/Layout proxies must remain because one flat page cannot delete shared
+structure. Editing either the proxy or its preview fails closed because
+silently compiling it as a picture or SVG-derived shapes would violate
+round-trip intent.
+
**Why there is only one PPTX compiler route.** Native export reads authored SVGs and translates supported SVG elements into DrawingML shapes. The normal deck path reads `svg_output/`; when requested, create-template invokes the same structured compiler on validated template prototypes to produce `exports/<id>_template_preview.pptx` as review evidence. The project does not package whole-slide SVG media or alternate raster renderings into a second PPTX. `svg_final/` is still generated on every standard deck run, but it is only a derived visual-preview / SVG-picture artifact rather than a PPTX source; PowerPoint's manual Convert to Shape command remains outside the supported contract.
**Why structure is authored before visual generation on structured reuse routes.** Master and Layout are not post-processing discoveries. With `template_reuse_scope: mirror|layout`, the Strategist writes unique Master/Layout definitions and complete page assignments before SVG generation; the Executor writes those identities, fixed atoms, and slots while composing each page, and export only compiles declared structure. `template_reuse_scope: style`, free-design, and brand-only decks make the opposite trade: they stay on `mode: flat`, keep every object Slide-local, author no structure metadata, and receive only a clean project-owned Master/Blank-Layout shell at export. Legacy inputs may inform a new `create-template` workspace, but they never enter an in-place structure-upgrade route; neither generation mode triggers heuristic Master/Layout promotion or placeholder inference.
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 6566f38b..14033306 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -689,6 +689,10 @@ SVG 与 DrawingML 的表达模型并不等价,因此主编译路径不把“
**为什么导入型与生成型 metadata 分层。** 导入 PPTX 时,完整 SVG 可以携带高级形状所需的 metadata、隐藏 carrier 和预览指纹,因此作为原生载荷后备留在临时分析工作区且保持不可变。`svg_authoring_view.py` 生成模板创建所用的可编辑 IR:轻量 SVG 通过文档内 source ref 标识对象,`authoring_manifest.json` 只记录路径与初始 hash,不重复保存原始载荷。`standard` / `fidelity` 创作项目规范化 SVG,只有精确匹配已登记 preset 时才使用 compact authored-preset 组。Mirror 从 IR 物化通过校验的模板,只为未改且 hash 匹配的 Slide-local/slot ref 重新接入转换器已支持的 metadata;固定结构层保持直接原子,不支持或已修改的对象保留当前 SVG fallback,IR 专用 ref 不进入最终模板 SVG。
+**为什么 PPTX 往返使用语义工作区,而不是照搬 ZIP 目录。** 可编辑页面源是 `authoring-svg-flat/`;PowerPoint 图片媒体、导入的可复用矢量、提示音、音频、视频、备注和不透明载荷分别位于 `images/`、`icons/imported/`、`sounds/`、`audio/`、`video/`、`notes/` 和 `native-payloads/`。精确来源包保存在 `sources/source.pptx`,结构与归属契约保存在 `analysis/`,诊断保存在 `validation/`,发布文件保存在 `exports/`。这样既让作者路径与普通项目一致,又由 `analysis/roundtrip_manifest.json` 把语义文件映射回 package 归属。导入与导出只接受这一份契约;根目录下的 `source_template.pptx`、`native_structure.json`、`conversion-report.json` 与 `assets/` 都不是兼容输入。
+
+大型导入表格和复杂组合被视为来源支撑的原子对象,而不是在模型可见 SVG 中展开成数千个节点。它们的精确浏览器预览以 hash 命名存放在 `images/source-object-previews/`,`authoring-svg-flat/` 只保留一个紧凑的 `native-restore` 图片代理和外层 source ref。未修改的代理会恢复完整原生 OOXML 对象,包括 PowerPoint 原生表格;删除 Slide-local 代理会删除该对象。继承自 Master/Layout 的代理必须保留,因为单个 flat 页面不能删除共享结构。修改代理或预览会直接阻止导出,因为静默编译为图片或 SVG 派生形状会违背往返意图。
+
**为什么只有一条 PPTX 编译路线。** Native 导出把作者 SVG 中受支持的元素逐个翻译成 DrawingML 形状。常规 deck 路线读取 `svg_output/`;用户需要时,create-template 对通过校验的模板原型调用同一 structured 编译器,生成 `exports/<id>_template_preview.pptx` 作为审阅证据。项目不会把整页 SVG 媒体或另一套位图渲染打包成第二类 PPTX。`svg_final/` 仍由常规 deck 的强制后处理生成,但只承担派生视觉预览和 SVG 图片插入,不为 PowerPoint 手工“转换为形状”提供兼容兜底。
**为什么结构化复用路线必须在视觉生成前确定结构。** Master 和 Layout 不是后处理阶段才发现的结果。使用 `template_reuse_scope: mirror|layout` 时,Strategist 在 SVG 生成前写出唯一 Master/Layout 定义和完整页面分配;Executor 在构图时同步写入这些身份、固定原子元素和槽位,导出器只编译声明。`template_reuse_scope: style`、自由设计与 brand-only deck 做的是相反的取舍:保持 `mode: flat`,所有对象留在 Slide 本地,不写任何结构 metadata,导出时只获得一个属于本项目的干净 Master/Blank-Layout 壳。旧输入可以为新的 `create-template` 工作区提供参考,但不存在原地升级结构的路线;两种生成模式都不会触发启发式 Master/Layout 提升或 placeholder 推断。
diff --git a/skills/ppt-master/references/shared-standards-core.md b/skills/ppt-master/references/shared-standards-core.md
index 5637c1fb..cf7df553 100644
--- a/skills/ppt-master/references/shared-standards-core.md
+++ b/skills/ppt-master/references/shared-standards-core.md
@@ -335,6 +335,16 @@ machine manifest. Moving a referenced subtree into
the vector inventory; re-inlining re-establishes the same mapping. Final materialized
template SVGs and normal project `svg_output/` must not contain this attribute.
+A round-trip flat bundle may represent one large imported logical object as an
+atomic `<image data-pptx-source-proxy="native-restore">` whose hashed SVG preview
+lives under `images/source-object-previews/`. The page keeps only the outer
+source ref; descendant source identity remains in immutable backing. An
+unchanged proxy restores the complete native object. Complete removal deletes a
+Slide-local object; an inherited Master/Layout proxy must remain because one
+flat page cannot delete shared structure. Any proxy or preview edit must fail
+export rather than downgrade the object. This compaction is round-trip-only and
+does not apply to layered create-template authoring IR.
+
**Hard rule — structural-layer boundary**: An unchanged imported logical object
may keep currently supported metadata while it remains Slide-local or inside a
slot. An imported logical `<g>` cannot be assigned to Master/Layout because
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index cfca9c5f..fdbb7c0e 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -140,7 +140,13 @@ Relative local image references are rewritten so the projected copy still
renders from its new location. The bundle's `authoring_summary.json` is the
model-readable current-file index; `authoring_manifest.json` records
source/authoring hashes and object paths for tools without duplicating opaque
-payload and does not enter model context. Imported model-facing frames and safe
+payload and does not enter model context. Round-trip flat bundles also replace
+large source-backed objects with compact `native-restore` image proxies whose
+hashed SVG previews live under `images/source-object-previews/`. Unchanged
+proxies restore the original native PowerPoint objects; complete removal deletes
+a Slide-local source object, while inherited-proxy removal and any proxy or
+preview edit fail export. Imported
+model-facing frames and safe
transform page coordinates use at most two decimals; immutable lossless SVGs
retain the original precision. In-place vector/picture extraction
refreshes the summary automatically; use `--refresh-summary` after other direct
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 5fefa726..8b3a837d 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -46,11 +46,24 @@ The projected copy:
- compacts imported model-facing frames and safe transform page coordinates to
at most two decimals.
+Round-trip flat projection additionally replaces any large source-backed
+logical object with one compact
+`<image data-pptx-source-proxy="native-restore">`. Its hashed SVG preview is
+stored under `images/source-object-previews/`, while the complete imported SVG
+and source PPTX remain the semantic authority. This keeps tables and complex
+group geometry out of model-facing page files without changing their browser
+rendering. A source proxy is atomic: leave it unchanged to restore the original
+native PowerPoint object. A complete Slide-local proxy may be removed to delete
+that object; an inherited Master/Layout proxy must remain because one flat page
+cannot delete shared structure. Editing the proxy or its preview asset fails
+round-trip export instead of silently rasterizing or flattening the object.
+
The summary stores the current SVG roster plus compact per-file canvas, size,
-text, image, vector, placeholder, icon, and source-ref counts. Models read the
+text, image, vector, placeholder, icon, source-ref, and source-proxy counts. Models read the
summary and editable SVGs; they do not read the machine manifest. The manifest
stores relative source/authoring filenames, source and initial authoring hashes,
-and source element paths. It deliberately does not copy the opaque payload.
+source element paths, and immutable preview hashes for source proxies. It
+deliberately does not copy the opaque payload.
The layered authoring bundle remains the editable source for template creation;
the complete imported SVG remains immutable native-payload backing. Final
`templates/*.svg` files are materialized and validated from that pair. A
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 56b2eabe..df220e75 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -929,7 +929,7 @@
"max_tokens": 3000
},
"stage.generate.customize-animations": {
- "description": "Object-animation stage plus animation resolution rules.",
+ "description": "Object-animation stage plus animation resolution rules. Ceiling raised after BUDGET_LOAD_SET reported 35742 tokens.",
"scope": "incremental",
"files": [
"skills/ppt-master/workflows/stages/customize-animations.md",
@@ -938,7 +938,7 @@
"skills/ppt-master/scripts/docs/pptx-transitions.md",
"skills/ppt-master/scripts/docs/svg-pipeline.md"
],
- "max_tokens": 35000
+ "max_tokens": 40000
},
"stage.generate.sound-selection": {
"description": "Complete post-motion sound identity vocabulary after a concrete auditory cue job exists.",