@liustack/pptwise 0.22.0 → 0.24.0

package/README.md

@@ -1,12 +1,13 @@
-<p align="center"><img src="assets/banner.png" alt="pptwise — make your deck in minutes, not hours" width="100%"></p>
+<p align="center"><img src="assets/banner.png" alt="pptwise: A real PowerPoint, not a picture or HTML." width="100%"></p>
 
 <h1 align="center">pptwise</h1>
 
-<p align="center"><b>Make your deck in minutes, not hours.</b></p>
+<p align="center"><b>A real PowerPoint, not a picture or HTML.</b></p>
 
 <p align="center">🥇 <b>The FIRST deck-generation plugin for DeepSeek Harness (dsh)</b> 🥇</p>
 
 <p align="center">
+  <a href="https://pptwise.com">pptwise.com</a> ·
   <a href="./README.zh-CN.md">简体中文</a> ·
   <a href="./INSTALL.md">Install (hand it to your AI)</a> ·
   <a href="./docs/cli.md">Commands</a> ·
@@ -31,13 +32,13 @@ Issues are welcome any time. [Open one](https://github.com/liustack/pptwise/issu
 
 ## Highlights
 
-**⚡ Tell your AI what to cover, get the deck.** You bring the content, the engine handles layout, color, type size, and spacing. The same content renders the same deck every time, so there is nothing to redo and no luck involved.
+**⚡ Tell your AI what to cover, get the deck.** You bring the intent, the engine turns semantic page kinds and typed components into a coherent theme-bound deck. The same bound input renders the same output every time.
 
-**✏️ A real deck, not a picture of one.** Every heading, bullet, and chart bar opens in PowerPoint for you to retype and restyle. Chart and table figures are the exception: to change the numbers, have your AI rebuild that page. 24 ready-made styles, and you can pull the colors and fonts out of a deck your company already uses.
+**✏️ Open it in PowerPoint and keep working.** Every heading, bullet, and chart bar opens in PowerPoint for you to retype and restyle. Chart and table figures are the exception: to change the numbers, have your AI rebuild that page. Start from 24 factory themes, copy one into your workspace, or extract colors and fonts from a deck your company already uses.
 
 **🔌 Installs into the agent you already use.** One command puts pptwise into DeepSeek Harness, Claude Code, or any agent that reads a skill folder (Codex and friends), and it knows how to build a deck the moment it lands.
 
-**🔁 Revisions without describing everything again.** One command opens a live preview in your browser. Tell your AI what to change in plain words — the page refreshes itself as each revision lands.
+**🔁 Revisions without describing everything again.** One command opens a live preview in your browser. Tell your AI what to change in plain words, and the page refreshes itself as each revision lands.
 
 **🔒 No account, no API key to render, no network at render time.** Install it and it works. Node 22.19+ or Bun is all you need on the machine. Optional stock-photo search uses the user's own Pexels key.
 
@@ -45,56 +46,86 @@ Issues are welcome any time. [Open one](https://github.com/liustack/pptwise/issu
 
 **Step 1, hand it to your AI.** Send it this line:
 
-> Install the pptwise deck skill following https://raw.githubusercontent.com/liustack/pptwise/main/INSTALL.md, then run the health check and tell me the result.
+> Install pptwise following https://raw.githubusercontent.com/liustack/pptwise/main/INSTALL.md, then run the health check and tell me the result.
 
-There is no step 2. Your AI puts the skill folder where your harness reads it, and the skill brings its own version-pinned launcher, so there is no CLI to install by hand. pptwise renders a PPTX entirely locally: no API key, no account, nothing to configure for render. Optional stock-photo search needs the user's own Pexels key. The only prerequisite is Node 22.19+ (or Bun).
+**On DeepSeek Harness, send this instead.** There pptwise is a native plugin rather than a skill folder, so it has its own guide. You pick the line, not your agent: an agent cannot reliably tell which harness it is running in.
 
-**On DeepSeek Harness, it is one command instead.** pptwise is a native DSH plugin there, not a skill folder:
+> Install pptwise following https://raw.githubusercontent.com/liustack/pptwise/main/INSTALL-dsh.md, then run the health check and tell me the result.
 
-```bash
-npx -y @deepseek-ai/dsh plugin --profile web add @liustack/pptwise@0.22.0
-```
-
-Name the version. Without it, the install quietly lands on an older release and you miss the newest features. `npm view @liustack/pptwise version` prints the current one. The plugin card shows up as "pptwise", registers the deck-generation skill, and carries the CLI inside its own package. Uninstalling removes the skill with no residue.
+There is no step 2. Your AI puts the skill folder where your harness reads it, and the skill brings its own version-pinned launcher, so there is no CLI to install by hand. pptwise renders a PPTX entirely locally: no API key, no account, nothing to configure for render. Optional stock-photo search needs the user's own Pexels key. The only prerequisite is Node 22.19+ (or Bun).
 
 ## Quick start
 
-An IR is one JSON file describing the whole deck. Write a minimal one, then run the validate → render → preview loop:
+IR v5 is one JSON file describing a complete bound deck. Every content page names its semantic `kind`. The theme menu turns that kind into a visual face.
 
-```bash
-cat > deck.json <<'EOF'
+```json
 {
+  "version": "5",
   "filename": "hello.pptx",
   "theme": { "id": "consulting" },
   "slides": [
-    { "type": "cover", "heading": "Hello pptwise", "subheading": "A first deck in ten minutes" },
-    { "type": "content", "heading": "Why it works", "components": [
-      { "type": "bullets", "items": ["Semantic IR in", "Native DrawingML out", "Every shape stays editable"] } ] },
+    {
+      "type": "cover",
+      "heading": "Hello pptwise",
+      "subheading": "A first native deck"
+    },
+    {
+      "type": "content",
+      "kind": "points",
+      "heading": "Why it works",
+      "components": [
+        {
+          "type": "bullets",
+          "items": ["Semantic IR in", "Theme-menu lookup", "Native DrawingML out"]
+        }
+      ]
+    },
     { "type": "ending", "heading": "Thanks" }
   ]
 }
-EOF
-pptwise validate deck.json                              # → OK — 3 slides, theme "consulting"
-pptwise render deck.json -o out/hello.pptx              # → wrote out/hello.pptx (3 slides, ~24 KB)
-pptwise render deck.json -o out/tech.pptx --theme tech  # same deck, different theme
-pptwise preview deck.json -o out/svgs                   # SVG per slide, for a visual self-check
 ```
 
-One shape rule: `cover`/`chapter`/`ending` slides are heading + subheading only, components live on `content` slides. `validate` says exactly this if you mix them up.
+Save that as `deck.json`, then run:
+
+```bash
+pptwise validate deck.json
+pptwise render deck.json -o out/hello.pptx
+pptwise preview deck.json -o out/review --html
+```
+
+Choose a theme from `pptwise themes --json` by matching `occasions` and `identity`. Compare two to four candidates before binding:
+
+```bash
+pptwise theme try consulting,swiss,memo
+```
+
+Create a complete independent v2 theme by copying a preset, forking a palette, or extracting an Office brand:
+
+```bash
+pptwise theme new --from consulting -o themes/acme.theme.json --id acme
+pptwise theme fork acme --primary "#0B5FFF" -o themes/acme-blue.theme.json --id acme-blue
+pptwise brand extract corp.pptx -o themes/acme-brand.theme.json --id acme-brand --from consulting
+```
+
+A deck project binds one theme in `deck.spec.json`, then keeps page content in `pages/<id>.json`. Render has no temporary theme switch. A same-menu color fork can replace the binding. A different menu requires returning to theme selection, then revisiting the spec and affected page fills.
 
-No install at all also works: `npx -y @liustack/pptwise validate deck.json`. In a source checkout, `node dist/cli.js` replaces `pptwise`, and `examples/` has ready-made IR files to try.
+No install also works: `npx -y @liustack/pptwise validate deck.json`. In a source checkout, use `node dist/cli.js` in place of `pptwise`. Ready-made v5 files live under `examples/`.
 
 The commands you will reach for most:
 
-| Command | Does |
-|---|---|
-| `validate <target>` | Check the IR, with page numbers on every error |
-| `render <target> [-o <out.pptx>] [--theme <id>]` | Render a `.pptx`. Omit `-o` to write `.pptwise/<deck>/<deck>.pptx` |
-| `preview <target> [-o <dir>] [--html]` | One SVG per slide, plus a self-contained review page. Omit `-o` to write `.pptwise/<deck>/` |
-| `serve <target>` | Live preview that reloads on every change |
-| `audit <target>` | Geometry review: overflow, out-of-bounds, low contrast, overlap |
-| `themes` | List the built-in themes |
-| `doctor` | Check the install: runtime, skill copies, optional capabilities, self-test render |
+| command | purpose |
+| --- | --- |
+| `spec validate <spec.json>` | Validate page order, kinds, headings, narrative, and theme-menu fit. |
+| `assemble <dir>` | Combine a deck project into derived IR v5 without storing rendering choices. |
+| `validate <target>` | Check IR, binding, menu, components, assets, and content quality. |
+| `render <target> [-o <out.pptx>]` | Render native editable PPTX. |
+| `audit <target>` | Check geometry, contrast, truncation, dropped content, and monotony. |
+| `preview <target> [--html]` | Write SVG pages and an optional self-contained review file. |
+| `serve <target>` | Start a live review that reloads on source changes. |
+| `themes [--json]` | List factory themes with occasion and identity metadata. |
+| `theme try <id,id,...>` | Compare the fixed sample across two to four themes. |
+| `theme new`, `theme fork` | Copy a complete theme or create a full-palette fork. |
+| `doctor` | Check runtime, skill copies, optional capabilities, and a self-test render. |
 
 Full reference: [`docs/cli.md`](./docs/cli.md).
 
@@ -105,12 +136,12 @@ Full reference: [`docs/cli.md`](./docs/cli.md).
 | [Install guide](./INSTALL.md) | Handing installation to an agent or checking prerequisites |
 | [Agent skill](./skills/pptwise/SKILL.md) | Learning the workflow pptwise teaches an agent |
 | [CLI manual](./docs/cli.md) | Looking up commands, flags, audits, previews, and health checks |
-| [IR reference](./docs/ir.md) | Writing a deck, slide, component, or narrative in JSON |
-| [Themes](./docs/themes.md) | Picking a built-in theme or extracting your own brand |
-| [Core concepts](./docs/concepts.md) | Understanding themes, layouts, components, narratives, and capacity |
-| [Architecture](./docs/architecture.md) | Working on the render chain or adding a theme, layout, or component |
-| [Deck projects](./docs/deck-projects.md) | Building a multi-file deck with locked specs, assets, and live review |
-| [Layout selection and seed](./docs/selection-and-seed.md) | Explaining why a layout was picked or keeping revisions stable |
+| [IR reference](./docs/ir.md) | Writing IR v5 pages, kinds, components, assets, and narrative in JSON |
+| [Themes](./docs/themes.md) | Copying, comparing, forking, binding, or authoring a complete v2 theme |
+| [Core concepts](./docs/concepts.md) | Understanding theme, spec, component, kind, menus, and capacity |
+| [Architecture](./docs/architecture.md) | Working on the menu route, render chain, or export boundary |
+| [Deck projects](./docs/deck-projects.md) | Building a multi-file deck with a bound theme, locked spec, assets, and live review |
+| [Menu lookup](./docs/menu-lookup.md) | Tracing how a page kind reaches one theme face across validation and render |
 | [Contrast system](./docs/contrast-system.md) | Debugging text color, painted backgrounds, or contrast findings |
 | [Designing themes](./docs/designing-themes.md) | Drawing a theme redesign that can actually compile to PPTX |
 | [Testing](./docs/testing.md) | Running the right gate, inspecting snapshots, or changing exported XML |

package/README.zh-CN.md

@@ -1,12 +1,13 @@
-<p align="center"><img src="assets/banner.png" alt="pptwise：PPT 不用等，马上就好" width="100%"></p>
+<p align="center"><img src="assets/banner.png" alt="pptwise：真正的 PPT，不是图片也不是 HTML" width="100%"></p>
 
 <h1 align="center">pptwise</h1>
 
-<p align="center"><b>PPT 不用等，马上就好。</b></p>
+<p align="center"><b>真正的 PPT，不是图片也不是 HTML</b></p>
 
 <p align="center">🥇 <b>全网第一个 DeepSeek Harness PPT 生成插件</b> 🥇</p>
 
 <p align="center">
+  <a href="https://pptwise.com/zh">pptwise.com</a> ·
   <a href="./README.md">English</a> ·
   <a href="./INSTALL.md">安装（转发给你的 AI）</a> ·
   <a href="./docs/cli.zh-CN.md">命令</a> ·
@@ -31,9 +32,9 @@
 
 ## 亮点
 
-**⚡ 跟 AI 说一句，PPT 就好了。** 你只管说要讲什么，版面、配色、字号、间距全由引擎排好。同一份内容做十遍是同一份，不用一遍遍重来碰运气。
+**⚡ 跟 AI 说一句，PPT 就好了。** 你给出意图，引擎把语义讲法与类型化组件做成一份主题统一的 deck。同一份绑定输入每次都会渲成同一份结果。
 
-**✏️ 交出来的是真 PPT，不是一张图。** 每个标题、每条要点、每根柱子都能在 PowerPoint 里点开改字改色。图表和表格里的数字是例外，换数字让 AI 重做一版。24 套现成风格，也能把你公司现有 PPT 里的配色和字体抽出来直接用。
+**✏️ 打开就能接着改。** 每个标题、每条要点、每根柱子都能在 PowerPoint 里点开改字改色。图表和表格里的数字是例外，换数字让 AI 重做一版。可以从 24 个出厂主题起步，拷进工作区继续改，也能从公司现有 PPT 抽取配色与字体。
 
 **🔌 装进你正在用的 agent。** 一条命令装进 DeepSeek Harness、Claude Code，或任何读 skill 文件夹的 agent（Codex 等），装完就会用。
 
@@ -45,56 +46,86 @@
 
 **第一步，交给你的 AI。** 把这行话发给它：
 
-> 按照 https://raw.githubusercontent.com/liustack/pptwise/main/INSTALL.md 安装 pptwise deck 技能，装完跑一遍健康检查，把结果告诉我。
+> 按照 https://raw.githubusercontent.com/liustack/pptwise/main/INSTALL.md 安装 pptwise，装完跑一遍健康检查，把结果告诉我。
 
-没有第二步。你的 AI 会把 skill 文件夹放到你这个 harness 读取的位置，skill 自带钉死版本的启动器，不需要你手动装 CLI。pptwise 在本地渲染 PPTX：渲染不要 API key、不用注册、无需配置。可选的图库搜索需要用户自己的 Pexels key。唯一前置是 Node 22.19+（或 Bun）。
+**在 DeepSeek Harness 上发另一句。** 那里 pptwise 是原生插件不是 skill 文件夹，所以有自己的一份指引。由你来挑发哪一句，不是让 agent 猜：agent 判断不了自己跑在哪个 harness 里。
 
-**在 DeepSeek Harness 上换成一条命令。** 那里 pptwise 是原生 DSH 插件，不走 skill 文件夹：
+> 按照 https://raw.githubusercontent.com/liustack/pptwise/main/INSTALL-dsh.md 安装 pptwise，装完跑一遍健康检查，把结果告诉我。
 
-```bash
-npx -y @deepseek-ai/dsh plugin --profile web add @liustack/pptwise@0.22.0
-```
-
-版本号要点名。不点名的话，安装会静默落到一个更旧的版本，拿不到最新能力。`npm view @liustack/pptwise version` 可查当前版本。插件卡片显示为「pptwise」，把整套生成流程的 skill 注册进 DSH 技能系统，驱动的 CLI 就在插件包自己里面。卸载即移除，不留残余。
+没有第二步。你的 AI 会把 skill 文件夹放到你这个 harness 读取的位置，skill 自带钉死版本的启动器，不需要你手动装 CLI。pptwise 在本地渲染 PPTX：渲染不要 API key、不用注册、无需配置。可选的图库搜索需要用户自己的 Pexels key。唯一前置是 Node 22.19+（或 Bun）。
 
 ## 快速开始
 
-IR 就是一份描述整份 PPT 内容的 JSON 文件。写一个最小的，跑一遍 validate → render → preview 回路：
+IR v5 是一份描述完整绑定 deck 的 JSON 文件。每张内容页都要写明语义 `kind`，主题菜单再把这个 kind 变成视觉脸。
 
-```bash
-cat > deck.json <<'EOF'
+```json
 {
+  "version": "5",
   "filename": "hello.pptx",
   "theme": { "id": "consulting" },
   "slides": [
-    { "type": "cover", "heading": "Hello pptwise", "subheading": "A first deck in ten minutes" },
-    { "type": "content", "heading": "Why it works", "components": [
-      { "type": "bullets", "items": ["Semantic IR in", "Native DrawingML out", "Every shape stays editable"] } ] },
+    {
+      "type": "cover",
+      "heading": "Hello pptwise",
+      "subheading": "A first native deck"
+    },
+    {
+      "type": "content",
+      "kind": "points",
+      "heading": "Why it works",
+      "components": [
+        {
+          "type": "bullets",
+          "items": ["Semantic IR in", "Theme-menu lookup", "Native DrawingML out"]
+        }
+      ]
+    },
     { "type": "ending", "heading": "Thanks" }
   ]
 }
-EOF
-pptwise validate deck.json                              # → OK — 3 slides, theme "consulting"
-pptwise render deck.json -o out/hello.pptx              # → wrote out/hello.pptx (3 slides, ~24 KB)
-pptwise render deck.json -o out/tech.pptx --theme tech  # 同一份 deck，换个主题
-pptwise preview deck.json -o out/svgs                   # 每页一张 SVG，供人工目检
 ```
 
-只有一条形状规则：`cover`/`chapter`/`ending` 页只有 heading + subheading，组件都放在 `content` 页上。写混了 `validate` 会原话告诉你。
+保存为 `deck.json`，然后运行：
+
+```bash
+pptwise validate deck.json
+pptwise render deck.json -o out/hello.pptx
+pptwise preview deck.json -o out/review --html
+```
+
+按 `pptwise themes --json` 的 `occasions` 与 `identity` 选择主题。绑定前可以比较两到四个候选：
+
+```bash
+pptwise theme try consulting,swiss,memo
+```
+
+可以通过拷贝预设、创建配色分叉，或抽取 Office 品牌，得到完整独立的 v2 主题：
+
+```bash
+pptwise theme new --from consulting -o themes/acme.theme.json --id acme
+pptwise theme fork acme --primary "#0B5FFF" -o themes/acme-blue.theme.json --id acme-blue
+pptwise brand extract corp.pptx -o themes/acme-brand.theme.json --id acme-brand --from consulting
+```
+
+Deck 项目在 `deck.spec.json` 中绑定唯一主题，再把页面内容放进 `pages/<id>.json`。渲染阶段没有临时主题切换。菜单相同的配色分叉可以替换绑定。菜单不同则需要回到主题选择，再修订 spec、受影响的 kind 与页面填充。
 
-不想安装也行：`npx -y @liustack/pptwise validate deck.json`。源码仓库里则用 `node dist/cli.js` 代替 `pptwise`，`examples/` 下有现成的 IR 文件可以直接试。
+不安装也能运行：`npx -y @liustack/pptwise validate deck.json`。源码仓库中用 `node dist/cli.js` 代替 `pptwise`。`examples/` 下有可直接尝试的 v5 文件。
 
-最常用的几条命令：
+最常用的命令：
 
-| 命令 | 作用 |
-|---|---|
-| `validate <target>` | 校验 IR，每条报错都带页码 |
-| `render <target> [-o <out.pptx>] [--theme <id>]` | 渲染出 `.pptx`。省略 `-o` 则写到 `.pptwise/<deck>/<deck>.pptx` |
-| `preview <target> [-o <dir>] [--html]` | 每页一张 SVG，外加一个自包含的审阅页。省略 `-o` 则写到 `.pptwise/<deck>/` |
-| `serve <target>` | 随改动自动刷新的实时预览 |
-| `audit <target>` | 几何审查：溢出、越界、低对比度、重叠 |
-| `themes` | 列出 24 套内置主题（24 个 id） |
-| `doctor` | 体检这套安装：运行时、skill 副本、可选能力、自检渲染 |
+| command | 作用 |
+| --- | --- |
+| `spec validate <spec.json>` | 验证页面顺序、kind、标题、叙事与主题菜单适配。 |
+| `assemble <dir>` | 把 deck 项目组合成派生 IR v5，不保存渲染选择。 |
+| `validate <target>` | 检查 IR、绑定、菜单、组件、资产与内容质量。 |
+| `render <target> [-o <out.pptx>]` | 渲染原生可编辑 PPTX。 |
+| `audit <target>` | 检查几何、对比度、截断、内容丢失与单调性。 |
+| `preview <target> [--html]` | 写出 SVG 页面与可选的自包含评审文件。 |
+| `serve <target>` | 启动随源文件变化自动刷新的实时评审。 |
+| `themes [--json]` | 列出带场合与个性强度元数据的出厂主题。 |
+| `theme try <id,id,...>` | 用两到四个主题对比固定样稿。 |
+| `theme new`、`theme fork` | 拷贝完整主题，或创建整套配色分叉。 |
+| `doctor` | 检查运行时、skill 副本、可选能力与自检渲染。 |
 
 完整命令表见 [`docs/cli.zh-CN.md`](./docs/cli.zh-CN.md)。
 
@@ -105,12 +136,12 @@ pptwise preview deck.json -o out/svgs                   # 每页一张 SVG，供
 | [安装手册](./INSTALL.md) | 把安装交给 agent，或检查运行前提 |
 | [Agent skill](./skills/pptwise/SKILL.zh-CN.md) | 了解 pptwise 教给 agent 的完整工作流 |
 | [CLI 手册](./docs/cli.zh-CN.md) | 查询命令、参数、审查、预览与健康检查 |
-| [IR 参考](./docs/ir.zh-CN.md) | 用 JSON 编写 deck、页面、组件与叙事 |
-| [主题](./docs/themes.zh-CN.md) | 挑选内置主题，或从自家 PPT 提取品牌 |
-| [核心概念](./docs/concepts.md) | 理解主题、版式、组件、叙事与容量模型 |
-| [架构](./docs/architecture.md) | 修改渲染链，或新增主题、版式与组件 |
-| [Deck 项目](./docs/deck-projects.md) | 用锁定 spec、页面文件、素材与实时审阅制作复杂 PPT |
-| [版式选型与 seed](./docs/selection-and-seed.md) | 排查版式为何被选中，或保持多次修订稳定 |
+| [IR 参考](./docs/ir.zh-CN.md) | 用 JSON 编写 IR v5 页面、kind、组件、资产与叙事 |
+| [主题](./docs/themes.zh-CN.md) | 拷贝、对比、分叉、绑定或编写完整 v2 主题 |
+| [核心概念](./docs/concepts.md) | 理解主题、spec、组件、讲法、菜单与容量模型 |
+| [架构](./docs/architecture.md) | 修改菜单路径、渲染链或导出边界 |
+| [Deck 项目](./docs/deck-projects.md) | 用绑定主题、锁定 spec、页面文件、素材与实时评审制作 PPT |
+| [菜单查表](./docs/menu-lookup.md) | 排查页面 kind 如何在验证与渲染中到达同一张脸 |
 | [对比度系统](./docs/contrast-system.md) | 排查文字颜色、自绘背景与低对比度问题 |
 | [测试](./docs/testing.md) | 选择验证命令、检查快照，或修改导出 XML |
 | [内部 API](./docs/internal-api.md) | 了解 JavaScript 内部模块为何不承诺 semver 稳定性 |