rasterport 0.1.5 → 0.1.6

package/README.md

@@ -6,12 +6,45 @@ Capture web screenshots + DOM in one command. Built for AI agents, CI, and autom
 npx rasterport https://example.com
 ```
 
+`rasterport` is a small Node CLI and library for grabbing a rendered page screenshot
+and the current DOM in one pass. It is useful when you want browser output without
+setting up a larger automation harness around Playwright.
+
 ## Example capture
 
 Landscape preview generated with `rasterport` from `https://vercel.com/home`:
 
 ![Landscape screenshot example](https://en3r1eqyd9.ufs.sh/f/2LgYpGpgMsliG2eLKyMTl9HkFm5Op0JnjMrAWvKRyux1bNgC)
 
+## Install
+
+Run it directly with `npx`:
+
+```bash
+npx rasterport https://example.com
+```
+
+Or install it in a project:
+
+```bash
+npm install rasterport
+```
+
+## CLI usage
+
+The CLI renders the page, waits for network idle, then returns JSON with:
+
+- `screenshot`: base64 by default, or an array of bytes with `--format buffer`
+- `dom`: the page HTML unless `--screenshot-only` is used
+- `url`: the final page URL after navigation
+- `viewport`: the width and height used for the capture
+
+Basic usage:
+
+```bash
+rasterport <url> [options]
+```
+
 ## Options
 
 ```bash
@@ -31,6 +64,38 @@ rasterport <url> [options]
 --help                 Show help
 ```
 
+### CLI examples
+
+Capture screenshot and DOM to stdout:
+
+```bash
+npx rasterport https://example.com
+```
+
+Write the JSON result to a file:
+
+```bash
+npx rasterport https://example.com --out capture.json
+```
+
+Capture only the screenshot for a wider viewport:
+
+```bash
+npx rasterport https://example.com --width 1440 --height 900 --screenshot-only
+```
+
+Capture the full scrollable page:
+
+```bash
+npx rasterport https://example.com --full-page --screenshot-only --out fullpage.json
+```
+
+Return only the DOM:
+
+```bash
+npx rasterport https://example.com --dom-only
+```
+
 JPEG is the default because it keeps screenshot payloads much smaller while
 remaining readable for agent workflows. Use PNG when you need lossless output:
 
@@ -52,6 +117,9 @@ The default output is JSON:
 }
 ```
 
+When `--format buffer` is used, `screenshot` is returned as a JSON array of byte
+values instead of base64.
+
 ## Why rasterport?
 
 - Single CLI command for screenshot + DOM capture
@@ -69,14 +137,16 @@ The default output is JSON:
 | API             | simple     | complex   |
 | Agent workflows | native     | manual    |
 
-## For AI agents
+## Library usage
+
+`capture()` uses the same behavior as the CLI and returns the same shape of data.
 
-rasterport exports the same `capture` function used by the CLI:
+Basic example:
 
 ```js
 import { capture } from "rasterport";
 
-await capture({
+const result = await capture({
   url: task.url,
   fullPage: false,
   width: 1280,
@@ -88,3 +158,99 @@ await capture({
   domOnly: false,
 });
 ```
+
+Example result:
+
+```js
+{
+  screenshot: "<base64>",
+  url: "https://example.com",
+  viewport: {
+    width: 1280,
+    height: 800,
+  },
+}
+```
+
+Capture both screenshot and DOM:
+
+```js
+import { capture } from "rasterport";
+
+const result = await capture({
+  url: "https://example.com",
+  fullPage: false,
+  width: 1280,
+  height: 800,
+  format: "base64",
+  imageFormat: "jpeg",
+  quality: 70,
+  screenshotOnly: false,
+  domOnly: false,
+});
+
+console.log(result.dom);
+console.log(result.screenshot);
+```
+
+Capture only the DOM:
+
+```js
+import { capture } from "rasterport";
+
+const result = await capture({
+  url: "https://example.com",
+  fullPage: false,
+  width: 1280,
+  height: 800,
+  format: "base64",
+  imageFormat: "jpeg",
+  quality: 70,
+  screenshotOnly: false,
+  domOnly: true,
+});
+```
+
+Capture a full-page PNG and get raw bytes:
+
+```js
+import { capture } from "rasterport";
+
+const result = await capture({
+  url: "https://example.com",
+  fullPage: true,
+  width: 1280,
+  height: 800,
+  format: "buffer",
+  imageFormat: "png",
+  screenshotOnly: true,
+  domOnly: false,
+});
+```
+
+### `capture()` options
+
+```ts
+capture(options: {
+  url: string;
+  fullPage: boolean;
+  width: number;
+  height: number;
+  format: "base64" | "buffer";
+  imageFormat: "png" | "jpeg";
+  quality?: number;
+  screenshotOnly: boolean;
+  domOnly: boolean;
+}): Promise<{
+  screenshot?: string | number[];
+  dom?: string;
+  url: string;
+  viewport: {
+    width: number;
+    height: number;
+  };
+}>
+```
+
+`quality` only applies when `imageFormat` is `jpeg`. `screenshotOnly` and
+`domOnly` are mutually exclusive.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rasterport",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Minimal CLI to capture webpage screenshots and DOM for LLM workflows.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,6 +17,7 @@
   },
   "files": [
     "dist",
+    "assets",
     "README.md",
     "llms.txt",
     "LICENSE"