fix: harden rendering contracts and format support

Author: iguangfei

CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.1.1] - 2026-08-13
+
+### Fixed
+
+- Publish declarations with an explicit Node type reference so strict TypeScript 7 consumers can
+  resolve the public `Buffer` APIs without changing their compiler options.
+- Validate SDK render options, plan inputs and custom engine output at runtime, returning
+  `DeckRenderError` instead of forwarding invalid values or exposing Node argument errors.
+- Isolate DeckRender, DeckFlow and DeckOps configuration plus credential environment variables in
+  CLI end-to-end tests.
+- Correct the legacy Office support matrix: `.doc` is unsupported, while `.ppt` supports image and
+  video output; `.ppt` to PDF remains planned pending a `.pptx` normalization step.
+
 ## [0.1.0] - 2026-08-07
 
 First release.
@@ -14,10 +29,12 @@ First release.
 
   | Input               | → image | → pdf | → video |
   | ------------------- | ------- | ----- | ------- |
-  | `.pptx` `.ppt`      | ✅      | ✅    | ✅      |
+  | `.pptx`             | ✅      | ✅    | ✅      |
+  | `.ppt`              | ✅      | 🕓    | ✅      |
   | `.pdf`              | ✅      | ✅    | 🕓      |
   | `.key`              | ✅      | ✅    | 🕓      |
-  | `.docx` `.doc`      | ✅      | ✅    | —       |
+  | `.docx`             | ✅      | ✅    | —       |
+  | `.doc`              | —       | —     | —       |
   | `.xlsx`             | 🕓      | 🕓    | —       |
   | `.pages` `.numbers` | ✅      | ✅    | —       |
   | `.html` and URLs    | ✅      | ✅    | ✅      |
@@ -62,4 +79,6 @@ output and diffs the result against the documented matrix. Several conversions
 that looked plausible from the type definitions turned out not to work, so the
 matrix reflects measurement rather than inference.
 
+[Unreleased]: https://github.com/deckflow/deckrender/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/deckflow/deckrender/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/deckflow/deckrender/releases/tag/v0.1.0

README.md

@@ -76,10 +76,12 @@ deckrender formats
 
 | Input          | → image | → pdf | → video |
 | -------------- | ------- | ----- | ------- |
-| `.pptx` `.ppt` | ✅      | ✅    | ✅      |
+| `.pptx`        | ✅      | ✅    | ✅      |
+| `.ppt`         | ✅      | 🕓    | ✅      |
 | `.pdf`         | ✅      | ✅    | 🕓      |
 | `.key`         | ✅      | ✅    | 🕓      |
-| `.docx` `.doc` | ✅      | ✅    | —       |
+| `.docx`        | ✅      | ✅    | —       |
+| `.doc`         | —       | —     | —       |
 | `.xlsx`        | 🕓      | 🕓    | —       |
 | `.pages`       | ✅      | ✅    | —       |
 | `.numbers`     | ✅      | ✅    | —       |
@@ -92,6 +94,9 @@ Image output supports `png`, `jpg` and `webp` via `--image-format`.
 
 Pages and Numbers render their embedded first-page preview — see [`docs/formats.md`](docs/formats.md) for that and the other per-format notes.
 
+Legacy Word `.doc` files are not supported. Save them as `.docx` or export them to PDF first.
+Legacy PowerPoint `.ppt` files support image and video output; PDF conversion is still planned.
+
 Full detail, including which flags each route accepts: [`docs/formats.md`](docs/formats.md).
 
 ## Authentication is optional

docs/cli.md

@@ -78,7 +78,9 @@ Frame numbers are zero-padded to at least three digits, widening for documents p
 
 ## Sizing
 
