@s8fy/xdoc 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +280 -39
- package/package.json +20 -6
package/README.md
CHANGED
|
@@ -1,49 +1,290 @@
|
|
|
1
|
-
#
|
|
1
|
+
# xdoc
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Create editable PowerPoint decks. Automate document workflows. Give your AI agent a document runtime.**
|
|
4
|
+
|
|
5
|
+
`@s8fy/xdoc` brings the native **xdoc CLI** to npm. Create and edit `.pptx`
|
|
6
|
+
files, export PDF and slide images, extract content for an AI workflow, and
|
|
7
|
+
inspect the result through structured reports. Text, shapes, tables, and
|
|
8
|
+
supported charts remain native PowerPoint objects you can keep editing.
|
|
9
|
+
|
|
10
|
+
Build a quarterly review from JSON. Refresh a report from business data.
|
|
11
|
+
Restyle an existing deck. Let an agent resolve exact objects, preview its
|
|
12
|
+
changes, and leave a record of how the presentation was produced.
|
|
13
|
+
|
|
14
|
+
## Install and try it
|
|
15
|
+
|
|
16
|
+
Requires **Node.js 22 or newer**. See [supported platforms](#supported-platforms).
|
|
4
17
|
|
|
5
18
|
```sh
|
|
6
19
|
npm install --global @s8fy/xdoc
|
|
7
20
|
xdoc --version
|
|
8
21
|
```
|
|
9
22
|
|
|
10
|
-
|
|
11
|
-
|
|
23
|
+
Start with an existing presentation and generate a review bundle in one command:
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
# Export PDF, slide PNGs, a contact sheet, and AI-ready Markdown
|
|
27
|
+
xdoc convert deck.pptx --to pdf,png,md --md-detail ai --contact-sheet --output-dir exports
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Conversion and native PPTX editing run locally without requiring an Office
|
|
31
|
+
installation. Rendering uses xdoc's own backends; available fonts affect the
|
|
32
|
+
result. Free mode has [task limits and visual watermarks](#free-mode-and-licensing).
|
|
33
|
+
|
|
34
|
+
## What you can do
|
|
35
|
+
|
|
36
|
+
| Goal | xdoc gives you |
|
|
37
|
+
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
38
|
+
| **Build an editable deck** | Declarative JSON patches, slide recipes, text, preset shapes, connectors, images, tables, supported charts, equations, and notes. |
|
|
39
|
+
| **Change an existing presentation** | Inspect its structure, select objects by id, name, or query, and apply focused changes with a non-writing dry-run first. |
|
|
40
|
+
| **Generate recurring reports** | Fill PPTX templates from JSON; bind text, table, and chart data; use macros, loops, and conditional patch operations. |
|
|
41
|
+
| **Refresh a deck's design** | Apply brand profiles, swap theme/style packs, copy slides between decks, or use native DeckKit skins. |
|
|
42
|
+
| **Prepare localization** | Scan text, plan replacements from supplied translations, and compare styles and layout after editing. |
|
|
43
|
+
| **Convert and extract** | PPTX to PDF, PNG, JSON, Markdown, or text; structured notes, links, fonts, and resource inventories; PDF text/rendering; HTML to Markdown. |
|
|
44
|
+
| **Review before delivery** | Font, link, asset, accessibility, and Office compatibility checks; static layout diagnostics; rendered previews; semantic and visual diffs. |
|
|
45
|
+
| **Connect an AI agent** | Runtime schemas, versioned JSON reports, structured errors, a local daemon, stdio JSON-RPC, and MCP over stdio. |
|
|
46
|
+
|
|
47
|
+
## Create your first deck from JSON
|
|
48
|
+
|
|
49
|
+
Save this as `review.patch.json`. It creates a title slide and a KPI slide
|
|
50
|
+
using built-in recipes:
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{
|
|
54
|
+
"schemaVersion": "pptx-patch/v1",
|
|
55
|
+
"ops": [
|
|
56
|
+
{
|
|
57
|
+
"op": "add-slide",
|
|
58
|
+
"recipe": {
|
|
59
|
+
"kind": "title",
|
|
60
|
+
"title": "Quarterly momentum",
|
|
61
|
+
"subtitle": "A business review built with xdoc"
|
|
62
|
+
}
|
|
63
|
+
},
|
|
64
|
+
{
|
|
65
|
+
"op": "add-slide",
|
|
66
|
+
"recipe": {
|
|
67
|
+
"kind": "kpi-grid",
|
|
68
|
+
"title": "Growth at a glance",
|
|
69
|
+
"items": [
|
|
70
|
+
{ "label": "Revenue", "value": "$2.4M", "delta": "+18%" },
|
|
71
|
+
{ "label": "Customers", "value": "1,280", "delta": "+22%" },
|
|
72
|
+
{ "label": "Retention", "value": "98%", "delta": "+2 pts" }
|
|
73
|
+
]
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
]
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Validate the plan, create the deck, and render a preview:
|
|
81
|
+
|
|
82
|
+
```sh
|
|
83
|
+
# Resolve and simulate the patch without writing the presentation
|
|
84
|
+
xdoc pptx apply --patch review.patch.json --output review.pptx --dry-run --json
|
|
85
|
+
|
|
86
|
+
# Create review.pptx and its review.pptx.xdoc.json sidecar
|
|
87
|
+
xdoc pptx apply --patch review.patch.json --output review.pptx --json
|
|
88
|
+
|
|
89
|
+
# Render PNGs and a contact sheet
|
|
90
|
+
xdoc pptx preview review.pptx --output-dir review-previews --contact-sheet --json
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Open `review.pptx` in PowerPoint and edit the generated text and shapes.
|
|
94
|
+
Change the KPI values in JSON to generate another review, or explore recipes
|
|
95
|
+
such as `timeline`, `roadmap`, `process-flow`, `comparison-table`, and `gantt`.
|
|
96
|
+
Compose individual operations to add charts, tables, diagrams, and supported
|
|
97
|
+
animations or transitions. Patch `slide`
|
|
98
|
+
indexes start at **0**, while CLI `--slides` selections start at **1**.
|
|
99
|
+
|
|
100
|
+
Existing output paths are protected by default. Add `--overwrite` when you
|
|
101
|
+
intend to replace a previous output.
|
|
102
|
+
|
|
103
|
+
## Turn everyday deck work into commands
|
|
104
|
+
|
|
105
|
+
### Inspect, target, and edit
|
|
106
|
+
|
|
107
|
+
Find the actual PowerPoint objects before constructing an edit patch:
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
xdoc pptx inspect deck.pptx --json
|
|
111
|
+
xdoc pptx select deck.pptx --query '{"textRegex":"Revenue"}' --json
|
|
112
|
+
|
|
113
|
+
# edit.patch.json contains your schema-valid changes to the selected objects
|
|
114
|
+
xdoc pptx apply --patch edit.patch.json --input deck.pptx --output updated.pptx --dry-run --json
|
|
115
|
+
xdoc pptx apply --patch edit.patch.json --input deck.pptx --output updated.pptx --json
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Inspect supplies object identity, text, geometry, layouts, and styles. Selectors
|
|
119
|
+
resolve targets deterministically; ambiguous matches produce an error with
|
|
120
|
+
candidates. Patch operations are adopted only after the full operation set
|
|
121
|
+
succeeds. The commands above write a separate candidate for review.
|
|
122
|
+
|
|
123
|
+
### Fill a template or try a new look
|
|
124
|
+
|
|
125
|
+
Use your own `template.pptx`, business data in `data.json`, and schema-defined
|
|
126
|
+
text/table/chart mappings in `bindings.json`:
|
|
127
|
+
|
|
128
|
+
```sh
|
|
129
|
+
xdoc pptx template-fill data.json --template template.pptx --bindings bindings.json --output report.pptx
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Discover built-in theme packs, then try one on a deck:
|
|
133
|
+
|
|
134
|
+
```sh
|
|
135
|
+
xdoc pptx catalog themes --json
|
|
136
|
+
xdoc pptx swap-theme deck.pptx --theme corporate-blue --output themed.pptx
|
|
137
|
+
xdoc pptx swap-style deck.pptx --style consulting --output styled.pptx
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Extract source material and convert batches
|
|
141
|
+
|
|
142
|
+
```sh
|
|
143
|
+
# Extract the outline, resource inventory, notes, links, and fonts
|
|
144
|
+
xdoc extract deck.pptx --parts map,resources,notes,links,fonts --pretty --output artifacts.json
|
|
145
|
+
|
|
146
|
+
# Read text from a PDF and normalize a local HTML page to Markdown
|
|
147
|
+
xdoc pdf extract-text source.pdf --json --pretty
|
|
148
|
+
xdoc html2md page.html --output page.md
|
|
149
|
+
|
|
150
|
+
# Convert a directory and retain a structured batch summary
|
|
151
|
+
xdoc convert ./decks --recursive --to pdf --output-dir ./converted --report batch.json
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
PDF text and HTML Markdown can feed a brief or an agent's content pipeline.
|
|
155
|
+
Creating the presentation then uses recipes, patches, or a PPTX template.
|
|
156
|
+
|
|
157
|
+
### Check the result and retain the evidence
|
|
158
|
+
|
|
159
|
+
```sh
|
|
160
|
+
# Include accessibility alongside the standard preflight checks
|
|
161
|
+
xdoc check updated.pptx --checks all --output preflight.json
|
|
162
|
+
|
|
163
|
+
# Check static layout risks and compare the source with the candidate
|
|
164
|
+
xdoc pptx vision-check updated.pptx --json
|
|
165
|
+
xdoc pptx diff deck.pptx updated.pptx --json
|
|
166
|
+
|
|
167
|
+
# Review the actual rendered slides
|
|
168
|
+
xdoc pptx preview updated.pptx --output-dir updated-previews --contact-sheet --json
|
|
169
|
+
|
|
170
|
+
# Inspect the revision record or replay its patch
|
|
171
|
+
xdoc pptx audit --from-sidecar updated.pptx.xdoc.json --json
|
|
172
|
+
xdoc pptx replay --from-sidecar updated.pptx.xdoc.json --output replayed.pptx
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
The default `.xdoc.json` sidecar records the materialized patch, runtime
|
|
176
|
+
identity, and apply report. Keep the source deck too: replay of an existing-deck
|
|
177
|
+
edit requires the recorded input to remain available. Sidecars contain revision
|
|
178
|
+
evidence; fresh checks and previews validate the current presentation.
|
|
179
|
+
|
|
180
|
+
## Built for AI agents
|
|
181
|
+
|
|
182
|
+
xdoc exposes its own operations, field contracts, examples, catalogs, feature
|
|
183
|
+
support, and report formats. An agent can discover the installed runtime,
|
|
184
|
+
inspect a deck, construct a patch, dry-run it, apply it, and verify the result
|
|
185
|
+
using machine-readable data at each step. Your agent supplies the content,
|
|
186
|
+
translations, and design decisions; xdoc executes the document work.
|
|
187
|
+
|
|
188
|
+
```sh
|
|
189
|
+
# Discover patch operations, then ask for the exact fields you need
|
|
190
|
+
xdoc schema --mode index
|
|
191
|
+
xdoc schema --mode ops --ops add-chart,set-chart-data --minimal
|
|
192
|
+
|
|
193
|
+
# Explore built-in examples and the complete runtime contract
|
|
194
|
+
xdoc schema --mode examples
|
|
195
|
+
xdoc schema > runtime-schema.json
|
|
196
|
+
|
|
197
|
+
# Browse native PowerPoint shapes
|
|
198
|
+
xdoc pptx catalog shapes --json
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
The **0.6.0** runtime exposes **58 patch operations, 18 slide recipe kinds,
|
|
202
|
+
182 preset shapes, 9 theme packs, and 4 style packs**. Chart types and advanced
|
|
203
|
+
features carry individual support statuses. Use the installed schema to choose
|
|
204
|
+
supported operations and read the scope of partial or preserve-only features.
|
|
205
|
+
|
|
206
|
+
Choose the process interface that fits your host:
|
|
207
|
+
|
|
208
|
+
| Interface | Entry point | Use it for |
|
|
209
|
+
| -------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
210
|
+
| CLI | `xdoc pptx ... --json` | Local scripts and individual operations. |
|
|
211
|
+
| Local daemon | `xdoc daemon start`, then `inspect`/`apply` with `--daemon` | Keeping parsed deck sessions in memory across local steps. |
|
|
212
|
+
| Stdio JSON-RPC | `xdoc json-rpc` | A host managing a persistent child process through JSON-RPC 2.0. |
|
|
213
|
+
| MCP over stdio | `xdoc mcp` | An MCP client discovering schemas, inspecting decks, and applying patches. |
|
|
214
|
+
|
|
215
|
+
For an MCP client that accepts `mcpServers` configuration:
|
|
216
|
+
|
|
217
|
+
```json
|
|
218
|
+
{
|
|
219
|
+
"mcpServers": {
|
|
220
|
+
"xdoc": {
|
|
221
|
+
"command": "xdoc",
|
|
222
|
+
"args": ["mcp"]
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
The MCP adapter exposes `xdoc_schema`, `pptx_inspect`, and `pptx_apply`.
|
|
229
|
+
Conversion, previews, and other checks use the CLI. For repeatable integrations,
|
|
230
|
+
pin the npm version and capture that executable's schema. This package exposes
|
|
231
|
+
the `xdoc` command; process arguments, stdio protocols, and JSON reports form
|
|
232
|
+
the public integration boundary.
|
|
12
233
|
|
|
13
234
|
## Supported platforms
|
|
14
235
|
|
|
15
|
-
| Operating system | Architecture
|
|
16
|
-
| ----------------- |
|
|
17
|
-
| Linux | arm64
|
|
18
|
-
| Linux | x64
|
|
19
|
-
| macOS
|
|
20
|
-
| Windows | x64
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
236
|
+
| Operating system | Architecture | Binary package |
|
|
237
|
+
| ----------------- | --------------------- | ------------------------ |
|
|
238
|
+
| Linux | arm64 | `@s8fy/xdoc-linux-arm64` |
|
|
239
|
+
| Linux | x64 | `@s8fy/xdoc-linux-x64` |
|
|
240
|
+
| macOS 13 or newer | arm64 (Apple Silicon) | `@s8fy/xdoc-macos-arm64` |
|
|
241
|
+
| Windows | x64 | `@s8fy/xdoc-windows-x64` |
|
|
242
|
+
|
|
243
|
+
npm selects an exact-version platform package containing the native executable
|
|
244
|
+
and bundled PDFium backend. Install scripts do not download binaries from an
|
|
245
|
+
external release server. Unsupported operating systems, architectures, or
|
|
246
|
+
macOS versions receive an actionable error.
|
|
247
|
+
|
|
248
|
+
## Scope and compatibility
|
|
249
|
+
|
|
250
|
+
- **Current inputs:** PPTX, PDF, and HTML, plus JSON patches, recipes, and data
|
|
251
|
+
bindings for PPTX authoring. DOCX and XLSX conversion remain reserved.
|
|
252
|
+
- **Editing and preservation:** ordinary PowerPoint objects have native edit
|
|
253
|
+
paths. Complex animation, SmartArt, and other advanced features have their
|
|
254
|
+
own supported, partial, preserve-only, or unsupported status.
|
|
255
|
+
- **Rendering and review:** font availability and the selected feature affect
|
|
256
|
+
output. Static checks, rendered previews, and target-Office compatibility
|
|
257
|
+
reports answer different questions; review the rendered result for delivery.
|
|
258
|
+
|
|
259
|
+
## Free mode and licensing
|
|
260
|
+
|
|
261
|
+
Free mode provides all core features for **single-user local use**, with up to
|
|
262
|
+
**10 slides per task** and **5 MiB of compressed PPTX inputs combined**.
|
|
263
|
+
Visual outputs carry an `XDOC DEMO` watermark. No account or license credential
|
|
264
|
+
is required to start; tasks exceeding the Free limits are denied.
|
|
265
|
+
|
|
266
|
+
Personal and Enterprise licenses are offline entitlements that remove the
|
|
267
|
+
plan-level slide/PPTX byte limits and new plan watermarks. Local scripts and a
|
|
268
|
+
per-user daemon are included in the launch plans; CI, shared servers, and
|
|
269
|
+
Service/API use are outside those plans.
|
|
270
|
+
|
|
271
|
+
The public packages use the
|
|
272
|
+
[PolyForm Noncommercial License 1.0.0](https://github.com/hustcer/workers/blob/main/xdoc-npm/LICENSE)
|
|
273
|
+
unless separately licensed. Runtime access and legal usage rights are separate;
|
|
274
|
+
commercial use requires the applicable separate terms. Platform packages also
|
|
275
|
+
retain the bundled PDFium third-party license notices.
|
|
276
|
+
|
|
277
|
+
## Support and package maintenance
|
|
278
|
+
|
|
279
|
+
Report installation, platform selection, and launcher issues in the
|
|
280
|
+
[`hustcer/workers` issue tracker](https://github.com/hustcer/workers/issues).
|
|
281
|
+
For native runtime behavior, use the upstream support channel supplied with
|
|
282
|
+
your xdoc distribution or license.
|
|
283
|
+
|
|
284
|
+
This directory maintains npm packaging and release automation. Native release
|
|
285
|
+
assets are pinned to reviewed SHA-256 digests in
|
|
286
|
+
[`release-lock.json`](https://github.com/hustcer/workers/blob/main/xdoc-npm/release-lock.json).
|
|
287
|
+
See the
|
|
288
|
+
[maintainer guide](https://github.com/hustcer/workers/blob/main/xdoc-npm/CONTRIBUTING.md)
|
|
289
|
+
for packaging and release checks. To keep exploring the CLI, start with
|
|
290
|
+
`xdoc schema --mode examples` or `xdoc pptx <action> --help`.
|
package/package.json
CHANGED
|
@@ -1,12 +1,26 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@s8fy/xdoc",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "The xdoc CLI packaged for installation through npm.",
|
|
5
5
|
"keywords": [
|
|
6
|
+
"ai-agent",
|
|
6
7
|
"cli",
|
|
7
8
|
"document",
|
|
9
|
+
"document-automation",
|
|
10
|
+
"document-converter",
|
|
11
|
+
"html-to-markdown",
|
|
12
|
+
"json-rpc",
|
|
13
|
+
"markdown",
|
|
14
|
+
"mcp",
|
|
8
15
|
"pdf",
|
|
16
|
+
"png",
|
|
17
|
+
"powerpoint",
|
|
9
18
|
"pptx",
|
|
19
|
+
"pptx-editor",
|
|
20
|
+
"pptx-generator",
|
|
21
|
+
"pptx-to-pdf",
|
|
22
|
+
"presentation",
|
|
23
|
+
"slides",
|
|
10
24
|
"xdoc"
|
|
11
25
|
],
|
|
12
26
|
"homepage": "https://github.com/hustcer/workers/tree/main/xdoc-npm#readme",
|
|
@@ -37,17 +51,17 @@
|
|
|
37
51
|
"test": "node --test tests/*.test.cjs"
|
|
38
52
|
},
|
|
39
53
|
"optionalDependencies": {
|
|
40
|
-
"@s8fy/xdoc-linux-arm64": "0.
|
|
41
|
-
"@s8fy/xdoc-linux-x64": "0.
|
|
42
|
-
"@s8fy/xdoc-macos-arm64": "0.
|
|
43
|
-
"@s8fy/xdoc-windows-x64": "0.
|
|
54
|
+
"@s8fy/xdoc-linux-arm64": "0.7.0",
|
|
55
|
+
"@s8fy/xdoc-linux-x64": "0.7.0",
|
|
56
|
+
"@s8fy/xdoc-macos-arm64": "0.7.0",
|
|
57
|
+
"@s8fy/xdoc-windows-x64": "0.7.0"
|
|
44
58
|
},
|
|
45
59
|
"engines": {
|
|
46
60
|
"node": ">=22.0.0"
|
|
47
61
|
},
|
|
48
62
|
"preferUnplugged": true,
|
|
49
63
|
"xdoc": {
|
|
50
|
-
"releaseTag": "v0.
|
|
64
|
+
"releaseTag": "v0.7.0",
|
|
51
65
|
"sourceRepository": "hustcer/pptx"
|
|
52
66
|
}
|
|
53
67
|
}
|