You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The format matrix labelled cells "chained", "local" and "copy", which said
something about DeckRender's internals and nothing a user can act on. Worse,
it read as a hierarchy: a supported route looked second class because it
happened to take two steps instead of one.
Supported is supported. The matrix now says yes / soon / not supported, in
the CLI, the README and docs/formats.md alike. `--json` still reports the
exact route for tooling that wants it.
Error and caveat text followed the same rule — messages named the backend
task or the engine that produced them ("DeckOps has no converter for it",
"the local engine"), which told users about the architecture rather than
about their document. They now describe the capability:
before: --width is not supported for .key input.
The backend task convertor.keynote2image accepts no resolution
parameters.
after: --width is not supported for .key input.
Rendering .key offers no resolution control.
The first-page limitation on Pages and Numbers stays stated plainly, since
that changes what you receive rather than how it was made.
Also corrects the README, which claimed rendering always runs in the cloud —
untrue since Pages and Numbers started rendering locally.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Image output supports `png`, `jpg` and `webp` via `--image-format`.
90
90
91
-
**local** runs on this machine with no network — Pages and Numbers have no cloud converter, so DeckRender extracts the preview embedded in the document (first page only). **🕓** is planned but not built; those report `not_implemented` with a message naming what is blocking them.
91
+
**🕓** is planned but not built; those report `not_implemented` with a message naming what is blocking them. Unsupported pairs fail with a clear message rather than producing something approximate.
92
92
93
-
"chained" means DeckRender runs more than one backend task — slower, and sometimes with a fidelity note. Every render reports the exact task chain it used in`--json`'s `route` field, so nothing is hidden. Unsupported pairs fail with a clear message rather than producing something approximate.
93
+
Pages and Numbers render their embedded first-page preview — see [`docs/formats.md`](docs/formats.md) for that and the other per-format notes.
94
94
95
95
Full detail, including which flags each route accepts: [`docs/formats.md`](docs/formats.md).
96
96
@@ -164,7 +164,7 @@ Input (file | URL | stdin)
164
164
165
165
Rendering is performed by [`@deckops/sdk`](https://www.npmjs.com/package/@deckops/sdk). DeckRender contributes the input model, the render routing, artifact naming, and a stable output contract.
166
166
167
-
Rendering always runs in the DeckFlow cloud today. A local engine (Playwright for HTML, pdfium for PDF) is planned for v0.2 — the `RenderEngine` seam is already in place, so adding it will not disturb the rest of the pipeline.
167
+
Most rendering runs in the DeckFlow cloud; a few formats are handled on your machine. Which is which is an implementation detail — `deckrender formats` reports what works, and `--json` reports how it was produced if you need to know.
Copy file name to clipboardExpand all lines: docs/cli.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -108,7 +108,7 @@ Pages are 1-based and ranges are inclusive. Requesting a page past the end of th
108
108
109
109
`--pages` filters at download time — **the backend still renders every page**, so this saves bandwidth and disk, not compute or cost. It does not apply to single-file output (pdf, video) or to HTML and Markdown, which produce one image.
110
110
111
-
On chained webp routes the filter is applied before the per-frame conversion, so unwanted frames are never converted.
111
+
For webp output the filter is applied before conversion, so narrowing the range also narrows the work.
**chained** means more than one backend task runs. It is slower, and `--json`'s `route` always shows the exact chain:
24
+
**🕓** means planned but not built. Those fail with `not_implemented` and a message naming what is blocking them, rather than pretending the combination is impossible.
25
+
26
+
How a conversion is produced — one step or several, in the cloud or on this machine — is DeckRender's problem, not yours. `--json` reports the exact route if you want it:
**copy** means the input is already in the target format, so DeckRender copies it rather than re-rendering.
31
-
32
-
**local** means it runs on this machine — no network, no credentials.
33
-
34
-
**🕓** means planned but not built. Those fail with `not_implemented` and a message naming what is blocking them, rather than pretending the combination is impossible.
35
-
36
32
An unsupported pair fails immediately with the alternatives spelled out:
37
33
38
34
```
@@ -43,7 +39,7 @@ Error: Cannot render .pdf to video.
43
39
44
40
## Which flags each route accepts
45
41
46
-
Sizing and encoding options land on whichever backend task actually produces the image. For chained routes that is the last one — which is why `docx → image` accepts `--width` while `docx → pdf` does not.
42
+
Not every option applies everywhere. What a route can honour depends on how the imageis produced, which is why `docx → image` accepts `--width` while `docx → pdf` does not.
@@ -59,49 +55,60 @@ Sizing and encoding options land on whichever backend task actually produces the
59
55
60
56
PDF and video output accept no sizing, encoding, quality or page options — the backend tasks have no such parameters.
61
57
62
-
## Notes on specific routes
63
-
64
-
### html → pdf ⚠️
65
-
66
-
HTML is rebuilt as PPTX before PDF export, so layout is constrained by the slide model. DeckRender warns on stderr and reports a `caveat` in `--json`.
67
-
68
-
For a faithful HTML→PDF today, render to image instead. A native path arrives with the local engine in v0.2.
69
-
70
-
### URLs
71
-
72
-
The page is fetched by DeckRender and given a `<base href>` so relative assets resolve. The resulting HTML is uploaded as the cloud task's source file. Scripts still execute — the backend renders in a real browser.
73
-
74
-
### webp
75
-
76
-
Each frame becomes its own conversion task, four at a time. A 40-slide deck rendered to webp creates 41 tasks. Combining with `--pages` filters first, so `--pages 1-2` on that deck creates 3 tasks rather than 41.
58
+
## Per-format notes
77
59
78
-
### Pages and Numbers ⚠️
60
+
Everything in the matrix works. These notes are about what the output _is_ — the
61
+
cases where the result differs from a plain full-fidelity render.
79
62
80
-
DeckOps has no converter for these. Every iWork document embeds a `preview.jpg` of its **first page**, so DeckRender extracts that instead of refusing the format — no network, no credentials, no dependencies.
63
+
### Pages and Numbers — first page only
81
64
82
-
It is a preview, not a render: one page, at whatever resolution iWork saved, so `--width`, `--scale`, `--quality` and `--image-format` have nothing to act on. `--format pdf` wraps that JPEG in a single-page PDF.
65
+
These render the preview iWork embeds in the document, which covers the **first
66
+
page only**, at whatever resolution iWork saved. `--width`, `--scale`,
67
+
`--quality` and `--image-format` have nothing to act on; `--format pdf` returns
68
+
that single page as a PDF.
83
69
84
-
Both shapes iWork writes are accepted — a single file, and the directory bundle Finder shows as one document:
70
+
Both shapes iWork writes are accepted — a single file, and the directory bundle
Keynote does **not** use this path — `.key` has real cloud converters and renders every slide.
78
+
Keynote is unaffected: `.key` renders every slide.
79
+
80
+
### HTML to PDF and video — laid out as slides
92
81
93
-
### Spreadsheets 🕓
82
+
HTML is reconstructed as a slide document before export, so layout follows the
83
+
slide model rather than the browser's. The video is a slideshow of that
84
+
reconstruction, not a capture of the live page. DeckRender warns on stderr and
85
+
reports a `caveat` in `--json`.
94
86
95
-
`.xlsx` has no cloud converter, and rendering a workbook locally needs a real layout pass. It reports `not_implemented` rather than failing silently. `.numbers` falls back to the embedded preview above.
87
+
For the most faithful HTML output today, render to image.
88
+
89
+
### URLs
90
+
91
+
The page is fetched and given a `<base href>` so relative assets resolve.
92
+
Scripts still execute — rendering happens in a real browser.
96
93
97
94
### Video
98
95
99
-
`.pptx`, `.ppt` and `.html` convert to video. The backend accepts no video parameters, so `--fps`, `--duration` and `--transition` fail with an explanation rather than being quietly ignored. PDF and Keynote to video are planned and need local frame assembly. See the [roadmap](roadmap.md).
96
+
`.pptx`, `.ppt` and `.html` convert to video. There are no video parameters yet,
97
+
so `--fps`, `--duration` and `--transition` fail with an explanation rather than
98
+
being quietly ignored. PDF and Keynote to video are on the
99
+
[roadmap](roadmap.md).
100
+
101
+
### webp
102
+
103
+
Each frame is converted individually, four at a time, so a long deck takes
104
+
noticeably longer in webp than in png. `--pages` is applied first, so narrowing
105
+
the range also narrows the work.
100
106
101
107
### No SVG
102
108
103
-
DeckOps has no task that emits SVG, so `--image-format svg` is not offered. Offering a value that always fails would be worse than leaving it out.
109
+
Nothing in the pipeline emits SVG, so `--image-format svg` is not offered.
110
+
Offering a value that always fails would be worse than leaving it out.
104
111
105
112
## Behind the matrix
106
113
107
-
Every cloud route maps to a task type in [`@deckops/sdk`](https://www.npmjs.com/package/@deckops/sdk); `deckrender formats --json`names the exact task chain for each one. The matrix is verified end to end by `scripts/conformance.mjs`, which renders a real document through every combination and diffs the result against this page.
114
+
`deckrender formats --json`reports how each combination is produced, if you need it. The matrix is verified end to end by `scripts/conformance.mjs`, which renders a real document through every combination and diffs the result against this page.
|`.xlsx` → image, pdf | A spreadsheet layout engine. DeckOps has no converter, and a workbook needs a real layout pass — not something to fake from an embedded preview. |
28
-
|`.pdf` → video | Local frame assembly (ffmpeg), not bundled. |
29
-
|`.key` → video | Local frame assembly (ffmpeg), not bundled. |
|`.xlsx` → image, pdf | A spreadsheet layout engine. A workbook needs a real layout pass — not something to fake from an embedded preview. |
28
+
|`.pdf` → video | Local frame assembly (ffmpeg), not bundled. |
29
+
|`.key` → video | Local frame assembly (ffmpeg), not bundled. |
30
30
31
-
`.pages` and `.numbers`reached coverage a different way: they have no cloud converter either, but every iWork document embeds a first-page `preview.jpg`, and extracting that needs only a ZIP reader. That ships today as the `local` engine, labelled as a preview rather than a render. A real renderer for them stays on this list in spirit — the preview is a floor, not the goal.
31
+
`.pages` and `.numbers`are supported today by rendering the first-page preview every iWork document embeds. That is a floor, not the goal: a full renderer for them stays on this list in spirit, and `docs/formats.md` states the first-page limitation plainly so nobody is surprised.
0 commit comments