@web-ppt/viewer-core 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 本文件记录对使用者可见的变化。版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## 0.4.4
+
+本版没有代码改动，只动文档——但 npm 上看到的东西全变了，所以值得单独发一版。
+
+### 变更
+
+- **npm 页面改英文**。三个包的 README 与 `description` 之前全是中文，
+  而 npm 的读者以国际开发者为主，等于最有说服力的能力矩阵对他们不存在。
+  现在 `@web-ppt/core` 的 npm 页取仓库的 `README.en.md`，另两个包各自
+  维护英文版，中文移到同目录的 `README.zh-CN.md`，两边顶部互链。
+
+  GitHub 首页仍是中文，两个入口各自面向自己的人群。
+
+- **README 首屏补了演示 GIF 与定位段**。GIF 由 `npm run demo-gif` 录制，
+  录的是仓库自己生成的 `fixtures/showcase.pptx`，引擎改了重跑即可，
+  不是一次性的手工录屏。
+
+## 0.4.3
+
+### 变更
+
+- **静态画面改回动画终态**，撤销 0.4.1 里改成初始态的那次调整。
+
+  对齐 PowerPoint 的模型：普通视图与缩略图看到的是「这一页演完的样子」，
+  按 F5 进入演示才从第一步开始建。所以**进全屏时画面跳一次是预期行为**，
+  不是 bug —— 0.4.1 当时是把这个跳变当成缺陷去消除的，方向错了。
+
+  「不能简单摊开全画」这条不变：一页里入场与退场的元素属于不同时刻，
+  全画出来等于把几帧叠在一起。全员退场的收尾页终态是空白，那种情况仍然
+  退回全部可见。
+
 ## 0.4.2
 
 ### 修复

package/README.md

@@ -1,16 +1,16 @@
 # @web-ppt/viewer-core
 
-[Web-PPT](https://github.com/unStone/web-ppt) 查看器的 headless 层。
+**English** · [简体中文](https://github.com/unStone/web-ppt/blob/master/packages/viewer-core/README.zh-CN.md)
 
-`PresentationState` 是零 DOM 的纯状态机——导航 / 缩放 / 搜索 / 动画批次 / 自动换片，
-可被原生 DOM、React、Vue、Svelte 任意 UI 驱动，也能在 Node 里直接跑测试。
-`Viewer` 是它之上最薄的一层 DOM 绑定（塞 SVG、设可见性、调播放，约 24 行）。
+The headless layer of [Web-PPT](https://github.com/unStone/web-ppt).
+
+`PresentationState` is a pure state machine with zero DOM — navigation, zoom, search, animation batching, auto-advance. Drive it from plain DOM, React, Vue or Svelte, or run it straight in Node for tests. `Viewer` is the thinnest possible DOM binding on top (inject SVG, set visibility, kick off playback — about 24 lines).
 
 ```bash
 npm i @web-ppt/core @web-ppt/viewer-core
 ```
 
-## 开箱即用
+## Batteries included
 
 ```ts
 import { parse } from '@web-ppt/core';
@@ -19,14 +19,14 @@ import { Viewer } from '@web-ppt/viewer-core';
 const pres = await parse(file);
 const v = new Viewer(container, pres, { animate: true, autoAdvance: true });
 
-v.next();              // 有待播动画时先播动画，否则翻页
-v.finishAnimations();  // 跳到本页动画终态
+v.next();              // plays a pending animation batch, otherwise advances the slide
+v.finishAnimations();  // jump to this slide's end state
 v.setZoom(1.5);
-v.search('关键词');     // → 命中的页索引数组
+v.search('keyword');   // → array of matching slide indices
 await v.exportPng(2);  // → Blob
 ```
 
-## 接自己的 UI
+## Bring your own UI
 
 ```ts
 import { PresentationState, playGroup, playTransition } from '@web-ppt/viewer-core';
@@ -43,11 +43,10 @@ st.subscribe((change) => {
 });
 
 st.next();
-st.hiddenElementIds;   // 当前批次下应隐藏的元素 id
-st.resolveLink(href);  // 'slide:3' → 2，外链 → null
+st.hiddenElementIds;   // element ids that should be hidden at the current batch
+st.resolveLink(href);  // 'slide:3' → 2, external links → null
 ```
 
-状态机只决定「该显示什么」，实际播放由 UI 层调 `playGroup` / `playTransition` 完成——
-所以换框架时不需要重写任何逻辑。
+The state machine only decides *what should be visible*; the UI layer performs the actual playback through `playGroup` / `playTransition` — so switching frameworks rewrites no logic.
 
 MIT

package/README.zh-CN.md

@@ -0,0 +1,55 @@
+# @web-ppt/viewer-core
+
+[English](README.md) · **简体中文**
+
+[Web-PPT](https://github.com/unStone/web-ppt) 查看器的 headless 层。
+
+`PresentationState` 是零 DOM 的纯状态机——导航 / 缩放 / 搜索 / 动画批次 / 自动换片，
+可被原生 DOM、React、Vue、Svelte 任意 UI 驱动，也能在 Node 里直接跑测试。
+`Viewer` 是它之上最薄的一层 DOM 绑定（塞 SVG、设可见性、调播放，约 24 行）。
+
+```bash
+npm i @web-ppt/core @web-ppt/viewer-core
+```
+
+## 开箱即用
+
+```ts
+import { parse } from '@web-ppt/core';
+import { Viewer } from '@web-ppt/viewer-core';
+
+const pres = await parse(file);
+const v = new Viewer(container, pres, { animate: true, autoAdvance: true });
+
+v.next();              // 有待播动画时先播动画，否则翻页
+v.finishAnimations();  // 跳到本页动画终态
+v.setZoom(1.5);
+v.search('关键词');     // → 命中的页索引数组
+await v.exportPng(2);  // → Blob
+```
+
+## 接自己的 UI
+
+```ts
+import { PresentationState, playGroup, playTransition } from '@web-ppt/viewer-core';
+
+const st = new PresentationState(pres, { skipHidden: true, animate: true });
+
+st.subscribe((change) => {
+  if (change.type === 'slide') {
+    render(change.index);
+    if (change.transition) playTransition(prevEl, nextEl, change.transition);
+  } else if (change.type === 'animation' && change.group) {
+    playGroup(container, change.group);
+  }
+});
+
+st.next();
+st.hiddenElementIds;   // 当前批次下应隐藏的元素 id
+st.resolveLink(href);  // 'slide:3' → 2，外链 → null
+```
+
+状态机只决定「该显示什么」，实际播放由 UI 层调 `playGroup` / `playTransition` 完成——
+所以换框架时不需要重写任何逻辑。
+
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@web-ppt/viewer-core",
-  "version": "0.4.2",
-  "description": "Web-PPT 查看器的 headless 状态机与播放层：导航 / 缩放 / 搜索 / 动画批次，可被任意 UI 框架驱动",
+  "version": "0.4.4",
+  "description": "Headless presentation state machine for Web-PPT: navigation, zoom, search and click-batched animation playback, drivable from any UI framework.",
   "keywords": [
     "pptx",
     "ppt",