-`--width` sets the long edge directly. `--scale` multiplies the route's own base — 1920 for slides, 1080 for PDF.
+`--width` sets the long edge directly and accepts integer values from 1 to 32768. `--scale`
+multiplies the route's own base — 1920 for slides, 1080 for PDF — and accepts values greater
+than 0 up to 16. `--timeout` accepts whole seconds from 1 to 86400.
 
 `convertor.ppt2image` only accepts 1080, 1920 or 2560, so other values snap to the nearest tier and the chosen value is reported on stderr:
 
@@ -104,7 +106,8 @@ deckrender report.pdf --pages 1,3,5-7
 deckrender deck.pptx --page 3
 ```
 
-Pages are 1-based and ranges are inclusive. Requesting a page past the end of the document is an error.
+Pages are 1-based, capped at 100000, and ranges are inclusive. Requesting a page past the end of
+the document is an error.
 
 `--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.
 

docs/configuration.md

@@ -90,13 +90,15 @@ deckrender config set width 2560
 deckrender config unset width
 ```
 
-| Key                       | Values                                      |
-| ------------------------- | ------------------------------------------- |
-| `profile`                 | `web`, `presentation`, `print`, `thumbnail` |
-| `format`                  | `image`, `pdf`, `video`                     |
-| `image-format`            | `png`, `jpg`, `webp`                        |
-| `quality`                 | `low`, `medium`, `high`                     |
-| `width` `scale` `timeout` | numbers                                     |
+| Key            | Values                                      |
+| -------------- | ------------------------------------------- |
+| `profile`      | `web`, `presentation`, `print`, `thumbnail` |
+| `format`       | `image`, `pdf`, `video`                     |
+| `image-format` | `png`, `jpg`, `webp`                        |
+| `quality`      | `low`, `medium`, `high`                     |
+| `width`        | integer from `1` to `32768`                 |
+| `scale`        | number greater than `0`, up to `16`         |
+| `timeout`      | integer seconds from `1` to `86400`         |
 
 Precedence, lowest first:
 
@@ -120,6 +122,7 @@ Redirect config to a scratch directory when you need isolation:
 ```bash
 export DECKFLOW_CONFIG_DIR=/tmp/deckflow
 export DECKRENDER_CONFIG_DIR=/tmp/deckrender
