Skip to content

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

docs(hyperlinks): define native authoring contract

hugohe3ba09f938d618
diff --git a/docs/faq.md b/docs/faq.md
index 27f18a42..706b9040 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -161,6 +161,20 @@ The native target is PowerPoint 2010+. Formula display and editability in
Keynote, WPS, LibreOffice, and other non-PowerPoint clients are not supported;
PPT Master does not add an image fallback for them.
+## Q: Can generated slides contain clickable links?
+
+Yes. PPT Master supports PowerPoint-native links on a whole object or an inline
+text run. External targets use an absolute URI such as `https:` or `mailto:`;
+same-deck jumps use the exact 1-based `#slide-N` form. Both compile from
+standard SVG `<a href>` anchors to native click relationships, and supported
+PPTX import reconstructs the same SVG form.
+
+This is a hyperlink contract, not a general PowerPoint action API. Mouse-over,
+custom-show, navigation-command, program/macro/OLE/file, and arbitrary action
+settings are not authored. See the [PowerPoint ↔ SVG Mapping
+Guide](./powerpoint-svg-mapping.md#10-powerpoint-playback-and-package-features)
+for the carrier and preservation boundaries.
+
## Q: Can I change page transitions and element animations?
Yes. Page transitions are on by default (`fade` 0.4s); per-element object
diff --git a/docs/powerpoint-svg-mapping.md b/docs/powerpoint-svg-mapping.md
index b84b744b..9e5966ee 100644
--- a/docs/powerpoint-svg-mapping.md
+++ b/docs/powerpoint-svg-mapping.md
@@ -223,7 +223,9 @@ content exists only so the authored page remains visible before export.
## 10. PowerPoint playback and package features
-These capabilities belong to PPTX package semantics. Their absence from page SVG is deliberate.
+These capabilities compile either from canonical page SVG or from the named
+package-level sidecar. A sidecar remains absent when the table names SVG as the
+owner.
| PowerPoint feature | Owning project representation | PPTX result | Import and fidelity | Validation boundary |
|---|---|---|---|---|
@@ -232,7 +234,11 @@ These capabilities belong to PPTX package semantics. Their absence from page SVG
| Object animation (entrance / emphasis / motion path / exit) | `animations.json` targeting stable top-level SVG group IDs; `effects[]` may assign several rows to one anchor | Root `p:timing` animation tree | `Sidecar/package`; the group ID is only the shape-target anchor | Static structural layers and placeholders cannot be animated |
| Narration audio | `audio/` asset plus recorded-narration export option | Media relationship, audio carrier, and timing | `Sidecar/package` | Asset, slide association, and timing must validate |
| Automatic slide advance | Explicit transition timing or narration-derived duration | `advTm`/advance behavior | `Sidecar/package` | Click-driven animation is incompatible with recorded narration |
-| Hyperlink or action | No main SVG compiler mapping | Not created by page SVG | `Direct preservation` where a native route retains source OOXML | An action-button preset supplies visual geometry only |
+| Whole-object hyperlink | Standard SVG `<a href="...">` around one visual element or group | `p:cNvPr/a:hlinkClick` on each clickable leaf plus one shared relationship | `Native-stable` for supported external and same-deck targets; PPTX import reconstructs the anchor | Add an explicit background shape when gaps inside a multi-object card/button must be clickable |
+| Inline-text hyperlink | `<a href="..."><tspan>visible text or an inline-formula marker</tspan></a>` inside ordinary SVG text | `a:rPr/a:hlinkClick` in the same DrawingML paragraph or Office Math leaf runs | `Native-stable` for supported external and same-deck targets | The anchor owns no positional attributes; nested links fail |
+| Same-deck slide jump | Either supported carrier with exact 1-based `href="#slide-N"` | Internal slide relationship plus `ppaction://hlinksldjump` | Reconstructed against the final presentation roster | Missing, out-of-range, orphaned, or ambiguous slide targets fail closed |
+| Imported shape click plus inner run links | Importer-only `data-pptx-shape-hyperlink="..."` on the logical `<g>`, with standard inline anchors retained inside | Restores both `p:cNvPr/a:hlinkClick` and the run-level clicks | Lossless transport for this source-only overlap | Authors never write this metadata; checker/export accept it only when the group contains a real inline anchor, because standard SVG forbids nested `<a>` |
+| Other action setting | No SVG authoring mapping | Not created | `Direct preservation` only where an owning native route leaves source OOXML unchanged | Mouse-over, custom-show, navigation-command, program/macro/OLE/file, and arbitrary `ppaction://` actions are outside the hyperlink contract; an action-button preset supplies visual geometry only |
| Comment or review thread | No SVG or generation-side mapping | Not authored | `Direct preservation` only when explicitly owned by another route | Do not convert review metadata into visible slide content automatically |
| Relationship not owned by a mapped feature | No generic SVG escape hatch | Not generated | `Direct preservation` where applicable | Arbitrary relationship injection is unsupported |
@@ -254,7 +260,7 @@ See [Animations & Transitions](./animations.md) (technical source: [`references/
|---|---|---|---|
| SmartArt / DiagramML | No native SVG compiler mapping | Reconstruct meaning with shapes, or preserve through a native/template route | A screenshot or fallback must be explicit |
| OLE or embedded Office object | Unsupported in the SVG route | Direct preservation or a rendered preview | Do not manufacture package relationships from SVG metadata |
-| Video | Unsupported as an SVG-authored media object | Direct preservation or an explicit poster/link workflow outside this contract | A `media` placeholder does not create video |
+| Video | Unsupported as an SVG-authored media object | Direct preservation or an explicit poster carrying an ordinary supported hyperlink | A `media` placeholder does not create video |
| 3D model | Unsupported | Direct preservation or baked preview | No browser-SVG approximation is treated as native 3D |
| Macro / VBA | Unsupported | Preserve only through a macro-aware direct workflow | The normal generated `.pptx` route does not synthesize VBA |
| Arbitrary Office extension XML | Unsupported | Direct preservation by an owning native workflow | The SVG compiler has no generic OOXML passthrough |
@@ -268,6 +274,9 @@ The importer reconstructs supported PowerPoint semantics into the same project v
| Preset shape | Expanded preset group with native carrier and visible preview evidence when supported |
| Custom geometry | `<path>` |
| Text body | `<text>` and `<tspan>` runs/paragraphs |
+| Supported text-run hyperlink | Inline `<a href>` containing the linked `<tspan>` run |
+| Supported shape/picture/group hyperlink | Canonical `<a href>` around the reconstructed visual object |
+| One shape with both a shape click and inner run links | Logical `<g data-pptx-shape-hyperlink="...">` transport plus canonical inline anchors; generated authoring never emits this exception |
| Picture | `<image>`, or the registered nested crop representation |
| SVG picture with raster compatibility fallback | `<image>` sourced from the `asvg:svgBlip` relationship; the ordinary `a:blip` relationship is used only when the SVG relationship or media part is unavailable |
| Connector | Expanded line/path preview plus connector/frame/topology evidence |
diff --git a/docs/roadmap.md b/docs/roadmap.md
index c78ede8b..efeaf264 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -70,7 +70,7 @@ A presentation is four layers: what is on the slide, how it is arranged, how it
| Object animation | Systematized | Off by default and opt-in; per-object configuration is explicit |
| Auto-advance | Covered | Derived from narration lead-in, audio duration, and page-tail padding |
| Media playback | Covered | Narration audio; arbitrary embedded media follows the Layer 1 row above |
-| Hyperlinks | Asymmetric by design | Links already present in a source deck survive conversion; authoring **new** links in generated decks is signal-driven |
+| Hyperlinks | Systematized | Whole-object and inline-text links author through standard SVG `<a href>`, export as native external or same-deck click relationships, and reconstruct on supported PPTX import |
| Actions & navigation | Bounded by design | An `actionButton*` preset maps visual geometry only — preset appearance never invents action behavior or navigation targets |
### Layer 4 — Document structure
@@ -104,7 +104,6 @@ Candidates already evaluated as "worth doing when real demand shows", listed so
- **Keep closing the native-coverage gaps** recorded in the [mapping guide](./powerpoint-svg-mapping.md) — release after release, move more "SVG-only" cells toward native PowerPoint structure and behavior.
- **Effects on authored preset shapes** (e.g. a native drop-shadow) — waits for a precise preset-effect contract plus checker coverage; until then, a stock shape that needs a shadow conservatively stays ordinary SVG.
-- **Hyperlink authoring in generated decks** — hyperlinks already present in source decks survive conversion today; letting the Strategist author new links waits for demand.
- **Picture slide backgrounds as native background fill** — solid/gradient page backgrounds already export as PowerPoint-native slide backgrounds; the picture case is demand-driven.
- **Accessibility delivery** — image manifests already carry `alt_text` for planning and confirmation, so alt text and reading order are a matter of connecting existing data to DrawingML `descr` and shape order, not of designing a new contract. Cheaper than the other open items on the map; waits for demand all the same.
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 8c757cd6..7b1cf3d1 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -515,6 +515,21 @@ forms keep ordinary SVG preview content because raw LaTeX does not render in
SVG. PowerPoint 2010+ is the target, with no formula PNG, media relationship,
or image fallback for non-PowerPoint clients.
+**Native hyperlinks use one SVG authoring truth plus package relationships.**
+Standard `<a href>` wraps either a complete visible object/group or one or more
+inline `<tspan>` runs. Absolute external URIs become external hyperlink
+relationships; exact 1-based `#slide-N` targets become internal Slide
+relationships with `ppaction://hlinksldjump`. The PPTX importer reconstructs
+the same anchors for supported shape and run clicks. Fill Native remaps an
+internal jump only when its output target is unambiguous, while Enhance Native
+leaves existing hyperlink XML and relationships untouched. Mouse-over, custom
+show, navigation-command, program/macro/OLE/file, and arbitrary action settings
+remain outside the contract. One source-only transport exception preserves a
+PowerPoint shape that has both a whole-shape click and inner run links:
+PPTX-to-SVG writes `data-pptx-shape-hyperlink` on the logical group and keeps
+the standard inline anchors, because SVG cannot nest the two `<a>` levels.
+Generated authoring never writes that attribute.
+
**Retained planning context** carries continuity; the on-demand page projector is only a diagnostic described below.
---
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index a047c255..a86bc8d4 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -161,6 +161,17 @@ marker 都携带普通可见预览;原生导出会替换该预览,不增加
客户端中的公式显示与编辑能力不在支持范围内;PPT Master 不为这些客户端附加
公式图片兜底。
+## Q: 生成的页面可以带可点击链接吗?
+
+可以。PPT Master 支持整体对象或行内文字 run 上的 PowerPoint 原生链接。
+外部目标使用 `https:`、`mailto:` 等绝对 URI;deck 内跳转使用精确的 1-based
+`#slide-N`。两类链接都从标准 SVG `<a href>` anchor 编译为原生 click
+relationship,受支持的 PPTX 回导也会重建同一种 SVG 表达。
+
+这是超链接合同,不是通用 PowerPoint action API。鼠标悬停、custom show、
+导航命令、程序 / macro / OLE / file 以及任意 action setting 不会被创作。
+carrier 与保留边界见 [PowerPoint ↔ SVG 映射指南](./powerpoint-svg-mapping.md)。
+
## Q: 页面切换和元素动画可以调吗?
可以。页间转场默认开(`fade` 0.4s),页内元素对象动画**默认关**——翻到
diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.md
index 189e19ae..486e3dca 100644
--- a/docs/zh/powerpoint-svg-mapping.md
+++ b/docs/zh/powerpoint-svg-mapping.md
@@ -216,7 +216,8 @@ SVG 预览内容只负责让导出前的作者页面保持可见。
## 10. PowerPoint 播放与打包功能
-这些能力属于 PPTX 包语义。它们不出现在页面 SVG 中是有意设计。
+这些能力要么从规范页面 SVG 编译,要么由表中点名的包级 sidecar 提供。
+当所有者一栏写的是 SVG 时,不另设 sidecar。
| PowerPoint 功能 | 项目中的所有者 | PPTX 结果 | 回导与保真度 | 校验边界 |
|---|---|---|---|---|
@@ -225,7 +226,11 @@ SVG 预览内容只负责让导出前的作者页面保持可见。
| 对象动画(进入 / 强调 / 动作路径 / 退出) | `animations.json`,目标为稳定的顶层 SVG group ID;`effects[]` 可让一个锚点拥有多条记录 | 根 `p:timing` 动画树 | `Sidecar/package`;group ID 仅为 shape target 锚点 | 静态结构层与占位符不可动画 |
| 旁白音频 | `audio/` 资产加 recorded-narration 导出选项 | media relationship、audio carrier 与 timing | `Sidecar/package` | 必须校验资产、Slide 关联与时序 |
| 幻灯片自动换页 | 显式 transition timing 或旁白派生时长 | `advTm`/换页行为 | `Sidecar/package` | 单击驱动动画与录制旁白不兼容 |
-| 超链接或动作 | 无主 SVG 编译器映射 | 不由页面 SVG 创建 | 原生路线保留源 OOXML 时为 `Direct preservation` | action-button preset 只提供可见几何 |
+| 整体对象超链接 | 标准 SVG `<a href="...">` 包裹一个可见元素或组 | 每个可点击叶子上的 `p:cNvPr/a:hlinkClick`,共用一个 relationship | 受支持外链与 deck 内目标为 `Native-stable`;PPTX 回导重建 anchor | 多对象卡片 / 按钮的间隙也要可点时,需显式加入背景形状 |
+| 行内文字超链接 | 普通 SVG 文字中的 `<a href="..."><tspan>可见文字或行内公式 marker</tspan></a>` | 同一 DrawingML 段落或 Office Math 叶子 run 中的 `a:rPr/a:hlinkClick` | 受支持外链与 deck 内目标为 `Native-stable` | anchor 不承载位置属性;嵌套链接会失败 |
+| deck 内跳转 | 任一受支持 carrier 使用精确的 1-based `href="#slide-N"` | 内部 Slide relationship 加 `ppaction://hlinksldjump` | 按最终 presentation roster 重建 | 缺失、越界、孤儿或歧义目标直接失败 |
+| 导入形状 click 与内部 run link 并存 | 仅供 importer 使用的逻辑 `<g data-pptx-shape-hyperlink="...">`,内部仍保留标准行内 anchor | 同时还原 `p:cNvPr/a:hlinkClick` 与 run 级 click | 这一 source-only 重叠可无损运输 | 作者不得写该 metadata;标准 SVG 禁止嵌套 `<a>`,因此 checker/export 仅在 group 内确有真实行内 anchor 时接受 |
+| 其他动作设置 | 无 SVG 创作映射 | 不创建 | 仅当拥有它的原生路线不改源 OOXML 时为 `Direct preservation` | 鼠标悬停、custom show、导航命令、程序 / macro / OLE / file 与任意 `ppaction://` 动作不在超链接合同内;action-button preset 仍只提供可见几何 |
| 批注或审阅线程 | 无 SVG 或生成侧映射 | 不编写 | 仅在其他路线明确拥有时为 `Direct preservation` | 不自动将审阅 metadata 转为可见 Slide 内容 |
| 不属于已映射功能的 relationship | 无通用 SVG 逃生口 | 不生成 | 适用时为 `Direct preservation` | 不支持任意 relationship 注入 |
@@ -244,7 +249,7 @@ sidecar 工作流见[转场与动画](./animations.md)(技术规范源为 [`re
|---|---|---|---|
| SmartArt / DiagramML | 无原生 SVG 编译器映射 | 使用 shape 重建语义,或通过原生/模板路线保留 | 截图或 fallback 必须是显式的 |
| OLE 或嵌入 Office 对象 | SVG 路线不支持 | 直接保留或渲染 preview | 不得通过 SVG metadata 制造包 relationship |
-| 视频 | 不支持作为 SVG 创作媒体对象 | 直接保留,或本合同之外的显式封面/链接工作流 | `media` 占位符不创建视频 |
+| 视频 | 不支持作为 SVG 创作媒体对象 | 直接保留,或使用带普通受支持超链接的显式封面 | `media` 占位符不创建视频 |
| 3D 模型 | 不支持 | 直接保留或烘焙 preview | 不将浏览器 SVG 近似当作原生 3D |
| 宏 / VBA | 不支持 | 仅通过感知宏的直接工作流保留 | 普通生成 `.pptx` 路线不生成 VBA |
| 任意 Office 扩展 XML | 不支持 | 由拥有该语义的原生工作流直接保留 | SVG 编译器不提供通用 OOXML 透传 |
@@ -258,6 +263,9 @@ sidecar 工作流见[转场与动画](./animations.md)(技术规范源为 [`re
| 预设形状 | 受支持时重建为含原生 carrier 与可见 preview 证据的 expanded preset 组 |
| 自定义几何 | `<path>` |
| 文本体 | `<text>` 与 `<tspan>` run/段落 |
+| 受支持文字 run 超链接 | 包含已链接 `<tspan>` run 的行内 `<a href>` |
+| 受支持形状 / 图片 / group 超链接 | 包裹重建后可见对象的规范 `<a href>` |
+| 同一形状同时有 shape click 与内部 run link | 逻辑 `<g data-pptx-shape-hyperlink="...">` transport 加规范行内 anchor;生成侧创作不输出该例外 |
| 图片 | `<image>`,或已登记嵌套 crop 表达 |
| 同时带栅格兼容预览的 SVG 图片 | 优先使用 `asvg:svgBlip` relationship 重建 `<image>`;仅当 SVG relationship 或 media part 不可用时才使用普通 `a:blip` relationship |
| 连接符 | expanded 线/path preview 加 connector/frame/topology 证据 |
diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.md
index fb6ddaec..e33346c0 100644
--- a/docs/zh/roadmap.md
+++ b/docs/zh/roadmap.md
@@ -70,7 +70,7 @@
| 对象动画 | 系统化 | 默认关闭、opt-in;逐对象配置为显式声明 |
| 自动翻页 | 已覆盖 | 由旁白起始留白、音频时长与页尾补白推导 |
| 音视频播放 | 已覆盖 | 旁白音频;任意嵌入媒体见第一层对应行 |
-| 超链接 | 有意的不对称 | 源 deck 中已有的链接在转换中保留;在生成 deck 中创作**新**链接属信号驱动 |
+| 超链接 | 系统化 | 整体对象与行内文字通过标准 SVG `<a href>` 创作,导出为原生外链或 deck 内跳转关系,并在受支持的 PPTX 回导中重建 |
| 动作与导航 | 有意边界 | `actionButton*` 预设只映射视觉几何——预设外观绝不凭空发明动作行为或导航目标 |
### 第四层 — 文档结构
@@ -104,7 +104,6 @@
- **持续收窄[映射指南](./powerpoint-svg-mapping.md)记录的原生覆盖缺口** — 逐版本把更多「仅 SVG」的格子推向 PowerPoint 原生结构与行为。
- **创作型预设形状的效果支持**(如原生阴影)— 等形成精确的 preset-effect 契约并补齐 checker 覆盖再做;在此之前,需要阴影的库存形状保守留普通 SVG。
-- **生成侧超链接创作** — 源 deck 里已有的超链接如今能在转换中保留;让 Strategist 主动创作新链接,等需求出现再做。
- **图片页面背景提升为原生背景填充** — 纯色 / 渐变页面背景已导出为 PowerPoint 原生底色;图片背景按需求驱动。
- **无障碍交付** — 图片 manifest 里已经为规划和确认环节带上了 `alt_text`,因此 Alt Text 与阅读顺序是把既有数据接到 DrawingML `descr` 和形状顺序上的问题,而不是重新设计一套契约。比地图上其他开放项都便宜,但同样等需求出现再做。
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 4e253800..d5eb1f83 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -436,6 +436,19 @@ Cambria Math;矩阵、多行推导等高结构表达仍使用块级形式。
2010+,不生成公式 PNG、media relationship,也不为非 PowerPoint 客户端提供
图片兜底。
+**原生超链接采用一份 SVG 创作真值,再编译为包内 relationship。** 标准
+`<a href>` 包裹完整可见对象 / group,或一个以上的行内 `<tspan>` run。
+绝对外部 URI 会成为 external hyperlink relationship;精确的 1-based
+`#slide-N` 会成为内部 Slide relationship,并写入
+`ppaction://hlinksldjump`。PPTX 回导器会把受支持的形状点击与文字 run 点击重建
+为同一种 anchor。Fill Native 只在输出目标唯一时重映射内部跳转;Enhance
+Native 则不改既有 hyperlink XML 与 relationship。鼠标悬停、custom show、
+导航命令、程序 / macro / OLE / file 以及任意 action setting 仍在合同外。
+唯一的 source-only transport 例外用于同一 PowerPoint shape 同时具有整体 click
+与内部 run link 的情况:PPTX→SVG 在逻辑 group 上写
+`data-pptx-shape-hyperlink`,并保留标准行内 anchor,因为 SVG 不能嵌套两层
+`<a>`。生成侧创作永远不写该属性。
+
**保留的规划上下文**负责跨页连续性;按需逐页投影只承担下文所述的诊断用途。
---
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 46a18194..4e33f243 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -14,6 +14,7 @@ Always-loaded Executor authority for flat SVG page authoring and behavior shared
| A page will use a preset pattern fill or an independent object is explicitly selected as native-ready | [`native-data-interface.md`](./native-data-interface.md) before emitting the pattern or replacement metadata |
| Any image | [`executor-image.md`](./executor-image.md) + [`image-layout-spec.md`](./image-layout-spec.md) + [`image-layout-patterns.md`](./image-layout-patterns.md) + [`svg-image-embedding.md`](./svg-image-embedding.md) |
| Any nontrivial mathematical expression | [`native-formula.md`](./native-formula.md) |
+| Any external or same-deck click hyperlink | [`native-hyperlinks.md`](./native-hyperlinks.md) |
| Any placed image is `Status: Sourced` or its filename has an `image_sources.json` record | [`executor-web-image.md`](./executor-web-image.md), after `executor-image.md` |
| Effective Speaker Notes outcome is enabled after all SVG pages pass | [`executor-notes.md`](./executor-notes.md) |
diff --git a/skills/ppt-master/references/native-hyperlinks.md b/skills/ppt-master/references/native-hyperlinks.md
new file mode 100644
index 00000000..a43a935e
--- /dev/null
+++ b/skills/ppt-master/references/native-hyperlinks.md
@@ -0,0 +1,100 @@
+# Native Hyperlink Specification
+
+Shared authoring contract for PowerPoint-native click hyperlinks on complete
+objects and inline text runs.
+
+## 1. Trigger and Ownership
+
+**Trigger**: A user instruction, source fact, or page plan requires an external
+destination or a jump to another slide in the same deck.
+
+| Layer | Ownership |
+|---|---|
+| Default Strategist | Record the linked text/object intent and exact target in the applicable §IX page block; never invent or normalize an unknown destination |
+| Default Executor | Choose the whole-object or inline carrier and author the canonical SVG anchor |
+| Active Quick context | Perform both content and authoring responsibilities directly |
+| SVG-to-PPTX exporter | Validate the target, create the native relationship, and attach the click action |
+
+**Hard rule — page content only**: Hyperlinks are not a confirmation field,
+resource, manifest, or `spec_lock.md` entry. Missing or ambiguous targets return
+upstream; do not substitute a search result or guessed URL.
+
+---
+
+## 2. Canonical SVG
+
+| Intent | Canonical form |
+|---|---|
+| Whole object, image, button, or group | `<a href="https://example.com"><g>...</g></a>` |
+| Inline text | `<text>Read <a href="https://example.com"><tspan>the guide</tspan></a>.</text>` |
+| Same-deck jump | `href="#slide-3"` using the 1-based final slide roster |
+| Imported shape-plus-run conflict | Importer-only `data-pptx-shape-hyperlink="..."` on the logical `<g>`, with standard inline anchors retained inside |
+
+**Hard rule — one target syntax**: Author SVG 2 `href`. Import may read legacy
+`xlink:href`, but generated SVG never writes both. Same-deck destinations use
+the exact `#slide-N` form and must resolve inside the final roster. External
+destinations are absolute URIs with an explicit scheme; percent-encode spaces.
+Relative paths, arbitrary fragments, filesystem paths, and `data:`, `file:`,
+`javascript:`, or `vbscript:` destinations fail closed.
+
+**Hard rule — inline run**: Put visible text in one or more `<tspan>` children
+inside the anchor. The anchor and its descendants own no `x`, `y`, `dx`, or
+`dy`; line positioning belongs to the enclosing line `<tspan>`. A linked inline
+formula uses one leaf formula `<tspan>` inside the anchor and retains its native
+math contract.
+
+**Hard rule — whole-object hit area**: Wrap at least one visible SVG element;
+do not put direct text or a bare `<tspan>` in a shape anchor. A multi-object
+anchor links each exported leaf object. Include an explicit background shape
+when gaps inside a button or card must also be clickable.
+
+Ordinary entrance, emphasis, motion-path, exit, and Morph animation may target
+an outer top-level `<g>`. A hyperlink-bearing group cannot also serve as an
+interactive `trigger_shape`; use a separate trigger so one click has one owner.
+
+**Forbidden — ambiguous ownership**: Do not nest `<a>` elements or place an
+anchor inside `defs`, metadata, geometry-detail, or a native-replacement
+subtree. A complete block formula or native Chart/Table marker may be wrapped
+as one whole object; its preview descendants may not contain another anchor.
+
+**Forbidden — authored transport metadata**: Never author
+`data-pptx-shape-hyperlink`. PPTX import uses it only when one source shape has
+both a whole-shape click and descendant run links, because standard SVG cannot
+nest their two anchors. Checker/export accept it only on that logical group
+with at least one real inline `<a>` descendant, then restore both native click
+levels. Every ordinary whole-object link uses the standard outer `<a href>`.
+
+---
+
+## 3. Native Result and Preservation
+
+| Carrier / target | Native result |
+|---|---|
+| Inline external link | `a:rPr/a:hlinkClick` plus an external hyperlink relationship |
+| Whole-object external link | `p:cNvPr/a:hlinkClick` on each clickable leaf plus one shared external relationship |
+| Inline or whole-object slide jump | The same click carrier plus an internal slide relationship and `ppaction://hlinksldjump` |
+| Supported PPTX import | Reconstruct the same canonical SVG `<a href>` form |
+
+**Hard rule — Fill Native preservation**: Preserve external links. Retarget a
+same-deck jump only when its source target maps unambiguously to one output
+slide; omitted or duplicated targets fail closed instead of linking to an
+orphan or wrong slide.
+
+**Hard rule — Enhance Native preservation**: Preserve existing hyperlink XML
+and relationships unchanged. This route does not use the SVG authoring contract
+to add new links.
+
+---
+
+## 4. Exclusions and Validation
+
+**Forbidden — unsupported action settings**: Mouse-over links, custom shows,
+first/last/next/previous navigation actions, program or macro execution, OLE or
+file actions, and arbitrary `ppaction://` or relationship injection are outside
+this contract. An `actionButton*` preset remains visual geometry until wrapped
+in an ordinary supported hyperlink anchor.
+
+**Validation**: The final SVG checker validates carrier structure, target
+syntax, and slide range. Export validates relationship type/mode and final
+presentation-roster membership. Unsupported PPTX click actions produce an
+import diagnostic; strict import fails rather than fabricating an SVG link.
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 7a1cd7dd..552f62f8 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -265,6 +265,14 @@ the text-versus-native-formula decision and its authoring; if the supported
LaTeX subset cannot preserve the planned content, return here for a
content-level correction.
+#### Hyperlink Content Planning
+
+Preserve every explicit or source-backed link intent. In the applicable §IX
+page block, record the linked text/object and its exact absolute URI or final
+1-based same-deck slide target. Never guess an external destination, select the
+inline/whole-object carrier, or create a link manifest or lock entry. Executor
+owns SVG authoring under [`native-hyperlinks.md`](./native-hyperlinks.md).
+
### h. Image Source Recommendation
| Source id | Approach | Use when |
diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.md
index 6e3f5e90..eaf1ad30 100644
--- a/skills/ppt-master/scripts/docs/conversion.md
+++ b/skills/ppt-master/scripts/docs/conversion.md
@@ -200,6 +200,7 @@ Behavior:
- preserves every readable chart dimension or series and emits `[Chart data warning: <reason>]` for missing caches/count mismatches; `[Chart data unavailable: <reason>]` is reserved for charts with no readable points (and unsupported ChartEx), so XY data is never flattened into a misleading category table
- transcribes SmartArt semantic nodes as hierarchical Markdown; unreadable diagram data emits an explicit placeholder and conversion warning
- exports embedded pictures to a sibling `_files/` directory
+- preserves supported run, table-cell, picture, and text-shape links as Markdown links, including `#slide-N` jumps
- appends speaker notes when present
- writes `<input>.conversion_profile.json` after successful conversion
@@ -258,6 +259,12 @@ relationship preference for asset identity; its existing missing-media gate
remains strict rather than silently treating the raster preview as the
template's canonical asset.
+Supported `a:hlinkClick` on shape/picture `p:cNvPr` and text `a:rPr` becomes
+the shared SVG `<a href>` form for absolute external URIs and final-roster
+`#slide-N` jumps. A source shape that also has linked inner runs uses the
+importer-only `data-pptx-shape-hyperlink` transport to avoid nested SVG anchors.
+Unsupported click actions produce a diagnostic; strict import stops.
+
### Import compatibility and recovery boundary
Import is tolerant by default because the source deck is user-owned or comes
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 94bf94b9..74605c27 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -18,7 +18,7 @@
"file_budgets": {
"AGENTS.md": 2750,
"skills/ppt-master/SKILL.md": 1250,
- "skills/ppt-master/references/executor-base.md": 9250,
+ "skills/ppt-master/references/executor-base.md": 10000,
"skills/ppt-master/references/executor-structured.md": 5500,
"skills/ppt-master/references/executor-chart.md": 3500,
"skills/ppt-master/references/executor-visualization.md": 1250,
@@ -335,6 +335,16 @@
"files": [],
"max_tokens": 110000
},
+ "route.generate.quick-generate.hyperlink": {
+ "description": "Quick Generate with direct PowerPoint-native external and same-deck hyperlink authoring.",
+ "scope": "cumulative",
+ "include": [
+ "route.generate.quick-generate",
+ "stage.generate.executor.hyperlink"
+ ],
+ "files": [],
+ "max_tokens": 110000
+ },
"route.generate.quick-generate.ai-two-types": {
"description": "Quick Generate with AI resource preparation, representative rendering inputs, and two local image types.",
"scope": "cumulative",
@@ -547,6 +557,18 @@
"files": [],
"max_tokens": 170000
},
+ "route.generate.flat-hyperlink": {
+ "description": "Default flat Generate-PPTX context with PowerPoint-native external and same-deck hyperlink authoring.",
+ "scope": "cumulative",
+ "include": [
+ "route.generate.planning",
+ "stage.generate.executor.flat",
+ "stage.generate.executor.hyperlink",
+ "stage.generate.executor.notes"
+ ],
+ "files": [],
+ "max_tokens": 170000
+ },
"route.generate.flat-ai-two-types": {
"description": "Generate-PPTX context with AI images, the selected preset or exact custom rendering bases, and two local types.",
"scope": "cumulative",
@@ -1032,6 +1054,14 @@
],
"max_tokens": 1250
},
+ "stage.generate.executor.hyperlink": {
+ "description": "Conditional direct authoring contract for PowerPoint-native external and same-deck click hyperlinks.",
+ "scope": "incremental",
+ "files": [
+ "skills/ppt-master/references/native-hyperlinks.md"
+ ],
+ "max_tokens": 1250
+ },
"stage.generate.executor.image": {
"description": "Conditional image embedding and execution rules with the always-read layout math and compact composition vocabulary.",
"scope": "incremental",
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index cdbbbf84..5c1e19db 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -425,6 +425,14 @@ derivations, and other high-structure expressions remain blocks.
No formula manifest, §VIII resource row, or `spec_lock.md images` entry is
created.
+**Native hyperlink content**: Hyperlinks are not a confirmation field or a
+resource-acquisition path. Strategist records the linked text/object intent and
+exact absolute URI or 1-based same-deck slide target in the applicable §IX page
+block. Executor chooses an inline or whole-object carrier and authors the
+canonical SVG `<a href>` under
+[`native-hyperlinks.md`](../references/native-hyperlinks.md). Unknown targets
+return upstream; no hyperlink manifest or `spec_lock.md` entry is created.
+
**Proactive production decisions**: Final Stage 2 records
`proactive_speaker_notes`, `proactive_custom_animations`, and
`proactive_narration_audio`. They control only what the agent initiates when the
@@ -585,6 +593,7 @@ Keep the core's shared visual-quality defaults and `svg-effects.md` §6.1 Visual
| Actual row × column fact grid | `executor-table.md` |
| Used preset pattern fill, or independent Chart/Table with §IX `<object-key>=yes` | `native-data-interface.md` before that object |
| §IX or current page content contains mathematical notation that may require native math | `native-formula.md` before choosing ordinary text, inline native math, or block native math |
+| §IX or current page content requires an external or same-deck click hyperlink | `native-hyperlinks.md` before authoring its inline or whole-object SVG anchor |
| `spec_lock.md images` / §VIII has an image row, or the template has bundled images | `executor-image.md` + `image-layout-spec.md` + `image-layout-patterns.md` + `svg-image-embedding.md` |
| At least one placed image is `Status: Sourced` or its filename has an `image_sources.json` record | `executor-web-image.md` after the image branch |
| §I records recorded/self-running/video delivery, or §X records a final/literal narration script | `video-design.md` before the first SVG; retain it through notes/motion handling |
diff --git a/skills/ppt-master/workflows/native-enhance-pptx.md b/skills/ppt-master/workflows/native-enhance-pptx.md
index 7d8b0695..b4283953 100644
--- a/skills/ppt-master/workflows/native-enhance-pptx.md
+++ b/skills/ppt-master/workflows/native-enhance-pptx.md
@@ -16,6 +16,7 @@ This route treats a `.pptx` as the artifact to preserve. It archives the source
|---|---|
| Source file | If already under `projects/`, move it into the enhancement project; otherwise copy it |
| Visible slides | Do not rewrite existing text, shapes, images, charts, tables, masters, or layouts |
+| Existing hyperlinks | Preserve hyperlink XML and relationships unchanged |
| Route | Direct PPTX package patching; no SVG conversion |
| Output | A new `.pptx` under `<project>/exports/` |
| Project kind | `native_pptx_enhancement` |
@@ -360,7 +361,9 @@ Patch scope:
| `ppt/presProps.xml` | `showPr useTimings=1` only when this run writes automatic slide advance |
| `[Content_Types].xml` | Required content types |
-**Hard rule**: Do not modify existing slide shapes, text bodies, images, chart data, master/layout parts, or existing non-target relationships.
+**Hard rule**: Do not modify existing slide shapes, text bodies, images, chart
+data, master/layout parts, hyperlink XML/relationships, or existing non-target
+relationships.
Before publishing the candidate, apply validates transitions, timing/object
animation structure, ZIP integrity, unique parts, internal relationships,
diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.md
index d2d59ad6..e87da1b3 100644
--- a/skills/ppt-master/workflows/profiles/quick-generate.md
+++ b/skills/ppt-master/workflows/profiles/quick-generate.md
@@ -24,7 +24,7 @@ Page count alone never activates or blocks this profile.
| Execution memory | Keep routine page, visual, and resource decisions only in the current active context; losing that context restarts Quick instead of reconstructing a plan from project files |
| Inputs | Any supported Generate input; convert/import sources and run bounded factual research when the input requires them |
| Templates | Directly validate and install at most one exact workspace root per kind supplied for this run; when none are supplied, use free design without catalog selection or Confirm UI |
-| Resources | Prepare every project-local image, icon, and required provenance/manifest artifact before its SVG; author native formula markers directly in the affected SVG; sound waits for §4 |
+| Resources | Prepare every project-local image, icon, and required provenance/manifest artifact before its SVG; author native formula markers and hyperlink anchors directly in the affected SVG; sound waits for §4 |
| Planning artifacts | Do not author a root project `design_spec.md`, `spec_lock.md`, confirmation payloads, or any substitute planning artifact; installed `templates/design_spec.<kind>.<id>.md` files remain template input |
| Traceability | Operational resource manifests, checker reports, postflight, and bounded Python command/outcome audit entries may remain, but they do not record the AI's design reasoning or form a resumable generation history |
| Delivery | Hand-author the resolved SVG roster, run one lockless final checker, skip `finalize_svg.py`, and export the final native PPTX through `--quick-generate` |
@@ -277,7 +277,8 @@ the roster after the whole-roster check:
image manifests may carry filenames, page relationship, status, and
generation/crop/focal cues, but do not create a general resource roster or an
icon-to-page assignment. Keep each selected formula's source LaTeX in active
- context for direct marker authoring; create no formula manifest or image;
+ context for direct marker authoring; retain each selected hyperlink's exact
+ absolute URI or 1-based same-deck target; create no formula/link manifest;
- the implementation path for each resource. An explicit user path wins;
otherwise choose the registered automatic/default path without another
interaction.
@@ -445,6 +446,12 @@ retain exact LaTeX in active context, then choose ordinary text, same-paragraph
native inline math, or a standalone native block and author its matching SVG
preview under [`native-formula.md`](../../references/native-formula.md).
+**Mandatory — native hyperlinks**: Quick creates no hyperlink resource or
+manifest. For every selected link, retain the exact target, choose an inline or
+whole-object carrier, and author canonical SVG `<a href>` under
+[`native-hyperlinks.md`](../../references/native-hyperlinks.md). Never guess an
+unknown destination.
+
Image to PPTX replaces this open composition decision for its canonical page
frame: preserve the source geometry, restore text natively, preserve
source-graphic identity through the prepared exact or reconstructed asset, and
@@ -471,6 +478,7 @@ capability menu, visualization recall, template geometry, or a later check.
| Any actual value-driven geometry, including mini/inset charts and sparklines | [`executor-chart.md`](../../references/executor-chart.md) |
| Any actual row × column fact grid | [`executor-table.md`](../../references/executor-table.md) |
| Any mathematical notation that may require native math | [`native-formula.md`](../../references/native-formula.md) before choosing ordinary text, inline native math, or block native math |
+| Any external or same-deck click hyperlink | [`native-hyperlinks.md`](../../references/native-hyperlinks.md) before authoring its inline or whole-object SVG anchor |
| A used preset pattern fill, or one independent Chart/Table object selected as native-ready in active context | [`native-data-interface.md`](../../references/native-data-interface.md) before drawing that object |
| Any data-driven chart geometry | [`verify-charts.md`](../stages/verify-charts.md) after the complete roster and before the one final checker |
@@ -620,6 +628,7 @@ or lock.
- [x] Every page considered the complete visual-carrier menu without a coverage quota
- [x] Every image-bearing page made its one pre-geometry composition decision
- [x] Every selected formula uses the checker-valid ordinary/inline/block form with a matching visible SVG preview and no formula image resource
+- [x] Every selected hyperlink uses a checker-valid inline/whole-object anchor and an exact external or same-deck target
- [x] Resolved SVG pages and their project-local references exist
- [x] Every role declared by an installed template spec is locatable in the finished pages, or its non-use is deliberate — checked per installed spec, not from memory
- [x] Every triggered capability-specific preparation and pre-checker verification completed
diff --git a/skills/ppt-master/workflows/template-fill-pptx.md b/skills/ppt-master/workflows/template-fill-pptx.md
index 80af10e7..7488e72e 100644
--- a/skills/ppt-master/workflows/template-fill-pptx.md
+++ b/skills/ppt-master/workflows/template-fill-pptx.md
@@ -298,6 +298,12 @@ The script:
| Adds timestamp to PPTX filename | Matches the main SVG-to-PPTX export convention |
| Drops orphaned source parts | Output carries only the selected pages and the layouts / media / charts they still reference (reachability prune) |
+**Hyperlink preservation**: External hyperlinks remain unchanged. A same-deck
+slide jump is retargeted only when its source destination maps unambiguously to
+one output slide; a self-link maps to the current clone. If the destination was
+omitted or reused into multiple output slides, `apply` fails instead of linking
+to an orphan or choosing a target silently.
+
**Animation policy**: Template-fill preserves each cloned slide's existing
object animation XML (the SVG pipeline's generated object animation defaults
are not applied here). It also preserves source page transitions by default.