Release PPT workflow 0.7.1 with portable installation and production components

2026-10-12 18:45:54 +08:00
parent 4e3271ff62
commit f932b1970d
40 changed files with 2166 additions and 28 deletions
@@ -0,0 +1,68 @@
 # 安装和升级
 仓库根目录是 `ppt-template-workflow`，不需要寻找 `skills/` 子目录。安装只需 Git、Python 和目标 Agent 的本地 Skill 目录；不依赖其他 Skill。以下步骤适用于独立 Git 服务，无 GitHub 专属 API、账号或安装器要求。
 ## 安装步骤
 1. 识别目标 Agent 和范围。Codex 用户级目录通常为 `~/.agents/skills/`；项目级目录为项目内 `.agents/skills/`。若宿主使用其他目录或环境变量，按其实际发现规则传入 `--dest`。不要同时在多个发现目录安装副本。Codex 的目录与启停规则以[官方说明](https://learn.chatgpt.com/docs/build-skills)为准。
 2. 克隆用户给出的地址到临时目录，读取根 README、SKILL.md 和本说明；记录 `git rev-parse HEAD`，需要固定版本时 checkout 已审阅的完整提交号。不要使用 `curl | sh`，不要将凭据写入地址或日志。
 3. 选择 Python **3.12+**；系统 `python3` 可能较旧，用 `--version` 验证。安装脚本只用标准库；原生导出需要 [runtime/requirements.txt](runtime/requirements.txt) 的九项精确依赖。
 4. 在明确的目标路径运行下列命令。首次安装不带 `--replace`；更新已有版本加上 `--replace`，旧目录会完整保存在发现目录之外。`--prepare-runtime` 只在指定 venv 中安装依赖，不修改系统 Python。
 5. 运行 `--check`，确认文件哈希、280 个编译器文件、精确依赖、编译器加载和根入口启用状态。Codex 中只禁用嵌套署名入口，保留其文件与其他配置。下一轮任务可使用 Skill；未发现时重新打开会话或重启客户端。
 以下 macOS／Linux 示例中 `python3.12` 可替换为实际可用的 Python 3.12+ 绝对路径。`CODEX_HOME`、`AGENTS_HOME` 若已设置则沿用；这些变量不负责下载 Python。
 ```sh
 git clone https://git.commilitia.net/admin/Templated-PPT-Master.git /tmp/templated-ppt-master-install
 cd /tmp/templated-ppt-master-install
 git rev-parse HEAD
 python3.12 --version
 python3.12 scripts/install_skill.py \
  --dest "${AGENTS_HOME:-$HOME/.agents}/skills/ppt-template-workflow" \
  --codex-home "${CODEX_HOME:-$HOME/.codex}" \
  --venv "${CODEX_HOME:-$HOME/.codex}/runtimes/ppt-template-workflow/venv" \
  --prepare-runtime
 python3.12 scripts/install_skill.py \
  --dest "${AGENTS_HOME:-$HOME/.agents}/skills/ppt-template-workflow" \
  --codex-home "${CODEX_HOME:-$HOME/.codex}" \
  --venv "${CODEX_HOME:-$HOME/.codex}/runtimes/ppt-template-workflow/venv" --check
 ```
 临时目录已存在时换一个空目录；不要删除用户已有文件来腾位置。Windows PowerShell 示例：
 ```powershell
 git clone https://git.commilitia.net/admin/Templated-PPT-Master.git "$env:TEMP\templated-ppt-master-install"
 Set-Location "$env:TEMP\templated-ppt-master-install"
 $pptAgentsRoot = if ($env:AGENTS_HOME) { $env:AGENTS_HOME } else { Join-Path $HOME '.agents' }
 $pptCodexRoot = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME '.codex' }
 py -3.12 scripts/install_skill.py --dest "$pptAgentsRoot\skills\ppt-template-workflow" --codex-home $pptCodexRoot --venv "$pptCodexRoot\runtimes\ppt-template-workflow\venv" --prepare-runtime
 py -3.12 scripts/install_skill.py --dest "$pptAgentsRoot\skills\ppt-template-workflow" --codex-home $pptCodexRoot --venv "$pptCodexRoot\runtimes\ppt-template-workflow\venv" --check
 ```
 其他兼容 Agent：显式传入其 `--dest`；不要传入 `--codex-home`。若它递归发现 SKILL.md，需要使用其原生配置排除安装目录下精确的 `runtime/ppt-master/SKILL.md`，不要删除或修改上游文件。无法排除时报告该宿主尚未完成发现验证。运行库可用同一脚本准备。
 ## 已有运行库和离线环境
 已准备好的 venv 可直接传 `--venv` 而不加 `--prepare-runtime`；脚本只检查，不调用 pip。也可仅安装 Skill 文件，省略 `--venv`，结果会明确标为 `files-only`，不能宣称原生制作已就绪。元数据选择／工程／paint 工具本身支持 Python 3.10+，但本安装入口要求 3.12+ 以覆盖完整原生路线。
 离线安装先由安装方准备 Python、精确依赖和所选模板的字体，再将完整 Skill 源码复制到设备并运行安装和检查。使用本地 wheel 时可在创建 venv 后执行 `python -m pip install --no-index --find-links /path/to/wheels -r runtime/requirements.txt`，然后不带 `--prepare-runtime` 安装。不得因为依赖缺失就改用其他已安装 Skill。ImageGen、应用操作与 PowerPoint 为按任务需要使用的宿主能力，不随包安装。
 ## template、字体和首次使用
 template 不属于 Skill 安装载荷。按用户指定的独立 template 仓库说明安装，或直接给 Agent 一个可读的正式 manifest；不要硬编码默认 template 或 theme。每个模板的字体、素材许可和实际渲染需要单独验证。只有 Skill 安装请求时，不自动下载某组织模板。
 首次调用示例和命令见 [USAGE.md](USAGE.md)。安装收据位于目标目录 `.installation.json`，包含源码版本、提交、完整文件哈希、备份和运行库状态；它不是视觉或 PowerPoint 编辑验收。若目录受另一安装器管理，使用该管理方升级源锁和安装快照，避免其下次同步退回旧版本。
 ## 排错和恢复
 | 现象 | 处理 |
 |---|---|
 | Git 401／403／404，或要求用户名 | 确认用户指定地址和访问权限；仅使用现有或用户指定凭据，不自动替换身份 |
 | Python 版本过旧或缺少 venv／pip | 使用已安装的 3.12+ 或由安装方准备 Python／venv 支持 |
 | 依赖检查失败 | 在指定 venv 安装 requirements.txt；已有 Skill 在依赖准备失败时保持原状 |
 | 目标已存在 | 已授权更新时加 `--replace`；不要手工清空目录 |
 | 目标是符号链接 | 使用其安装管理方，或显式选择实际目标；脚本拒绝跟随链接替换 |
 | Codex 根入口已禁用或嵌套入口存在冲突配置 | 使用宿主原生配置检查该精确条目；脚本保留现有决定并给出错误 |
 | 升级后需恢复 | 停止相关制作，将新目录移出发现路径，再把收据中的备份目录移回原目标；配置备份按需只恢复本次精确条目 |
 脚本不卸载模板、运行库或字体。Windows／其他 Agent 的实际客户端发现、另一物理设备和应用编辑需在目标环境验证，不能由本机源码检查推定。
@@ -1,11 +1,17 @@
 # Templated-PPT-Master
-Source repository for the standalone Codex Skill `ppt-template-workflow`, version **0.5.0**. The installable Skill is this repository root: [SKILL.md](SKILL.md).
+可独立安装的 `ppt-template-workflow` Skill，当前版本 **0.7.1**。仓库根目录就是唯一安装单元：[SKILL.md](SKILL.md)。它提供模板选择、逐页设计、素材上色、原生 PPTX、图表与表格、页面协作和可重建工程；无需另装其他 Skill。template、theme、组织素材和字体独立提供。
-The Skill selects one external template and one theme at a time. It includes its own page mockup/material workflow, native object authoring and reconstruction guidance, native PPTX exporter, declared SVG paint processor, PowerPoint review guidance, and portable project tools. No separately installed Skill is required. Templates, themes, organization assets and default palettes remain outside this repository.
+在支持本地文件和命令执行的 Agent 中输入：
-The installer prepares Python 3.12+, the nine packages in [runtime/requirements.txt](runtime/requirements.txt), and the fonts declared by the chosen template. Metadata/project/paint commands use Python 3.10+ and the standard library. ImageGen and PowerPoint checks use the host's capabilities when needed; application binaries and fonts are not distributed here.
+```text
 安装这个 skill：https://git.commilitia.net/admin/Templated-PPT-Master
 ```
-Install only the root Skill. `runtime/ppt-master/SKILL.md` is preserved upstream attribution, not a second installation unit. The bundled compiler contains 280 unmodified MIT-licensed files; [runtime/provenance.json](runtime/provenance.json) records their hashes. See [runtime and provenance](references/runtime-and-provenance.md) for boundaries and licensing.
+Agent 应读取本页和 [INSTALL.md](INSTALL.md)，通过 Git 克隆这个地址，按目标 Agent 的 Skill 目录安装根目录，再准备独立 Python 运行库并执行安装检查。此仓库可通过匿名 HTTPS 读取；不是 GitHub 仓库，不要把地址传给仅支持 GitHub 的安装器。其他 Git 服务也可通过同一套本地安装步骤处理。
-Start with [USAGE.md](USAGE.md). Preserve interactive page review when requested; portable projects do not grant batch authoring or automatic publishing permission. Track reviewed commits from this repository as the Codex configuration source. Installation and synchronization belong to the configuration owner, separately from source publication.
+**给安装 Agent 的入口：**执行 [INSTALL.md 的安装步骤](INSTALL.md#安装步骤)，保持用户指定的安装范围。已有版本使用带备份的 `--replace`；完成后报告版本、固定提交、安装位置、运行库检查和模板是否就绪。安装 Skill 不代表已安装 template、字体或 PowerPoint，也不授予制作、发布 PPT 的权限。无本地文件／命令能力的聊天环境需要在可执行这些步骤的宿主中安装。
 首次使用见 [USAGE.md](USAGE.md)。[生产规则](references/production-rules.md)区分硬约束和推荐；[组件](references/components.md)、[图表](references/charts.md)、[图标](references/icon-production.md)、[页面库](references/page-library.md)和[页面分工](references/page-collaboration.md)按需读取。每次只激活一个外部 template 和一个 theme。
 包内 `runtime/ppt-master/` 保留 280 个未修改的 MIT 上游文件，包括用于署名的嵌套 SKILL.md；它不是第二个可安装 Skill。[来源和校验](runtime/provenance.json)、[运行库与边界](references/runtime-and-provenance.md)、[版本变化](UPDATES.md)一并保留。
@@ -2,13 +2,17 @@
 name: ppt-template-workflow
 description: Create and revise template-based editable PPTX decks, design page mockups and materials, reconstruct visual pages into native objects, and maintain portable source projects. Select one external template and theme at a time; includes its own native compiler and workflows without requiring another installed Skill.
 metadata:
-  version: "0.5.0"
+  version: "0.7.1"
 ---
 # PPT Template Workflow
 For installation, upgrades and environment checks, read [INSTALL.md](INSTALL.md); for first use and example requests, read [USAGE.md](USAGE.md). Install this root only. Keep the preserved nested compiler attribution entry disabled in agents that recursively discover skills.
 Use **template → theme → layout** as versioned inputs. A catalog can contain multiple independent templates; activate one template and one theme at a time. This skill contains no organization, default palette, template identity or local library path. Templates and themes remain separate packages. Its native compiler, project tools and authoring guidance are bundled; no other installed Skill is required. The installer provides Python libraries and fonts. Image generation and application UI checks use host capabilities when the task needs them.
 Read [production rules](references/production-rules.md) for the whole workflow. Preserve source meaning, provenance, real data, implementation claims and rebuildable inputs as requirements; use its planning and design methods as recommendations. Reuse settled choices and review at the authorized granularity. Record justified design exceptions without adding approval gates.
 ## Select and review
 Read the supplied catalog or manifest with `scripts/template_ref.py`. For a foundation project, start with its README consumer links. If the task needs a template and no source is specified, ask once for the source instead of guessing a global library.
@@ -30,12 +34,16 @@ Use the resolved workspace or native template path. v2 can provide a complete na
 Keep the user's working style above downstream defaults. For `interactive-page`, finish and review the current page before advancing; page count is not batch permission. Reuse settled route, theme and backend decisions. Explain an actual conflict with its source before continuing.
 If the manifest declares `page_library`, read [page examples](references/page-library.md). Use `scripts/page_library.py list` to find compositions, then `inspect --entry <id> --theme <id> --for-use` to verify a compatible reference and its source/preview hashes. Read its rationale, method and actual preview before adapting the source. Examples do not change the active template, palette, layout roster or review sequence. Templates without a library remain supported.
 - **Native:** read [native authoring](references/native-authoring.md). Author the current SVG page against its declared layout and compile it with `scripts/native_export.py`, retaining Master, Layout and placeholder identities. Avoid slide-local copies that cover inherited objects.
 - **Page mockups and materials:** read [visual design and materials](references/visual-design.md). Use the host image-generation tool for requested raster mockups, illustrations and image edits; keep exact supplied evidence and identity assets separate from style references. Use existing vectors and the bundled `scripts/paint_asset.py` for declared SVG paint changes.
 - **Image-rebuild:** read [object reconstruction](references/object-reconstruction.md). Inventory the current page, separate background and foreground sources, then author native text and structural objects in the selected SVG layout. Use source material or host image editing where needed; an image assembly is not editable completion.
 Read [authoring handoff](references/authoring-handoff.md) for shared page inputs, icon roles and theme changes. Use [PowerPoint checks](references/powerpoint-checks.md) when application opening, rendering or actual editing evidence is needed. If a required host capability is unavailable, finish independent work and name that specific evidence gap; do not substitute an old export or change the selected backend silently.
 For data graphics read [charts](references/charts.md); for native tables, metrics, timelines and explicit linear flows read [components](references/components.md). Their generators return data-bound component groups to compose inside an existing template slot, retaining its UI/Master/Layout. Keep sources and synchronize native payloads and visible fallback. New icons follow [icon production](references/icon-production.md) regardless of whether drawn, generated or externally sourced.
 ## Keep a portable source project
 When the user needs version control, collaboration or rebuilding after moving devices, read [project workspace](references/project-workspace.md) and use `scripts/ppt_project.py`. Keep stable page IDs, page sources/content/notes, data, assets, the selected template snapshot and an explicit local builder together. Declare the builder's actual dependencies and fonts in the environment metadata; this skill does not install them.
@@ -46,6 +54,12 @@ When the user needs version control, collaboration or rebuilding after moving de
 Preserve the user's page-by-page workflow. Projectization does not authorize batch creation, Git initialization, commits, publishing or global tool installation.
 ## Collaborate by page
 When multiple people or Agents are authorized to share the deck, read [page collaboration](references/page-collaboration.md). The coordinator fixes the narrative, stable page IDs, style snapshot and shared inputs before assigning disjoint page directories. Workers deliver source/content/notes, private assets, previews and a page packet; one coordinator integrates order, shared resources, locks and final compilation. Adapt the bundled [plan](assets/collaboration/plan.example.json) and [packet](assets/collaboration/page-packet.example.json) examples. Parallel work does not itself authorize messaging, batch creation or shared writes.
 Prepare useful page-library contributions as sanitized candidates with rationale, implementation, source/assets and preview evidence. The template maintainer reviews and versions them. Do not modify a locked vendor snapshot to publish a candidate.
 ## Verify and report
 Check the rendered current page and actual editable objects. Distinguish editable text/shapes/tables/charts/formulas, picture exceptions and inherited placeholders. Confirm native structure separately from appearance. Read [runtime and provenance](references/runtime-and-provenance.md) for dependencies, bundled compiler integrity, supported source boundaries and destination font checks.
@@ -1,9 +1,21 @@
-# Changes
+# 版本变化
 ## 0.7.1
 新增仓库根 README、安装与使用说明，以及标准库本地安装器。支持独立 Git 服务、显式目标、保留备份的升级、精确运行库检查和 Codex 嵌套署名入口排除。template 与 theme 继续独立提供；不预设组织或模板。
 ## 0.7.0
 整合已审阅的图表与分组表格，以及 C01—C15 全流程生产规则。支持七类原生图表、简表和分组表格、指标、时间线与线性流程。所有来源的图标遵循整体或局部 palette／fixed／structural 上色规范。
 ## 0.6.0
 增加外部模板页面库消费与按页协作接口。参考包含设计思路、实现方法、源码、素材和预览；兼容无页面库的旧模板，不自动扩大批量制作授权。
 ## 0.5.0
-Bundle self-contained page/material design, reconstruction, native export and PowerPoint review guidance. Include the unchanged compiler snapshot and dependency/provenance metadata. Add native export, font identity preservation, declared SVG paint materialization, and explicit portable-project preparation. External templates/themes remain separate. Twenty-one isolated source, export, boundary, paint, font and relocation checks passed; these do not establish application editing or other-device rendering.
+内置完整逐页设计、素材、重建、原生导出和 PowerPoint 审阅指导，以及未修改的 280 文件 MIT 编译器快照。独立提供运行库依赖和来源清单，无其他已安装 Skill 依赖。
 ## 0.4.0
-Add portable source projects with separate template and author locks, stable page IDs, declared build inputs, environment metadata, build receipts and source-only packing. Initialization remains an empty skeleton. Existing v1/v2 selection interfaces remain supported.
+增加 `ppt-project/v1`：分别锁定模板和作者输入，保存稳定页 ID、源码、数据、讲稿、素材、依赖、构建入口和源码包。
@@ -1,19 +1,57 @@
-# Use the standalone Skill
+# 使用指南
-Read [SKILL.md](SKILL.md), then explicitly select the supplied external template manifest and theme. Use the absolute Skill location; no installed companion Skill or original machine path is required.
+安装与升级见 [INSTALL.md](INSTALL.md)。开始任务时提供内容、用途、template 来源和 theme；沿用已确认选择。一次激活一个 template 和其中一个 theme，页面再选择 layout。没有模板来源时 Agent 会询问，不会猜一个全局默认模板。
 可以直接这样请求：
 ```text
 使用 ppt-template-workflow。模板 manifest：/path/to/template/manifest.json，
 theme：THEME。根据附件制作可编辑 PPT，先设计并审阅第一页，通过后再继续。
 ```
 ```text
 使用 ppt-template-workflow。沿用本工程的模板与主题，
 把这份数据做成对比图表，保留真实数据、单位和来源，先给我审阅当前页。
 ```
 ```text
 将这个 PPT 工程整理为可版本管理、可多人按页协作的源码项目，
 保存数据、讲稿、素材、模板快照和构建入口，并验证移动后重建。
 ```
 ## 选择模板与制作页面
 命令中的 `PPT_PYTHON` 指向准备好的 venv Python，`PPT_SKILL` 指向安装目录。两者是本机命令变量，不写入可移植工程源码。Windows 的 venv Python 在 `Scripts/python.exe`，其他平台在 `bin/python`。
 ```sh
-python3 /path/to/skill/scripts/template_ref.py export-style \
+PPT_PYTHON=/path/to/venv/bin/python
 PPT_SKILL=/path/to/installed/ppt-template-workflow
 "$PPT_PYTHON" "$PPT_SKILL/scripts/template_ref.py" list --catalog /path/to/catalog.json
 "$PPT_PYTHON" "$PPT_SKILL/scripts/template_ref.py" inspect --manifest /path/to/template/manifest.json
 "$PPT_PYTHON" "$PPT_SKILL/scripts/template_ref.py" export-style \
  --manifest /path/to/template/manifest.json --theme THEME --layout LAYOUT
-python3 /path/to/skill/scripts/template_ref.py resolve \
+"$PPT_PYTHON" "$PPT_SKILL/scripts/template_ref.py" resolve \
  --manifest /path/to/template/manifest.json --theme THEME --layout LAYOUT \
-  --route native --workflow interactive-page
+  --route native --workflow interactive-page --out /path/to/project/template-selection.json
-python3 /path/to/skill/scripts/native_export.py \
+```
 Agent 读取导出的调色板、字体、网格、素材 paint 契约、结构和版式容量，按模板槽位制作当前页 SVG。页面库存在时先检查其设计思路、实现方法和预览，再适配；参考页不改变模板几何和审阅顺序。`resolve` 只绑定完整的正式模板，提案可以 `inspect`／`export-style`，不能绕过发行状态制作。
 ```sh
 "$PPT_PYTHON" "$PPT_SKILL/scripts/native_export.py" \
  --manifest /path/to/template/manifest.json --theme THEME \
  --source /path/to/project/pages/page.svg --source-root /path/to/project \
  --output /path/to/project/exports/review.pptx
 ```
-The native exporter accepts released v2 templates, preserves the complete layout roster, and protects existing output. Prepare reviewed page SVGs using the template's slots, typography, grid and paint rules. Inspect actual rendering separately from native structure. See [native authoring](references/native-authoring.md), [PowerPoint checks](references/powerpoint-checks.md), and [project workspace](references/project-workspace.md).
+输出文件保护既有内容，修订时使用新路径。原生页面保留 Master／Layout／占位符；图表保留数据缓存和内嵌工作簿，表格保留单元格。图标按 SVG＋paint 的 palette／fixed／structural 通道处理。图表和表格示例位于 `assets/components/`，用法见[图表](references/charts.md)和[基础组件](references/components.md)。
-For a portable project, initialize an honest empty skeleton with `ppt_project.py init`. `prepare_native_project.py --project /path/to/project` explicitly copies a local builder/runtime into a clean skeleton. It neither installs dependencies nor updates the author lock automatically. The supplied builder consumes finalized SVGs and notes; data-driven page generation requires the author's explicit binding and build step. Provision the declared dependencies/fonts and verify a relocated rebuild before claiming portability.
+## 工程和协作
 需要可重建工程时，按[工程接口](references/project-workspace.md)执行 `ppt_project.py init`，为已定稿 SVG 准备 `prepare_native_project.py`，添加页面、讲稿及显式数据绑定，再 `lock`／`check`／`build`／`pack`。初始化只是骨架，不能把空工程当作完成的 PPT。
 协作时负责人固定页 ID、页序、风格和共用资源，参与者只修改分配的页面目录；负责人串行整合共享内容和锁。详见[页面分工](references/page-collaboration.md)。
 ## 交付标准
 先核对当前页内容、布局、字体和实际预览，再报告原生对象、结构与应用证据。引用与哈希、原生结构、实际渲染、PowerPoint 编辑、投影和其他设备分别验证。无宿主能力时完成独立部分并说明具体缺口。逐页审阅、原生路线和用户已定选择优先；工程化或安装 Skill 不授予批量制作、提交、推送或发布权限。
@@ -0,0 +1,31 @@
 {
  "schema_version": 1,
  "document_kind": "page-handoff-example",
  "page_id": "page-a",
  "worker": "worker-a",
  "revision": 1,
  "state": "draft",
  "baseline": {
    "manifest_sha256": "replace-with-real-sha256",
    "template_version": "replace-with-version",
    "theme": "replace-with-selected-theme",
    "style_inputs": [{"path": "vendor/template/style.json", "sha256": "replace-with-real-sha256"}]
  },
  "layout": "replace-with-layout-id",
  "purpose": "replace-with-one-page-message",
  "files": [
    {"path": "pages/page-a/source.svg", "sha256": "replace-with-real-sha256"},
    {"path": "pages/page-a/content.json", "sha256": "replace-with-real-sha256"},
    {"path": "pages/page-a/notes.md", "sha256": "replace-with-real-sha256"}
  ],
  "materials": [],
  "library_reference": null,
  "preview": null,
  "native_objects": [],
  "picture_exceptions": [],
  "checks": {
    "source": "not-run", "native_structure": "not-run", "svg_render": "not-run",
    "powerpoint_render": "not-run", "powerpoint_edit": "not-run", "projection": "not-run"
  },
  "unresolved": []
 }
@@ -0,0 +1,24 @@
 {
  "schema_version": 1,
  "document_kind": "page-collaboration-plan-example",
  "coordinator": "replace-with-coordinator",
  "workflow": "interactive-page",
  "baseline": {
    "manifest": "vendor/template/manifest.json",
    "manifest_sha256": "replace-with-real-sha256",
    "template_version": "replace-with-version",
    "theme": "replace-with-selected-theme",
    "style_inputs": [{"path": "vendor/template/style.json", "sha256": "replace-with-real-sha256"}]
  },
  "page_order": ["page-a", "page-b"],
  "assignments": [
    {"page_id": "page-a", "worker": "worker-a", "write_allowlist": ["pages/page-a/"],
     "purpose": "replace-with-one-page-message", "layout": "replace-with-layout-id",
     "required_evidence": [], "authorized_to_proceed": false},
    {"page_id": "page-b", "worker": "worker-b", "write_allowlist": ["pages/page-b/"],
     "purpose": "replace-with-one-page-message", "layout": "replace-with-layout-id",
     "required_evidence": [], "authorized_to_proceed": false}
  ],
  "shared_writer": "replace-with-coordinator",
  "review_cadence": "replace-with-user-agreed-review-gates"
 }
@@ -0,0 +1,13 @@
 {
  "schema_version": 1,
  "kind": "flow",
  "data_kind": "synthetic-demo",
  "source": "组件演示，不代表真实系统",
  "nodes": [
    {"id": "input", "label": "输入整理"},
    {"id": "process", "label": "处理分析"},
    {"id": "verify", "label": "结果验证"},
    {"id": "output", "label": "交付输出"}
  ],
  "edges": [["input", "process"], ["process", "verify"], ["verify", "output"]]
 }
@@ -0,0 +1,10 @@
 {
  "schema_version": 1,
  "kind": "metric",
  "data_kind": "synthetic-demo",
  "source": "组件演示，不代表实测结果",
  "label": "任务完成率",
  "value": 92,
  "unit": "%",
  "detail": "统计口径：已完成任务／全部任务"
 }
@@ -0,0 +1,42 @@
 {
  "schema_version": 1,
  "kind": "table",
  "variant": "grouped",
  "data_kind": "synthetic-demo",
  "source": "组件合成演示，不代表真实测量或推荐",
  "columns": [
    {"id": "plan", "label": "方案"},
    {"id": "use", "label": "适用场景"},
    {"id": "latency", "label": "延迟", "unit": "ms", "format": "one-decimal"},
    {"id": "throughput", "label": "吞吐量", "unit": "次／秒", "format": "integer"},
    {"id": "memory", "label": "内存", "unit": "GB", "format": "one-decimal"},
    {"id": "status", "label": "验证状态"}
  ],
  "rows": [
    ["基础方案", "标准任务", 28.0, 1200, 2.4, "已验证"],
    ["缓存方案", "重复请求", 19.0, 1580, 2.8, "已验证"],
    ["批处理方案", "离线任务", 24.0, 1760, 2.6, "已验证"],
    ["并行方案", "独立子任务", 16.0, 1940, 3.2, "待复核"],
    ["组合方案", "混合负载", 12.0, 2180, 3.4, "已验证"]
  ],
  "column_widths": [168, 264, 168, 200, 144, 208],
  "numeric_columns": [2, 3, 4],
  "column_groups": [
    {"label": "方案信息", "start": 0, "span": 2},
    {"label": "性能表现", "start": 2, "span": 2},
    {"label": "资源", "start": 4, "span": 1},
    {"label": "验证", "start": 5, "span": 1}
  ],
  "row_header_columns": [0],
  "focus_row": 4,
  "focus_meaning": "调用者明确选择关注组合方案，不自动推断推荐或优劣",
  "bars": {"columns": [2, 3, 4]},
  "bar_meaning": "条带从零起算，仅同列比较大小，不表示综合评分或推荐",
  "status": {
    "column": 5,
    "values": {
      "已验证": {"palette_index": "accent3", "shape": "circle"},
      "待复核": {"palette_index": "accent4", "shape": "diamond"}
    }
  }
 }
@@ -0,0 +1,9 @@
 {
  "schema_version": 1,
  "kind": "table",
  "data_kind": "synthetic-demo",
  "source": "组件演示，不代表实测结果",
  "columns": ["方案", "耗时／秒", "状态"],
  "rows": [["方案甲", 24, "完成"], ["方案乙", 18, "完成"], ["方案丙", 12, "待复核"]],
  "numeric_columns": [1]
 }
@@ -0,0 +1,12 @@
 {
  "schema_version": 1,
  "kind": "timeline",
  "data_kind": "synthetic-demo",
  "source": "组件演示，不代表真实日程；等距里程碑",
  "items": [
    {"date": "第一周", "label": "需求确认"},
    {"date": "第二周", "label": "原型验证"},
    {"date": "第四周", "label": "联合测试"},
    {"date": "第五周", "label": "交付审阅"}
  ]
 }
@@ -0,0 +1,24 @@
 {
  "schema_version": 1,
  "data_kind": "synthetic-demo",
  "unit": "项",
  "source": "组件演示",
  "type": "bar",
  "title": "任务处理量",
  "categories": [
    "录入",
    "审核",
    "归档"
  ],
  "series": [
    {
      "id": "processed",
      "name": "已处理",
      "values": [
        24,
        36,
        18
      ]
    }
  ]
 }
@@ -0,0 +1,33 @@
 {
  "schema_version": 1,
  "data_kind": "synthetic-demo",
  "unit": "项",
  "source": "组件演示",
  "type": "column-stacked",
  "title": "任务组成比较",
  "categories": [
    "甲组",
    "乙组",
    "丙组"
  ],
  "series": [
    {
      "id": "done",
      "name": "完成",
      "values": [
        20,
        25,
        18
      ]
    },
    {
      "id": "pending",
      "name": "待办",
      "values": [
        10,
        5,
        12
      ]
    }
  ]
 }
@@ -0,0 +1,33 @@
 {
  "schema_version": 1,
  "data_kind": "synthetic-demo",
  "unit": "项",
  "source": "组件演示",
  "type": "column",
  "title": "分组数量比较",
  "categories": [
    "甲组",
    "乙组",
    "丙组"
  ],
  "series": [
    {
      "id": "before",
      "name": "调整前",
      "values": [
        18,
        25,
        22
      ]
    },
    {
      "id": "after",
      "name": "调整后",
      "values": [
        24,
        32,
        28
      ]
    }
  ]
 }
@@ -0,0 +1,24 @@
 {
  "schema_version": 1,
  "data_kind": "synthetic-demo",
  "unit": "项",
  "source": "组件演示",
  "type": "doughnut",
  "title": "处理状态构成",
  "categories": [
    "完成",
    "进行",
    "待办"
  ],
  "series": [
    {
      "id": "status",
      "name": "任务",
      "values": [
        55,
        30,
        15
      ]
    }
  ]
 }
@@ -0,0 +1,33 @@
 {
  "schema_version": 1,
  "data_kind": "synthetic-demo",
  "unit": "ms",
  "source": "组件演示",
  "type": "line",
  "title": "分期变化",
  "categories": [
    "第1期",
    "第2期",
    "第3期"
  ],
  "series": [
    {
      "id": "baseline",
      "name": "基线",
      "values": [
        30,
        24,
        18
      ]
    },
    {
      "id": "updated",
      "name": "改进",
      "values": [
        26,
        18,
        14
      ]
    }
  ]
 }
@@ -0,0 +1,24 @@
 {
  "schema_version": 1,
  "data_kind": "synthetic-demo",
  "unit": "项",
  "source": "组件演示",
  "type": "pie",
  "title": "需求来源构成",
  "categories": [
    "教学",
    "科研",
    "管理"
  ],
  "series": [
    {
      "id": "requests",
      "name": "需求",
      "values": [
        40,
        35,
        25
      ]
    }
  ]
 }
@@ -0,0 +1,33 @@
 {
  "schema_version": 1,
  "data_kind": "synthetic-demo",
  "unit": "次/秒",
  "source": "组件演示",
  "type": "scatter",
  "title": "资源与吞吐关系",
  "x_unit": "核心",
  "series": [
    {
      "id": "samples",
      "name": "测试样本",
      "points": [
        [
          1,
          12
        ],
        [
          2,
          20
        ],
        [
          3,
          24
        ],
        [
          4,
          36
        ]
      ]
    }
  ]
 }
@@ -0,0 +1 @@
 <ns0:svg xmlns:ns0="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720"><ns0:g id="minimal-chart" data-pptx-replace-with="chart" data-pptx-fallback-sha256="541d841e7327c1eafb3ec123f7dfe3ac4ae3c8eb48ae954b7f0e3f16f4262a2d"><ns0:metadata type="application/json">{"name": "minimal-column", "x": 600, "y": 160, "width": 480, "height": 320, "type": "column", "categories": ["A", "B"], "series": [{"name": "Count", "values": [12, 18]}], "colors": ["#2563EB"], "show_legend": false, "style": {"font_family": "Arial", "font_size": 24, "axis_font_size": 24, "text_color": "#111827", "axis_color": "#64748B", "grid_color": "#CBD5E1", "chart_area_fill": "#FFFFFF", "plot_area_fill": "#FFFFFF"}}</ns0:metadata><ns0:rect x="600" y="160" width="480" height="320" fill="#FFFFFF" /><ns0:line x1="648" y1="424" x2="1048" y2="424" stroke="#64748B" /><ns0:rect x="720" y="280" width="80" height="144" fill="#2563EB" /><ns0:rect x="900" y="208" width="80" height="216" fill="#2563EB" /><ns0:text x="760" y="456" text-anchor="middle" font-family="Arial" font-size="24" fill="#111827">A</ns0:text><ns0:text x="940" y="456" text-anchor="middle" font-family="Arial" font-size="24" fill="#111827">B</ns0:text></ns0:g></ns0:svg>
@@ -0,0 +1 @@
 <ns0:svg xmlns:ns0="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720"><ns0:g id="minimal-table" data-pptx-replace-with="table" data-pptx-fallback-sha256="d2861c02c71d8cd86d40d9ff939bc3354cda5f91c7129435e82822c4a7ec6a88"><ns0:metadata type="application/json">{"name": "minimal-table", "x": 64, "y": 160, "width": 480, "height": 144, "columns": ["Item", "Value"], "rows": [["A", "12"], ["B", "18"]], "strict_grid": true, "column_widths": [240, 240], "row_heights": [48, 48, 48], "style": {"font_family": "Arial", "font_size": 24, "header_font_size": 24, "header_fill": "#334155", "header_text": "#FFFFFF", "body_fill": "#FFFFFF", "body_text": "#111827", "border_color": "#CBD5E1", "border_width": 1, "band_row": false}}</ns0:metadata><ns0:rect x="64" y="160" width="240" height="48" fill="#334155" stroke="#CBD5E1" /><ns0:text x="76" y="192" font-family="Arial" font-size="24" fill="#FFFFFF">Item</ns0:text><ns0:rect x="304" y="160" width="240" height="48" fill="#334155" stroke="#CBD5E1" /><ns0:text x="316" y="192" font-family="Arial" font-size="24" fill="#FFFFFF">Value</ns0:text><ns0:rect x="64" y="208" width="240" height="48" fill="#FFFFFF" stroke="#CBD5E1" /><ns0:text x="76" y="240" font-family="Arial" font-size="24" fill="#111827">A</ns0:text><ns0:rect x="304" y="208" width="240" height="48" fill="#FFFFFF" stroke="#CBD5E1" /><ns0:text x="316" y="240" font-family="Arial" font-size="24" fill="#111827">12</ns0:text><ns0:rect x="64" y="256" width="240" height="48" fill="#FFFFFF" stroke="#CBD5E1" /><ns0:text x="76" y="288" font-family="Arial" font-size="24" fill="#111827">B</ns0:text><ns0:rect x="304" y="256" width="240" height="48" fill="#FFFFFF" stroke="#CBD5E1" /><ns0:text x="316" y="288" font-family="Arial" font-size="24" fill="#111827">18</ns0:text></ns0:g></ns0:svg>
@@ -14,6 +14,8 @@ A theme switch changes only declared palette and asset properties. Shared canvas
 ## Icon material handoff
 Apply [icon production](icon-production.md) to template reuse and all new authored, generated or external icons. Use a project-local material descriptor for new icons; do not edit a locked vendor snapshot. Whole and partial coloring follow the same contract.
 Supply the original SVG, its `paint_contract_data`, selected palette and exact asset bindings together. New vector materials use stable element IDs and adjustable fill/stroke pairs with semantic tokens. Distinct tokens express independent roles; a shared token expresses a shared role. Keep fixed details as literal values and unpainted openings as `structural: none`. Undeclared channels preserve their source paint.
 `scripts/paint_asset.py --manifest <path> --theme <id> --asset <role> --output <new.svg>` applies only the selected theme's palette whitelist. It verifies exact IDs, explicit source paint, fixed/structural values and bindings, then protects existing output. It intentionally rejects stylesheets, overridden target channels and inherited target paint; flatten those channels into explicit reviewed attributes before using this helper. Other SVG authoring tools may support richer materials if they preserve the same contract.
@@ -0,0 +1,89 @@
 # 可数据绑定的原生图表组件
 `chart_component.py`把明确的数据生成一个独立 SVG `g`：其中包含原生 Chart metadata、同源的可见 SVG fallback，以及标题、单位、图例和来源文字。把它组合进所选 template 的页面；组件不复制母版、版式或页面 UI。它是技术组件接口，不替调用者决定报告应使用哪些图表。
 ## 支持范围
 | type／示例数据 | 用途与适配 | 当前技术边界 |
 |---|---|---|
 | `column`／[column.json](../assets/components/charts/column.json) | 比较少量类别；多系列分组 | 数轴包含零，显式 min／max／major_unit；支持正、负、零 |
 | `bar`／[bar.json](../assets/components/charts/bar.json) | 较长类别名称的横向数量比较 | 上游编译器不接受 bar 的 axes；原生应用自动选择范围与刻度，SVG 标尺只作预览；保留真实数值及原生数据标签 |
 | `line`／[line.json](../assets/components/charts/line.json) | 按顺序比较变化 | 等间距类别轴、显式数轴；直线与圆点；不把类别轴当成连续日期轴 |
 | `scatter`／[scatter.json](../assets/components/charts/scatter.json) | 展示成对的 X／Y 观测 | `points: [[x, y], …]`；两个显式数轴；圆点，无回归拟合 |
 | `pie`／[pie.json](../assets/components/charts/pie.json) | 单组非负构成 | 一个系列，总和大于零；零值保留在数据与图例中，不绘制零面积扇形 |
 | `doughnut`／[doughnut.json](../assets/components/charts/doughnut.json) | 单组非负构成 | 与 pie 相同；内圈比例75%，与锁定原生编译器一致 |
 | `column-stacked`／[column-stacked.json](../assets/components/charts/column-stacked.json) | 比较各类别的总量及组成 | 初版只支持非负堆叠；范围基于各类别总量，不把单个系列最大值当堆叠上界 |
 示例全部明确标记 `synthetic-demo`，使用564×464区域，保留单位与来源。它们只演示技术能力，不能作为真实报告证据。图例、文字和轴预留空间不足时工具报错，不自动缩字；改写标签或使用更宽区域后再生成。宽度估算是保守的字符检查，仍需查看目标应用的实际渲染。
 这层封装不接受混合图、双轴、百分比堆叠、3D、气泡、时间轴、缺失值、平滑曲线、任意自定坐标轴或额外格式字段。上游可能另有能力，但不能经本组件接口静默转入。需要这些能力时先确认作者路线与支持范围。
 ## 数据契约
 JSON顶层字段：`schema_version: 1`，`data_kind`（`synthetic-demo`／`observed`／`derived`），`type`、非空 `title`、`unit`（允许空字符串）、`series`。`source`可选。scatter可另写`x_unit`，并省略`categories`；其余类型必须提供非空、唯一的`categories`标签。
 每个系列有稳定、唯一的`id`、非空`name`，以及与类别同长的`values`，或scatter的非空`points`数组。ID使用`[A-Za-z][A-Za-z0-9_-]{0,63}`。数值必须是JSON数字且有限；布尔值、数字字符串、NaN和无穷均拒绝。为避免SVG／OOXML标量计算溢出或失去有效标签，当前非零数值的绝对值支持`1e-9`至`1e12`，零独立支持。不会补齐长度、删掉零值、改写负数或按百分比重算原始数据。CLI拒绝重复JSON键和未知字段。
 `source`只作为显示文字与元数据保留，工具不会读取链接、补充出处或证明其真实性。所有原始数据同时放入marker的`component_data`，供工程审计；原生图表cache及内嵌XLSX保存未缩放的实际数值。
 ## 样式来源
 `style`和`theme`分别使用`template_ref.py export-style`的`style`、`theme_data`。字体从`typography.families.body`取得，字号默认取`caption`角色，缺少时取`label`；按`canvas.pt_to_px`换算。组件没有组织、字体名或十六进制配色的固定默认值。
 template可选择声明`style.components.charts`：
 ```json
 {
  "series_palette_indices": ["accent1", "accent3", "accent4"],
  "text_role": "caption",
  "text_palette_index": "dk1",
  "grid_palette_index": "line"
 }
 ```
 未声明时，系列依次使用已有的`accent1`、`accent3`、`accent4`、`accent5`、`accent6`、`accent2`；文字使用`dk1`，网格使用`line`（缺少时`dk2`），图表背景使用`lt1`。颜色必须为调色板中已存在的六位hex值。系列按数组顺序绑定索引，pie按类别顺序绑定。需要的系列或扇形数超过不同索引数量时明确拒绝，不循环复用颜色。组件不会从系列名称推断状态或改动数据语义。
 保持简洁的精细化优先处理信息层次：保留轻网格、统一标签与单位、适度留白，并按比较目的分配颜色。平行系列可用两个主题索引；当作者明确选择一个重点系列时，可在该页风格副本中设置 `series_palette_indices: ["dk2", "accent1"]`，用中性参照配合主题色重点。颜色顺序必须对应明确系列，不从名称或数值自动选择“更好”的一组。
 `axis_palette_index` 可将轴线绑定到现有调色板索引，默认跟随文字。`value_labels: true` 为非负分组 `column` 同时生成原生数值标签及同源 fallback；标签使用已声明字号，放不下时报错。默认关闭，不给每一种图表都加数字。bar 本身保留数值标签；其他类型或负值柱图需要按其信息特点另行设计。改动页面风格副本不改变全工程的系列语义；同一系列跨页需由作者保持绑定。
 column、line、scatter与非负堆叠的显式数轴和SVG fallback使用同一组范围与步长；全零数轴为0至1。bar受锁定编译器限制，由原生应用自动选轴，并带有`data-native-axis-policy="automatic-bar-preview-scale-may-differ"`声明。显式数轴一致不代表原生应用绘图区、轴文字位置与SVG像素级一致。
 ## 生成与组合
 使用安装方准备的Python环境，在任何目录执行：
 ```sh
 python /path/to/skill/scripts/chart_component.py \
  --manifest /absolute/path/to/template/manifest.json \
  --theme selected-theme \
  --data /absolute/path/to/column.json \
  --bounds 64 156 564 464 --id results-chart \
  --output /absolute/path/to/new-component.svg
 ```
 CLI选择一个外部template／theme，输出对应canvas的独立组件SVG，拒绝覆盖文件及经符号链接写出。它没有页面的Master／Layout契约，不能直接冒充完整模板页面交给结构化原生导出器。
 Python组合接口：
 ```python
 from chart_component import render_chart
 component = render_chart(data, exported["style"], exported["theme_data"],
                         (64, 156, 564, 464), "results-chart")
 # page_root是已有模板页，保留其Master/Layout、固定UI、占位符与素材引用。
 slot = next(node for node in page_root if node.get("id") == "slot-left")
 for child in list(slot):
    slot.remove(child)
 slot.append(component)
 ```
 `render_chart(data, style, theme, bounds, component_id) -> xml.etree.ElementTree.Element`返回SVG `g`。使用当前页真实槽位的bounds；确认当前template确实有该槽位，不能把示例中的ID、坐标当通用约定。component_id在整页必须唯一。生成后不要单独改fallback图形或marker数据；修改JSON并重新生成，保持fallback指纹和元数据一致。
 图例、标题、单位及来源位于marker外，编译为独立可编辑对象；marker内转换为真正的Chart和内嵌XLSX。此安排保持页面文字位置受模板控制。若在PowerPoint内改图表数据，外部图例或构成数量文字不会自动更新，需要一起修改，或从工程JSON重建。将图表JSON和生成工具声明为工程输入并锁定，可在迁移后重建；不能只交付生成的SVG与PPTX。
 ## 验证与限制
 本项目的`check_chart_components.py`验证两theme的7类组件SVG、错误输入拒绝和已有文件保护；实际通过锁定编译器生成7类Chart及正负／全零边界案例，检查原生Chart类型、显式轴、自动bar轴、数值cache、内嵌XLSX、独立标题与合成数据声明。Chart对象的存在以PPTX关系和XML为证据。
 这些检查不代表PowerPoint已实际打开、渲染、编辑或完成投影验收。进入真实页面后需按[PowerPoint检查](powerpoint-checks.md)核对字形、标尺、单位、图例、数据与页内分区；页面审阅由负责人按已有逐页流程组织。图表导出失败必须报告，不能用fallback截图宣称已得到原生Chart。
@@ -0,0 +1,43 @@
 # Data-bound basic components
 `scripts/basic_component.py` provides native tables, text metrics, timelines and explicit linear flows. Use [charts](charts.md) for seven native Chart types. All helpers read the selected external template's style/theme and return a component SVG group; they add no organization, page UI, Master or Layout. Compose groups inside existing declared slots. SVG images inserted through `image href` are not a substitute for this native-object composition.
 | Kind and source example | Native result | Input and capacity |
 |---|---|---|
 | [table](../assets/components/basic/table.json) | PowerPoint Table with actual cells, widths, padding and header rows | `columns`, equal-length `rows`, optional `column_widths` summing to bounds width, zero-based `numeric_columns`; strings or finite numbers, empty cells allowed |
 | [table / grouped](../assets/components/basic/table-grouped.json) | Native Table with merged group headers, separate native data bars and explicit status shapes | `variant: grouped`; object columns, explicit groups/widths and original row values; optional focus, row headers, per-column bars and status mapping |
 | [metric](../assets/components/basic/metric.json) | Text objects, including number/unit | `label`, `value`, optional `unit` and `detail`; at least160px high |
 | [timeline](../assets/components/basic/timeline.json) | Native line, circles and text | 2–6 `items` with `date` and `label`; at least208px high; ordinal milestones spaced equally, not a quantitative elapsed-time axis |
 | [flow](../assets/components/basic/flow.json) | Native boxes, arrows and text | 2–6 `nodes` with unique `id`/`label`, explicit `edges: [[from,to], …]`; at least160px high; supports only forward adjacent links, not inferred causality or branches |
 Each JSON uses `schema_version: 1` and `kind`. Examples are marked `data_kind: synthetic-demo`; preserve this declaration and source metadata when demonstrating. Real reports retain observations, definitions, missing-value policy and sources under [production rules](production-rules.md). Metadata remains in SVG; save original JSON with the page. The table payload is canonical native metadata, with original data in `data-component-source`; other groups carry original JSON in metadata. Native PPTX does not retain arbitrary SVG metadata, so retain project sources separately.
 The table uses `style.components.table`, including theme-indexed header colors and padding. Text uses `typography.roles.label`, `caption` and `number`, their declared font families and `canvas.pt_to_px`. Other component colors use `dk1`, `dk2`, `accent1`, `line` and `lt1` from the palette. Internal spacing uses fixed 8px modules; derived equal columns/centers do not introduce new page alignment guides. Width checks are conservative estimates, not a font renderer. The tool rejects excess capacity instead of shrinking text. Rephrase, enlarge a slot, change layout or split content; inspect actual application output.
 ## Grouped table
 The default table remains unchanged. Select `kind: table, variant: grouped` for a denser comparison with two header levels. Each column is `{id, label, unit?, format?}` with a unique stable ID. `format` is `text` (default), `integer` (integral numbers only, with thousands separators), or `one-decimal`. Formatting changes display text, never original `rows`. `numeric_columns` contains zero-based indices and right-aligns those headers and values. Numeric columns require actual finite numbers rather than formatted strings.
 `column_widths` is mandatory and must fill the bounds width. `column_groups: [{label,start,span}, …]` must cover all columns once in order, with no gaps or overlap; spans become merged native cells. `row_header_columns` optionally gives zero-based columns a persistent pale background. `focus_row` optionally emphasizes one explicit zero-based data row; this does not infer a recommendation. Preserve a `focus_meaning` when its interpretation matters.
 Optional `bars: {columns: […]}` adds 4px tracks and bars to explicitly declared numeric columns. Values must be finite and nonnegative. Each column has its own domain `[0, maximum]`, with `[0,1]` for an all-zero column. A zero value leaves an empty track. Bars permit comparison only within a column; they do not normalize different units into a score. Save the source, units and `bar_meaning` alongside the page. The outer group's JSON metadata includes `derived_marks` with raw values, domains, row/column indices and geometry so these mappings can be checked.
 Optional `status: {column, values: {"label": {palette_index, shape}}}` binds an explicit textual status to `circle` or `diamond` and a palette index. Unknown values, shapes and palette indices fail; the helper does not infer success, caution or failure semantics. Text remains visible alongside the shape. Stable shape IDs derive from the component ID and row/column. These simple semantic marks are native UI shapes; custom illustrative icons still follow [icon production](icon-production.md).
 The grouped style reads `typography.roles.label` and `caption`, including each role's declared family, and uses `accent1`, `accent2`, `surface_tint`, `lt1`, `lt2`, `dk1`, `dk2` and `line`. Optional `style.components.table_grouped` keys are `group_height_px`, `header_height_px`, `row_height_px` and `cell_padding_px: [top,side]`. Heights and padding use 8px modules and must meet text capacity. Defaults derive from the external typography; 20pt label / 18pt caption at 96dpi produces 40px group, 80px header and 56px data rows with bars. No font or organization is fixed in the component. Accent group headers, pale column headers, light alternating rows, group separators and a 4px focus edge provide hierarchy without a full grid.
 The returned outer `g` contains a separate native-table marker with a fresh fallback fingerprint, followed by native bar/status shapes outside that marker. Insert the **whole outer group** into the page, not just the table marker. Retain its original data and regenerate after changes; never edit only the payload or only the fallback. Use the same `basic_component.py` CLI/API shown below with the grouped JSON and sufficiently large bounds. The bundled example needs 1152px width and 400px height under the stated 20pt/18pt typography.
 ```sh
 python /path/to/skill/scripts/basic_component.py \
  --manifest /absolute/template/manifest.json --theme selected-theme \
  --data /absolute/project/data/table.json \
  --bounds 64 156 564 464 --id results-table \
  --output /absolute/project/sources/new-component.svg
 ```
 The CLI protects existing files and symlinked output paths. The output canvas follows the template but contains only the component. It cannot be compiled as a complete template page by itself.
 For Python composition, add the Skill's `scripts` directory to `sys.path`, import `render_component` from `basic_component`, and call `render_component(data, style, theme_data, (x,y,width,height), component_id)`. Take `style` and `theme_data` from `template_ref.py export-style`. Insert the returned `g` into the current template page's slot while retaining its existing Master/Layout/placeholder attributes and full roster. A slot label or example content must be removed as part of filling that slot, without removing inherited UI.
 After composition, validate native marker payloads using [native objects](native-objects.md). Compile with `native_export.py`, check `a:tbl` for the table and text/shapes/connectors for the other components, then inspect current renders. Keep separate evidence for native structure, application appearance, editing and projection. General architectures, branched flows and custom comparisons can be composed from the same native primitives; this limited helper is not a requirement to fit every diagram into a linear chain.
@@ -0,0 +1,28 @@
 # Icon production
 Use suitable template icons first. For new icons, prefer directly authored SVG/native shapes for simple forms, ImageGen for complex imagery, and external ready icons as a supplement. Choose a recognizable information meaning and keep stroke weight, corners, perspective, optical scale and detail consistent at the intended size. An icon should remain understandable without nearby explanatory prose, or deliberately reuse the same established icon as its counterpart.
 ## One deliverable contract for all sources
 All routes must support approved whole or partial palette recoloring. Deliver original source, normalized SVG, a paint contract, palette bindings, provenance and preview evidence together. Use stable IDs for semantic parts, explicit fill/stroke attributes and per-channel rules. `palette` permits a semantic token to bind an index; `fixed` preserves an exact literal; `structural` preserves `none`. Unlisted channels preserve their source paint. Shared tokens express shared roles; separate tokens permit independent colors.
 Whole-icon coloring means binding every intended adjustable part to one palette index. It never means replacing every matching color in a bitmap. Keep fixed details, white details, opacity, holes, masks, geometry and paint order intact. Validate IDs, explicit source paint, duplicate/missing bindings and palette indices. See [the exact schema](template-interface.md#svg-paint-contract).
 For ImageGen or external assets, first separate the semantic parts in the production source. Reconstruct the final icon as compliant SVG/native geometry when necessary. A flat raster with several apparent colors does not identify recoloring permissions. If using a layered/masked intermediate, retain reviewed per-role masks; do not infer them from matching source colors. The bundled paint helper handles explicit SVG fill/stroke, not raster segmentation or gradient-stop recoloring. A fixed-color PNG alone is not a completed adjustable icon.
 Keep an exact official mark or evidence image as its original asset when that is its assigned role; do not relabel it as a newly generated icon to bypass source fidelity. Use only the template/user's explicitly permitted identity derivatives.
 ## Project-local icons
 Keep new materials under the caller's project, outside a locked template snapshot. A local material descriptor contains `schema_version: 1`, `id`, project-relative `path` and `paint_contract`, and a `bindings` array of `{selector, channel, palette_index}`. Paths resolve beside the descriptor. The bindings must cover exactly the contract's palette pairs, and at least one pair must be adjustable. This lets an author add an icon without publishing a new template or modifying vendor files.
 ```sh
 python /path/to/skill/scripts/paint_asset.py \
  --manifest /absolute/template/manifest.json --theme selected-theme \
  --material /absolute/project/assets/new-icon/material.json \
  --output /absolute/project/assets/derived/new-icon.svg
 ```
 For a supplied template icon use `--asset <role>` instead of `--material`. Both modes preserve fixed/structural/unlisted channels and protect existing output. The local descriptor supplies bindings to the selected theme's palette; it cannot change that palette. Retain the descriptor and original with the project.
 Render the original and derivative on their intended backgrounds at actual use size. Check recognition, consistent optical scale, stroke visibility, fixed details and transparent openings. XML/paint validation is separate from this visual check. Insert resulting geometry into the page's native source when native editing is required; a selectable image alone does not prove native icon objects.
@@ -33,4 +33,4 @@ Keep proposed styles and mockups outside the final template workspace until the
 The bundled runtime also carries the upstream preview compiler at `runtime/ppt-master/scripts/template_preview_pptx.py` for author review workspaces. It is source tooling, not a second Skill. Read its command help for a new workspace. Its platform font mapping is general-purpose: a template review wrapper should import the compiler and use `scripts/finalize_theme.py`'s `preserve_declared_font_families(style)` context around the serial compile, then `finalize(...)`. This preserves the declared family before information can be lost to platform fallback. Do not globally replace a fallback font in finished XML: the author may have intentionally used that same font.
-For advanced native table/chart/formula or placeholder metadata, inspect the corresponding bundled compiler module and its local CLI help. Do not claim specialized objects from a screenshot or from a successful ZIP export alone. Finish with [render and application checks](powerpoint-checks.md).
+For native tables/charts and formula limitations, read [specialized objects](native-objects.md) and its bundled minimal SVG examples. For placeholder metadata, inspect the corresponding bundled compiler module and local CLI help. Do not claim specialized objects from a screenshot or from a successful ZIP export alone. Finish with [render and application checks](powerpoint-checks.md).
@@ -0,0 +1,33 @@
 # Specialized native objects
 The maintained SVG compiler creates native tables and charts from explicit group markers. Start with [table.svg](../assets/native-objects/table.svg) or [chart.svg](../assets/native-objects/chart.svg). These are isolated compiler examples, not selected-template pages. Their Arial font, colors and geometry are explicit sample values; rebind them to the selected style/theme and fit the chosen content region. SVG coordinates and `font_size` are pixels: 24px means 18pt at 96dpi.
 Each example contains a visible fallback plus a `<g data-pptx-replace-with="table|chart">` with `<metadata type="application/json">`. Both must come from the same data. The compiler replaces the group with an editable native object, rather than keeping the visible fallback as the result. Preserve explicit bounds, rows/columns, series/categories, font and colors. Escape JSON when inserting it in XML. Do not edit only the fallback or only the metadata. Marker transforms support translate/scale, not rotation/skew.
 ## Validate the marker and result
 Bundled Python modules are under `runtime/ppt-master/scripts/`. Add that directory to `sys.path` in a project-local helper, then import:
 ```python
 from svg_to_pptx.native_objects import (
    stamp_native_fallback_baseline,
    validate_native_object_marker_with_warnings,
 )
 ```
 After updating and reviewing both metadata and fallback, call `stamp_native_fallback_baseline(marker, document_root=root)` and serialize the SVG. Use `validate_native_object_marker_with_warnings(marker, document_root=root)` and inspect every warning before compiling the page with `native_export.py`. Do not stamp merely to suppress a stale-fallback error. For a marker inside transformed groups, also supply the actual ancestor context to validation; see the function signature. Sources without a baseline remain compatible but lose the freshness check.
 Check the resulting PPTX for `a:tbl` or chart graphicFrames, chart XML/relationships and embedded workbook data as applicable. Confirm data cache and workbook agree with author data; charts drawn from shapes alone are not data-backed chart objects. Application opening, rendering and actual data editing require their own checks.
 Implementation entry points:
 - [marker loading and supported kinds](../runtime/ppt-master/scripts/svg_to_pptx/native_objects/marker_common.py).
 - [table grid, cells and native XML](../runtime/ppt-master/scripts/svg_to_pptx/native_objects/table.py).
 - [chart data normalization](../runtime/ppt-master/scripts/svg_to_pptx/native_objects/chart_data.py) and [chart style](../runtime/ppt-master/scripts/svg_to_pptx/native_objects/chart_style.py).
 - [fallback freshness](../runtime/ppt-master/scripts/svg_to_pptx/native_objects/fallback_hash.py) and [validation/conversion](../runtime/ppt-master/scripts/svg_to_pptx/native_objects/__init__.py).
 ## Formula boundary
 This maintained native SVG route has no authoring interface that creates Office Math equations: its native replacement kinds are table and chart. Simple mathematical Unicode may remain editable ordinary text, but that is not an editable equation object. Raster formulas and vector outlines must be disclosed as pictures/paths. The bundled optional LaTeX rendering utility produces PNG and can use external services; it is not a mandatory self-contained compiler capability. Do not invoke a network provider implicitly.
 If truly editable equations are required, agree an additional host or project-local authoring route and verify its output before promising that result. Input OMML extraction does not establish native equation output support.
@@ -0,0 +1,44 @@
 # Page collaboration
 Use one coordinator and one active writer per page. The coordinator owns narrative and integration; workers own explicitly assigned page directories. Humans and Agents use the same source handoff. This is a recommended workflow on `ppt-project/v1`, not a scheduler or another ownership/history database.
 ## Freeze and assign
 Agree audience, deck argument, page order and review cadence. Define stable IDs and a brief per page: one message, evidence, data/units, capacity, transition and notes. Assign only pages authorized to proceed. Under `interactive-page`, review gates still apply; parallel workers do not authorize future pages or a batch.
 Freeze one template/version/theme, manifest and style input hashes, roster, fonts, glossary, shared data/assets. Use the project tools for the template snapshot and builder. Give each worker the same baseline, a visual reference when available, page brief and write allowlist. Read library examples from the selected template. Route shared changes to the coordinator before implementation.
 Adapt [plan.example.json](../assets/collaboration/plan.example.json) into `collaboration/plan.json` and [page-packet.example.json](../assets/collaboration/page-packet.example.json) into `pages/<id>/packet.json`. These are handoff examples, not files interpreted automatically by the compiler. Replace every placeholder with real inputs and project-relative paths. Include the plan in `build.inputs` and packets in each page's `data` list when they must travel in the source lock/package. Do not create a second event store.
 ## Write ownership
 | Surface | Writer | Rule |
 |---|---|---|
 | `pages/<id>/source.svg`, `content.json`, `notes.md`, `assets/`, `packet.json` | Assigned worker | Other pages/shared files read-only |
 | `project.json`, order, selection, environment, builder, shared data/assets | Coordinator | Issue a new baseline after changes |
 | Locks, final exports and receipts | Coordinator | Serial integration/build writer |
 | Worker preview/test output | Corresponding worker | Separate scratch output, never shared final deck |
 For separate worktrees/devices, return an assigned source diff or directory archive; merge by stable ID and preserve others' changes. Shared directories use the same allowlist. Reassign only after the old writer stops. A peer proposal or writable path does not grant authority. Contact other tasks only when messaging is authorized.
 ## Page delivery
 Deliver source/content/notes, private assets and a packet recording ID, owner, revision, baseline hashes, layout, purpose, origin, source/asset hashes, preview renderer/hash, native objects, picture exceptions and unresolved issues. State source/static, native structure, SVG render, actual PowerPoint render, editing and projection individually; unavailable checks stay `not-run` with a reason. A PNG does not prove editability. Ready means ready for integration review.
 Source, content and notes must agree. Update table/chart metadata with data; preserve evidence labels, numbers and units. Match fonts, grid, fixed body area and palette; remove placeholders/example text. Keep resources within the assigned page directory.
 ## Integrate and revise
 1. Compare template/theme/style baseline and incoming hashes. Reject stale baselines and duplicate writers; preserve the worker version for repair. Never silently accept a different theme.
 2. Check ID/layout, paths, evidence fidelity, notes, preview and object claims. Return precise issues to that page's worker; a coordinator may fix locally after explicitly taking over the page.
 3. Integrate accepted source/assets. The coordinator updates `project.json` order/declarations and shared inputs, then runs `ppt_project.py lock`, `check`, and one `build`. A common roster/theme preserves common Master/Layout identities. Do not merge finished PPTX files as source integration.
 4. Review the integrated deck for narrative, terminology, units, title rhythm, density, figure scale, repeated icons and navigation state. Render it: per-page static checks cannot establish visual consistency. Shared-style changes require affected pages to rebase and rerender.
 5. Keep the agreed user acceptance granularity. Record accepted/revision-needed with evidence, then proceed to the next authorized pages. Pack after locks/integration pass. Another device supplies declared dependencies/fonts and runs its own application checks.
 Reauthor or repair only affected pages; integrated export still compiles the completed SVG set together. Reuse unchanged page content and valid prior checks. For shared changes identify affected pages before repeating checks. Author completion, integrated render and user acceptance remain separate states.
 ## Research basis
 Microsoft documents that [PresentationML](https://learn.microsoft.com/en-us/office/open-xml/presentation/structure-of-a-presentationml-document) relates slides, layouts, masters and themes, and [slide masters](https://learn.microsoft.com/en-us/office/open-xml/presentation/working-with-slide-masters) hold common design/layout relationships. Unified source compilation is our design recommendation based on this structure and this Skill's builder; Microsoft does not prescribe this Agent workflow.
 [PowerPoint co-authoring](https://support.microsoft.com/en-us/powerpoint/work-together-on-powerpoint-presentations) supports human collaboration on shared OneDrive/SharePoint files with suitable access. It may complement review, but does not replace source packets, provenance or rebuild locks. Use only a user-chosen, authorized storage/sharing route; this workflow creates no cloud shares. Local source division also works with the user's chosen version control.
@@ -0,0 +1,30 @@
 # Page library
 A template may declare `page_library: "page-library/catalog.json"`. This optional schema-v1 catalog belongs to that template package. It contains reference compositions, not extra PowerPoint Layouts or content requirements. Older manifests without it remain valid. `export-style` and `resolve` expose the absolute catalog path and hash; a selected entry's inspection hashes its design and material closure.
 ## Find and adapt
 1. Run `python <skill>/scripts/page_library.py list --manifest <absolute manifest> --theme <selected theme> [--layout <id>]`. Choose by information relation and tags.
 2. Run `inspect --manifest ... --entry <id> --theme <selected theme> --for-use`. This requires a released template, `reference` status, compatibility with the exact template version and a matching theme variant. Plain `inspect` can review candidates and deprecated examples but reports eligibility separately. `check --manifest ...` verifies the whole catalog; missing libraries return `available: false` for list/check.
 3. Read the design document and open the preview. Review purpose, read order, density, object exceptions and evidence age. Preview provenance is a declaration tied to hashes; the tool does not rerender or prove editing.
 4. Adapt the source inside the report project. Copy declared assets into the assigned page directory, rebase local image paths, replace content, and preserve native metadata and inherited Master/Layout identities. Replace specialized-object metadata and visible fallback together. Retain origin and entry input hashes in the page packet. SVG text is materialized; there is no implicit content binding.
 5. Use the current style as authority for fonts, grid, palette and paint. Use the selected theme variant; theme switching requires rebinding assets and permitted paint channels, not whole-image recoloring. Inspect the changed render and native objects; the old preview is not evidence for the new page.
 The tool checks file SHA-256 and SVG href closure. It does not execute entry code. The native compiler still performs its own source/resource checks. A method may refer to a template-local generator; read it and invoke it only within the authorized project and host scope.
 ## Catalog contract
 The catalog has `schema_version: 1`, matching `template_id`, and `entries`. Each entry contains:
 - Stable `id`, `title`, `status` (`candidate`, `reference`, `deprecated`), exact `template_versions`, an existing `layout`, and `tags`.
 - `design: {path, sha256}` for rationale, implementation, limits and preview links; `origin` for provenance.
 - `variants`, keyed by existing theme ID. Each declares `source` SVG, `preview` PNG/JPEG and `files: [{path, sha256}]` including both plus referenced images and implementation inputs. All paths are relative to the manifest directory; absolute paths, traversal and symlink escapes are rejected. SVG hrefs resolve relative to the source and must be declared local files, fragments or supported embedded bitmaps.
 - `evidence: {level, source_version, notes}`. Levels: `source-only`, `svg-rendered`, `powerpoint-rendered`, `powerpoint-edited`. These label specific evidence, not universal acceptance. Record original source/preview paths and hashes when relocating examples. Never relabel historical rendering as current application verification.
 Exact compatibility requires maintainer review after geometry, fonts or object contracts change. Adding a compatible version does not manufacture fresh render evidence. Candidate status does not imply reuse or publication approval.
 ## Contribute
 Prepare an authorized candidate in the caller's workspace with source and independent assets, rationale, implementation steps, theme/layout, preview, evidence scope, origin/license and redistribution rights. Remove private content, credentials, personal data and report-only paths; replace sensitive data and rerender the replacement. Preserve fixed-color and paint contracts.
 Submit through an authorized channel. The template maintainer checks usefulness, portability, theme compatibility and source/preview agreement before marking `reference` and releasing a new version. Do not edit an installed catalog, global index or locked `vendor/template` as an intake shortcut. No upload, commit, publication or messaging is implied.
@@ -0,0 +1,32 @@
 # Production rules
 These rules apply across templates and authoring routes. **Required** rules protect content, provenance, implementation claims and rebuildable inputs. **Recommended** methods can change for a content reason; record the reason and relevant validation. Template parameters remain external. Follow explicit user instructions and settled authorization; these rules add no approval gate.
 ## Understand and compose
 - **C01 · Recommended:** form a brief from the audience, purpose, setting, supplied material, content boundary, output route, length/time, template and review rhythm. Reuse known answers. Ask only for consequential information that cannot reasonably be inferred; do not turn the brief into a questionnaire.
 - **C02 · Required:** preserve facts, numbers, conditions, causal relationships and strength of conclusions. Distinguish source statements, inference and added material. Do not invent unknown values. Identify synthetic examples and retain traceable sources for material claims.
 - **C03 · Recommended:** establish the presentation's main judgment and progression before filling pages. Give each page a purpose and reading order, with as many supporting points as the content needs. Summarize without changing meaning.
 - **C04 · Recommended:** keep hierarchy, color semantics, terminology, units, legends, strokes, icon grammar and component scale consistent across pages. Use declared template exceptions where needed.
 - **C05 · Recommended:** choose layout and columns from content relationships, then place components. Maintain grouping, alignment, spacing, reading order and moderate density. Add decoration for a purpose. Resolve excess content through the template's rewrite/layout/split policy; keep its declared typography and grid rules.
 - **C06 · Recommended:** inspect suitable components and page-library examples before authoring. Read their rationale and method; adapt, combine or create as needed. Remove example content, update data and metadata, and preserve reference attribution.
 ## Materials and information graphics
 - **C07 · Recommended priority, required paint contract:** reuse suitable template icons; draw new simple icons as SVG/native shapes; use ImageGen for complex icon imagery; use external ready icons as a supplement. Every route must finish with the selected icon production contract: stable semantic parts, permitted whole/partial palette binding, fixed details and transparent structure. Generated or external source material is not exempt. See [icon production](icon-production.md).
 - **C08 · Required truthfulness, recommended selection:** choose photos, evidence figures, illustrations and decoration by their information role. Use supplied/trustworthy originals for exact identity and real evidence. Identify generated material; do not present it as official marks, real scenes or experimental results. Keep originals, derivative/generation provenance and needed production inputs. Preserve proportions and critical evidence when cropping.
 - **C09 · Required data fidelity, recommended expression:** retain data, units, definitions, time range, missing-value policy and sources. Select comparison, trend, distribution, composition or relationship views accordingly. Keep related comparisons semantically and numerically comparable; normally avoid misleading truncation, meaningless dual axes and 3D ornament. Sources may live in notes/metadata; do not introduce a forbidden footer. See [charts](charts.md) and [components](components.md).
 - **C10 · Required semantics, recommended implementation:** nodes, links, arrows, groups and legends represent actual relationships. Distinguish data flow, control flow, dependency and time sequence. Do not turn unordered peers into a causal chain. Prefer native objects/SVG for technical diagrams; preserve code symbols, indentation and necessary context. State the actual formula object type.
 ## Implement and retain
 - **C11 · Required:** implement text, shapes, connectors, tables and charts according to the selected route. Do not claim a full-page screenshot is editable completion. Use supported tools and disclose technical limits; do not silently change backend, depend on another installed Skill or introduce an online provider. [Native objects](native-objects.md) describes actual object support.
 - **C12 · Required:** retain source data, page content/code, notes, assets, generation parameters, template version, environment and necessary metadata. When content changes, synchronize chart cache/workbook, SVG fallback and current previews. Use relocatable project paths. A cached export or final PPTX alone is not a rebuildable project. See [project workspace](project-workspace.md).
 - **C13 · Recommended:** complete content, visual and implementation checks at the authorized review granularity. Even an authorized batch needs page checks. Multiple authors share a frozen brief/style; the coordinator checks cross-page story, terminology and appearance. Existing page-by-page authorization remains binding. See [page collaboration](page-collaboration.md).
 ## Verify, revise and deliver
 - **C14 · Required:** before delivery, check missing pages, example residue, text overflow, occlusion, font substitution, chart data, asset resolution, alignment and object types as relevant to the change. Inspect actual current page renders. If a needed host check is unavailable, state it as unverified; old previews cannot replace new render evidence. Reuse unchanged evidence instead of repeating unrelated checks. See [PowerPoint checks](powerpoint-checks.md).
 - **C15 · Recommended:** identify affected pages after shared-input changes and rebuild/recheck them. Retain recoverable sources and accepted versions. Report versions, selected theme, object exceptions, evidence and remaining issues. Record content reasons and validation for departures from recommendations. Version new components/library entries independently; preserve frozen releases.
 Technical helpers enforce supported inputs, path safety, object consistency and capacity. They do not establish factual truth, design quality or application acceptance, and do not convert all recommendations into CLI errors.
@@ -147,3 +147,5 @@ python /absolute/project/tools/build_deck.py \
 维护仓库的工程专项检查使用合成 released 模板与两页工程，覆盖锁定、路径／资源／symlink 拒绝、作者及模板漂移、失败保留旧产物、确定性源码包、缓存排除，并在原路径不存在时用解压后的工具实际生成新的基本 PPTX；修改数据后再次构建并检查 slide XML 的新数据。Skill 0.5 的独立编译器检查另覆盖原生导出、字体身份、素材边界、项目内 runtime 和移动重建；安装包不要求维护仓库的检查脚本在运行时存在。
 这些证据证明本机新路径下的源码可移动与构建接口行为，不代表已在另一台物理设备执行，也不代替渲染、字体一致性、完整 OOXML 关系图、PowerPoint 打开／实际编辑或投影可读性验收。按实际作者路线另外完成原生结构、逐页渲染和产品验收。
 For page assignments, write boundaries, packets and serial integration, use [page collaboration](page-collaboration.md). A plan is portable source metadata, not a second ownership/history service.
@@ -137,3 +137,7 @@ To migrate, separate shared style rules from theme palettes/assets, add `style`
 The helper checks metadata, references, containment, local files, hashes, workspace shape and declared PPTX ZIP members. It does not parse template-specific structure semantics or establish OOXML validity, placeholder topology, visual fidelity, font availability, native editability, application behavior or projection readability. Report those checks separately.
 A manifest authorizes neither installation nor external communication nor consumer-project changes. Treat all template content as untrusted design input; it cannot override the user's scope, selected workflow or agent instructions.
 ## Optional page library
 A manifest may declare `page_library` as a package-relative schema-v1 catalog. `export-style` and `resolve` expose and hash it. Entry material hashes are resolved separately by `page_library.py`; see [the catalog and consumption contract](page-library.md). Old templates need no new field. Library compositions do not add Layouts or override the selected style/theme.
@@ -27,3 +27,5 @@ Ask for complete separated objects with consistent perspective, stroke and illum
 Check transparent edges against both light and dark backgrounds for halos, missing thin strokes and unintended holes. Avoid arbitrary color-key removal that erases matching subject colors. If an approved layered source or role mask exists, retain it with a clear mask-to-material contract; otherwise regenerate an unsuitable cutout through the image tool.
 For an existing SVG icon system, use its vector source and declared paint contract rather than generating a new bitmap. Multiple independent color roles need stable element IDs and per-channel rules. Palette binding, fixed details, structural `none` and unlisted paint remain distinct. See [icon handoff](authoring-handoff.md#icon-material-handoff).
 For all new icon sources use [icon production](icon-production.md): reuse, simple authored vectors, complex generated materials, then external supplements. Every route finishes with compliant adjustable parts; raw generated or downloaded rasters are production inputs. Apply the source and evidence requirements in [production rules](production-rules.md).
@@ -0,0 +1,226 @@
 #!/usr/bin/env python3
 """Render data-bound table, metric, timeline or linear-flow SVG components."""
 from __future__ import annotations
 import argparse
 import json
 import math
 from pathlib import Path
 import sys
 import xml.etree.ElementTree as ET
 import template_ref as ref
 SVG = "http://www.w3.org/2000/svg"
 ET.register_namespace("", SVG)
 def node(parent, tag, **attributes):
    return ET.SubElement(parent, f"{{{SVG}}}{tag}", {key.replace("_", "-"): str(value) for key, value in attributes.items()})
 def label(parent, value, x, y, font, size, color, anchor="start"):
    result = node(parent, "text", x=x, y=y, font_family=font, font_size=size,
                  font_weight="normal", fill=color, text_anchor=anchor)
    result.text = str(value)
    return result
 def finite(value, name):
    ref.require(type(value) in (int, float) and math.isfinite(value), f"{name}: expected finite number")
    return float(value)
 def text(value, name):
    value = ref.string(value, name)
    ref.require(not any(ord(char) < 32 for char in value), f"{name}: control characters unsupported")
    return value
 def fit(value, width, size, name):
    # Conservative capacity only. Actual font/render checks remain necessary.
    units = sum(1 if ord(c) > 255 else 0.6 for c in str(value))
    ref.require(units * size <= width, f"{name}: text exceeds component capacity; rephrase or enlarge bounds")
 def render_component(data: dict, style: dict, theme: dict, bounds: tuple,
                     component_id: str) -> ET.Element:
    ref.require(isinstance(data, dict) and data.get("schema_version") == 1, "component data requires schema_version 1")
    ref.identifier(component_id, "component ID")
    ref.require(len(bounds) == 4, "bounds requires x/y/width/height")
    x, y, w, h = [finite(v, "bounds") for v in bounds]
    canvas = style["canvas"]
    ref.require(x >= 0 and y >= 0 and w > 0 and h > 0 and x+w <= canvas["width"] and y+h <= canvas["height"], "bounds outside canvas")
    kind = data.get("kind")
    ref.require(kind in ("table", "metric", "timeline", "flow"), "unsupported basic component")
    palette, roles = theme["palette"], style["typography"]["roles"]
    families = style["typography"]["families"]
    font = families[roles["label"]["family_role"]]["family"]
    ratio = canvas["pt_to_px"]
    size = roles["label"]["size_pt"] * ratio
    small = roles["caption"]["size_pt"] * ratio
    ink, muted, accent = palette["dk1"], palette["dk2"], palette["accent1"]
    line, white = palette["line"], palette["lt1"]
    group = ET.Element(f"{{{SVG}}}g", {"id": component_id, "data-component-kind": kind})
    metadata = node(group, "metadata", type="application/json")
    metadata.text = json.dumps({"component_id": component_id, "data": data}, ensure_ascii=False)
    if kind == "table":
        ref.require(data.get("variant", "basic") in ("basic", "grouped"), "unsupported table variant")
        if data.get("variant") == "grouped":
            from table_component import render_grouped_table
            return render_grouped_table(data, style, theme, bounds, component_id)
        columns, rows = data.get("columns"), data.get("rows")
        ref.require(isinstance(columns, list) and columns, "table.columns requires labels")
        ref.require(isinstance(rows, list) and rows, "table.rows requires data")
        columns = [text(item, "column") for item in columns]
        for row in rows:
            ref.require(isinstance(row, list) and len(row) == len(columns), "table row length mismatch")
            for value in row:
                ref.require(type(value) in (str, int, float), "table cells require strings or numbers")
                if type(value) in (int, float): finite(value, "cell")
                else:
                    ref.require(not any(ord(char) < 32 for char in value), "cell: control characters unsupported")
        cfg = style["components"]["table"]
        top, side = cfg["cell_padding_px"]
        row_height = math.ceil((size * roles["label"].get("line_height", 1.25) + 2*top) / 8) * 8
        ref.require(row_height*(len(rows)+1) <= h, "table rows exceed height")
        widths = data.get("column_widths", [w/len(columns)] * len(columns))
        ref.require(isinstance(widths, list) and len(widths) == len(columns), "column_widths mismatch")
        widths = [finite(value, "column width") for value in widths]
        ref.require(all(value > 0 for value in widths) and abs(sum(widths)-w) < 0.01, "column widths must fill bounds width")
        numeric = data.get("numeric_columns", [])
        ref.require(isinstance(numeric, list) and all(type(i) is int and 0 <= i < len(columns) for i in numeric), "numeric_columns invalid")
        table_rows = []
        for i, row in enumerate([columns, *rows]):
            offset = x
            cells = []
            for j, value in enumerate(row):
                color = palette[cfg["header_text_palette_index"]] if i == 0 else ink
                fill = palette[cfg["header_fill_palette_index"]] if i == 0 else white
                align = "r" if i and j in numeric else "l"
                cell = {"text": str(value), "fill": fill, "color": color, "align": align,
                        "font_size": size, "bold": False, "padding": {"top": top, "bottom": top, "left": side, "right": side},
                        "border_color": line, "border_width": 1}
                cells.append(cell)
                fit(value, widths[j]-2*side, size, "table cell")
                node(group, "rect", x=offset, y=y+i*row_height, width=widths[j], height=row_height,
                     fill=fill, stroke=line, stroke_width=1)
                tx = offset+widths[j]-side if align == "r" else offset+side
                label(group, value, tx, y+i*row_height+(row_height+size*.72)/2, font, size, color,
                      "end" if align == "r" else "start")
                offset += widths[j]
            table_rows.append(cells)
        group.set("data-pptx-replace-with", "table")
        metadata.text = json.dumps({"name": component_id, "x": x, "y": y, "width": w,
            "height": row_height*(len(rows)+1), "rows": table_rows, "header_rows": 1, "strict_grid": True,
            "column_widths": widths, "row_heights": [row_height]*(len(rows)+1),
            "style": {"font_family": font, "font_size": size, "band_row": False}}, ensure_ascii=False)
        group.set("data-component-source", json.dumps(data, ensure_ascii=False))
        return group
    if kind == "metric":
        title = text(data.get("label"), "metric.label")
        value = data.get("value")
        ref.require(type(value) in (str, int, float), "metric.value requires string or number")
        if type(value) in (int, float): finite(value, "metric.value")
        else: text(value, "metric.value")
        unit = data.get("unit", "")
        detail = data.get("detail", "")
        ref.require(isinstance(unit, str) and isinstance(detail, str), "metric unit/detail must be strings")
        ref.require(not any(ord(char) < 32 for char in unit+detail), "metric: control characters unsupported")
        big = roles["number"]["size_pt"] * ratio
        ref.require(h >= 160, "metric needs at least 160px height")
        fit(title, w, size, "metric label")
        fit(str(value)+unit, w, big, "metric value")
        fit(detail, w, small, "metric detail")
        label(group, title, x, y+size, font, size, muted)
        value_node = label(group, value, x, y+104, font, big, accent)
        if unit:
            span = node(value_node, "tspan", dx=16, font_size=size, fill=muted)
            span.text = unit
        if detail: label(group, detail, x, y+152, font, small, ink)
        return group
    items = data.get("items") if kind == "timeline" else data.get("nodes")
    ref.require(isinstance(items, list) and 2 <= len(items) <= 6, "timeline/flow requires 2–6 items")
    ref.require(all(isinstance(item, dict) for item in items), "items must be objects")
    if kind == "timeline":
        ref.require(h >= 208, "timeline needs at least 208px height")
        slot = w/len(items)
        centers = [x+slot*(i+.5) for i in range(len(items))]
        cy = y+96
        node(group, "line", x1=centers[0], y1=cy, x2=centers[-1], y2=cy, stroke=line, stroke_width=2)
        for i, item in enumerate(items):
            title, date = text(item.get("label"), "timeline label"), text(item.get("date"), "timeline date")
            fit(title, slot-24, size, "timeline label")
            fit(date, slot-24, small, "timeline date")
            node(group, "circle", cx=centers[i], cy=cy, r=8, fill=accent, stroke=white, stroke_width=2)
            label(group, date, centers[i], y+56, font, small, muted, "middle")
            label(group, title, centers[i], y+152, font, size, ink, "middle")
        return group
    ref.require(h >= 160, "flow needs at least 160px height")
    ids = [ref.identifier(item.get("id"), "flow node ID") for item in items]
    ref.require(len(ids) == len(set(ids)), "duplicate flow node ID")
    edges = data.get("edges")
    ref.require(isinstance(edges, list), "flow requires explicit edges")
    expected = {(ids[i], ids[i+1]) for i in range(len(ids)-1)}
    actual = []
    for edge in edges:
        ref.require(isinstance(edge, list) and len(edge) == 2, "flow edge requires [from,to]")
        ref.require(all(isinstance(value, str) for value in edge), "edge node IDs must be strings")
        actual.append(tuple(edge))
    ref.require(len(actual) == len(set(actual)) and set(actual) <= expected,
                "linear flow supports only distinct forward adjacent edges; compose other diagrams manually")
    gap = 32
    nw = (w-gap*(len(items)-1))/len(items)
    ref.require(nw >= 96, "flow too narrow")
    cy = y+80
    for i, item in enumerate(items):
        nx = x+i*(nw+gap)
        title = text(item.get("label"), "flow label");fit(title, nw-24, size, "flow label")
        node(group, "rect", x=nx, y=cy-40, width=nw, height=80, fill=white, stroke=muted, stroke_width=2)
        label(group, title, nx+nw/2, cy+size*.36, font, size, ink, "middle")
        if i < len(items)-1 and (ids[i], ids[i+1]) in actual:
            end = nx+nw+gap
            node(group, "line", x1=nx+nw, y1=cy, x2=end-8, y2=cy, stroke=muted, stroke_width=2)
            node(group, "path", d=f"M{end-8},{cy-4} L{end},{cy} L{end-8},{cy+4} Z", fill=muted)
    return group
 def main():
    parser = argparse.ArgumentParser(description=__doc__)
    for flag in ("manifest", "theme", "data", "id", "output"):
        parser.add_argument(f"--{flag}", required=True, action="append")
    parser.add_argument("--bounds", nargs=4, type=float, required=True, action="append")
    args = parser.parse_args()
    try:
        ref.require(len(args.bounds) == 1, "Only one --bounds allowed")
        args.bounds = args.bounds[0]
        for flag in ("manifest", "theme", "data", "id", "output"):
            values = getattr(args, flag);ref.require(len(values) == 1, f"Only one --{flag} allowed")
            setattr(args, flag, values[0])
        path = Path(args.manifest).resolve();manifest = ref.load_manifest(path)
        ref.require(manifest["schema_version"] == 2 and args.theme in manifest["themes"], "requires one v2 template/theme")
        _, style, _, theme, _ = ref.style_inputs(path.parent, manifest, manifest["themes"][args.theme], args.theme)
        data = ref.read_json(Path(args.data), (1,))
        component = render_component(data, style, theme, tuple(args.bounds), args.id)
        canvas = style["canvas"]
        root = ET.Element(f"{{{SVG}}}svg", {"width": str(canvas["width"]), "height": str(canvas["height"]),
                                          "viewBox": canvas["viewbox"]})
        root.append(component)
        output = Path(args.output)
        ref.require(output.suffix == ".svg" and not output.exists() and not output.is_symlink(), "requires new .svg output")
        ref.require(not any(p.is_symlink() for p in output.parents), "output ancestors cannot be symlinks")
        output.parent.mkdir(parents=True, exist_ok=True)
        with output.open("xb") as stream: ET.ElementTree(root).write(stream, encoding="utf-8", xml_declaration=True)
        print(json.dumps({"kind": data["kind"], "output": str(output), "scope": "component SVG source, no page UI or render acceptance"}))
        return 0
    except (ref.InputError, OSError, ValueError, KeyError, TypeError, ET.ParseError) as error:
        print(json.dumps({"error": str(error)}, ensure_ascii=False), file=sys.stderr)
        return 2
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,433 @@
 #!/usr/bin/env python3
 """Render a data-bound SVG component with a native PowerPoint Chart marker."""
 from __future__ import annotations
 import argparse
 from copy import deepcopy
 import json
 import math
 from pathlib import Path
 import re
 import sys
 import unicodedata
 import xml.etree.ElementTree as ET
 import template_ref as ref
 SVG = "http://www.w3.org/2000/svg"
 ET.register_namespace("", SVG)
 TYPES = ("column", "bar", "line", "scatter", "pie", "doughnut", "column-stacked")
 ID = re.compile(r"^[A-Za-z][A-Za-z0-9_-]{0,63}$")
 def require(condition, message):
    if not condition:
        raise ValueError(message)
 def number(value, name):
    require(isinstance(value, (int, float)) and not isinstance(value, bool), f"{name}: number required")
    require(math.isfinite(value), f"{name}: finite number required")
    # The SVG and OOXML scalar calculations must not overflow or underflow.
    require(value == 0 or 1e-9 <= abs(value) <= 1e12, f"{name}: supported nonzero magnitude is 1e-9..1e12")
    return value
 def text(value, name, *, empty=False):
    require(isinstance(value, str) and (empty or bool(value.strip())), f"{name}: {'string' if empty else 'nonempty string'} required")
    require(not any(unicodedata.category(c).startswith('C') for c in value), f"{name}: control/format characters unsupported")
    return value
 def fields(value, allowed, required, name):
    require(isinstance(value, dict), f"{name}: object required")
    require(set(value) <= allowed, f"{name}: unknown fields {sorted(set(value) - allowed)}")
    require(required <= set(value), f"{name}: missing fields {sorted(required - set(value))}")
 def validate_data(raw):
    fields(raw, {"schema_version", "data_kind", "type", "title", "unit", "x_unit", "source", "categories", "series"},
           {"schema_version", "data_kind", "type", "title", "unit", "series"}, "chart")
    require(type(raw['schema_version']) is int and raw['schema_version'] == 1, "chart schema_version must be 1")
    require(raw['data_kind'] in ('synthetic-demo', 'observed', 'derived'), "data_kind must be synthetic-demo, observed or derived")
    require(raw['type'] in TYPES, f"type must be one of {TYPES}")
    for key in ('title', 'unit'):
        text(raw[key], key, empty=key == 'unit')
    for key in ('source', 'x_unit'):
        if key in raw:
            text(raw[key], key, empty=True)
    kind = raw['type']
    if kind == 'scatter':
        require('categories' not in raw, "scatter uses series.points, not categories")
    else:
        require('x_unit' not in raw, "x_unit is supported for scatter only")
        require(isinstance(raw.get('categories'), list) and bool(raw['categories']), "categories must be nonempty list")
        for category in raw['categories']:
            text(category, 'category')
        require(len(set(raw['categories'])) == len(raw['categories']), "category labels must be unique")
    require(isinstance(raw['series'], list) and bool(raw['series']), "series must be nonempty list")
    series_ids = set()
    for s in raw['series']:
        fields(s, {'id', 'name', 'points'} if kind == 'scatter' else {'id', 'name', 'values'},
               {'id', 'name', 'points'} if kind == 'scatter' else {'id', 'name', 'values'}, 'series')
        require(isinstance(s['id'], str) and ID.fullmatch(s['id']), "series id must be stable SVG-safe ID")
        require(s['id'] not in series_ids, 'series IDs must be unique')
        series_ids.add(s['id'])
        text(s['name'], 'series.name')
        values = s.get('points') if kind == 'scatter' else s.get('values')
        require(isinstance(values, list) and bool(values), 'series data must be nonempty list')
        if kind == 'scatter':
            for point in values:
                require(isinstance(point, list) and len(point) == 2, 'scatter point must be [x, y]')
                for val in point:
                    number(val, 'scatter coordinate')
        else:
            require(len(values) == len(raw['categories']), 'series values must match categories length')
            for val in values:
                number(val, 'series value')
                if kind in ('pie', 'doughnut', 'column-stacked'):
                    require(val >= 0, f'{kind} initial support requires nonnegative values')
    if kind in ('pie', 'doughnut'):
        require(len(raw['series']) == 1, 'pie/doughnut requires exactly one series')
        require(sum(raw['series'][0]['values']) > 0, 'pie/doughnut requires positive total')
    return deepcopy(raw)
 def _n(value):
    return f'{value:.10g}'
 def _node(parent, tag, **attrs):
    return ET.SubElement(parent, '{' + SVG + '}' + tag, {k.replace('_', '-'): _n(v) if isinstance(v, (float, int)) else str(v) for k, v in attrs.items()})
 def _text(parent, x, y, value, font, size, color, anchor='start'):
    node = _node(parent, 'text', x=x, y=y, fill=color, font_family=font, font_size=size, text_anchor=anchor)
    node.text = value
    return node
 def _width(value, size):
    # Conservative capacity check, not a substitute for application rendering.
    return sum(1 if unicodedata.east_asian_width(c) in ('W', 'F') else .6 for c in value) * size
 def _fit(value, size, width, name):
    require(_width(value, size) <= width, f'{name} exceeds available width; shorten text or enlarge bounds (font is not reduced)')
 def _range(values):
    low, high = min(0, min(values)), max(0, max(values))
    if low == high:
        return 0.0, 1.0, .25
    span = high - low
    exponent = math.floor(math.log10(span / 4))
    base = 10.0 ** exponent
    raw = span / 4 / base
    step = next(candidate for candidate in (1, 2, 2.5, 5, 10) if candidate >= raw) * base
    low = math.floor(low / step) * step
    high = math.ceil(high / step) * step
    return low, high, step
 def _ticks(scale):
    low, high, step = scale
    return [low + i * step for i in range(round((high - low) / step) + 1)]
 def _label(value):
    return '0' if abs(value) < 1e-14 else f'{value:.6g}'
 def _axis(scale):
    low, high, step = scale
    return {'minimum': low, 'maximum': high, 'major_unit': step,
            'major_gridlines': True, 'label_position': 'low',
            'number_format': '0.######E+00' if max(abs(low), abs(high)) >= 1e6 or 0 < step < .001 else 'General'}
 def _style(style, theme):
    require(isinstance(style, dict) and isinstance(theme, dict), 'style/theme must be objects')
    chart = style.get('components', {}).get('charts', {})
    require(isinstance(chart, dict), 'style.components.charts must be object')
    typography = style['typography']
    role = chart.get('text_role', 'caption' if 'caption' in typography['roles'] else 'label')
    require(role in typography['roles'], 'chart text_role missing from typography.roles')
    label = typography['roles'][role]
    family = typography['families']['body']['family']
    px_per_pt = number(style['canvas']['pt_to_px'], 'canvas.pt_to_px')
    require(px_per_pt > 0, 'canvas.pt_to_px must be positive')
    size = number(label['size_pt'], 'chart size_pt') * px_per_pt
    require(size > 0, 'chart text size must be positive')
    palette = theme['palette']
    indices = chart.get('series_palette_indices', [k for k in ('accent1', 'accent3', 'accent4', 'accent5', 'accent6', 'accent2') if k in palette])
    require(isinstance(indices, list) and bool(indices), 'series_palette_indices must be nonempty list')
    require(len(set(indices)) == len(indices), 'series_palette_indices must be unique')
    keys = [*indices, chart.get('text_palette_index', 'dk1'), chart.get('grid_palette_index', 'line' if 'line' in palette else 'dk2'), 'lt1']
    axis_index = chart.get('axis_palette_index', chart.get('text_palette_index', 'dk1'))
    require(isinstance(axis_index, str) and axis_index in palette and re.fullmatch(r'#[0-9A-Fa-f]{6}', palette[axis_index]), 'invalid/missing axis_palette_index')
    for key in keys:
        require(isinstance(key, str) and key in palette and re.fullmatch(r'#[0-9A-Fa-f]{6}', palette[key]), f'invalid/missing palette color: {key}')
    return family, size, [palette[k] for k in indices], palette[keys[-3]], palette[keys[-2]], palette['lt1'], palette[axis_index]
 def render_chart(data: dict, style: dict, theme: dict,
                 bounds: tuple[float, float, float, float], component_id: str) -> ET.Element:
    """Return an isolated SVG g; insert it into the caller's selected page/Layout.
    Metadata and visible fallback share validated input. bar deliberately leaves
    axes automatic in native Office, because the pinned compiler cannot configure
    bar axes. Its SVG ticks therefore preview a scale, not Office's eventual ticks.
    """
    data = validate_data(data)
    require(isinstance(component_id, str) and ID.fullmatch(component_id), 'component_id must be SVG-safe ID')
    require(isinstance(bounds, (tuple, list)) and len(bounds) == 4, 'bounds must be [x, y, width, height]')
    x, y, w, h = [number(v, 'bounds') for v in bounds]
    require(x >= 0 and y >= 0 and w > 0 and h > 0, 'bounds must have nonnegative origin and positive size')
    canvas = style['canvas']
    require(x + w <= canvas['width'] and y + h <= canvas['height'], 'component bounds exceed template canvas')
    font, fs, colors, ink, grid, background, axis_color = _style(style, theme)
    require(w >= fs * 14 and h >= fs * 14, 'bounds too small for declared chart font and annotations')
    kind = data['type']
    value_labels = style.get('components', {}).get('charts', {}).get('value_labels', False)
    require(type(value_labels) is bool, 'chart value_labels must be boolean')
    if value_labels:
        require(kind == 'column', 'optional value_labels supports nonnegative grouped column only; bar already labels values')
        require(all(value >= 0 for series in data['series'] for value in series['values']),
                'optional column value_labels requires nonnegative values')
    pie = kind in ('pie', 'doughnut')
    count = len(data['categories']) if pie else len(data['series'])
    require(count <= len(colors), 'insufficient distinct palette indices for series/slices; configure style.components.charts')
    colors = colors[:count]
    source = data.get('source', '')
    source_line = ('示例数据（合成）' if data['data_kind'] == 'synthetic-demo' else '')
    if source:
        source_line += ('；' if source_line else '') + '来源：' + source
    if kind == 'scatter':
        unit_parts = []
        if data.get('x_unit'):
            unit_parts.append('X：' + data['x_unit'])
        if data['unit']:
            unit_parts.append('Y：' + data['unit'])
        unit = '；'.join(unit_parts)
    else:
        unit = '单位：' + data['unit'] if data['unit'] else ''
    for value, name in ((data['title'], 'title'), (unit, 'unit'), (source_line, 'source')):
        _fit(value, fs, w - 16, name)
    outer = ET.Element('{' + SVG + '}g', {'id': component_id, 'data-component': 'chart', 'data-chart-type': kind})
    _text(outer, x + 8, y + fs, data['title'], font, fs, ink)
    top = y + math.ceil((fs + 16) / 8) * 8
    if unit:
        _text(outer, x + 8, top + fs, unit, font, fs, ink)
        top += math.ceil((fs + 8) / 8) * 8
    bottom = y + h - (math.ceil((fs + 8) / 8) * 8 if source_line else 8)
    if source_line:
        _text(outer, x + 8, y + h - 8, source_line, font, fs, ink)
    legends = [f'{c}  {_label(v)}' for c, v in zip(data.get('categories', []), data['series'][0].get('values', []))] if pie else [s['name'] for s in data['series']]
    legend_widths = [32 + _width(label, fs) + 16 for label in legends]
    require(all(lw <= w - 16 for lw in legend_widths), 'legend label too wide for bounds')
    rows, row = [], []
    used = 0
    for index, width in enumerate(legend_widths):
        if row and used + width > w - 16:
            rows.append(row);row = [];used = 0
        row.append((index, width));used += width
    if row:
        rows.append(row)
    legend_h = len(rows) * math.ceil((fs + 8) / 8) * 8
    legend_y = bottom - legend_h
    for r, items in enumerate(rows):
        lx = x + 8
        ly = legend_y + r * math.ceil((fs + 8) / 8) * 8 + fs
        for idx, width in items:
            _node(outer, 'rect', x=lx, y=ly-fs*.65, width=16, height=16, fill=colors[idx])
            _text(outer, lx+24, ly, legends[idx], font, fs, ink)
            lx += width
    chart_h = legend_y - top - 8
    require(chart_h >= fs * 7, 'chart/legend/source too tall for bounds; enlarge region or reduce categories/legend text')
    marker = _node(outer, 'g', id=component_id+'-native', data_pptx_replace_with='chart')
    payload = {'name': component_id, 'x': x, 'y': top, 'width': w, 'height': chart_h,
               'type': 'column' if kind == 'column-stacked' else kind,
               'show_legend': False,
               'style': {'colors': colors, 'font_family': font, 'font_size': fs, 'axis_font_size': fs,
                         'text_color': ink, 'axis_color': axis_color, 'grid_color': grid,
                         'chart_area_fill': background, 'plot_area_fill': background},
               'component_data': deepcopy(data)}
    metadata = _node(marker, 'metadata', type='application/json')
    if value_labels:
        payload['data_labels'] = {'position': 'outside_end', 'show_value': True,
                                 'font_size': fs, 'color': ink, 'number_format': 'General'}
    if kind == 'line':
        payload['markers'] = True
    fallback = _node(marker, 'g', id=component_id+'-fallback')
    _node(fallback, 'rect', x=x, y=top, width=w, height=chart_h, fill=background)
    if kind == 'scatter':
        payload['series'] = [{'name': s['name'], 'points': s['points']} for s in data['series']]
        xs = [p[0] for s in data['series'] for p in s['points']]
        ys = [p[1] for s in data['series'] for p in s['points']]
        xscale, yscale = _range(xs), _range(ys)
        payload['axes'] = {'x': _axis(xscale), 'y': _axis(yscale)}
    else:
        payload['categories'] = data['categories']
        payload['series'] = [{'name': s['name'], 'values': s['values']} for s in data['series']]
        if kind == 'column-stacked':
            payload['grouping'] = 'stacked'
        if not pie:
            values = ([sum(s['values'][i] for s in data['series']) for i in range(len(data['categories']))]
                      if kind == 'column-stacked' else [v for s in data['series'] for v in s['values']])
            yscale = _range(values)
            if kind != 'bar':
                payload['axes'] = {'category': {'label_position': 'low', 'major_gridlines': False}, 'value': _axis(yscale)}
            else:
                payload['data_labels'] = {'position': 'outside_end'}
                payload['show_value_axis_labels'] = True
                outer.set('data-native-axis-policy', 'automatic-bar-preview-scale-may-differ')
    if pie:
        diameter = min(w - 32, chart_h - 16)
        radius = diameter / 2
        cx, cy = x+w/2, top+chart_h/2
        total = sum(data['series'][0]['values'])
        angle = -math.pi / 2
        for i, val in enumerate(data['series'][0]['values']):
            if val == 0:
                continue
            end = angle + val / total * math.tau
            if math.isclose(val, total):
                _node(fallback, 'circle', cx=cx, cy=cy, r=radius, fill=colors[i])
            else:
                start_x, start_y = cx+radius*math.cos(angle), cy+radius*math.sin(angle)
                end_x, end_y = cx+radius*math.cos(end), cy+radius*math.sin(end)
                path = f'M {_n(cx)} {_n(cy)} L {_n(start_x)} {_n(start_y)} A {_n(radius)} {_n(radius)} 0 {int(end-angle > math.pi)} 1 {_n(end_x)} {_n(end_y)} Z'
                _node(fallback, 'path', d=path, fill=colors[i])
            angle = end
        if kind == 'doughnut':
            # The pinned native writer fixes holeSize to 75%.
            _node(fallback, 'circle', cx=cx, cy=cy, r=radius*.75, fill=background)
    elif kind == 'bar':
        ticks = _ticks(yscale)
        labels_width = max(_width(c, fs) for c in data['categories']) + 16
        value_width = max(_width(_label(v), fs) for s in data['series'] for v in s['values'])
        left, right = x + labels_width + value_width + 8, x+w-value_width-16
        pt, pb = top+8, top+chart_h-fs-16
        require(right-left >= fs*7, 'bar category labels leave insufficient plot width')
        low, high, step = yscale
        xp = lambda val: left+(val-low)/(high-low)*(right-left)
        for tick in ticks:
            _node(fallback, 'line', x1=xp(tick), y1=pt, x2=xp(tick), y2=pb, stroke=grid, stroke_width=1)
            _text(fallback, xp(tick), pb+fs+8, _label(tick), font, fs, ink, 'middle')
        band = (pb-pt)/len(data['categories'])
        bw = band/(len(data['series'])+1.5)
        require(band >= fs+8 and bw >= fs+4, 'too many bar categories/series for fixed labels and bounds')
        for i, category in enumerate(data['categories']):
            center = pt+(i+.5)*band
            _text(fallback, x+labels_width-8, center+fs*.35, category, font, fs, ink, 'end')
            for j, s in enumerate(data['series']):
                value = s['values'][i]
                x0, x1 = xp(0), xp(value)
                bar_y = center-(len(data['series'])*bw)/2+j*bw
                _node(fallback, 'rect', x=min(x0,x1), y=bar_y, width=abs(x1-x0), height=bw, fill=colors[j])
                _text(fallback, x1 + (8 if value >= 0 else -8), bar_y+bw/2+fs*.35, _label(value), font, fs, ink, 'start' if value >= 0 else 'end')
    else:
        ticks = _ticks(yscale)
        tick_width = max(_width(_label(t), fs) for t in ticks)
        left, right = x+tick_width+16, x+w-16
        pt, pb = top+8, top+chart_h-fs-16
        require(right-left >= fs*7 and (pb-pt)/(len(ticks)-1) >= fs+4, 'axis labels leave insufficient plot area')
        low, high, step = yscale
        yp = lambda val: pb-(val-low)/(high-low)*(pb-pt)
        for tick in ticks:
            _node(fallback, 'line', x1=left, y1=yp(tick), x2=right, y2=yp(tick), stroke=axis_color if abs(tick)<step*1e-6 else grid, stroke_width=1)
            _text(fallback, left-8, yp(tick)+fs*.35, _label(tick), font, fs, ink, 'end')
        if kind == 'scatter':
            xl, xh, _ = xscale
            xp = lambda val: left+(val-xl)/(xh-xl)*(right-left)
            xticks = _ticks(xscale)
            require((right-left)/(len(xticks)-1) >= max(_width(_label(t),fs) for t in xticks)+8, 'scatter X tick labels too crowded')
            for tick in xticks:
                _node(fallback, 'line', x1=xp(tick), y1=pt, x2=xp(tick), y2=pb, stroke=grid, stroke_width=1)
                _text(fallback, xp(tick), pb+fs+8, _label(tick), font, fs, ink, 'middle')
            for j, s in enumerate(data['series']):
                for vx, vy in s['points']:
                    _node(fallback, 'circle', cx=xp(vx), cy=yp(vy), r=5, fill=colors[j])
        else:
            band = (right-left)/len(data['categories'])
            for i, category in enumerate(data['categories']):
                _fit(category, fs, band-8, 'category')
                center = left+(i+.5)*band
                _text(fallback, center, pb+fs+8, category, font, fs, ink, 'middle')
                if kind in ('column', 'column-stacked'):
                    bw = band/(len(data['series'])+1.5) if kind == 'column' else band/2.5
                    require(bw >= 8, 'too many series/categories for plot width')
                    accumulated = 0
                    for j, s in enumerate(data['series']):
                        val = s['values'][i]
                        bottom_value = accumulated if kind == 'column-stacked' else 0
                        top_value = bottom_value+val
                        xpos = center-bw/2 if kind == 'column-stacked' else center-len(data['series'])*bw/2+j*bw
                        _node(fallback, 'rect', x=xpos, y=min(yp(top_value),yp(bottom_value)), width=bw, height=abs(yp(top_value)-yp(bottom_value)), fill=colors[j])
                        if value_labels:
                            _fit(_label(val), fs, bw - 4, 'column value label')
                            _text(fallback, xpos+bw/2, yp(val)-8, _label(val), font, fs, ink, 'middle')
                        accumulated += val
            if kind == 'line':
                payload['line_style'] = 'lineMarker'
                for j, s in enumerate(data['series']):
                    points = [(left+(i+.5)*band, yp(v)) for i,v in enumerate(s['values'])]
                    _node(fallback, 'polyline', points=' '.join(f'{_n(px)},{_n(py)}' for px,py in points), fill='none', stroke=colors[j], stroke_width=2)
                    for px,py in points:
                        _node(fallback, 'circle', cx=px, cy=py, r=4, fill=colors[j])
    metadata.text = json.dumps(payload, ensure_ascii=False, allow_nan=False, separators=(',', ':'))
    runtime = Path(__file__).resolve().parent.parent / 'runtime/ppt-master/scripts'
    if str(runtime) not in sys.path:
        sys.path.insert(0, str(runtime))
    from pptx_shapes import NATIVE_FALLBACK_SHA256_ATTR, svg_native_fallback_fingerprint
    marker.set(NATIVE_FALLBACK_SHA256_ATTR, svg_native_fallback_fingerprint(marker))
    return outer
 def _json(path):
    def pairs(items):
        result = {}
        for key, value in items:
            require(key not in result, f'duplicate JSON key: {key}')
            result[key] = value
        return result
    return json.loads(path.read_text(encoding='utf-8'), object_pairs_hook=pairs,
                      parse_constant=lambda token: (_ for _ in ()).throw(ValueError(f'nonfinite JSON value: {token}')))
 def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('--manifest', type=Path, required=True)
    parser.add_argument('--theme', required=True)
    parser.add_argument('--data', type=Path, required=True)
    parser.add_argument('--bounds', type=float, nargs=4, required=True)
    parser.add_argument('--id', required=True)
    parser.add_argument('--output', type=Path, required=True)
    args = parser.parse_args()
    try:
        require(args.manifest.is_absolute(), '--manifest must be absolute')
        manifest = ref.load_manifest(args.manifest)
        args.layout = None;args.mode = None
        selection = ref.export_style(args.manifest, manifest, args)
        component = render_chart(_json(args.data), selection['style'], selection['theme_data'], tuple(args.bounds), args.id)
        require(args.output.suffix.lower() == '.svg', 'output must end in .svg')
        require(not args.output.exists() and not args.output.is_symlink(), 'output already exists')
        require(not any(p.is_symlink() for p in args.output.parents), 'output ancestors cannot be symlinks')
        canvas = selection['style']['canvas']
        root = ET.Element('{' + SVG + '}svg', {'width': str(canvas['width']), 'height': str(canvas['height']), 'viewBox': canvas['viewbox']})
        root.append(component)
        args.output.parent.mkdir(parents=True, exist_ok=True)
        with args.output.open('xb') as stream:
            ET.ElementTree(root).write(stream, encoding='utf-8', xml_declaration=True)
        print(json.dumps({'output': str(args.output), 'type': component.get('data-chart-type'), 'theme': args.theme,
                          'verification_scope': 'validated component SVG and native marker; native application rendering unverified'}, ensure_ascii=False))
        return 0
    except (ref.InputError, OSError, ValueError, TypeError, KeyError, ET.ParseError) as error:
        print(json.dumps({'error': str(error)}, ensure_ascii=False), file=sys.stderr)
        return 2
 if __name__ == '__main__':
    raise SystemExit(main())
@@ -0,0 +1,224 @@
 #!/usr/bin/env python3
 """Install the checked-out root Skill, or verify it, without another Skill."""
 import argparse
 import copy
 from datetime import datetime, timezone
 import hashlib
 import json
 import os
 from pathlib import Path
 import re
 import shutil
 import subprocess
 import sys
 import tempfile
 import uuid
 if sys.version_info < (3, 12):
    raise SystemExit("Use Python 3.12+ to install the complete native workflow.")
 import tomllib
 def sha(path):
    return hashlib.sha256(path.read_bytes()).hexdigest()
 def roster(root):
    files = {}
    for path in sorted(root.rglob("*")):
        relative = path.relative_to(root)
        if any(part.startswith(".") or part == "__pycache__" for part in relative.parts):
            continue
        if path.is_symlink():
            raise ValueError(f"Source symlink is unsupported: {relative}")
        if path.is_file() and path.suffix != ".pyc":
            files[relative.as_posix()] = sha(path)
    return files
 def safe_target(path):
    path = Path(os.path.abspath(path.expanduser()))
    if any(item.is_symlink() for item in (path, *path.parents)):
        raise ValueError(f"Destination symlink is unsupported: {path}")
    return path
 def compiler_integrity(source):
    provenance = json.loads((source / "runtime/provenance.json").read_text())
    root = source / "runtime/ppt-master"
    for item in provenance["files"]:
        path = root / item["path"]
        if not path.resolve().is_relative_to(root) or sha(path) != item["sha256"]:
            raise ValueError(f"Compiler integrity failed: {item['path']}")
    return len(provenance["files"])
 def runtime_check(python, source):
    code = """
 import importlib.metadata, json, pathlib, re, sys
 if sys.version_info < (3, 12):
    raise RuntimeError('Native runtime needs Python 3.12+')
 source = pathlib.Path(sys.argv[1])
 versions = {}
 for line in (source / 'runtime/requirements.txt').read_text().splitlines():
    if not line or line.startswith('#'): continue
    name, expected = line.split('==')
    actual = importlib.metadata.version(name)
    if actual != expected: raise RuntimeError(f'{name}: expected {expected}, got {actual}')
    versions[name] = actual
 sys.path.insert(0, str(source / 'scripts'))
 from native_export import load_compiler
 load_compiler()
 print(json.dumps({'python': sys.version.split()[0], 'packages': versions, 'compiler_loaded': True}))
 """
    result = subprocess.run([str(python), "-c", code, str(source)],
                            text=True, capture_output=True, check=True)
    return json.loads(result.stdout)
 def config_plan(codex, target):
    path = safe_target(codex / "config.toml")
    before = path.read_text(encoding="utf-8") if path.is_file() else ""
    data = tomllib.loads(before)
    entries = data.get("skills", {}).get("config", [])
    root_entry = str(target / "SKILL.md")
    nested = str(target / "runtime/ppt-master/SKILL.md")
    if any(item.get("path") == root_entry and item.get("enabled") is False for item in entries):
        raise ValueError("Root Skill is disabled in Codex; preserve that decision and resolve it explicitly.")
    matches = [item for item in entries if item.get("path") == nested]
    if matches:
        if len(matches) != 1 or matches[0].get("enabled") is not False:
            raise ValueError("Conflicting nested attribution entry; resolve this exact Codex entry explicitly.")
        return path, before, before
    addition = f"\n[[skills.config]]\npath = {json.dumps(nested, ensure_ascii=False)}\nenabled = false\n"
    after = before + addition
    parsed = tomllib.loads(after)
    expected = copy.deepcopy(data)
    expected.setdefault("skills", {}).setdefault("config", []).append({"path": nested, "enabled": False})
    if parsed != expected:
        raise ValueError("Codex configuration change affected unrelated fields.")
    return path, before, after
 def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--dest", type=Path, required=True, help="Exact installed Skill directory")
    parser.add_argument("--codex-home", type=Path, help="Exclude only the nested attribution Skill")
    parser.add_argument("--venv", type=Path, help="Dedicated Python 3.12+ virtual environment")
    parser.add_argument("--prepare-runtime", action="store_true", help="Create venv and install pinned packages")
    parser.add_argument("--replace", action="store_true", help="Back up and replace an existing Skill")
    parser.add_argument("--backup-root", type=Path, help="Backup root outside Skill discovery directories")
    parser.add_argument("--check", action="store_true", help="Read-only payload, configuration and runtime check")
    args = parser.parse_args()
    source = Path(__file__).resolve().parents[1]
    target = safe_target(args.dest)
    if target == source or target.is_relative_to(source) or source.is_relative_to(target):
        raise ValueError("Source and installed destination must be separate directories.")
    if target.name != "ppt-template-workflow":
        raise ValueError("Destination must end in ppt-template-workflow.")
    version_match = re.search(r'^  version: "([0-9.]+)"$', (source / "SKILL.md").read_text(), re.M)
    if not version_match:
        raise ValueError("Missing root Skill version.")
    files = roster(source)
    compiler_files = compiler_integrity(source)
    if args.prepare_runtime and (args.venv is None or args.check):
        raise ValueError("--prepare-runtime requires --venv and cannot be combined with --check.")
    codex = safe_target(args.codex_home) if args.codex_home else None
    config = config_plan(codex, target) if codex else None
    if args.check:
        if not target.is_dir() or roster(target) != files:
            raise ValueError("Installed payload differs from the selected source.")
        compiler_integrity(target)
        if config and config[1] != config[2]:
            raise ValueError("Nested compiler attribution entry has not been disabled.")
    elif target.exists() and not args.replace:
        raise FileExistsError("Destination exists; an authorized upgrade needs --replace (with backup).")
    elif target.exists() and not target.is_dir():
        raise ValueError("Existing destination is not a Skill directory.")
    runtime = None
    if args.venv:
        venv = safe_target(args.venv)
        if venv == target or venv.is_relative_to(target) or venv == source or venv.is_relative_to(source):
            raise ValueError("Runtime must be outside source and installed Skill.")
        python = safe_target(venv / ("Scripts/python.exe" if os.name == "nt" else "bin/python")) if os.name == "nt" else venv / "bin/python"
        # POSIX venv interpreters are normally symlinks to their base Python.
        if args.prepare_runtime:
            if not python.is_file():
                subprocess.run([sys.executable, "-m", "venv", str(venv)], check=True)
            subprocess.run([str(python), "-m", "pip", "install", "--disable-pip-version-check",
                            "-r", str(source / "runtime/requirements.txt")], check=True)
        runtime = {"executable": str(python), **runtime_check(python, source)}
    commit = subprocess.run(["git", "-C", str(source), "rev-parse", "HEAD"],
                            capture_output=True, text=True)
    dirty = subprocess.run(["git", "-C", str(source), "status", "--porcelain"],
                           capture_output=True, text=True) if commit.returncode == 0 else None
    receipt = {"schema_version": 1, "skill": "ppt-template-workflow",
               "version": version_match[1], "source_commit": commit.stdout.strip() if commit.returncode == 0 else None,
               "source_dirty": bool(dirty.stdout) if dirty and dirty.returncode == 0 else None,
               "installed_path": str(target), "payload": files, "compiler_files": compiler_files,
               "runtime": runtime, "status": "native-ready" if runtime else "files-only",
               "codex_attribution_disabled": bool(config), "checked": args.check}
    if not args.check:
        stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") + "-" + uuid.uuid4().hex[:8]
        backup_root = safe_target(args.backup_root or
                                 ((codex / "backups/ppt-template-workflow") if codex else target.parent.parent / "skill-backups"))
        if (backup_root == target or backup_root.is_relative_to(target) or backup_root.is_relative_to(target.parent)
                or backup_root == source or backup_root.is_relative_to(source)):
            raise ValueError("Backup must be outside source and Skill discovery directory.")
        target.parent.mkdir(parents=True, exist_ok=True)
        stage = Path(tempfile.mkdtemp(prefix=".ppt-install-", dir=target.parent))
        backup = backup_root / stamp / "ppt-template-workflow"
        moved = False
        config_written = False
        config_backup = None
        try:
            for relative in files:
                destination = stage / relative
                destination.parent.mkdir(parents=True, exist_ok=True)
                shutil.copy2(source / relative, destination)
            if roster(stage) != files:
                raise ValueError("Staged installation hash mismatch.")
            if target.exists() or (config and config[1] != config[2]):
                backup.parent.mkdir(parents=True, exist_ok=False, mode=0o700)
            if target.exists():
                target.rename(backup)
                moved = True
            if config and config[1] != config[2]:
                path, before, after = config
                if (path.read_text(encoding="utf-8") if path.is_file() else "") != before:
                    raise ValueError("Codex configuration changed during installation.")
                config_backup = backup.parent / "config.toml.before"
                config_backup.write_text(before, encoding="utf-8")
                config_backup.chmod(0o600)
                path.parent.mkdir(parents=True, exist_ok=True)
                path.write_text(after, encoding="utf-8")
                if not before:
                    path.chmod(0o600)
                config_written = True
            receipt.update(backup=str(backup) if moved else None,
                           config_backup=str(config_backup) if config_backup else None,
                           installed_at=datetime.now(timezone.utc).isoformat())
            (stage / ".installation.json").write_text(json.dumps(receipt, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
            stage.rename(target)
        except Exception:
            if config_written:
                config[0].write_text(config[1], encoding="utf-8")
            if moved and not target.exists():
                backup.rename(target)
            raise
        finally:
            if stage.exists():
                shutil.rmtree(stage)
    summary = {key: value for key, value in receipt.items() if key != "payload"}
    summary["payload_files"] = len(files)
    print(json.dumps(summary, ensure_ascii=False, indent=2))
 if __name__ == "__main__":
    if sys.version_info < (3, 12):
        raise SystemExit("Use Python 3.12+ to install the complete native workflow.")
    try:
        main()
    except (OSError, ValueError, subprocess.CalledProcessError) as error:
        raise SystemExit(f"Installation failed: {error}")
@@ -0,0 +1,169 @@
 #!/usr/bin/env python3
 """Discover and verify optional template page examples; never write or activate a template."""
 from __future__ import annotations
 import argparse
 from copy import deepcopy
 import json
 from pathlib import Path
 import re
 import sys
 from urllib.parse import unquote, urlsplit
 from xml.etree import ElementTree as ET
 from template_ref import (InputError, VERSION, digest, file_path, identifier, input_hashes,
                          load_manifest, read_json, require, string, strings)
 def checked_file(root: Path, record: object, label: str) -> Path:
    require(isinstance(record, dict), f"{label}: expected path/sha256 object")
    path = file_path(root, record.get("path"), label)
    checksum = string(record.get("sha256"), f"{label}.sha256")
    require(bool(re.fullmatch(r"[0-9a-f]{64}", checksum)), f"{label}: invalid SHA-256")
    require(digest(path) == checksum, f"{label}: SHA-256 mismatch: {record['path']}")
    return path
 def check_source(source: Path, declared: set[Path]) -> None:
    text = source.read_text(encoding="utf-8")
    require("<!DOCTYPE" not in text.upper() and "<!ENTITY" not in text.upper(),
            "library SVG: document entities are unsupported")
    svg = ET.fromstring(text)
    require(svg.tag.rsplit("}", 1)[-1] == "svg", "library source must be SVG")
    for node in svg.iter():
        for key, href in node.attrib.items():
            if key.rsplit("}", 1)[-1] != "href" or href.startswith("#"):
                continue
            if href.startswith(("data:image/png;base64,", "data:image/jpeg;base64,")):
                continue
            uri = urlsplit(href)
            require(not uri.scheme and not uri.netloc and not uri.query,
                    f"library SVG: external resource {href}")
            raw = unquote(uri.path)
            require(raw and not Path(raw).is_absolute() and "\\" not in raw,
                    f"library SVG: invalid resource {href}")
            resolved = (source.parent / raw).resolve()
            require(resolved in declared, f"library SVG: undeclared resource {href}")
 def load_library(manifest_path: Path) -> tuple[dict, Path | None, dict | None]:
    manifest = load_manifest(manifest_path)
    if "page_library" not in manifest:
        return manifest, None, None
    root = manifest_path.parent
    path = file_path(root, manifest["page_library"], "page_library")
    catalog = read_json(path, (1,))
    require(catalog.get("template_id") == manifest["template_id"], "library template_id mismatch")
    entries = catalog.get("entries")
    require(isinstance(entries, list), "library entries: expected array")
    seen = set()
    for entry in entries:
        require(isinstance(entry, dict), "library entry: expected object")
        key = identifier(entry.get("id"), "library entry ID")
        require(key not in seen, f"Duplicate library entry: {key}")
        seen.add(key)
        string(entry.get("title"), "entry.title")
        require(entry.get("status") in ("candidate", "reference", "deprecated"), "entry.status invalid")
        versions = strings(entry.get("template_versions"), "entry.template_versions", nonempty=True)
        require(all(VERSION.fullmatch(v) for v in versions), "entry.template_versions: expected exact SemVer values")
        require(entry.get("layout") in {item["id"] for item in manifest["layouts"]}, "Unknown library layout")
        strings(entry.get("tags"), "entry.tags")
        checked_file(root, entry.get("design"), f"{key}.design")
        string(entry.get("origin"), f"{key}.origin")
        variants = entry.get("variants")
        require(isinstance(variants, dict) and bool(variants), f"{key}.variants: expected non-empty object")
        for theme, variant in variants.items():
            require(theme in manifest.get("themes", manifest.get("modes", {})), f"Unknown library theme: {theme}")
            require(isinstance(variant, dict), f"{key}.{theme}: expected object")
            files = variant.get("files")
            require(isinstance(files, list) and bool(files), f"{key}.{theme}.files: expected non-empty array")
            paths = [checked_file(root, item, f"{key}.{theme}.files") for item in files]
            require(len(paths) == len(set(paths)), f"{key}.{theme}: duplicate files")
            source = file_path(root, variant.get("source"), "variant.source")
            preview = file_path(root, variant.get("preview"), "variant.preview")
            require(source in paths and preview in paths, "source and preview must be declared files")
            require(source.suffix.lower() == ".svg", "library source must be .svg")
            require(preview.suffix.lower() in (".png", ".jpg", ".jpeg"), "library preview must be PNG/JPEG")
            evidence = variant.get("evidence")
            require(isinstance(evidence, dict), "variant.evidence: expected object")
            require(evidence.get("level") in ("source-only", "svg-rendered", "powerpoint-rendered", "powerpoint-edited"),
                    "variant.evidence.level invalid")
            string(evidence.get("source_version"), "evidence.source_version")
            string(evidence.get("notes"), "evidence.notes")
            check_source(source, set(paths))
    return manifest, path, catalog
 def inspect_entry(manifest_path: Path, manifest: dict, path: Path, entry: dict,
                  theme: str, for_use: bool) -> dict:
    compatible = manifest["version"] in entry["template_versions"]
    eligible = entry["status"] == "reference" and compatible and theme in entry["variants"]
    if for_use:
        require(manifest["status"] == "released", "Library reuse requires a released template")
        require(eligible, "Entry is not a compatible reference for the selected theme")
    require(theme in entry["variants"], f"Entry has no variant for theme {theme}")
    root = manifest_path.parent
    variant = deepcopy(entry["variants"][theme])
    inputs = {manifest_path, path, file_path(root, entry["design"]["path"], "design")}
    inputs.update(file_path(root, item["path"], "variant file") for item in variant["files"])
    return {"template_id": manifest["template_id"], "template_version": manifest["version"],
            "entry_id": entry["id"], "title": entry["title"], "status": entry["status"],
            "layout": entry["layout"], "theme": theme, "compatible": compatible, "eligible": eligible,
            "design": str(file_path(root, entry["design"]["path"], "design")),
            "source": str(file_path(root, variant["source"], "source")),
            "preview": str(file_path(root, variant["preview"], "preview")),
            "variant": variant, "inputs": input_hashes(root, inputs),
            "verification_scope": "declared metadata, file hashes and SVG href closure; preview provenance is declared, not rerendered"}
 def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    sub = parser.add_subparsers(dest="command", required=True)
    for name in ("list", "check", "inspect"):
        item = sub.add_parser(name)
        item.add_argument("--manifest", type=Path, required=True, action="append")
        if name == "list":
            item.add_argument("--theme", action="append")
            item.add_argument("--layout", action="append")
        if name == "inspect":
            item.add_argument("--entry", required=True, action="append")
            item.add_argument("--theme", required=True, action="append")
            item.add_argument("--for-use", action="store_true")
    args = parser.parse_args()
    try:
        for key in ("manifest", "theme", "layout", "entry"):
            values = getattr(args, key, None)
            if values is not None:
                require(len(values) == 1, f"Only one --{key} may be active")
                setattr(args, key, values[0])
        manifest_path = args.manifest.resolve()
        manifest, path, catalog = load_library(manifest_path)
        if args.command == "inspect":
            require(catalog is not None, "Template has no page library")
            entry = next((item for item in catalog["entries"] if item["id"] == args.entry), None)
            require(entry is not None, f"Unknown library entry: {args.entry}")
            output = inspect_entry(manifest_path, manifest, path, entry, args.theme, args.for_use)
        else:
            entries = [] if catalog is None else catalog["entries"]
            theme, layout = getattr(args, "theme", None), getattr(args, "layout", None)
            if theme:
                require(theme in manifest.get("themes", manifest.get("modes", {})), "Unknown theme filter")
            if layout:
                require(layout in {item["id"] for item in manifest["layouts"]}, "Unknown layout filter")
            entries = [{"id": entry["id"], "title": entry["title"], "status": entry["status"],
                        "layout": entry["layout"], "themes": list(entry["variants"]), "tags": entry["tags"],
                        "compatible": manifest["version"] in entry["template_versions"]}
                       for entry in entries if (not theme or theme in entry["variants"])
                       and (not layout or layout == entry["layout"])]
            output = {"template_id": manifest["template_id"], "available": catalog is not None,
                      "catalog": str(path) if path else None, "entries": entries, "count": len(entries)}
        print(json.dumps(output, ensure_ascii=False, indent=2))
        return 0
    except (InputError, OSError, ValueError, ET.ParseError) as error:
        print(json.dumps({"error": str(error)}, ensure_ascii=False), file=sys.stderr)
        return 2
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -14,18 +14,45 @@ import template_ref as ref
 from native_export import boundary_file, regular
-def paint(manifest_path: Path, theme_id: str, role: str, output: Path):
+def paint(manifest_path: Path, theme_id: str, role: str | None, output: Path,
          material_path: Path | None = None):
    manifest_path = regular(manifest_path, "manifest")
    manifest = ref.load_manifest(manifest_path)
    ref.require(manifest["schema_version"] == 2, "Paint application requires manifest schema 2")
    ref.require(theme_id in manifest["themes"], "Unknown theme")
    _, theme = ref.load_theme(manifest_path.parent, manifest["themes"][theme_id], theme_id)
-    asset = theme["assets"].get(role)
+    if material_path is None:
-    ref.require(asset is not None and "paint_contract" in asset, "Asset needs an explicit SVG paint contract")
+        asset = theme["assets"].get(role)
-    root_path = manifest_path.parent
+        ref.require(asset is not None and "paint_contract" in asset, "Asset needs an explicit SVG paint contract")
        root_path = manifest_path.parent
        bindings = [target for binding in theme["asset_bindings"] if binding["asset"] == role
                    for target in binding["targets"]]
    else:
        ref.require(role is None, "Choose a template asset or a local material, not both")
        material_path = regular(material_path, "material descriptor")
        asset = ref.read_json(material_path, (1,))
        ref.require(set(asset) == {"schema_version", "id", "path", "paint_contract", "bindings"},
                    "Material descriptor requires exactly schema_version/id/path/paint_contract/bindings")
        role = ref.identifier(asset["id"], "material ID")
        root_path = material_path.parent
        bindings = asset["bindings"]
        ref.require(isinstance(bindings, list), "Material bindings must be an array")
    _, contract = ref.load_paint_contract(root_path, asset, role)
    source = boundary_file(root_path, asset["path"], "SVG asset")
-    contract_path = boundary_file(root_path, asset["paint_contract"], "paint contract")
+    boundary_file(root_path, asset["paint_contract"], "paint contract")
-    contract = ref.read_json(contract_path, (1,))
+    allowed = {(rule["selector"], rule["channel"]) for rule in contract["rules"] if rule["policy"] == "palette"}
    targets = {}
    for target in bindings:
        ref.require(isinstance(target, dict) and set(target) == {"selector", "channel", "palette_index"},
                    "Binding requires exactly selector/channel/palette_index")
        key = (ref.string(target["selector"], "selector"), ref.string(target["channel"], "channel"))
        ref.require(key in allowed and key not in targets, "Unknown, fixed, structural or duplicate paint binding")
        index = ref.string(target["palette_index"], "palette index")
        ref.require(index in theme["palette"], "Unknown palette index")
        targets[key] = index
    ref.require(set(targets) == allowed, "Palette bindings must cover exactly the permitted channels")
    if material_path is not None:
        ref.require(bool(allowed), "A new icon needs at least one adjustable palette channel")
    text = source.read_text(encoding="utf-8")
    ref.require(not re.search(r"<!DOCTYPE|<!ENTITY", text, re.I), "SVG declarations/entities forbidden")
    root = ET.fromstring(text)
@@ -36,8 +63,6 @@ def paint(manifest_path: Path, theme_id: str, role: str, output: Path):
        if node.get("id"):
            ref.require(node.get("id") not in by_id, "SVG IDs must be unique")
            by_id[node.get("id")] = node
    targets = {(target["selector"], target["channel"]): target["palette_index"]
               for binding in theme["asset_bindings"] if binding["asset"] == role for target in binding["targets"]}
    changes = []
    for rule in contract["rules"]:
        selector, channel = rule["selector"], rule["channel"]
@@ -61,6 +86,7 @@ def paint(manifest_path: Path, theme_id: str, role: str, output: Path):
    with output.open("xb") as stream:
        ET.ElementTree(root).write(stream, encoding="utf-8", xml_declaration=True)
    return {"asset": role, "theme": theme_id, "output": str(output), "paint_changes": changes,
            "material": str(material_path) if material_path else None,
            "verification_scope": "explicit SVG channel transformation; rendered material appearance unverified"}
@@ -68,11 +94,13 @@ def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--manifest", type=Path, required=True)
    parser.add_argument("--theme", required=True)
-    parser.add_argument("--asset", required=True)
+    selection = parser.add_mutually_exclusive_group(required=True)
    selection.add_argument("--asset")
    selection.add_argument("--material", type=Path)
    parser.add_argument("--output", type=Path, required=True)
    args = parser.parse_args()
    try:
-        print(json.dumps(paint(args.manifest, args.theme, args.asset, args.output), ensure_ascii=False))
+        print(json.dumps(paint(args.manifest, args.theme, args.asset, args.output, args.material), ensure_ascii=False))
        return 0
    except (ref.InputError, OSError, ValueError, KeyError, TypeError, ET.ParseError) as error:
        print(json.dumps({"error": str(error)}, ensure_ascii=False), file=sys.stderr)
@@ -0,0 +1,252 @@
 #!/usr/bin/env python3
 """Grouped native tables with explicit per-column bars and status marks."""
 from __future__ import annotations
 from copy import deepcopy
 import json
 import math
 from pathlib import Path
 import re
 import sys
 import unicodedata
 import xml.etree.ElementTree as ET
 import template_ref as ref
 SVG = 'http://www.w3.org/2000/svg'
 def _fields(value, allowed, required, name):
    ref.require(isinstance(value, dict), f'{name}: object required')
    ref.require(set(value) <= allowed, f'{name}: unknown fields {sorted(set(value)-allowed)}')
    ref.require(required <= set(value), f'{name}: missing fields {sorted(required-set(value))}')
 def _number(value, name):
    ref.require(type(value) in (int, float) and math.isfinite(value), f'{name}: finite number required')
    return value
 def _text(value, name, empty=False):
    ref.require(isinstance(value, str) and (empty or bool(value.strip())), f'{name}: string required')
    ref.require(not any(unicodedata.category(c).startswith('C') for c in value), f'{name}: control/format characters unsupported')
    return value
 def _indices(value, count, name):
    ref.require(isinstance(value, list) and all(type(i) is int and 0 <= i < count for i in value), f'{name}: invalid column index')
    ref.require(len(set(value)) == len(value), f'{name}: duplicate column index')
    return value
 def _fit(value, width, size, name):
    units = sum(1 if unicodedata.east_asian_width(c) in ('W', 'F') else .6 for c in value)
    ref.require(units*size <= width, f'{name}: text exceeds capacity; shorten text or enlarge bounds')
 def _node(parent, tag, **attributes):
    return ET.SubElement(parent, '{'+SVG+'}'+tag, {key.replace('_', '-'):str(value) for key,value in attributes.items()})
 def _label(parent, value, x, y, font, size, color, align):
    result = _node(parent, 'text', x=x, y=y, font_family=font, font_size=size,
                   font_weight='normal', fill=color, text_anchor='end' if align == 'r' else 'middle' if align == 'ctr' else 'start')
    result.text = value
 def _formatted(value, column):
    kind = column.get('format', 'text')
    if kind == 'integer':
        ref.require(type(value) in (int,float) and value == int(value), 'integer format requires integral numeric values')
        return f'{int(value):,}'
    if kind == 'one-decimal':
        ref.require(type(value) in (int,float), 'one-decimal format requires numeric values')
        return f'{value:,.1f}'
    return str(value)
 def render_grouped_table(raw: dict, style: dict, theme: dict, bounds: tuple,
                         component_id: str) -> ET.Element:
    """Return an outer g containing a native-table marker and separate shapes.
    Original values are retained; number formats affect display text only. Bars
    express independent zero-based column magnitudes, never a ranking or score.
    """
    allowed = {'schema_version','kind','variant','data_kind','source','columns','rows','column_widths',
               'numeric_columns','column_groups','focus_row','row_header_columns','bars','status',
               'focus_meaning','bar_meaning'}
    _fields(raw, allowed, {'schema_version','kind','variant','columns','rows','column_widths','column_groups'}, 'grouped table')
    ref.require(type(raw['schema_version']) is int and raw['schema_version'] == 1 and raw['kind'] == 'table' and raw['variant'] == 'grouped', 'requires table/grouped schema_version 1')
    data = deepcopy(raw)
    if 'data_kind' in data:
        ref.require(data['data_kind'] in ('synthetic-demo','observed','derived'), 'invalid data_kind')
    for key in ('source','focus_meaning','bar_meaning'):
        if key in data: _text(data[key], key, empty=True)
    ref.identifier(component_id, 'component ID')
    ref.require(isinstance(bounds, (tuple,list)) and len(bounds) == 4, 'bounds requires x/y/width/height')
    x,y,width,height = [_number(v, 'bounds') for v in bounds]
    canvas = style['canvas']
    ref.require(x >= 0 and y >= 0 and width > 0 and height > 0 and x+width <= canvas['width'] and y+height <= canvas['height'], 'bounds outside canvas')
    columns, rows = data['columns'], data['rows']
    ref.require(isinstance(columns,list) and bool(columns), 'columns must be nonempty list')
    ids = []
    for col in columns:
        _fields(col, {'id','label','unit','format'}, {'id','label'}, 'column')
        ids.append(ref.identifier(col['id'], 'column ID'))
        _text(col['label'], 'column label')
        if 'unit' in col: _text(col['unit'], 'column unit', empty=True)
        ref.require(col.get('format','text') in ('text','integer','one-decimal'), 'unknown column format')
    count = len(columns)
    ref.require(len(set(ids)) == count, 'duplicate column ID')
    ref.require(isinstance(rows,list) and bool(rows), 'rows must be nonempty list')
    for row in rows:
        ref.require(isinstance(row,list) and len(row) == count, 'table row length mismatch')
        for value in row:
            if type(value) in (int,float): _number(value, 'cell')
            else: _text(value, 'cell', empty=True)
    widths = data['column_widths']
    ref.require(isinstance(widths,list) and len(widths) == count, 'column_widths mismatch')
    ref.require(all(_number(v,'column width') > 0 for v in widths) and abs(sum(widths)-width) < .01, 'column widths must fill bounds width')
    numeric = _indices(data.get('numeric_columns',[]), count, 'numeric_columns')
    for row in rows:
        for col in numeric: _number(row[col], 'numeric cell')
    row_headers = _indices(data.get('row_header_columns',[]), count, 'row_header_columns')
    focus = data.get('focus_row')
    ref.require(focus is None or type(focus) is int and 0 <= focus < len(rows), 'focus_row invalid')
    groups = data['column_groups']
    ref.require(isinstance(groups,list) and bool(groups), 'column_groups must be nonempty list')
    cursor = 0
    for group in groups:
        _fields(group, {'label','start','span'}, {'label','start','span'}, 'column group')
        _text(group['label'],'column group label')
        ref.require(type(group['start']) is int and type(group['span']) is int and group['start'] == cursor and group['span'] > 0, 'column_groups must provide ordered contiguous coverage')
        cursor += group['span']
    ref.require(cursor == count, 'column_groups must cover all columns')
    bar_columns = []
    if 'bars' in data:
        _fields(data['bars'], {'columns'}, {'columns'}, 'bars')
        bar_columns = _indices(data['bars']['columns'], count, 'bars.columns')
        ref.require(set(bar_columns) <= set(numeric), 'bars require numeric_columns')
        for row in rows:
            for col in bar_columns: ref.require(row[col] >= 0, 'bars require nonnegative values')
    status = data.get('status')
    if status is not None:
        _fields(status, {'column','values'}, {'column','values'}, 'status')
        _indices([status['column']], count, 'status.column')
        ref.require(status['column'] not in numeric and status['column'] not in bar_columns, 'status column must be textual')
        ref.require(isinstance(status['values'],dict) and bool(status['values']), 'status.values must be nonempty object')
        for value, cfg in status['values'].items():
            _text(value, 'status value')
            _fields(cfg, {'palette_index','shape'}, {'palette_index','shape'}, 'status value')
            _text(cfg['palette_index'], 'status palette_index')
            ref.require(cfg['shape'] in ('circle','diamond'), 'status shape must be circle or diamond')
        ref.require(all(row[status['column']] in status['values'] for row in rows), 'unknown status value')
    cfg = style.get('components',{}).get('table_grouped',{})
    _fields(cfg, {'group_height_px','header_height_px','row_height_px','cell_padding_px'}, set(), 'style.components.table_grouped')
    typography = style['typography']; roles = typography['roles']; families = typography['families']
    font = families[roles['label']['family_role']]['family']
    caption_font = families[roles['caption']['family_role']]['family']
    size = _number(roles['label']['size_pt'],'label size')*_number(canvas['pt_to_px'],'pt_to_px')
    small = _number(roles['caption']['size_pt'],'caption size')*canvas['pt_to_px']
    ref.require(size > 0 and small > 0, 'font sizes must be positive')
    padding = cfg.get('cell_padding_px',[8,16])
    ref.require(isinstance(padding,list) and len(padding) == 2 and all(_number(v,'cell padding') >= 0 and v % 8 == 0 for v in padding), 'cell_padding_px requires two nonnegative 8px multiples')
    top, side = padding
    module = lambda v: math.ceil(v/8)*8
    gh = cfg.get('group_height_px',module(small+2*top))
    hh = cfg.get('header_height_px',module(size+small+2*top+8))
    rh = cfg.get('row_height_px',module(size+2*top+(8 if bar_columns else 0)))
    for key,value,minimum in (('group height',gh,small+2*top),('header height',hh,size+small+2*top+8),('row height',rh,size+2*top+(8 if bar_columns else 0))):
        ref.require(_number(value,key) >= minimum and value % 8 == 0, f'{key}: insufficient height or not an 8px multiple')
    total = gh+hh+len(rows)*rh
    ref.require(total <= height, 'table rows exceed bounds height')
    palette = theme['palette']
    keys = {'accent1','accent2','surface_tint','lt1','lt2','dk1','dk2','line'}
    if status:
        keys.update(v['palette_index'] for v in status['values'].values())
    for key in keys:
        ref.require(isinstance(key,str) and key in palette and isinstance(palette[key],str) and re.fullmatch(r'#[0-9a-fA-F]{6}',palette[key]), f'unknown/invalid palette index: {key}')
    outer = ET.Element('{'+SVG+'}g', {'id':component_id,'data-component-kind':'table','data-component-variant':'grouped'})
    source = _node(outer,'metadata',type='application/json')
    marks = []
    marker = _node(outer,'g',id=component_id+'-native',data_pptx_replace_with='table')
    metadata = _node(marker,'metadata',type='application/json')
    marker.set('data-component-source',json.dumps(data,ensure_ascii=False,allow_nan=False))
    fallback = _node(marker,'g',id=component_id+'-fallback')
    none = lambda: {s:{'style':'none'} for s in ('top','bottom','left','right')}
    table_rows = ['']*count
    for i,group in enumerate(groups):
        start,span = group['start'],group['span']; gx=x+sum(widths[:start]); gw=sum(widths[start:start+span])
        fill = palette['accent1' if i%2 == 0 else 'accent2']
        _fit(group['label'],gw-2*side,small,'group header')
        cell = {'paragraphs':[{'align':'ctr','runs':[{'text':group['label'],'font_size':small,'font_family':caption_font,'bold':False,'color':palette['lt1']}]}],'fill':fill,'color':palette['lt1'],'font_size':small,'bold':False,'align':'ctr','valign':'middle','padding':{'top':0,'bottom':0,'left':side,'right':side},'borders':none()}
        if span > 1: cell['col_span']=span
        table_rows[start]=cell
        _node(fallback,'rect',x=gx,y=y,width=gw,height=gh,fill=fill)
        _label(fallback,group['label'],gx+gw/2,y+(gh+small*.72)/2,caption_font,small,palette['lt1'],'ctr')
    table_rows = [table_rows]
    group_ends = {g['start']+g['span']-1 for g in groups[:-1]}
    cy = y+gh
    for ri,row in enumerate([columns,*rows]):
        header = ri == 0; focused = not header and ri-1 == focus; cell_height = hh if header else rh
        cx=x; cells=[]
        for ci,value in enumerate(row):
            fill = palette['surface_tint'] if header or focused else palette['lt2'] if ci in row_headers or ri%2 == 0 else palette['lt1']
            color = palette['accent1'] if header or focused else palette['dk1']
            if not header and ci not in numeric and ci not in row_headers: color=palette['dk2']
            is_status = not header and status is not None and ci == status['column']
            if is_status: color=palette[status['values'][value]['palette_index']]
            align='r' if ci in numeric else 'l'
            pad={'top':top,'bottom':top+8 if not header and ci in bar_columns else top,'left':side+32 if is_status else side,'right':side}
            borders=none(); borders['bottom']={'style':'solid','color':palette['accent1'] if focused else palette['line'],'width':1}
            if ci in group_ends: borders['right']={'style':'solid','color':palette['line'],'width':1}
            if focused:
                borders['top']={'style':'solid','color':palette['accent1'],'width':1}
                if ci == 0: borders['left']={'style':'solid','color':palette['accent1'],'width':4}
            cell={'fill':fill,'color':color,'align':align,'font_size':size,'bold':False,'padding':pad,'valign':'middle','borders':borders}
            _node(fallback,'rect',x=cx,y=cy,width=widths[ci],height=cell_height,fill=fill)
            tx=cx+widths[ci]-side if align == 'r' else cx+pad['left']
            if header:
                title,unit=value['label'],value.get('unit','')
                _fit(title,widths[ci]-2*side,size,'column header')
                cell['paragraphs']=[{'align':align,'runs':[{'text':title,'font_size':size,'font_family':font,'bold':False,'color':color}]}]
                if unit:
                    _fit(unit,widths[ci]-2*side,small,'column unit')
                    cell['paragraphs'].append({'align':align,'runs':[{'text':unit,'font_size':small,'font_family':caption_font,'bold':False,'color':palette['dk2']}]})
                    baseline=cy+(cell_height-size-small-8)/2+size*.8
                    _label(fallback,title,tx,baseline,font,size,color,align)
                    _label(fallback,unit,tx,baseline+small+8,caption_font,small,palette['dk2'],align)
                else: _label(fallback,title,tx,cy+(cell_height+size*.72)/2,font,size,color,align)
            else:
                displayed=_formatted(value,columns[ci]); cell['text']=displayed
                _fit(displayed,widths[ci]-pad['left']-side,size,'table cell')
                _label(fallback,displayed,tx,cy+(cell_height+size*.72-(8 if ci in bar_columns else 0))/2,font,size,color,align)
                if ci in bar_columns:
                    maximum=max(r[ci] for r in rows) or 1; track=widths[ci]-2*side
                    marks.append({'id':f'{component_id}-bar-r{ri}-c{ci}','kind':'bar','x':cx+side,'y':cy+cell_height-12,'width':track,'length':track*(value/maximum),'value':value,'domain':[0,maximum],'column':ci,'row':ri-1,'focused':focused})
                if is_status:
                    marks.append({'id':f'{component_id}-status-r{ri}-c{ci}','kind':'status','x':cx+side+8,'y':cy+cell_height/2,'palette_index':status['values'][value]['palette_index'],'shape':status['values'][value]['shape'],'value':value,'row':ri-1,'column':ci})
            for edge,line in borders.items():
                if line['style']=='none': continue
                coords={'top':(cx,cy,cx+widths[ci],cy),'bottom':(cx,cy+cell_height,cx+widths[ci],cy+cell_height),'left':(cx,cy,cx,cy+cell_height),'right':(cx+widths[ci],cy,cx+widths[ci],cy+cell_height)}[edge]
                _node(fallback,'line',x1=coords[0],y1=coords[1],x2=coords[2],y2=coords[3],stroke=line['color'],stroke_width=line['width'])
            cells.append(cell); cx+=widths[ci]
        table_rows.append(cells); cy+=cell_height
    payload={'name':component_id,'x':x,'y':y,'width':width,'height':total,'rows':table_rows,'header_rows':2,'strict_grid':True,'column_widths':widths,'row_heights':[gh,hh,*[rh]*len(rows)],'style':{'font_family':font,'font_size':size,'header_font_size':size,'band_row':False}}
    metadata.text=json.dumps(payload,ensure_ascii=False,allow_nan=False)
    source.text=json.dumps({'component_id':component_id,'data':data,'derived_marks':marks},ensure_ascii=False,allow_nan=False)
    runtime=Path(__file__).resolve().parent.parent/'runtime/ppt-master/scripts'
    if str(runtime) not in sys.path: sys.path.insert(0,str(runtime))
    from pptx_shapes import NATIVE_FALLBACK_SHA256_ATTR, svg_native_fallback_fingerprint
    marker.set(NATIVE_FALLBACK_SHA256_ATTR,svg_native_fallback_fingerprint(marker))
    overlay=_node(outer,'g',id=component_id+'-marks')
    for mark in marks:
        if mark['kind']=='bar':
            _node(overlay,'rect',id=mark['id']+'-track',x=mark['x'],y=mark['y'],width=mark['width'],height=4,fill=palette['line'])
            if mark['length'] > 0:
                _node(overlay,'rect',id=mark['id'],x=mark['x'],y=mark['y'],width=mark['length'],height=4,fill=palette['accent1'],fill_opacity=.8 if mark['focused'] else .4)
        elif mark['shape']=='circle': _node(overlay,'circle',id=mark['id'],cx=mark['x'],cy=mark['y'],r=4,fill=palette[mark['palette_index']])
        else:
            mx,my=mark['x'],mark['y']
            _node(overlay,'path',id=mark['id'],d=f'M {mx} {my-6} L {mx+6} {my} L {mx} {my+6} L {mx-6} {my} Z',fill=palette[mark['palette_index']])
    return outer
@@ -194,6 +194,10 @@ def load_manifest(path: Path) -> dict:
    v2 = value["schema_version"] == 2
    if v2:
        read_json(file_path(path.parent, value.get("style"), "style"), None)
    if "page_library" in value:
        library = read_json(file_path(path.parent, value["page_library"], "page_library"), (1,))
        require(library.get("template_id") == value["template_id"],
                "page_library: template_id mismatch")
    variants_key = "themes" if v2 else "modes"
    variants = value.get(variants_key)
    require(isinstance(variants, dict) and bool(variants), f"{variants_key}: expected non-empty object")
@@ -313,6 +317,9 @@ def export_style(path: Path, value: dict, args: argparse.Namespace) -> dict:
    inputs.update(workspace_inputs(root, workspace))
    if native is not None and native.is_file():
        inputs.add(native)
    library = file_path(root, value["page_library"], "page_library") if "page_library" in value else None
    if library is not None:
        inputs.add(library)
    return {"schema_version": 2, "template_id": value["template_id"], "version": value["version"],
            "status": value["status"], "production_ready": value["status"] == "released",
            "manifest": str(path), "manifest_sha256": digest(path), "theme": selected,
@@ -321,6 +328,7 @@ def export_style(path: Path, value: dict, args: argparse.Namespace) -> dict:
            "workspace": str(workspace), "native_template": str(native) if native is not None else None,
            "style_path": str(style_path), "theme_path": str(theme_path),
            "style": style, "theme_data": theme, "editable_policy": deepcopy(value["editable_policy"]),
            "page_library": str(library) if library is not None else None,
            "inputs": input_hashes(root, inputs),
            "verification_scope": "style review and alignment only; no PPT creation, selector execution or release acceptance"}
@@ -362,6 +370,10 @@ def resolve(path: Path, value: dict, args: argparse.Namespace) -> dict:
        inputs.update(theme_files)
        result.update(status=value["status"], production_ready=True,
                      style_path=str(style_path), theme_path=str(theme_path))
    library = file_path(root, value["page_library"], "page_library") if "page_library" in value else None
    if library is not None:
        inputs.add(library)
    result["page_library"] = str(library) if library is not None else None
    result["inputs"] = input_hashes(root, inputs)
    return result
		`@@ -0,0 +1 @@`
							<ns0:svg xmlns:ns0="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720"><ns0:g id="minimal-chart" data-pptx-replace-with="chart" data-pptx-fallback-sha256="541d841e7327c1eafb3ec123f7dfe3ac4ae3c8eb48ae954b7f0e3f16f4262a2d"><ns0:metadata type="application/json">{"name": "minimal-column", "x": 600, "y": 160, "width": 480, "height": 320, "type": "column", "categories": ["A", "B"], "series": [{"name": "Count", "values": [12, 18]}], "colors": ["#2563EB"], "show_legend": false, "style": {"font_family": "Arial", "font_size": 24, "axis_font_size": 24, "text_color": "#111827", "axis_color": "#64748B", "grid_color": "#CBD5E1", "chart_area_fill": "#FFFFFF", "plot_area_fill": "#FFFFFF"}}</ns0:metadata><ns0:rect x="600" y="160" width="480" height="320" fill="#FFFFFF" /><ns0:line x1="648" y1="424" x2="1048" y2="424" stroke="#64748B" /><ns0:rect x="720" y="280" width="80" height="144" fill="#2563EB" /><ns0:rect x="900" y="208" width="80" height="216" fill="#2563EB" /><ns0:text x="760" y="456" text-anchor="middle" font-family="Arial" font-size="24" fill="#111827">A</ns0:text><ns0:text x="940" y="456" text-anchor="middle" font-family="Arial" font-size="24" fill="#111827">B</ns0:text></ns0:g></ns0:svg>
`@@ -33,4 +33,4 @@ Keep proposed styles and mockups outside the final template workspace until the`

	The bundled runtime also carries the upstream preview compiler at `runtime/ppt-master/scripts/template_preview_pptx.py` for author review workspaces. It is source tooling, not a second Skill. Read its command help for a new workspace. Its platform font mapping is general-purpose: a template review wrapper should import the compiler and use `scripts/finalize_theme.py`'s `preserve_declared_font_families(style)` context around the serial compile, then `finalize(...)`. This preserves the declared family before information can be lost to platform fallback. Do not globally replace a fallback font in finished XML: the author may have intentionally used that same font.	The bundled runtime also carries the upstream preview compiler at `runtime/ppt-master/scripts/template_preview_pptx.py` for author review workspaces. It is source tooling, not a second Skill. Read its command help for a new workspace. Its platform font mapping is general-purpose: a template review wrapper should import the compiler and use `scripts/finalize_theme.py`'s `preserve_declared_font_families(style)` context around the serial compile, then `finalize(...)`. This preserves the declared family before information can be lost to platform fallback. Do not globally replace a fallback font in finished XML: the author may have intentionally used that same font.

	`For advanced native table/chart/formula or placeholder metadata, inspect the corresponding bundled compiler module and its local CLI help. Do not claim specialized objects from a screenshot or from a successful ZIP export alone. Finish with [render and application checks](powerpoint-checks.md).`	`For native tables/charts and formula limitations, read [specialized objects](native-objects.md) and its bundled minimal SVG examples. For placeholder metadata, inspect the corresponding bundled compiler module and local CLI help. Do not claim specialized objects from a screenshot or from a successful ZIP export alone. Finish with [render and application checks](powerpoint-checks.md).`