+export DECKOPS_CONFIG_DIR=/tmp/deckops
 ```
 
 ## File permissions

docs/formats.md

@@ -9,10 +9,12 @@ deckrender formats --json   # machine-readable, includes the backend task chain
 
 | Input                   | → image | → pdf | → video |
 | ----------------------- | ------- | ----- | ------- |
-| `.pptx` `.ppt`          | ✅      | ✅    | ✅      |
+| `.pptx`                 | ✅      | ✅    | ✅      |
+| `.ppt`                  | ✅      | 🕓    | ✅      |
 | `.pdf`                  | ✅      | ✅    | 🕓      |
 | `.key`                  | ✅      | ✅    | 🕓      |
-| `.docx` `.doc`          | ✅      | ✅    | —       |
+| `.docx`                 | ✅      | ✅    | —       |
+| `.doc`                  | —       | —     | —       |
 | `.xlsx`                 | 🕓      | 🕓    | —       |
 | `.pages`                | ✅      | ✅    | —       |
 | `.numbers`              | ✅      | ✅    | —       |
@@ -45,7 +47,7 @@ Not every option applies everywhere. What a route can honour depends on how the
 | ------------------- | ---------------------------- | ---------------- | ----------- |
 | `.pptx` `.ppt`      | ✅ snapped to 1080/1920/2560 | png, jpg, webp   | ✅          |
 | `.pdf`              | ✅ any value                 | png, jpg, webp   | ✅          |
-| `.docx` `.doc`      | ✅ any value                 | png, jpg, webp   | ✅          |
+| `.docx`             | ✅ any value                 | png, jpg, webp   | ✅          |
 | `.key`              | ✗                            | png, webp        | ✅          |
 | `.html` and URLs    | ✅                           | png, webp        | ✗ one image |
 | `.md`               | ✅                           | png, webp        | ✗ one image |
@@ -57,9 +59,17 @@ PDF and video output accept no sizing, encoding, quality or page options — the
 
 ## Per-format notes
 
-Everything in the matrix works. These notes are about what the output _is_ — the
+Everything marked ✅ in the matrix works. These notes are about what the output _is_ — the
 cases where the result differs from a plain full-fidelity render.
 
+### Legacy Office formats
+
+Legacy PowerPoint `.ppt` files render to images and video. PDF output is planned but not currently
+supported: the reliable route needs to normalize `.ppt` to `.pptx` before PDF conversion.
+
+Legacy Word `.doc` files are not supported by the backend converter. Save them as `.docx` or export
+them to PDF before rendering.
+
 ### Pages and Numbers — first page only
 
 These render the preview iWork embeds in the document, which covers the **first

docs/roadmap.md

@@ -2,8 +2,9 @@
 
 ## v0.1 — shipped
 
-- `pptx` `ppt` `pdf` `key` `docx` `doc` `html` `md` and URLs → image and PDF
-- `pptx` `ppt` → video
+- `pptx` `pdf` `key` `docx` `html` `md` and URLs → image and PDF
+- `ppt` → image and video
+- `pptx` → video
 - Cloud engine over `@deckops/sdk`
 - Profiles, `--json` envelope, page selection, zip and stdout output
 - Credentials shared with DeckHTML and DeckOps; guest mode without login
@@ -24,6 +25,7 @@ Combinations the CLI marks `soon` and reports as `not_implemented`:
 
 | Combination          | Blocked on                                                                                                         |
 | -------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `.ppt` → pdf         | Normalize the legacy binary file to `.pptx` before invoking the stable PDF converter.                              |
 | `.xlsx` → image, pdf | A spreadsheet layout engine. A workbook needs a real layout pass — not something to fake from an embedded preview. |
 | `.pdf` → video       | Local frame assembly (ffmpeg), not bundled.                                                                        |
 | `.key` → video       | Local frame assembly (ffmpeg), not bundled.                                                                        |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deckflow/deckrender",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Render any document format into visual artifacts. PPTX, PDF, DOCX, Keynote, HTML and Markdown to images, PDF or video.",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,12 +28,13 @@
     "test:integration": "vitest run tests/integration",
     "test:e2e": "vitest run tests/e2e",
     "test:cloud": "vitest run tests/e2e/cloud.test.ts",
+    "test:consumer": "node node_modules/typescript-7/bin/tsc -p tests/consumer/tsconfig.json",
     "test:conformance": "node scripts/conformance.mjs",
     "test:coverage": "vitest run --coverage",
     "lint": "eslint src tests --ext .ts",
     "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts'",
-    "typecheck": "tsc --noEmit",
-    "check": "pnpm typecheck && pnpm lint && pnpm test:unit && pnpm test:integration"
+    "typecheck": "node node_modules/typescript/bin/tsc --noEmit",
+    "check": "pnpm typecheck && pnpm lint && pnpm test:unit && pnpm test:integration && pnpm build && pnpm test:consumer"
   },
   "keywords": [
     "cli",
@@ -58,6 +59,7 @@
   },
   "dependencies": {
     "@deckops/sdk": "^0.7.3",
+    "@types/node": "^20.10.0",
     "chalk": "^5.3.0",
     "commander": "^11.1.0",
     "open": "^11.0.0",
@@ -66,14 +68,14 @@
     "zod": "^3.22.0"
   },
   "devDependencies": {
-    "@types/node": "^20.10.0",
     "@typescript-eslint/eslint-plugin": "^6.13.0",
     "@typescript-eslint/parser": "^6.13.0",
     "@vitest/coverage-v8": "^1.0.0",
     "eslint": "^8.55.0",
     "prettier": "^3.1.0",
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",
+    "typescript-7": "npm:typescript@7.0.2",
     "vitest": "^1.0.0"
   },
   "engines": {