@liustack/pptfast 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leon Liu
+
+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/README.md

@@ -0,0 +1,95 @@
+# pptfast
+
+Stable, editable PPTX generation for AI agents — semantic IR in, native
+DrawingML out.
+
+[English] | [简体中文](./README.zh-CN.md)
+
+## Why
+
+Freeform SVG/HTML-to-PPTX pipelines have a high ceiling but an unstable floor — a weak model (or a strong one having an off turn) produces a deck that's broken, off-brand, or unreadable. pptfast trades freeform drawing for a controlled vocabulary: a semantic IR (zod schema), 13 built-in themes driven by design tokens, an archetype/block layout library with seeded variety, and native DrawingML output where every shape stays editable — not a picture pasted onto a slide.
+
+A deck is really five things: a content model, a 2D layout, a visual style, motion, and a narrative. pptfast owns the last four — you (or your agent) own the content model by writing the IR.
+
+## Install
+
+```bash
+npm install -g @liustack/pptfast
+pptfast --help
+```
+
+Node >= 18. Or build from source: `git clone https://github.com/liustack/pptfast.git && cd pptfast && pnpm install && pnpm build`.
+
+## Quick start
+
+```bash
+node dist/cli.js validate examples/basic.json
+# → OK — 5 slides, theme "consulting"
+node dist/cli.js render examples/basic.json -o out/basic.pptx
+# → wrote out/basic.pptx (5 slides, ~29 KB)
+node dist/cli.js render examples/basic.json -o out/basic-tech.pptx --theme tech
+node dist/cli.js preview examples/basic.json -o out/svgs   # SVG per slide, for a visual self-check
+```
+
+Or drive the SDK directly (Node requires `installNodePlatform()` once, before
+any render call — the CLI does this for you):
+
+```ts
+import { installNodePlatform } from "@liustack/pptfast/node"
+import { generatePptx } from "@liustack/pptfast"
+
+installNodePlatform()
+const bytes = await generatePptx(ir) // Uint8Array, ready to write to a .pptx
+```
+
+## CLI
+
+| Command | Does |
+|---|---|
+| `render <ir.json> -o <out.pptx> [--theme <id>]` | Validate + render to a `.pptx` |
+| `validate <ir.json>` | Check the IR, print page-scoped errors |
+| `schema` | Print the IR JSON Schema |
+| `themes [--json]` | List the 13 built-in themes |
+| `preview <ir.json> -o <dir>` | Render each slide to a standalone SVG |
+
+## The IR
+
+Run `node dist/cli.js schema` for the full JSON Schema — feed it to a model before asking it to write IR. A deck (`PptxIR`) is a required `filename`, `version`, `theme`, `meta`, `assets`, an optional `brand`, and an ordered list of `slides`; each slide has a `type` (`cover`, `chapter`, `content`, `ending`) and, for content slides, a list of typed `blocks` (`bullets`, `kpi_cards`, `image`, `chart`, …). `assets` is `{ images: { [id]: { src, alt? } } }` — blocks reference images by `asset_id`, so the same image can be reused across slides without duplication.
+
+## Themes
+
+Each theme is a token set (color, type, motif) plus a manifest of which archetypes it allows — themes never touch layout code.
+
+| id | label |
+|---|---|
+| `consulting` | Business Consulting |
+| `enterprise` | Enterprise |
+| `academic` | Academic |
+| `insight` | Financial Insight |
+| `campaign` | Marketing Campaign |
+| `bloom` | Soft Bloom |
+| `classroom` | Classroom |
+| `ink` | Ink Wash |
+| `tech` | Tech |
+| `runway` | Fashion Runway |
+| `journal` | Editorial Journal |
+| `luxe` | Luxe |
+| `heritage` | Heritage |
+
+## For AI agents
+
+The recommended loop for an agent generating a deck: read `pptfast schema` to learn the vocabulary, write an IR JSON, run `pptfast validate` and fix whatever it reports (errors carry a page number and a fixable-in-place message — the point is to close this loop without a human), then `pptfast render`. `pptfast preview` gives the agent SVG files it can look at to self-check layout before committing to a render. A Claude Code plugin that wraps this loop as a skill is planned for v0.2 (see Roadmap).
+
+## Roadmap
+
+- **v0.2** — Claude Code plugin + skills wrapping the render loop, design token overrides (`--tokens`), `init`/self-update commands.
+- **v0.3** — theme-customization skill (brand colors → tokens), custom manifest slots, 1.0.
+- **v0.4** — richer motion (more entrance animations), Office real-device testing, web playground.
+
+## Credits
+
+Icon primitives are extracted from [lucide](https://lucide.dev) (ISC License). pptfast itself was extracted from a production AI-deck-generation system and CJK-typography-tuned (full-width punctuation width, Chinese line breaking, a Chinese-first font stack) from day one.
+
+## License
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,93 @@
+# pptfast
+
+面向 AI agent 的稳定、可编辑 PPTX 生成工具：输入语义化 IR，输出原生 DrawingML。
+
+[English](./README.md) | [简体中文]
+
+## 为什么
+
+自由绘制 SVG/HTML 再转 PPTX 的链路上限很高，但下限不稳定——弱模型（或强模型状态不好时）画出来的往往是版式错乱、脱离品牌规范、甚至无法阅读的产物。pptfast 用受控词汇取代自由绘制：一份语义化 IR（zod schema）、由 design tokens 驱动的 13 个内置主题、带 seed 多样性的 archetype/block 版式库，以及每个图形都保持可编辑的原生 DrawingML 输出——不是贴上去的一张图。
+
+一份 PPT 本质上是五件事：内容模型、二维布局、视觉样式、动效、叙事。pptfast 负责后四项，内容模型交给你（或你的 agent）通过写 IR 来掌控。
+
+## 安装
+
+```bash
+npm install -g @liustack/pptfast
+pptfast --help
+```
+
+需要 Node >= 18。也可从源码构建：`git clone https://github.com/liustack/pptfast.git && cd pptfast && pnpm install && pnpm build`。
+
+## 快速开始
+
+```bash
+node dist/cli.js validate examples/basic.json
+# → OK — 5 slides, theme "consulting"
+node dist/cli.js render examples/basic.json -o out/basic.pptx
+# → wrote out/basic.pptx (5 slides, ~29 KB)
+node dist/cli.js render examples/basic.json -o out/basic-tech.pptx --theme tech
+node dist/cli.js preview examples/basic.json -o out/svgs   # 每页一张 SVG，供人工目检
+```
+
+也可以直接调用 SDK（Node 环境下渲染前需先调用一次 `installNodePlatform()`，CLI 内部已经帮你调过）：
+
+```ts
+import { installNodePlatform } from "@liustack/pptfast/node"
+import { generatePptx } from "@liustack/pptfast"
+
+installNodePlatform()
+const bytes = await generatePptx(ir) // Uint8Array，可直接写成 .pptx 文件
+```
+
+## CLI
+
+| 命令 | 作用 |
+|---|---|
+| `render <ir.json> -o <out.pptx> [--theme <id>]` | 校验并渲染成 `.pptx` |
+| `validate <ir.json>` | 校验 IR，输出带页码的错误信息 |
+| `schema` | 输出 IR 的 JSON Schema |
+| `themes [--json]` | 列出 13 个内置主题 |
+| `preview <ir.json> -o <dir>` | 逐页渲染为独立 SVG |
+
+## IR
+
+运行 `node dist/cli.js schema` 获取完整 JSON Schema——让模型写 IR 之前先读它。一份 deck（`PptxIR`）由必填的 `filename`、`version`、`theme`、`meta`、`assets`、可选的 `brand`，和一个有序的 `slides` 列表组成。每张 slide 有一个 `type`（`cover`、`chapter`、`content`、`ending`），content 类型的 slide 还带一组带类型的 `blocks`（`bullets`、`kpi_cards`、`image`、`chart` 等）。`assets` 的形状是 `{ images: { [id]: { src, alt? } } }`，block 通过 `asset_id` 引用图片，同一张图可以在多页复用而不必重复内嵌。
+
+## 主题
+
+每个主题是一组 token（配色、字体、motif）加一份 manifest（声明允许使用哪些 archetype）——主题本身从不涉及布局代码。
+
+| id | label |
+|---|---|
+| `consulting` | Business Consulting |
+| `enterprise` | Enterprise |
+| `academic` | Academic |
+| `insight` | Financial Insight |
+| `campaign` | Marketing Campaign |
+| `bloom` | Soft Bloom |
+| `classroom` | Classroom |
+| `ink` | Ink Wash |
+| `tech` | Tech |
+| `runway` | Fashion Runway |
+| `journal` | Editorial Journal |
+| `luxe` | Luxe |
+| `heritage` | Heritage |
+
+## 面向 AI agent
+
+推荐给 agent 的生成回路：先读 `pptfast schema` 学词汇表，写出 IR JSON，跑 `pptfast validate` 并根据报错自纠（错误信息带页码和可直接照抄的修正方式，目的就是让这个回路不必依赖人工介入），再执行 `pptfast render`。`pptfast preview` 能让 agent 在正式渲染前先看一遍 SVG，自查版式是否合理。把这套回路封装成 skill 的 Claude Code plugin 计划在 v0.2 落地（见 Roadmap）。
+
+## 路线图
+
+- **v0.2**——封装该回路的 Claude Code plugin + skills、design token 覆盖（`--tokens`）、`init`/自更新命令。
+- **v0.3**——主题定制 skill（品牌色 → tokens）、自定义 manifest 插槽、1.0 版本。
+- **v0.4**——更丰富的动效（更多入场动画）、Office 真机实测、web playground。
+
+## 致谢
+
+图标原语抽取自 [lucide](https://lucide.dev)（ISC License）。pptfast 本身从一套生产环境的 AI 出 PPT 系统中抽取而来，从第一天起就针对 CJK 排版做了优化（全角标点宽度、中文换行、雅黑优先字体栈）。
+
+## License
+
+[MIT](./LICENSE)

package/dist/chunk-4WISUDXE.js

@@ -0,0 +1,34 @@
+import {
+  installPlatform
+} from "./chunk-G76EVNVT.js";
+
+// src/platform/node.ts
+import { DOMParser as LinkedomDOMParser } from "linkedom";
+async function recodeWithSharp(dataUrl) {
+  let sharpMod;
+  try {
+    sharpMod = (await import("sharp")).default;
+  } catch (e) {
+    const err = e;
+    if (err?.code === "ERR_MODULE_NOT_FOUND" || /Cannot find/.test(err?.message ?? "")) {
+      throw new Error(
+        'Re-encoding non-PNG/JPEG/GIF images requires the optional dependency "sharp" (npm i sharp), or convert the image beforehand'
+      );
+    }
+    throw e;
+  }
+  const base64 = dataUrl.slice(dataUrl.indexOf(",") + 1);
+  const png = await sharpMod(Buffer.from(base64, "base64")).png().toBuffer();
+  return `data:image/png;base64,${png.toString("base64")}`;
+}
+function installNodePlatform() {
+  installPlatform({
+    domParser: LinkedomDOMParser,
+    recodeImageToPng: recodeWithSharp
+  });
+}
+
+export {
+  installNodePlatform
+};
+//# sourceMappingURL=chunk-4WISUDXE.js.map

package/dist/chunk-4WISUDXE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/platform/node.ts"],"sourcesContent":["import { DOMParser as LinkedomDOMParser } from \"linkedom\"\nimport { installPlatform } from \"./registry\"\n\nasync function recodeWithSharp(dataUrl: string): Promise<string> {\n  let sharpMod: typeof import(\"sharp\")\n  try {\n    sharpMod = (await import(\"sharp\")).default as unknown as typeof import(\"sharp\")\n  } catch (e) {\n    const err = e as NodeJS.ErrnoException\n    if (err?.code === \"ERR_MODULE_NOT_FOUND\" || /Cannot find/.test(err?.message ?? \"\")) {\n      throw new Error(\n        'Re-encoding non-PNG/JPEG/GIF images requires the optional dependency \"sharp\" (npm i sharp), or convert the image beforehand'\n      )\n    }\n    throw e\n  }\n  const base64 = dataUrl.slice(dataUrl.indexOf(\",\") + 1)\n  const png = await sharpMod(Buffer.from(base64, \"base64\")).png().toBuffer()\n  return `data:image/png;base64,${png.toString(\"base64\")}`\n}\n\n/** Wire Node implementations (linkedom DOM, sharp image re-encode) into the SDK. */\nexport function installNodePlatform(): void {\n  installPlatform({\n    domParser: LinkedomDOMParser as unknown as typeof DOMParser,\n    recodeImageToPng: recodeWithSharp,\n  })\n}\n"],"mappings":";;;;;AAAA,SAAS,aAAa,yBAAyB;AAG/C,eAAe,gBAAgB,SAAkC;AAC/D,MAAI;AACJ,MAAI;AACF,gBAAY,MAAM,OAAO,OAAO,GAAG;AAAA,EACrC,SAAS,GAAG;AACV,UAAM,MAAM;AACZ,QAAI,KAAK,SAAS,0BAA0B,cAAc,KAAK,KAAK,WAAW,EAAE,GAAG;AAClF,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,UAAM;AAAA,EACR;AACA,QAAM,SAAS,QAAQ,MAAM,QAAQ,QAAQ,GAAG,IAAI,CAAC;AACrD,QAAM,MAAM,MAAM,SAAS,OAAO,KAAK,QAAQ,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS;AACzE,SAAO,yBAAyB,IAAI,SAAS,QAAQ,CAAC;AACxD;AAGO,SAAS,sBAA4B;AAC1C,kBAAgB;AAAA,IACd,WAAW;AAAA,IACX,kBAAkB;AAAA,EACpB,CAAC;AACH;","names":[]}