smooth-screenshot 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luccas Carvalho
+
+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,104 @@
+# smooth-screenshot
+
+[![npm version](https://img.shields.io/npm/v/smooth-screenshot.svg)](https://www.npmjs.com/package/smooth-screenshot)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/smooth-screenshot)](https://bundlephobia.com/package/smooth-screenshot)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/smooth-screenshot?activeTab=dependencies)
+[![types](https://img.shields.io/npm/types/smooth-screenshot)](https://www.npmjs.com/package/smooth-screenshot)
+[![license](https://img.shields.io/npm/l/smooth-screenshot)](./LICENSE)
+
+**Capture any DOM element to PNG, JPEG, WebP, SVG, or PDF — without ever freezing the UI.**
+
+Most DOM-to-image libraries do all their work in one synchronous burst: on a large
+element the page locks up, animations stutter, and your loading spinner freezes
+mid-spin. `smooth-screenshot` slices the work across frames with an internal
+cooperative scheduler, so the main thread stays responsive the whole time. Your
+skeletons and progress animations keep running while the capture happens.
+
+- **Never blocks the main thread** — work yields to the event loop on a frame budget.
+- **Per-phase progress** — drive real loading states (`clone` → `embed` → `rasterize` → `encode`).
+- **Cancellable** — pass an `AbortSignal`.
+- **Huge content** — PNG and PDF render in memory-bounded tiles, beyond the browser's single-canvas size limit.
+- **Multi-format** — `toPng`, `toJpeg`, `toWebp`, `toSvg`, `toPdf`, `toBlob`, `toCanvas`.
+- **Zero runtime dependencies.** Inline web worker, hand-written PDF, native compression.
+
+```bash
+npm install smooth-screenshot
+```
+
+## Usage
+
+```ts
+import { toPng, toPdf, toSvg } from 'smooth-screenshot'
+
+const node = document.querySelector('#capture')!
+
+// PNG data URL
+const url = await toPng(node)
+
+// PDF blob
+const pdf = await toPdf(node)
+
+// SVG (vector, infinite zoom)
+const svg = await toSvg(node)
+```
+
+### Loading state that doesn't freeze
+
+```ts
+await toPng(node, {
+  onProgress({ phase, overall }) {
+    setLabel(phase) // 'clone' | 'embed' | 'rasterize' | 'encode'
+    setBar(overall) // 0..1
+  },
+})
+```
+
+### Cancellation
+
+```ts
+const controller = new AbortController()
+cancelButton.onclick = () => controller.abort()
+
+try {
+  await toPng(node, { signal: controller.signal })
+} catch (err) {
+  if (err instanceof DOMException && err.name === 'AbortError') {
+    // user cancelled
+  }
+}
+```
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `type` | `'png'` | Image format for `toBlob` (`png` \| `jpeg` \| `webp`). |
+| `quality` | `0.92` | 0–1 for lossy formats. |
+| `scale` | `devicePixelRatio` | Output pixel density (alias: `pixelRatio`). |
+| `backgroundColor` | transparent | Background painted behind the element (JPEG defaults to white). |
+| `width` / `height` | element size | Force output dimensions (CSS px). |
+| `crop` | — | `{ x, y, width, height }` — capture a sub-region. Use for full-res sections of very large content. |
+| `signal` | — | `AbortSignal` to cancel the capture. |
+| `onProgress` | — | `(p: { phase, phaseRatio, overall }) => void`. |
+| `frameBudgetMs` | `5` | Main-thread time per slice before yielding. |
+| `worker` | `true` | Offload resource fetching to an inline worker. `false` or `{ count }`. |
+| `maxTileSize` | `4096` | Tile edge (device px) before tiling kicks in. |
+| `filter` | — | `(node) => boolean` to exclude nodes. |
+| `fonts` | — | `{ skip?, preferWoff2? }`. |
+| `fetch` | — | `{ requestInit?, placeholder?, timeoutMs?, retries? }`. |
+| `onResourceError` | — | `(url, error) => void` — a failed resource doesn't fail the capture. |
+
+## Notes & limits
+
+- **Very large content:** `toPng` and `toPdf` render at full resolution via tiling.
+  `toJpeg` / `toWebp` / `toCanvas` are bound by the browser's single-canvas size
+  limit and are downscaled to fit when exceeded. To export huge content crisply in
+  those formats, capture sections with `crop`.
+- **Cross-origin resources** must allow CORS, otherwise they can't be embedded and
+  are replaced with a transparent placeholder (see `onResourceError`).
+- **Browser support:** requires `CompressionStream` for tiled PNG/PDF output
+  (Chrome 80+, Firefox 113+, Safari 16.4+).
+
+## License
+
+MIT © Luccas Carvalho