@web-ppt/viewer-core 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 本文件记录对使用者可见的变化。版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## 0.4.1
+
+全是中文排版的修正。四处都由同一份小学课件暴露出来，每一处都拿 PowerPoint
+自己写进文件的 `spAutoFit` 框高做的判据 —— 那个高度是它按实际行数算完存下来的，
+等于文件自己作证该排几行。
+
+### 修复
+
+- **CJK 标点挤压**。汉字和全角标点都占一整格，但标点的墨迹只占半格
+  （`，` `。` 的墨在左半格，`（` `《` 在右半格）。一行放不下时 PowerPoint 会把
+  这些空半格挤掉，我们没做，于是多断出一行。规则取「放不下才挤」：放得下时
+  保持全角。两条渲染路径算同一笔账——原生 `<text>` 用逐字符 `dx`，
+  HTML 用负边距，都与字体无关，不依赖字体是否提供 `halt` 半角替换字形。
+
+  顺带一句：这类问题**换字体救不了**。所有中文字体的方格一样大，黑体、
+  PingFang、思源黑体量出来完全相同
+- **量不到字时的中文估宽**。回退估算原本把每个字符都当 0.55em，中文因此窄掉
+  将近一半。Node / jsdom 里恒走这条路，于是**自动缩放对中文一直缩不够**——
+  autofit 固件实测旧值排出来 204px、框只有 140px，仍然溢出；按全角整格算
+  之后是 146px
+- **百分比行距的基准**。`lnSpc/spcPct` 是「单倍行距」的百分比，而单倍行距是
+  **字体的行高**（≈1.2em），不是字号。把 150% 直接当 CSS `line-height:1.5` 用，
+  每行矮两成。中文文档里 1.5 倍行距是标配，影响面不小；行距偏紧还会连累
+  自动缩放与居中 / 底对齐文本的位置
+- **静态画面改取动画初始态**（原本取终态）。缩略图、主视图、进演示模式后的
+  第一帧现在是同一个画面，不再「先把这页演完、再从头演一遍」。
+  「不能全部画出来」的理由不变：一页里入场与退场的元素属于不同时刻，摊开画
+  等于把几帧叠在一起。例外从「全员退场的收尾页」换成「整页都带入场动画的
+  封面页」——那种情况初始态一片空白，退回全部可见
+
+### 其它
+
+- 测试：1848 → **1873 项断言**，快照 160 → 162 个。`sample-autofit.pptx` 补一页
+  把百分比行距与绝对行距放在一起对照——之前 17 个固件里没有一个用过
+  `spcPct`，这条路径从没被走过
+- `@web-ppt/viewer-core` 与 `@web-ppt/fonts` 本版无改动，跟随版本号对齐
+
+## 0.4.0
+
+本版围绕**字体**：嵌入字体此前从来没有真正生效过，替换字体则完全没有。
+顺带修掉一个让静态画面把动画的几帧叠在一起的问题。
+
+### 新增
+
+- **嵌入字体真的能用了**。PowerPoint 的 `ppt/fonts/*.fntdata` 不是裸 TTF，是 EOT 容器，
+  而且实测**全部**开着 MTX 压缩（POI 语料 6/6、ORCID 样本 10/10）。此前把这段字节
+  原样当 `font/ttf` 塞进 `@font-face`，浏览器一个都不认，只在控制台留一行
+  `invalid sfntVersion`。现在 core 自己剥容器（含异或混淆），MTX 解压走
+  `setFontDecoder()` 注入——官网接的是 [`mtx-decompressor`](https://www.npmjs.com/package/mtx-decompressor) 的 `eotToTtf`，
+  core 本身仍然只依赖 fflate。解不出来就跳过这个字体，不再塞浏览器注定拒绝的字节
+- **`collectFonts(slides)`**：统计若干页用到哪些字体、每个字体要渲染哪些字。
+  纯函数、只依赖 `types.ts`，`.ppt` 链路同样适用，Worker 里能跑
+- **新包 [`@web-ppt/fonts`](packages/fonts)**（gzip 2.8KB，**包里零字节字体**）：
+  文件没带字体、本机也没装时的兜底。拉丁换**度量兼容**的免费字体
+  （Calibri→Carlito、Arial→Arimo 等，前进宽度逐字相等，断行与 PowerPoint 对齐），
+  中文换思源系 / 霞鹜文楷。切片指向钉死版本的 fontsource，按 `unicode-range` 只下用到的那几片
+- **`Viewer.refresh()`**：重渲当前页而不动页码与动画进度。网络字体到货后必须重渲——
+  排版是同步的、加载是异步的，首帧一定是按回退字体断的行
+
+### 修复
+
+- **静态渲染取动画终态，而不是「全部可见」**。一页里入场与退场的元素属于不同时刻，
+  全画出来等于把几帧叠在一起：ORCID 那份样本的第 7 页三段文字本该逐条替换，
+  叠起来一个字都读不出。终态会清空整页时（全员退场的收尾页）退回全部可见
+- **run 没写 `a:latin` 时落到主题的 minorFont**。ECMA-376 的继承链最后一站就是
+  `fontScheme/minorFont`，此前直接当「没有字体」，渲染掉到 CSS 通用回退上，
+  字宽与 PowerPoint 对不齐。真实文件大多在母版 txStyles 里写了 `+mn-lt` 所以少见，
+  但这是「断行对不齐」的一个隐藏来源
+- 字体栈去重：主题的 ea 字体常常正好是回退列表里的 `PingFang SC`，之前会拼出重复项
+
+### 其它
+
+- 测试：1689 → **1848 项断言**，快照 158 → 160 个；新增 `sample-embedfont.pptx`
+  覆盖嵌入字体的四种容器形态（未压缩 EOT / 未压缩+异或 / MTX 压缩 / 裸 TTF）
+- `@web-ppt/core` gzip 84KB 不变；`@web-ppt/viewer-core` 6.8KB → 7.4KB
+- 两个既有包的 peer 依赖同步升到 `^0.4.0`
+
 ## 0.3.0
 
 本版把 ECMA-376 的几处主要缺口补齐，并首次拿 **Apache POI 的 242 个公开测试文件**跑批验证：

package/LICENSE

@@ -1,201 +1,21 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+MIT License
+
+Copyright (c) 2026 unStone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -11,5 +11,5 @@ export { Viewer } from './viewer';
 export { foreignObjectScalesCorrectly, resetForeignObjectProbe } from './foreign-object';
 export type { ViewerOptions } from './viewer';
 export { autoAdvanceMs, framesFor, morphPairs, playGroup, playTransition, transitionFrames } from './playback';
-export { groupSteps, hiddenBefore } from '@web-ppt/core';
+export { groupSteps, hiddenBefore, staticHidden } from '@web-ppt/core';
 export type { PlayHandle } from './playback';

package/dist/state.d.ts

@@ -55,7 +55,12 @@ export declare class PresentationState {
     get animationTotal(): number;
     get animationDone(): number;
     get hasPendingAnimation(): boolean;
-    /** 当前批次下应当隐藏的元素 id —— UI 据此设置可见性 */
+    /**
+     * 当前应当隐藏的元素 id —— UI 据此设置可见性。
+     *
+     * 不播动画时不是「全部可见」，而是动画终态：入场与退场的元素属于不同时刻，
+     * 一起画出来就是几帧叠在一起（见 core 的 staticHidden）。
+     */
     get hiddenElementIds(): ReadonlySet<number>;
     /** 本页的自动换片延迟（毫秒），未配置则为 null */
     get autoAdvanceDelay(): number | null;

package/dist/viewer-core.js

@@ -1,7 +1,7 @@
-import { hiddenBefore as P, groupSteps as S, slideText as M, renderSlideToSvg as v, slideToPng as C } from "@web-ppt/core";
-import { groupSteps as Z, hiddenBefore as R } from "@web-ppt/core";
+import { hiddenBefore as C, staticHidden as w, groupSteps as M, slideText as S, renderSlideToSvg as v, slideToPng as T } from "@web-ppt/core";
+import { groupSteps as R, hiddenBefore as W, staticHidden as G } from "@web-ppt/core";
 const h = 1.15;
-function T(s) {
+function $(s) {
   switch (s) {
     case "l":
       return [-100 * h, 0];
@@ -40,12 +40,12 @@ function d(s, t) {
       return `inset(${e}% 0 0 0)`;
   }
 }
-function w(s) {
+function A(s) {
   switch (s.effect) {
     case "appear":
       return { from: { opacity: 0 }, to: { opacity: 1 } };
     case "fly": {
-      const [t, e] = T(s.dir);
+      const [t, e] = $(s.dir);
       return {
         from: { opacity: 0, transform: `translate(${t}%, ${e}%)` },
         to: { opacity: 1, transform: "translate(0, 0)" }
@@ -83,11 +83,11 @@ function w(s) {
       return { from: { opacity: 0 }, to: { opacity: 1 } };
   }
 }
-function $(s) {
-  const t = w({ ...s });
+function k(s) {
+  const t = A({ ...s });
   return { from: t.to, to: t.from };
 }
-function k(s) {
+function E(s) {
   switch (s.effect) {
     case "spin":
       return { from: { transform: "rotate(0)" }, to: { transform: "rotate(360deg)" } };
@@ -97,10 +97,10 @@ function k(s) {
       return { from: { opacity: 1 }, to: { opacity: 0.35 } };
   }
 }
-function E(s) {
-  return s.kind === "exit" ? $(s) : s.kind === "emphasis" ? k(s) : s.kind === "motion" ? { from: { opacity: 1 }, to: { opacity: 1 } } : w(s);
+function z(s) {
+  return s.kind === "exit" ? k(s) : s.kind === "emphasis" ? E(s) : s.kind === "motion" ? { from: { opacity: 1 }, to: { opacity: 1 } } : A(s);
 }
-function z(s, t) {
+function Y(s, t) {
   var n, r;
   const e = [];
   let a = 0;
@@ -109,7 +109,7 @@ function z(s, t) {
     if (!c) continue;
     const o = i.trigger === "afterPrev" ? a + i.delayMs : i.delayMs;
     i.trigger === "afterPrev" ? a = o + i.durationMs : a = Math.max(a, o + i.durationMs);
-    const { from: l, to: p } = E(i);
+    const { from: l, to: p } = z(i);
     c.style.visibility = "visible", i.kind === "entrance" && (c.style.opacity = "");
     const f = (n = i.motionPath) != null && n.length ? i.motionPath.map(([u, y]) => ({ transform: `translate(${u}px, ${y}px)` })) : [l, p];
     try {
@@ -244,13 +244,13 @@ function x(s, t) {
       return t ? [{ opacity: 0 }, { opacity: 1 }] : [{ opacity: 1 }, { opacity: 0 }];
   }
 }
-function A(s, t) {
+function b(s, t) {
   const e = Promise.all(s.map((a) => a.catch(() => {
   }))).then(() => {
   });
   return typeof setTimeout != "function" ? e : Promise.race([e, new Promise((a) => setTimeout(a, t + 250))]);
 }
-function Y(s, t) {
+function L(s, t) {
   const e = /* @__PURE__ */ new Map();
   s.querySelectorAll("[data-el]").forEach((n) => {
     const r = n.getBoundingClientRect();
@@ -264,18 +264,18 @@ function Y(s, t) {
     i.width <= 0 && i.height <= 0 || a.push({ node: n, from: r, to: i });
   }), a;
 }
-function L(s, t, e) {
+function X(s, t, e) {
   if (!s) return Promise.resolve();
-  const a = { duration: e.durationMs, easing: "ease-in-out", fill: "both" }, n = Y(s, t), r = new Set(n.map((o) => o.node.getAttribute("data-el"))), i = [], c = (o, l) => {
+  const a = { duration: e.durationMs, easing: "ease-in-out", fill: "both" }, n = L(s, t), r = new Set(n.map((o) => o.node.getAttribute("data-el"))), i = [], c = (o, l) => {
     try {
       i.push(o.animate(l, a).finished);
     } catch {
     }
   };
   for (const { node: o, from: l, to: p } of n) {
-    const f = l.left - p.left, u = l.top - p.top, y = p.width > 0 ? l.width / p.width : 1, b = p.height > 0 ? l.height / p.height : 1;
+    const f = l.left - p.left, u = l.top - p.top, y = p.width > 0 ? l.width / p.width : 1, P = p.height > 0 ? l.height / p.height : 1;
     c(o, [
-      { transformOrigin: "left top", transform: `translate(${f}px, ${u}px) scale(${y}, ${b})` },
+      { transformOrigin: "left top", transform: `translate(${f}px, ${u}px) scale(${y}, ${P})` },
       { transformOrigin: "left top", transform: "none" }
     ]);
   }
@@ -284,30 +284,30 @@ function L(s, t, e) {
     c(o, l ? [{ opacity: 0 }, { opacity: 0 }] : [{ opacity: 1 }, { opacity: 0 }]);
   }), t.querySelectorAll("[data-el]").forEach((o) => {
     r.has(o.getAttribute("data-el")) || c(o, [{ opacity: 0 }, { opacity: 1 }]);
-  }), A(i, e.durationMs).then(() => {
+  }), b(i, e.durationMs).then(() => {
     s.remove();
   });
 }
-function X(s, t, e) {
+function N(s, t, e) {
   if (!e || e.type === "none")
     return s == null || s.remove(), Promise.resolve();
-  if (e.type === "morph" && s) return L(s, t, e);
+  if (e.type === "morph" && s) return X(s, t, e);
   const a = { duration: e.durationMs, easing: "ease-in-out", fill: "both" }, n = [];
   try {
     n.push(t.animate(x(e, !0), a).finished), s && n.push(s.animate(x(e, !1), a).finished);
   } catch {
     return s == null || s.remove(), Promise.resolve();
   }
-  return A(n, e.durationMs).then(() => {
+  return b(n, e.durationMs).then(() => {
     s == null || s.remove();
   });
 }
-function N(s) {
+function V(s) {
   var e;
   const t = (e = s.transition) == null ? void 0 : e.advanceAfterMs;
   return t !== void 0 && t > 0 ? t : null;
 }
-class V {
+class F {
   constructor(t, e = {}) {
     this.presentation = t, this.options = e, this.idx = 0, this.zoomValue = 1, this.groups = [], this.cursor = 0, this.listeners = /* @__PURE__ */ new Set(), this.autoTimer = null, this.textCache = /* @__PURE__ */ new Map(), this.idx = this.clamp(e.index ?? 0), this.loadAnimations();
   }
@@ -336,13 +336,18 @@ class V {
   get hasPendingAnimation() {
     return this.animate && this.cursor < this.groups.length;
   }
-  /** 当前批次下应当隐藏的元素 id —— UI 据此设置可见性 */
+  /**
+   * 当前应当隐藏的元素 id —— UI 据此设置可见性。
+   *
+   * 不播动画时不是「全部可见」，而是动画终态：入场与退场的元素属于不同时刻，
+   * 一起画出来就是几帧叠在一起（见 core 的 staticHidden）。
+   */
   get hiddenElementIds() {
-    return this.animate ? P(this.groups, this.cursor) : /* @__PURE__ */ new Set();
+    return this.animate ? C(this.groups, this.cursor) : w(this.slide);
   }
   /** 本页的自动换片延迟（毫秒），未配置则为 null */
   get autoAdvanceDelay() {
-    return this.options.autoAdvance ? N(this.slide) : null;
+    return this.options.autoAdvance ? V(this.slide) : null;
   }
   // ---------------- 订阅 ----------------
   subscribe(t) {
@@ -395,7 +400,7 @@ class V {
   }
   // ---------------- 动画 ----------------
   loadAnimations() {
-    this.groups = this.animate ? S(this.slide.animations) : [], this.cursor = 0;
+    this.groups = this.animate ? M(this.slide.animations) : [], this.cursor = 0;
   }
   /**
    * 推进一批动画。返回应播放的这一批；没有待播批次时返回 null。
@@ -426,7 +431,7 @@ class V {
   // ---------------- 文本 / 搜索 ----------------
   text(t) {
     let e = this.textCache.get(t);
-    return e === void 0 && (e = M(this.presentation.slides[t]), this.textCache.set(t, e)), e;
+    return e === void 0 && (e = S(this.presentation.slides[t]), this.textCache.set(t, e)), e;
   }
   /** 全文搜索，返回命中的页索引 */
   search(t) {
@@ -447,12 +452,12 @@ class V {
     this.cancelAutoAdvance(), this.listeners.clear(), this.textCache.clear();
   }
 }
-const g = "http://www.w3.org/2000/svg", F = "http://www.w3.org/1999/xhtml";
+const g = "http://www.w3.org/2000/svg", D = "http://www.w3.org/1999/xhtml";
 let m = null;
-function j() {
+function H() {
   m = null;
 }
-function D(s) {
+function q(s) {
   if (m !== null) return m;
   const t = s.body ?? s.documentElement;
   if (!t) return !0;
@@ -460,7 +465,7 @@ function D(s) {
   e.setAttribute("viewBox", "0 0 100 100"), e.setAttribute("width", "200"), e.setAttribute("height", "200"), e.setAttribute("style", "position:absolute;left:-9999px;top:-9999px;pointer-events:none");
   const a = s.createElementNS(g, "foreignObject");
   a.setAttribute("width", "100"), a.setAttribute("height", "100");
-  const n = s.createElementNS(F, "div");
+  const n = s.createElementNS(D, "div");
   n.setAttribute("style", "width:100px;height:100px"), a.appendChild(n), e.appendChild(a), t.appendChild(e);
   const r = n.getBoundingClientRect().width;
   return e.remove(), m = r === 0 || r > 150, m;
@@ -479,7 +484,7 @@ class O {
       l && this.onLinkClick && this.onLinkClick(l) === !0 && r.preventDefault();
     }, this.media = a.media ?? "badge";
     const n = a.textMode ?? "auto";
-    this.textMode = n !== "auto" ? n : D(t.ownerDocument) ? "html" : "svg", this.state = new V(e, a), this.unsubscribe = this.state.subscribe((r) => {
+    this.textMode = n !== "auto" ? n : q(t.ownerDocument) ? "html" : "svg", this.state = new F(e, a), this.unsubscribe = this.state.subscribe((r) => {
       var i, c;
       r.type === "slide" ? (this.paint(r.transition), (i = this.onChange) == null || i.call(this, r.index)) : r.type === "animation" ? (r.group ? this.play(r.group) : this.applyVisibility(), (c = this.onAnimStep) == null || c.call(this, r.done, r.total)) : r.type === "zoom" && this.applyZoom();
     }), this.container.addEventListener("click", this.handleClick), this.paint();
@@ -544,10 +549,26 @@ class O {
   }
   /** 不走缓存，用于缩略图等需要独立 defs id 的场景 */
   renderSlide(t) {
-    return v(this.presentation, this.presentation.slides[t], { textMode: this.textMode });
+    const e = this.presentation.slides[t];
+    return v(this.presentation, e, {
+      // 缩略图不嵌播放器：既没意义，还会为每个缩略图各建一个媒体元素
+      textMode: this.textMode,
+      // 缩略图是静态产物，没有后续的 applyVisibility，隐藏状态只能烘进 SVG
+      hiddenElements: [...w(e)]
+    });
+  }
+  /**
+   * 重渲当前页，页码与动画进度都不变。
+   *
+   * 给「渲染完之后世界才变」的情况用，最典型的是网络字体到货：原生 `<text>`
+   * 路径的断行是渲染时拿 canvas 量出来烘进 SVG 的，字体换了就必须重量一遍；
+   * `foreignObject` 路径由浏览器自己重排，重渲只是顺带把缓存换掉。
+   */
+  refresh() {
+    this.svgCache.delete(this.index), this.paint();
   }
   exportPng(t = 2, e = this.index) {
-    return C(this.presentation, this.presentation.slides[e], t);
+    return T(this.presentation, this.presentation.slides[e], t);
   }
   paint(t) {
     var i, c, o;
@@ -555,17 +576,20 @@ class O {
     const e = document.createElement("div");
     e.style.cssText = "position:absolute;inset:0;display:flex;align-items:center;justify-content:center", e.innerHTML = this.slideSvg(this.index);
     const a = this.container.firstElementChild, n = this.container.ownerDocument.defaultView;
-    (!n || n.getComputedStyle(this.container).position === "static") && (this.container.style.position = "relative"), t && a ? (this.container.appendChild(e), X(a, e, t).then(() => this.startAutoAdvance())) : (this.container.innerHTML = "", this.container.appendChild(e), this.startAutoAdvance());
+    (!n || n.getComputedStyle(this.container).position === "static") && (this.container.style.position = "relative"), t && a ? (this.container.appendChild(e), N(a, e, t).then(() => this.startAutoAdvance())) : (this.container.innerHTML = "", this.container.appendChild(e), this.startAutoAdvance());
     const r = e.querySelector("svg");
     r && (r.style.display = "block", r.style.maxWidth = "none"), this.applyZoom(), this.applyVisibility(), (o = this.onAnimStep) == null || o.call(this, this.state.animationDone, this.state.animationTotal);
   }
   play(t) {
     var e;
-    (e = this.playing) == null || e.cancel(), this.playing = z(this.container, t), this.applyVisibility();
+    (e = this.playing) == null || e.cancel(), this.playing = Y(this.container, t), this.applyVisibility();
   }
-  /** 按状态机给出的隐藏集合设置元素可见性 */
+  /**
+   * 按状态机给出的隐藏集合设置元素可见性。
+   *
+   * 不播动画时也要跑：静态画面取的是动画终态，退场元素同样得藏起来。
+   */
   applyVisibility() {
-    if (!this.state.animate) return;
     const t = this.state.hiddenElementIds;
     this.container.querySelectorAll("[data-el]").forEach((e) => {
       const a = Number(e.getAttribute("data-el"));
@@ -587,16 +611,17 @@ class O {
   }
 }
 export {
-  V as PresentationState,
+  F as PresentationState,
   O as Viewer,
-  N as autoAdvanceMs,
-  D as foreignObjectScalesCorrectly,
-  E as framesFor,
-  Z as groupSteps,
-  R as hiddenBefore,
-  Y as morphPairs,
-  z as playGroup,
-  X as playTransition,
-  j as resetForeignObjectProbe,
+  V as autoAdvanceMs,
+  q as foreignObjectScalesCorrectly,
+  z as framesFor,
+  R as groupSteps,
+  W as hiddenBefore,
+  L as morphPairs,
+  Y as playGroup,
+  N as playTransition,
+  H as resetForeignObjectProbe,
+  G as staticHidden,
   x as transitionFrames
 };

package/dist/viewer.d.ts

@@ -55,10 +55,22 @@ export declare class Viewer {
     slideSvg(i: number): string;
     /** 不走缓存，用于缩略图等需要独立 defs id 的场景 */
     renderSlide(i: number): string;
+    /**
+     * 重渲当前页，页码与动画进度都不变。
+     *
+     * 给「渲染完之后世界才变」的情况用，最典型的是网络字体到货：原生 `<text>`
+     * 路径的断行是渲染时拿 canvas 量出来烘进 SVG 的，字体换了就必须重量一遍；
+     * `foreignObject` 路径由浏览器自己重排，重渲只是顺带把缓存换掉。
+     */
+    refresh(): void;
     exportPng(scale?: number, i?: number): Promise<Blob>;
     private paint;
     private play;
-    /** 按状态机给出的隐藏集合设置元素可见性 */
+    /**
+     * 按状态机给出的隐藏集合设置元素可见性。
+     *
+     * 不播动画时也要跑：静态画面取的是动画终态，退场元素同样得藏起来。
+     */
     private applyVisibility;
     private applyZoom;
     private startAutoAdvance;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web-ppt/viewer-core",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Web-PPT 查看器的 headless 状态机与播放层：导航 / 缩放 / 搜索 / 动画批次，可被任意 UI 框架驱动",
   "keywords": [
     "pptx",
@@ -50,7 +50,7 @@
     "prepack": "node ../../tooling/sync-package-docs.mjs"
   },
   "peerDependencies": {
-    "@web-ppt/core": "^0.3.0"
+    "@web-ppt/core": "^0.4.0"
   },
   "publishConfig": {
     "access": "public"