diff --git a/README.md b/README.md
index 9857524..049a450 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,9 @@
 HTML to image rendering for PHP, powered by Rust and [Takumi](https://github.com/kane50613/takumi).
 Generate Open Graph images and more from HTML/CSS without headless browser overhead.
 
+<img src="./examples/htmlshot/output/htmlshot.png" width="480px">
+
+
 ## Features
 
 - **No headless browser.** Rendering runs in-process through a native Rust library, so there is no Chromium to install, launch, or keep alive.
@@ -45,12 +48,18 @@ vendor/bin/htmlshot update
 ```
 
 > [!NOTE]
-> A natives.lock file is added to the root of the project. Commit this file to your repo to ensure that each time you'll get the same native version.
+> A `natives.lock` file is added to the root of the project. Commit this file to your repo to ensure that each time you'll get the same native version.
+
 
+## Documentation
 
+- [Getting started](docs/getting-started.md) — install and render your first image
+- [Fonts & styles](docs/fonts-and-styles.md) — custom fonts, inline/`<style>`/external CSS, and `tw` utilities
+- [Advanced usage](docs/advanced.md) — HiDPI output and using `Context` + `Renderer` directly
+- [Examples](examples/README.md) — runnable Open Graph and social-card scripts
 
 
-## Quick Example
+## Quick start
 
 The fastest way in is the `HtmlShot` façade. Give it some HTML and a few
 options, and it hands back the encoded image bytes:
@@ -81,6 +90,12 @@ Available options: `width`, `height`, `format` (`png` | `webp` | `jpeg`),
 `quality` (1–100 for the lossy formats), `stylesheets` (extra CSS),
 `fonts`, and `devicePixelRatio` (e.g. `2.0` for Retina output).
 
+
+> [!NOTE]
+> See the [`examples/`](examples/) directory for deep dive with fonts, custom styles, images and high resolution.
+
+
+
 ### Reusing a context
 
 The façade loads fonts on every call. When you render repeatedly, build a
@@ -110,6 +125,7 @@ foreach ($posts as $post) {
 ```
 
 
+
 ## Deep Dive
 
 ### How HTML & CSS are handled
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..cd7f24e
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,15 @@
+# Documentation
+
+Guides for rendering HTML to images with `html-shot`.
+
+- **[Getting started](getting-started.md)** — install the package and the native
+  library, then render your first image.
+- **[Fonts & styles](fonts-and-styles.md)** — load custom fonts and style your
+  markup with inline CSS, `<style>` blocks, external stylesheets, or `tw`
+  utilities.
+- **[Advanced usage](advanced.md)** — HiDPI / Retina output, and driving a
+  `Context` + `Renderer` directly for repeated rendering.
+
+For complete, runnable scripts see the [`examples/`](../examples/) directory and
+its [README](../examples/README.md). The main [project README](../README.md) has
+a "Deep Dive" section describing how the engine interprets HTML and CSS.
diff --git a/docs/advanced.md b/docs/advanced.md
new file mode 100644
index 0000000..dab7dcc
--- /dev/null
+++ b/docs/advanced.md
@@ -0,0 +1,156 @@
+# Advanced usage
+
+## HiDPI / Retina output
+
+`width` and `height` describe the logical canvas: the coordinate space your CSS
+lays out in. The `devicePixelRatio` option scales the physical bitmap without
+touching that layout, so a 1200×630 layout at `devicePixelRatio: 2.0` produces a
+2400×1260 image, pixel-doubled and crisp on Retina displays.
+
+```php
+use HtmlShot\HtmlShot;
+
+// 1× — 1200×630 physical pixels
+$png = HtmlShot::render($html, [
+    'width'  => 1200,
+    'height' => 630,
+    'format' => 'png',
+]);
+
+// 2× — same layout, 2400×1260 physical pixels
+$retina = HtmlShot::render($html, [
+    'width'            => 1200,
+    'height'           => 630,
+    'format'           => 'webp',
+    'devicePixelRatio' => 2.0,
+]);
+```
+
+Because the layout is unchanged, font sizes, padding, and positions stay
+identical between the 1× and 2× renders; only the output resolution differs.
+This is the usual way to ship both a normal and an `@2x` asset from one
+template. The [`banner`](../examples/banner/banner.php) example emits both.
+
+### Choosing a format and quality
+
+`format` accepts `'png'`, `'webp'`, or `'jpeg'`. For the lossy formats, set
+`quality` from 1–100 (`0` uses the library default):
+
+```php
+$jpeg = HtmlShot::render($html, [
+    'width'   => 1200,
+    'height'  => 630,
+    'format'  => 'jpeg',
+    'quality' => 82,
+]);
+```
+
+PNG is lossless and ignores `quality`. WebP at a high quality is usually the
+best size/clarity trade-off for HiDPI assets.
+
+## Using Context and Renderer directly
+
+The `HtmlShot` façade builds a fresh `Context` and reloads every font on each
+call. When you render repeatedly (a batch of cards, or an HTTP endpoint serving
+many images), build the `Context` once, load the fonts a single time, and drive
+a `Renderer` directly.
+
+```php
+use HtmlShot\Context;
+use HtmlShot\Renderer;
+
+$context = new Context;
+$context->loadFontFile('/fonts/Inter-Regular.ttf', family: 'Inter', weight: 400);
+$context->loadFontFile('/fonts/Inter-Bold.ttf',    family: 'Inter', weight: 700);
+
+$renderer = new Renderer($context);
+
+foreach ($posts as $post) {
+    $html = renderTemplate($post); // your own HTML builder
+
+    // 1× PNG
+    file_put_contents("{$post->slug}.png", $renderer->render($html, 1200, 630));
+
+    // 2× WebP for HiDPI displays
+    $webp = $renderer->render($html, 1200, 630, 'webp', devicePixelRatio: 2.0);
+    file_put_contents("{$post->slug}@2x.webp", $webp);
+}
+```
+
+The fonts are parsed once and reused across every `render()` call, which is the
+main reason to prefer this path over the façade in a loop or a long-running
+process.
+
+### `Renderer::render()` signature
+
+```php
+$renderer->render(
+    string $html,
+    int    $width = 1200,
+    int    $height = 628,
+    string $format = 'png',
+    int    $quality = 0,
+    array  $stylesheets = [],
+    float  $devicePixelRatio = 1.0,
+    float  $baseFontSize = 16.0,
+): string;
+```
+
+Using named arguments keeps calls readable when you only need a couple of the
+options:
+
+```php
+$bytes = $renderer->render(
+    $html,
+    width: 1200,
+    height: 630,
+    stylesheets: [$css],
+    devicePixelRatio: 2.0,
+);
+```
+
+`baseFontSize` is the root font size in pixels used to resolve `rem` and the
+initial `em`. It's the equivalent of the browser's `<html>` font-size, 16px by
+default. Raise it to scale a whole `rem`-based template at once.
+
+### Loading fonts onto a Context
+
+A `Context` exposes the same loaders as the `Font` helper:
+
+```php
+// From a file
+$context->loadFontFile('/fonts/Inter-Bold.ttf', family: 'Inter', weight: 700);
+
+// From raw bytes
+$context->loadFontData(file_get_contents('/fonts/Inter-Bold.ttf'), family: 'Inter', weight: 700);
+```
+
+You can also build `Font` descriptors and load them in:
+
+```php
+use HtmlShot\Font;
+
+Font::fromFile('/fonts/Inter-Bold.ttf', family: 'Inter', weight: 700)->loadInto($context);
+```
+
+## Error handling
+
+Render and font-loading failures throw `HtmlShot\Exception\RuntimeException`.
+Wrap calls that depend on external input (user-supplied HTML, fonts read from
+disk) so a single bad render doesn't take down the request:
+
+```php
+use HtmlShot\Exception\RuntimeException;
+
+try {
+    $png = $renderer->render($html, 1200, 630);
+} catch (RuntimeException $e) {
+    // log and fall back to a static placeholder
+}
+```
+
+## See also
+
+- [Getting started](getting-started.md)
+- [Fonts & styles](fonts-and-styles.md)
+- [`examples/`](../examples/)
\ No newline at end of file
diff --git a/docs/fonts-and-styles.md b/docs/fonts-and-styles.md
new file mode 100644
index 0000000..6218432
--- /dev/null
+++ b/docs/fonts-and-styles.md
@@ -0,0 +1,155 @@
+# Fonts & styles
+
+## Custom fonts
+
+`html-shot` ships no fonts. Any text you render needs a font that covers it, so
+load your own with the `Font` helper and pass them in the `fonts` option. The
+`family` you give here is the name you then reference from CSS `font-family`.
+
+```php
+use HtmlShot\Font;
+use HtmlShot\HtmlShot;
+
+$png = HtmlShot::render(
+    '<div style="font-family: Inter; font-size: 64px; font-weight: 700;">Hello</div>',
+    [
+        'width'  => 1200,
+        'height' => 630,
+        'fonts'  => [
+            Font::fromFile('/fonts/Inter-Regular.ttf', family: 'Inter', weight: 400),
+            Font::fromFile('/fonts/Inter-Bold.ttf',    family: 'Inter', weight: 700),
+        ],
+    ],
+);
+```
+
+Load one descriptor per weight/style you intend to use, all under the same
+`family`; the engine picks the right file based on the CSS `font-weight` and
+`font-style` at render time.
+
+### From a file or from bytes
+
+```php
+// From a path on disk
+Font::fromFile('/fonts/Inter-Regular.ttf', family: 'Inter', weight: 400);
+
+// From raw bytes, handy when the font lives in a database, cache, or archive
+Font::fromData(file_get_contents('/fonts/Inter-Regular.ttf'), family: 'Inter', weight: 400);
+```
+
+Both accept `family`, `weight`, and `style` overrides:
+
+| Argument | Default | Notes |
+| --- | --- | --- |
+| `family` | `''` | Override the family name; empty auto-detects from the font metadata |
+| `weight` | `0` | Override weight 1–1000; `0` auto-detects |
+| `style` | `''` | `'normal'`, `'italic'`, or `'oblique'`; empty auto-detects |
+
+Supported file formats are TTF, OTF, WOFF, and WOFF2.
+
+### Variable fonts
+
+A single variable font file covers a range of weights. Register it once and use
+any weight from its axis. The examples in this repo do exactly that with Geist:
+
+```php
+Font::fromFile(__DIR__.'/tests/fonts/Geist/variable/Geist[wght].ttf', family: 'Geist');
+```
+
+```html
+<h1 style="font-family: Geist; font-weight: 800;">Bold</h1>
+<p  style="font-family: Geist; font-weight: 400;">Regular</p>
+```
+
+### Multiple families in one render
+
+Register as many families as you need and switch between them in CSS:
+
+```php
+'fonts' => [
+    Font::fromFile($base.'/Geist/variable/Geist[wght].ttf',         family: 'Geist'),
+    Font::fromFile($base.'/GeistMono/variable/GeistMono[wght].ttf', family: 'Geist Mono'),
+],
+```
+
+```html
+<span style="font-family: 'Geist Mono';">vercel/</span>
+<span style="font-family: Geist;">satori</span>
+```
+
+## Styling your markup
+
+Layout and appearance are driven entirely by CSS. There are four ways to apply
+it, and they can be combined.
+
+### 1. Inline `style` attributes
+
+The most direct option, good for self-contained snippets:
+
+```html
+<div style="display:flex; align-items:center; justify-content:center;
+            width:100%; height:100%; background:#09090b; color:#fff;">
+  Hello
+</div>
+```
+
+### 2. `<style>` blocks
+
+A `<style>` tag inside the document is pulled out and applied as a stylesheet,
+so class selectors work as expected:
+
+```html
+<style>
+  .card { display:flex; width:100%; height:100%; background:#0b1020; color:#fff; }
+</style>
+<div class="card">Hello</div>
+```
+
+### 3. External stylesheets (`stylesheets` option)
+
+Keep styling out of the markup entirely by passing CSS through the
+`stylesheets` option. This works well when your CSS lives in its own file: the
+HTML carries only semantic class names.
+
+```php
+$css = file_get_contents(__DIR__.'/styles.css');
+
+$png = HtmlShot::render('<div class="card">Hello</div>', [
+    'width'       => 1200,
+    'height'      => 630,
+    'stylesheets' => [$css], // pass any number of sheets
+]);
+```
+
+The array can hold several sheets; they are applied on top of the document just
+like linked stylesheets in a browser. See the
+[`event-card`](../examples/event-card/) example for a complete walkthrough.
+
+### 4. `tw` Tailwind utilities
+
+Takumi's engine understands a `tw` attribute carrying Tailwind utility classes,
+so you can lay out a card without writing any CSS:
+
+```html
+<div tw="flex h-full w-full flex-col justify-end bg-[#16130f] p-20">
+  <h1 tw="m-0 text-8xl font-bold tracking-tighter text-white">HtmlShot.</h1>
+  <p  tw="mt-10 text-3xl text-[#a8a29a]">html in, image out</p>
+</div>
+```
+
+Arbitrary values (`bg-[#16130f]`, `text-[12em]`) are supported. The
+[`tailwind`](../examples/tailwind/) and [`stars`](../examples/stars/) examples
+use this approach.
+
+## Images and SVG
+
+Both `<img src="...">` and CSS `background-image: url(...)` accept local file
+paths and `data:` URIs; `http(s)` URLs are passed through to the engine. Inline
+`<svg>` is rasterized as an image, so vector graphics render without a separate
+conversion step. The [main README's "Deep Dive"](../README.md#deep-dive) covers
+the exact handling.
+
+## Next steps
+
+- [Advanced usage](advanced.md) — HiDPI output and reusing a `Context` +
+  `Renderer` for repeated rendering.
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..916b4aa
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,107 @@
+# Getting started
+
+## Requirements
+
+- PHP 8.3 or higher
+- The FFI extension enabled (`ext-ffi`)
+
+Check that FFI is active:
+
+```bash
+php -m | grep FFI
+```
+
+If it is missing, enable it in your `php.ini` and restart PHP:
+
+```ini
+extension=ffi
+ffi.enable=true
+```
+
+## Install
+
+```bash
+composer require avvertix/html-shot
+```
+
+The package renders through a compiled native library. Download the binary that
+matches your platform and package version with the bundled console command:
+
+```bash
+vendor/bin/htmlshot install
+```
+
+This fetches the correct binary from the matching GitHub release, verifies its
+checksum, and stores it under the package `lib/` directory. It also writes a
+`natives.lock` file to your project root. Commit it so every environment
+resolves the same native version. After upgrading the package, refresh the
+library:
+
+```bash
+composer update avvertix/html-shot
+vendor/bin/htmlshot update
+```
+
+## Your first image
+
+The quickest way in is the `HtmlShot` façade. Give it some HTML and a few
+options; it returns the encoded image bytes, which you can write to disk or
+stream to a response.
+
+```php
+use HtmlShot\HtmlShot;
+
+$png = HtmlShot::render(
+    '<div style="display:flex; width:100%; height:100%; align-items:center;
+                 justify-content:center; background:#ecfeff; color:#0f172a;
+                 font-size:96px; font-weight:800;">That was fast!</div>',
+    [
+        'width'  => 1280,
+        'height' => 630,
+        'format' => 'png',
+    ],
+);
+
+file_put_contents('hello.png', $png);
+```
+
+A few things to know up front:
+
+- The single wrapper `<div>` is sized to fill the canvas with `width:100%;
+  height:100%`. Layout is driven entirely by CSS, so reach for Flexbox or Grid
+  to position things.
+- Text only renders if a font covering it is available. The snippet above relies
+  on a system fallback; to control typography, load your own font (see
+  [Fonts & styles](fonts-and-styles.md)).
+
+## Render options
+
+All options are passed in the array argument to `HtmlShot::render()`:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `width` | `int` | `1200` | Logical canvas width in pixels |
+| `height` | `int` | `628` | Logical canvas height in pixels |
+| `format` | `string` | `'png'` | `'png'`, `'webp'`, or `'jpeg'` |
+| `quality` | `int` | `0` | 1–100 for the lossy formats; `0` uses the library default |
+| `stylesheets` | `string[]` | `[]` | Extra CSS applied on top of the document |
+| `fonts` | `Font[]` | `[]` | Fonts to load for this render |
+| `devicePixelRatio` | `float` | `1.0` | Output scale factor (e.g. `2.0` for Retina) |
+
+## Serving the bytes
+
+`render()` returns raw image bytes, so you can stream them straight to a
+response without touching the filesystem. For example, in plain PHP:
+
+```php
+header('Content-Type: image/png');
+echo HtmlShot::render($html, ['width' => 1200, 'height' => 630]);
+```
+
+## Next steps
+
+- [Fonts & styles](fonts-and-styles.md) — custom typography and the different
+  ways to style your markup.
+- [Advanced usage](advanced.md) — HiDPI output and reusing a `Context` +
+  `Renderer` for repeated rendering.
+- [`examples/`](../examples/) — runnable Open Graph and social-card scripts.
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..8a73ef4
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,52 @@
+# Examples
+
+Here a few examples on how to render images with `html-shot`. Each one is a small,
+self-contained recipe: read the source to see the technique, run it to get the
+PNG in that example's `output/` folder.
+
+
+| | | |
+| :---: | :---: | :---: |
+| <img src="simple/output/simple.png" width="240"><br>`simple` | <img src="tailwind/output/tailwind.png" width="240"><br>`tailwind` |  <img src="event/output/event.png" width="240"><br>`event` |
+| <img src="changelog/output/changelog.png" width="240"><br>`changelog` | <img src="quote/output/quote.png" width="240"><br>`quote` | <img src="repository/output/repository.png" width="240"><br>`repository` |
+| <img src="stars/output/stars.png" width="240"><br>`stars` | <img src="event-card/output/event-card.png" width="240"><br>`event-card` | <img src="line-chart/output/line-chart.png" width="240"><br>`line-chart` |
+| <img src="banner/output/banner.png" width="240"><br>`banner` | | |
+
+## What each example teaches
+
+| Folder | What you'll learn |
+| --- | --- |
+| `simple/` | The **`HtmlShot::render()` façade**, inline CSS, loading a single font |
+| `tailwind/` | Styling with the **`tw` Tailwind** utility attribute instead of CSS |
+| `htmlshot/` | Generate HtmlShot Open Graph image |
+| `stars/` | Absolute positioning and a full-bleed background image with `tw` |
+| `changelog/` | Building repeated rows from a PHP array, uppercase tag labels |
+| `event/` | A full-height flex column split into three regions, letter-spacing |
+| `quote/` | Large decorative typography and an inline metadata row |
+| `repository/` | Mixing **two font families** (Geist + Geist Mono) in one render |
+| `event-card/` | Passing a **custom stylesheet** via the `stylesheets` option — markup carries only class names, all styling lives in `styles.css` |
+| `line-chart/` | Generating an **inline `<svg>`** from a data array (computed points, area fill, grid) with HTML axis labels laid over the same coordinate space |
+| `banner/` | Reusing a `Context` + `Renderer`, emitting multiple outputs (1× PNG and a 2× WebP via `devicePixelRatio`), an inline SVG watermark |
+
+
+## Running them
+
+```bash
+# from the project root
+php examples/simple/simple.php
+```
+
+Every example writes to its own `output/` directory and prints the file it
+saved. To rebuild them all at once:
+
+```bash
+php examples/regenerate.php
+```
+
+**Prerequisites**
+
+- `composer install`
+- `vendor/bin/htmlshot install` to download the native rendering library
+- The bundled fonts under `tests/fonts/` (Geist, Geist Mono) — most examples
+  load one or both.
+
diff --git a/examples/assets/images/fresh-htmlshot-no-bg.png b/examples/assets/images/fresh-htmlshot-no-bg.png
new file mode 100644
index 0000000..3051221
Binary files /dev/null and b/examples/assets/images/fresh-htmlshot-no-bg.png differ
diff --git a/examples/assets/images/fresh-htmlshot.png b/examples/assets/images/fresh-htmlshot.png
new file mode 100644
index 0000000..6ef12e2
Binary files /dev/null and b/examples/assets/images/fresh-htmlshot.png differ
diff --git a/examples/banner/banner.php b/examples/banner/banner.php
new file mode 100644
index 0000000..185d00f
--- /dev/null
+++ b/examples/banner/banner.php
@@ -0,0 +1,90 @@
+<?php
+
+use HtmlShot\Context;
+use HtmlShot\Renderer;
+
+require __DIR__.'/../common.php';
+
+$outputDir = __DIR__.'/output';
+
+/**
+ * A release announcement banner
+ *
+ * Usage:
+ *   php examples/banner/banner.php
+ */
+$COMPONENT = [
+    'name' => 'v1',
+    'width' => 1200,
+    'height' => 675,
+    'fonts' => [
+        ['path' => __DIR__.'/../../tests/fonts/Geist/variable/Geist[wght].ttf',         'family' => 'Geist'],
+        ['path' => __DIR__.'/../../tests/fonts/GeistMono/variable/GeistMono[wght].ttf', 'family' => 'Geist Mono'],
+    ],
+    'html' => static function () use ($assetsImages): string {
+        // Build the 18-row repeated pattern
+        $rows = '';
+        for ($i = 0; $i < 18; $i++) {
+            $marginLeft = (($i * 137) % 600);
+            $items = '';
+            for ($j = 0; $j < 15; $j++) {
+                $items .= <<<'HTML'
+<div style="display: flex; align-items: center; flex-shrink: 0; gap: 0.25em; margin-left: -1rem;">
+  <span style="margin-right: 1rem;">Shake.</span>
+  <span style="margin-right: 1rem;">Render.</span>
+  <span style="margin-right: 1rem;">Refresh.</span>
+  <span>&nbsp;</span>
+</div>
+HTML;
+            }
+            $rows .= <<<HTML
+<div style="margin: 0; font-size: 64px; line-height: 0.9; font-weight: 900; color: #18181b;
+            font-family: Geist, sans-serif; white-space: nowrap; display: flex;
+            align-items: center; margin-left: -{$marginLeft}px;">
+  {$items}
+</div>
+HTML;
+        }
+
+        return <<<HTML
+<div style="width: 100%; height: 100%; background-color: #14532d; display: flex;
+            align-items: center; justify-content: center; position: relative; overflow: hidden;
+            font-family: Geist, sans-serif;">
+
+  <!-- Watermark rows (rotated) -->
+  <div style="mix-blend-mode: screen;position: absolute; display: flex; flex-direction: column; justify-content: center;
+              width: 2400px; height: 1600px; left: -600px; top: -450px; transform: rotate(-12deg);">
+    {$rows}
+  </div>
+
+  <!-- Foreground content -->
+  <div style="display: flex; flex-direction: column; align-items: center; justify-content: center;
+              position: relative; z-index: 10;">
+              <img src="{$assetsImages}/fresh-htmlshot-no-bg.png" style="height:260px;">
+    <h1 style="margin: 0; color: #fff; font-size: 120px; font-weight: 700;
+               letter-spacing: -0.05em; line-height: 1;">v0.3.0 Released</h1>
+    <div style="margin-top: 3rem; display: flex; align-items: center; padding: 1rem 2rem;
+                background-color: #052e16; border-radius: 9999px;">
+      <span style="font-family: Geist Mono, monospace; color: #f0fdf4; font-size: 32px; letter-spacing: -0.02em;">composer require avvertix/html-shot</span>
+    </div>
+  </div>
+
+</div>
+HTML;
+    },
+];
+
+$ctx = new Context;
+foreach ($COMPONENT['fonts'] as $f) {
+    $ctx->loadFontFile($f['path'], family: $f['family']);
+}
+$renderer = new Renderer($ctx);
+$html = ($COMPONENT['html'])();
+
+$png = $renderer->render($html, $COMPONENT['width'], $COMPONENT['height'], 'png');
+
+save_to_output($png, 'banner.png', $outputDir);
+
+$webp = $renderer->render($html, $COMPONENT['width'], $COMPONENT['height'], 'webp', devicePixelRatio: 2.0);
+
+save_to_output($webp, 'banner@2x.webp', $outputDir);
diff --git a/examples/banner/output/banner.png b/examples/banner/output/banner.png
new file mode 100644
index 0000000..06d5e36
Binary files /dev/null and b/examples/banner/output/banner.png differ
diff --git a/examples/banner/output/banner@2x.webp b/examples/banner/output/banner@2x.webp
new file mode 100644
index 0000000..f9e392a
Binary files /dev/null and b/examples/banner/output/banner@2x.webp differ
diff --git a/examples/changelog/changelog.php b/examples/changelog/changelog.php
new file mode 100644
index 0000000..6429d8f
--- /dev/null
+++ b/examples/changelog/changelog.php
@@ -0,0 +1,80 @@
+<?php
+
+/**
+ * Changelog / release notes card
+ *
+ * PHP port of https://takumi.kane.tw/docs/templates#changelog-template
+ *
+ * Usage:
+ *   php examples/templates/changelog.php
+ */
+
+require __DIR__.'/../common.php';
+
+use HtmlShot\Font;
+use HtmlShot\HtmlShot;
+
+$outputDir = __DIR__.'/output';
+
+$version = 'v0.3.0';
+$date = 'June 28, 2026';
+$headline = 'Faster installation';
+$bullets = [
+    ['tag' => 'New', 'text' => 'Installation script'],
+    ['tag' => 'Perf', 'text' => '30% smaller package footprint'],
+    ['tag' => 'Fixed', 'text' => 'Out of the box Tailwind CSS'],
+];
+
+$ink = '#16140F';
+$muted = '#6E6A60';
+$accent = '#1F9D55';
+
+$bulletRows = '';
+foreach ($bullets as $b) {
+    $tag = $b['tag'];
+    $text = $b['text'];
+    $bulletRows .= <<<HTML
+        <div style="display: flex; align-items: center; gap: 28px;">
+            <div style="display: flex; width: 92px; font-size: 20px; font-weight: 700;
+                        letter-spacing: 0.12em; text-transform: uppercase; color: {$accent};">
+                {$tag}
+            </div>
+            <span style="display: flex; font-size: 32px; font-weight: 500; color: {$ink};">
+                {$text}
+            </span>
+        </div>
+    HTML;
+}
+
+$html = <<<HTML
+<div style="display: flex; flex-direction: column; width: 100%; height: 100%;
+            background-color: #F5F3EC; color: {$ink}; padding: 80px 76px;
+            font-family: Geist; justify-content: center;">
+
+    <div style="display: flex; align-items: center; gap: 16px; margin-bottom: 24px;">
+        <span style="display: flex; font-size: 28px; font-weight: 700; color: {$accent};">{$version}</span>
+        <span style="display: flex; font-size: 28px; color: {$muted};">·</span>
+        <span style="display: flex; font-size: 28px; color: {$muted};">{$date}</span>
+    </div>
+
+    <h1 style="display: flex; font-size: 72px; font-weight: 800; line-height: 1.05;
+               letter-spacing: -0.03em; margin: 0; margin-bottom: 56px; max-width: 980px; color: {$ink};">
+        {$headline}
+    </h1>
+
+    <div style="display: flex; flex-direction: column; gap: 24px;">
+        {$bulletRows}
+    </div>
+</div>
+HTML;
+
+$png = HtmlShot::render($html, [
+    'width' => 1200,
+    'height' => 630,
+    'format' => 'png',
+    'fonts' => [
+        Font::fromFile("{$fontsPath}/Geist/variable/Geist[wght].ttf", 'Geist'),
+    ],
+]);
+
+save_to_output($png, 'changelog.png', $outputDir);
diff --git a/examples/changelog/output/changelog.png b/examples/changelog/output/changelog.png
new file mode 100644
index 0000000..523dc4f
Binary files /dev/null and b/examples/changelog/output/changelog.png differ
diff --git a/examples/common.php b/examples/common.php
new file mode 100644
index 0000000..79fc3ec
--- /dev/null
+++ b/examples/common.php
@@ -0,0 +1,21 @@
+<?php
+
+require __DIR__.'/../vendor/autoload.php';
+
+$assetsImages = realpath(__DIR__.'/assets/images');
+
+$fontsPath = realpath(__DIR__.'/../tests/fonts');
+
+/**
+ * Save PNG to file
+ */
+function save_to_output(mixed $png, string $filename, string $directory): void
+{
+    if (! is_dir($directory)) {
+        mkdir($directory, 0755, true);
+    }
+
+    file_put_contents($directory.'/'.$filename, $png);
+
+    echo 'Saved: '.basename($directory)."/{$filename}\n";
+}
diff --git a/examples/event-card/event-card.php b/examples/event-card/event-card.php
new file mode 100644
index 0000000..04eb16a
--- /dev/null
+++ b/examples/event-card/event-card.php
@@ -0,0 +1,55 @@
+<?php
+
+/**
+ * Luma-style event invite card rendered with a custom stylesheet.
+ *
+ * Instead of inline styles, the layout is styled entirely from an external
+ * CSS file (styles.css). The file is read at runtime and passed to the
+ * renderer through the `stylesheets` option, so the markup stays clean and
+ * only references semantic class names.
+ *
+ * Usage:
+ *   php examples/event-card/event-card.php
+ */
+
+require __DIR__.'/../common.php';
+
+use HtmlShot\Font;
+use HtmlShot\HtmlShot;
+
+$outputDir = __DIR__.'/output';
+
+$logo = $assetsImages.'/luma.svg';
+$photo = $assetsImages.'/martin-martz-W0NRebXbsjM-unsplash.jpg';
+
+// The custom stylesheet lives next to this script.
+$stylesheet = file_get_contents(__DIR__.'/styles.css');
+
+$html = <<<HTML
+<div class="card">
+    <div class="left">
+        <img class="logo" src="{$logo}" alt="luma" />
+        <div class="body">
+            <h1 class="title">Bloom &amp; Breathe: A Mindful Floral Session</h1>
+            <div class="rsvp">RSVP</div>
+        </div>
+    </div>
+    <div class="right">
+        <img class="photo" src="{$photo}" alt="Event cover" />
+    </div>
+</div>
+HTML;
+
+$png = HtmlShot::render($html, [
+    'width' => 1200,
+    'height' => 630,
+    'format' => 'png',
+    // Pass any number of custom stylesheets here; they are applied on top of
+    // the document just like a linked CSS file would be in a browser.
+    'stylesheets' => [$stylesheet],
+    'fonts' => [
+        Font::fromFile("{$fontsPath}/Geist/variable/Geist[wght].ttf", 'Geist'),
+    ],
+]);
+
+save_to_output($png, 'event-card.png', $outputDir);
diff --git a/examples/event-card/output/event-card.png b/examples/event-card/output/event-card.png
new file mode 100644
index 0000000..f582cbd
Binary files /dev/null and b/examples/event-card/output/event-card.png differ
diff --git a/examples/event-card/styles.css b/examples/event-card/styles.css
new file mode 100644
index 0000000..c4daa97
--- /dev/null
+++ b/examples/event-card/styles.css
@@ -0,0 +1,68 @@
+/*
+ * Custom stylesheet for the event card.
+ *
+ * Everything that styles the card lives here, not inline on the elements.
+ * The example loads this file and hands it to HtmlShot through the
+ * `stylesheets` option, so the HTML only carries semantic class names.
+ */
+
+.card {
+    display: flex;
+    width: 100%;
+    height: 100%;
+    font-family: Geist, sans-serif;
+    color: #ffffff;
+    background-image: linear-gradient(115deg, #5460c8 0%, #7d79bb 52%, #a39ba2 100%);
+}
+
+.left {
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    padding: 60px;
+}
+
+.logo {
+    width: 96px;
+    height: 36px;
+}
+
+.body {
+    display: flex;
+    flex-direction: column;
+    margin-top: auto;
+    gap: 32px;
+}
+
+.title {
+    margin: 0;
+    max-width: 540px;
+    font-size: 46px;
+    font-weight: 600;
+    line-height: 1.18;
+    letter-spacing: -0.02em;
+}
+
+.rsvp {
+    display: flex;
+    align-self: flex-start;
+    padding: 14px 36px;
+    border-radius: 9999px;
+    background-color: #ffffff;
+    color: #4b3f8f;
+    font-size: 22px;
+    font-weight: 600;
+}
+
+.right {
+    display: flex;
+    width: 470px;
+    padding: 34px 34px 34px 0;
+}
+
+.photo {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    border-radius: 28px;
+}
diff --git a/examples/event/event.php b/examples/event/event.php
new file mode 100644
index 0000000..3ba728c
--- /dev/null
+++ b/examples/event/event.php
@@ -0,0 +1,70 @@
+<?php
+
+/**
+ * Event announcement card
+ *
+ * PHP port of https://takumi.kane.tw/docs/templates#event-template
+ *
+ * Usage:
+ *   php examples/templates/event.php
+ */
+
+require __DIR__.'/../common.php';
+
+use HtmlShot\Font;
+use HtmlShot\HtmlShot;
+
+$outputDir = __DIR__.'/output';
+
+$name = 'Shipping Rust to PHP: FFI in Production';
+$track = 'Workshop';
+$datetime = 'Thu, Sep 18, 2026 · 10:00 AM PT';
+$location = 'Online';
+$hostName = 'Claude';
+$hostTitle = 'AI Agent, Code Company';
+
+$ink = '#16140F';
+$muted = '#6E6A60';
+$accent = '#E5341F';
+
+$html = <<<HTML
+<div style="display: flex; flex-direction: column; width: 100%; height: 100%;
+            background-color: #F5F3EC; color: {$ink}; padding: 80px 76px;
+            font-family: Geist; justify-content: space-between;">
+
+    <span style="display: flex; font-size: 20px; font-weight: 700; letter-spacing: 0.22em;
+                 text-transform: uppercase; color: {$accent};">
+        {$track}
+    </span>
+
+    <div style="display: flex; flex: 1; flex-direction: column; justify-content: center;">
+        <span style="display: flex; font-size: 88px; font-weight: 800; line-height: 1.05;
+                     letter-spacing: -0.035em; color: {$ink};">
+            {$name}
+        </span>
+    </div>
+
+    <div style="display: flex; align-items: flex-end; justify-content: space-between;">
+        <div style="display: flex; flex-direction: column; gap: 8px;">
+            <span style="display: flex; font-size: 28px; font-weight: 600; color: {$ink};">{$datetime}</span>
+            <span style="display: flex; font-size: 24px; color: {$muted};">{$location}</span>
+        </div>
+        <div style="display: flex; align-items: center; gap: 12px;">
+            <span style="display: flex; font-size: 24px; font-weight: 600; color: {$ink};">{$hostName}</span>
+            <span style="display: flex; font-size: 24px; color: {$muted};">·</span>
+            <span style="display: flex; font-size: 24px; color: {$muted};">{$hostTitle}</span>
+        </div>
+    </div>
+</div>
+HTML;
+
+$png = HtmlShot::render($html, [
+    'width' => 1200,
+    'height' => 630,
+    'format' => 'png',
+    'fonts' => [
+        Font::fromFile("{$fontsPath}/Geist/variable/Geist[wght].ttf", 'Geist'),
+    ],
+]);
+
+save_to_output($png, 'event.png', $outputDir);
diff --git a/examples/event/output/event.png b/examples/event/output/event.png
new file mode 100644
index 0000000..d0bc77a
Binary files /dev/null and b/examples/event/output/event.png differ
diff --git a/examples/htmlshot/htmlshot.php b/examples/htmlshot/htmlshot.php
new file mode 100644
index 0000000..11fa5c7
--- /dev/null
+++ b/examples/htmlshot/htmlshot.php
@@ -0,0 +1,115 @@
+<?php
+
+/**
+ * HtmlShot Open Graph
+ *
+ * Usage:
+ *   php examples/templates/htmlshot/htmlshot.php
+ */
+
+require __DIR__.'/../common.php';
+
+use HtmlShot\Font;
+use HtmlShot\HtmlShot;
+
+$outputDir = __DIR__.'/output';
+
+$owner = 'avvertix';
+$name = 'html-shot';
+$description = 'HTML to image rendering for PHP.<br/>Generate OG image with native PHP.';
+$stars = '0';
+$forks = '0';
+
+$ink = '#16140F';
+$muted = '#6E6A60';
+$mono = "'Geist Mono', monospace";
+
+$rows = '';
+for ($i = 0; $i < 18; $i++) {
+    $marginLeft = (($i * 137) % 600);
+    $items = '';
+    for ($j = 0; $j < 15; $j++) {
+        $items .= <<<'HTML'
+<div style="display: flex; align-items: center; flex-shrink: 0; gap: 0.25em; margin-left: -1rem;">
+  <span style="margin-right: 1rem;">Shake.</span>
+  <span style="margin-right: 1rem;">Render.</span>
+  <span style="margin-right: 1rem;">Refresh.</span>
+  <span>&nbsp;</span>
+</div>
+HTML;
+    }
+    $rows .= <<<HTML
+<div style="margin: 0; font-size: 64px; line-height: 0.9; font-weight: 900; color: #f4f4f0;
+            font-family: Geist, sans-serif; white-space: nowrap; display: flex;
+            align-items: center; margin-left: -{$marginLeft}px;">
+  {$items}
+</div>
+HTML;
+}
+
+$html = <<<HTML
+<div style="display: flex; flex-direction: column; width: 100%; height: 100%;
+            background-color: #F5F3EC; color: {$ink}; padding: 80px 76px;
+            font-family: Geist; justify-content: center;">
+
+<!-- top: -450px; -->
+    <div style="mix-blend-mode: multiply;position: absolute; display: flex; flex-direction: column; justify-content: center;
+              left: -600px; 
+              top: 200px;
+              width: 2400px; height: 1600px;  transform: rotate(-12deg);">
+    {$rows}
+  </div>
+
+
+    <div style="position:absolute;right:-66%;top:-36px;height:100%;width:100%">
+        <img src="{$assetsImages}/fresh-htmlshot-no-bg.png" alt="" style="height:100%">
+    </div>
+
+    <span style="display: flex; font-size: 40px; font-weight: 500; font-family: {$mono};
+                 color: {$muted}; letter-spacing: -0.01em;">
+        {$owner}/
+    </span>
+    <span style="display: flex; font-size: 132px; font-weight: 700; font-family: {$mono};
+                 color: {$ink}; line-height: 0.96; letter-spacing: -0.045em; margin-top: 4px;">
+        {$name}
+    </span>
+    <span style="display: flex; flex-direction: column; font-size: 32px; font-weight: 400; color: #37352F;
+                 line-height: 1.36; max-width: 920px; margin-top: 32px;">
+        {$description}
+    </span>
+
+    <div style="display: flex; align-items: center; gap: 16px; margin-top: 44px;">
+        <!-- <div style="display: flex; align-items: baseline; gap: 8px;">
+            <span style="display: flex; font-size: 28px; font-weight: 700; color: {$ink};">{$stars}</span>
+            <span style="display: flex; font-size: 28px; color: {$muted};">stars</span>
+        </div>
+        <span style="display: flex; font-size: 28px; color: {$muted};">·</span>
+        <div style="display: flex; align-items: baseline; gap: 8px;">
+            <span style="display: flex; font-size: 28px; font-weight: 700; color: {$ink};">{$forks}</span>
+            <span style="display: flex; font-size: 28px; color: {$muted};">forks</span>
+        </div>
+        <span style="display: flex; font-size: 28px; color: {$muted};">·</span> -->
+        <div style="display: flex; align-items: center; gap: 12px;">
+            <div style="display: flex; width: 20px; height: 20px; border-radius: 50%;
+                        background-color: #5b21b6;"></div>
+            <span style="display: flex; font-size: 28px; font-weight: 600; color: #5b21b6;">PHP</span>
+            +
+            <div style="display: flex; width: 20px; height: 20px; border-radius: 50%;
+                        background-color: #9f1239;"></div>
+            <span style="display: flex; font-size: 28px; font-weight: 600; color: #9f1239;">Rust</span>
+        </div>
+    </div>
+</div>
+HTML;
+
+$png = HtmlShot::render($html, [
+    'width' => 1280,
+    'height' => 640,
+    'format' => 'png',
+    'fonts' => [
+        Font::fromFile("{$fontsPath}/Geist/variable/Geist[wght].ttf", 'Geist'),
+        Font::fromFile("{$fontsPath}/GeistMono/variable/GeistMono[wght].ttf", 'Geist Mono'),
+    ],
+]);
+
+save_to_output($png, 'htmlshot.png', $outputDir);
diff --git a/examples/htmlshot/output/htmlshot.png b/examples/htmlshot/output/htmlshot.png
new file mode 100644
index 0000000..1c632ee
Binary files /dev/null and b/examples/htmlshot/output/htmlshot.png differ
diff --git a/examples/line-chart/line-chart.php b/examples/line-chart/line-chart.php
new file mode 100644
index 0000000..a0ca65a
--- /dev/null
+++ b/examples/line-chart/line-chart.php
@@ -0,0 +1,120 @@
+<?php
+
+/**
+ * Line chart with a dither effect.
+ *
+ * The chart geometry (area fill, line, point markers) is drawn with an inline
+ * SVG whose points are computed from a data array. Title and axis labels are
+ * HTML laid over the same 1200x630 coordinate space, on top of a smooth
+ * gradient background.
+ *
+ * Usage:
+ *   php examples/line-chart/line-chart.php
+ */
+
+require __DIR__.'/../common.php';
+
+use HtmlShot\Font;
+use HtmlShot\HtmlShot;
+
+$outputDir = __DIR__.'/output';
+
+// ── Data ─────────────────────────────────────────────────────────────────────
+$months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+$data = [12, 19, 15, 27, 24, 38, 35, 49, 52, 47, 63, 71]; // renders, in thousands
+$gridValues = [0, 20, 40, 60, 80];
+$maxScale = 80;
+
+// ── Plot geometry (matches the 1200x630 canvas) ──────────────────────────────
+$W = 1200;
+$H = 630;
+$plotL = 90;
+$plotR = 1140;
+$plotT = 150;
+$plotB = 540;
+$plotW = $plotR - $plotL;
+$plotH = $plotB - $plotT;
+
+$n = count($data);
+$x = static fn (int $i): float => $plotL + $plotW * $i / ($n - 1);
+$y = static fn (float $v): float => $plotB - $plotH * ($v / $maxScale);
+
+// Point list for the line + area path.
+$points = [];
+for ($i = 0; $i < $n; $i++) {
+    $points[] = round($x($i), 1).','.round($y($data[$i]), 1);
+}
+$polyline = implode(' ', $points);
+$areaPath = "M {$plotL},{$plotB} L ".implode(' L ', $points)." L {$plotR},{$plotB} Z";
+
+// Horizontal grid lines.
+$grid = '';
+foreach ($gridValues as $v) {
+    $gy = round($y($v), 1);
+    $grid .= "<line x1=\"{$plotL}\" y1=\"{$gy}\" x2=\"{$plotR}\" y2=\"{$gy}\" stroke=\"#262e4d\" stroke-width=\"1\" />";
+}
+
+// Point markers.
+$markers = '';
+for ($i = 0; $i < $n; $i++) {
+    $cx = round($x($i), 1);
+    $cy = round($y($data[$i]), 1);
+    $markers .= "<circle cx=\"{$cx}\" cy=\"{$cy}\" r=\"5\" fill=\"#0b1020\" stroke=\"#9db4ff\" stroke-width=\"3\" />";
+}
+
+$svg = <<<SVG
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {$W} {$H}" width="{$W}" height="{$H}">
+    <defs>
+        <linearGradient id="area" x1="0" y1="0" x2="0" y2="1">
+            <stop offset="0" stop-color="#7c93ff" stop-opacity="0.55" />
+            <stop offset="1" stop-color="#7c93ff" stop-opacity="0.02" />
+        </linearGradient>
+    </defs>
+    {$grid}
+    <path d="{$areaPath}" fill="url(#area)" />
+    <polyline points="{$polyline}" fill="none" stroke="#9db4ff" stroke-width="4"
+              stroke-linejoin="round" stroke-linecap="round" />
+    {$markers}
+</svg>
+SVG;
+
+// ── Axis labels positioned over the same coordinate space ────────────────────
+$yLabels = '';
+foreach ($gridValues as $v) {
+    $top = round($y($v) - 13, 1);
+    $yLabels .= "<span style=\"position: absolute; left: 0; top: {$top}px; width: 66px;
+                 text-align: right; font-size: 20px; color: #6b7399;\">{$v}k</span>";
+}
+$xLabels = '';
+for ($i = 0; $i < $n; $i++) {
+    $left = round($x($i) - 40, 1);
+    $xLabels .= "<span style=\"position: absolute; left: {$left}px; top: 552px; width: 80px;
+                 text-align: center; font-size: 20px; color: #6b7399;\">{$months[$i]}</span>";
+}
+
+$html = <<<HTML
+<div style="position: relative; display: flex; width: 100%; height: 100%; font-family: Geist;
+            background-image: linear-gradient(160deg, #0b1020 0%, #161d3a 55%, #20284b 100%);">
+
+    <span style="position: absolute; left: 90px; top: 50px; font-size: 36px; font-weight: 700;
+                 color: #f4f6ff; letter-spacing: -0.01em;">Monthly active renders</span>
+    <span style="position: absolute; left: 90px; top: 100px; font-size: 22px; color: #8b93b5;">
+        2026 · in thousands
+    </span>
+
+    {$svg}
+    {$yLabels}
+    {$xLabels}
+</div>
+HTML;
+
+$png = HtmlShot::render($html, [
+    'width' => $W,
+    'height' => $H,
+    'format' => 'png',
+    'fonts' => [
+        Font::fromFile("{$fontsPath}/Geist/variable/Geist[wght].ttf", 'Geist'),
+    ],
+]);
+
+save_to_output($png, 'line-chart.png', $outputDir);
diff --git a/examples/line-chart/output/line-chart.png b/examples/line-chart/output/line-chart.png
new file mode 100644
index 0000000..464b495
Binary files /dev/null and b/examples/line-chart/output/line-chart.png differ
diff --git a/examples/quote/output/quote.png b/examples/quote/output/quote.png
new file mode 100644
index 0000000..4eeeebd
Binary files /dev/null and b/examples/quote/output/quote.png differ
diff --git a/examples/quote/quote.php b/examples/quote/quote.php
new file mode 100644
index 0000000..5caa51e
--- /dev/null
+++ b/examples/quote/quote.php
@@ -0,0 +1,64 @@
+<?php
+
+/**
+ * Pull-quote card
+ *
+ * PHP port of https://takumi.kane.tw/docs/templates#quote-template
+ *
+ * Usage:
+ *   php examples/templates/quote.php
+ */
+
+require __DIR__.'/../common.php';
+
+use HtmlShot\Font;
+use HtmlShot\HtmlShot;
+
+$outputDir = __DIR__.'/output';
+
+// The quote and attribution below are invented for this example — they are
+// fictional and not a real testimonial from any person or company.
+$quote = 'We swapped a whole headless-browser farm for a single PHP call.';
+$author = 'Claude';
+$role = 'AI Assistant';
+$company = 'Code Company';
+
+$ink = '#16140F';
+$muted = '#6E6A60';
+$accent = '#E5341F';
+
+$html = <<<HTML
+<div style="display: flex; flex-direction: column; width: 100%; height: 100%;
+            background-color: #F5F3EC; color: {$ink}; padding: 80px 76px;
+            font-family: Geist; justify-content: center;">
+
+    <span style="display: flex; height: 72px; margin-left: -8px; margin-bottom: 8px;
+                 font-size: 180px; line-height: 1; font-weight: 700; color: {$accent};">
+        &ldquo;
+    </span>
+
+    <h1 style="display: flex; font-size: 64px; font-weight: 700; line-height: 1.12;
+               letter-spacing: -0.02em; margin: 0; margin-bottom: 48px; max-width: 1000px; color: {$ink};">
+        {$quote}
+    </h1>
+
+    <div style="display: flex; align-items: center; gap: 12px;">
+        <span style="display: flex; font-size: 28px; font-weight: 700; color: {$ink};">{$author}</span>
+        <span style="display: flex; font-size: 28px; color: {$muted};">·</span>
+        <span style="display: flex; font-size: 28px; color: {$muted};">{$role}</span>
+        <span style="display: flex; font-size: 28px; color: {$muted};">·</span>
+        <span style="display: flex; font-size: 28px; color: {$muted};">{$company}</span>
+    </div>
+</div>
+HTML;
+
+$png = HtmlShot::render($html, [
+    'width' => 1200,
+    'height' => 630,
+    'format' => 'png',
+    'fonts' => [
+        Font::fromFile("{$fontsPath}/Geist/variable/Geist[wght].ttf", 'Geist'),
+    ],
+]);
+
+save_to_output($png, 'quote.png', $outputDir);
diff --git a/examples/regenerate.php b/examples/regenerate.php
new file mode 100644
index 0000000..3e16a78
--- /dev/null
+++ b/examples/regenerate.php
@@ -0,0 +1,70 @@
+<?php
+
+/**
+ * Regenerate every example image.
+ *
+ * Discovers each example script (examples/<name>/<name>.php) and runs it in its
+ * own PHP process with shell_exec, so a single failing example can't abort the
+ * rest of the batch. The helper (common.php) and the diagnostic (debug.php) at
+ * the top level are skipped.
+ *
+ * Usage:
+ *   php examples/regenerate.php
+ */
+$examplesDir = __DIR__;
+
+// Collect runnable example scripts: one level deep, examples/<dir>/*.php.
+$scripts = [];
+foreach (glob($examplesDir.'/*', GLOB_ONLYDIR) as $dir) {
+    foreach (glob($dir.'/*.php') as $script) {
+        $scripts[] = $script;
+    }
+}
+sort($scripts);
+
+if ($scripts === []) {
+    fwrite(STDERR, "No example scripts found under {$examplesDir}.\n");
+    exit(1);
+}
+
+$php = escapeshellarg(PHP_BINARY);
+$failures = [];
+$saved = 0;
+$start = microtime(true);
+
+echo 'Regenerating '.count($scripts)." examples...\n\n";
+
+foreach ($scripts as $script) {
+    $rel = str_replace('\\', '/', substr($script, strlen($examplesDir) + 1));
+    echo "==> {$rel}\n";
+
+    $t0 = microtime(true);
+    // Run the example and capture stdout + stderr together.
+    $output = (string) shell_exec($php.' '.escapeshellarg($script).' 2>&1');
+    $ms = (int) round((microtime(true) - $t0) * 1000);
+
+    foreach (explode("\n", rtrim($output)) as $line) {
+        if (trim($line) !== '') {
+            echo "    {$line}\n";
+        }
+    }
+
+    $saved += substr_count($output, 'Saved:');
+
+    // Treat PHP-level errors as failures; warnings/notices are reported but pass.
+    if (preg_match('/(Fatal error|Uncaught|Parse error)/i', $output)) {
+        $failures[] = $rel;
+        echo "    [FAIL] in {$ms}ms\n\n";
+    } else {
+        echo "    [ok] {$ms}ms\n\n";
+    }
+}
+
+$elapsed = number_format(microtime(true) - $start, 1);
+echo str_repeat('-', 48)."\n";
+echo count($scripts)." scripts, {$saved} images, ".count($failures)." failed in {$elapsed}s\n";
+
+if ($failures !== []) {
+    echo 'Failed: '.implode(', ', $failures)."\n";
+    exit(1);
+}
diff --git a/examples/repository/output/repository.png b/examples/repository/output/repository.png
new file mode 100644
index 0000000..04836d6
Binary files /dev/null and b/examples/repository/output/repository.png differ
diff --git a/examples/repository/repository.php b/examples/repository/repository.php
new file mode 100644
index 0000000..b18b9a4
--- /dev/null
+++ b/examples/repository/repository.php
@@ -0,0 +1,81 @@
+<?php
+
+/**
+ * GitHub repository card
+ *
+ * PHP port of https://takumi.kane.tw/docs/templates#repository-template
+ *
+ * Usage:
+ *   php examples/templates/repository.php
+ */
+
+require __DIR__.'/../common.php';
+
+use HtmlShot\Font;
+use HtmlShot\HtmlShot;
+
+$outputDir = __DIR__.'/output';
+
+$owner = 'avvertix';
+$name = 'html-shot';
+$description = 'HTML to image rendering for PHP. Generate OG image with native PHP.';
+$stars = '0';
+$forks = '0';
+
+$ink = '#16140F';
+$muted = '#6E6A60';
+$mono = "'Geist Mono', monospace";
+
+$html = <<<HTML
+<div style="display: flex; flex-direction: column; width: 100%; height: 100%;
+            background-color: #F5F3EC; color: {$ink}; padding: 80px 76px;
+            font-family: Geist; justify-content: center;">
+
+    <span style="display: flex; font-size: 40px; font-weight: 500; font-family: {$mono};
+                 color: {$muted}; letter-spacing: -0.01em;">
+        {$owner}/
+    </span>
+    <span style="display: flex; font-size: 132px; font-weight: 700; font-family: {$mono};
+                 color: {$ink}; line-height: 0.96; letter-spacing: -0.045em; margin-top: 4px;">
+        {$name}
+    </span>
+    <span style="display: flex; font-size: 32px; font-weight: 400; color: #37352F;
+                 line-height: 1.36; max-width: 920px; margin-top: 32px;">
+        {$description}
+    </span>
+
+    <div style="display: flex; align-items: center; gap: 16px; margin-top: 44px;">
+        <div style="display: flex; align-items: baseline; gap: 8px;">
+            <span style="display: flex; font-size: 28px; font-weight: 700; color: {$ink};">{$stars}</span>
+            <span style="display: flex; font-size: 28px; color: {$muted};">stars</span>
+        </div>
+        <span style="display: flex; font-size: 28px; color: {$muted};">·</span>
+        <div style="display: flex; align-items: baseline; gap: 8px;">
+            <span style="display: flex; font-size: 28px; font-weight: 700; color: {$ink};">{$forks}</span>
+            <span style="display: flex; font-size: 28px; color: {$muted};">forks</span>
+        </div>
+        <span style="display: flex; font-size: 28px; color: {$muted};">·</span>
+        <div style="display: flex; align-items: center; gap: 12px;">
+            <div style="display: flex; width: 20px; height: 20px; border-radius: 50%;
+                        background-color: #5b21b6;"></div>
+            <span style="display: flex; font-size: 28px; font-weight: 600; color: #5b21b6;">PHP</span>
+            +
+            <div style="display: flex; width: 20px; height: 20px; border-radius: 50%;
+                        background-color: #9f1239;"></div>
+            <span style="display: flex; font-size: 28px; font-weight: 600; color: #9f1239;">Rust</span>
+        </div>
+    </div>
+</div>
+HTML;
+
+$png = HtmlShot::render($html, [
+    'width' => 1200,
+    'height' => 630,
+    'format' => 'png',
+    'fonts' => [
+        Font::fromFile("{$fontsPath}/Geist/variable/Geist[wght].ttf", 'Geist'),
+        Font::fromFile("{$fontsPath}/GeistMono/variable/GeistMono[wght].ttf", 'Geist Mono'),
+    ],
+]);
+
+save_to_output($png, 'repository.png', $outputDir);
diff --git a/examples/simple/output/simple.png b/examples/simple/output/simple.png
new file mode 100644
index 0000000..029a9b7
Binary files /dev/null and b/examples/simple/output/simple.png differ
diff --git a/examples/simple/simple.php b/examples/simple/simple.php
new file mode 100644
index 0000000..66de863
--- /dev/null
+++ b/examples/simple/simple.php
@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * Render a simple text in the middle of the canvas
+ *
+ * Usage:
+ *   php examples/simple/simple.php
+ */
+
+require __DIR__.'/../common.php';
+
+use HtmlShot\Font;
+use HtmlShot\HtmlShot;
+
+$outputDir = __DIR__.'/output';
+
+$html = '<div style="display:flex; justify-content: center; align-items: center; width:100%; height:100%; font-family:Geist; font-size:100px; font-weight:900; color: #000; background: #ecfeff">That was fast!</div>';
+
+$png = HtmlShot::render($html, [
+    'width' => 1280,
+    'height' => 630,
+    'format' => 'png',
+    'fonts' => [
+        Font::fromFile("{$fontsPath}/Geist/variable/Geist[wght].ttf", 'Geist'),
+    ],
+]);
+
+save_to_output($png, 'simple.png', $outputDir);
diff --git a/examples/stars/output/stars.png b/examples/stars/output/stars.png
new file mode 100644
index 0000000..6134b0c
Binary files /dev/null and b/examples/stars/output/stars.png differ
diff --git a/examples/stars/stars.php b/examples/stars/stars.php
new file mode 100644
index 0000000..f313a2a
--- /dev/null
+++ b/examples/stars/stars.php
@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * Render a GitHub repo stars counter
+ *
+ * Usage:
+ *   php examples/stars/stars.php
+ */
+
+require __DIR__.'/../common.php';
+
+use HtmlShot\Font;
+use HtmlShot\HtmlShot;
+
+$outputDir = __DIR__.'/output';
+
+$star = $assetsImages.'/golden-star-disco-ball.png';
+
+$html = <<<HTML
+<div tw="flex h-full w-full flex-col items-center justify-end bg-taupe-800 p-20">
+    <div tw="absolute h-full w-full text-center">
+        <img src="{$star}" alt="" tw="h-full ">
+    </div>
+    <div tw="flex flex-col ">
+        <h1 tw="text-shadow-lg m-0 text-[12em] font-bold leading-none tracking-tighter text-white">zero stars</h1>
+    </div>
+</div>
+HTML;
+
+$png = HtmlShot::render($html, [
+    'width' => 1280,
+    'height' => 630,
+    'format' => 'png',
+    'fonts' => [
+        Font::fromFile("{$fontsPath}/Geist/variable/Geist[wght].ttf", 'Geist'),
+    ],
+]);
+
+save_to_output($png, 'stars.png', $outputDir);
diff --git a/examples/tailwind/output/tailwind.png b/examples/tailwind/output/tailwind.png
new file mode 100644
index 0000000..5caf5fc
Binary files /dev/null and b/examples/tailwind/output/tailwind.png differ
diff --git a/examples/tailwind/tailwind.php b/examples/tailwind/tailwind.php
new file mode 100644
index 0000000..925b2cb
--- /dev/null
+++ b/examples/tailwind/tailwind.php
@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * Render a simple text in the middle of the canvas
+ *
+ * Usage:
+ *   php examples/tailwind/tailwind.php
+ */
+
+require __DIR__.'/../common.php';
+
+use HtmlShot\Font;
+use HtmlShot\HtmlShot;
+
+$outputDir = __DIR__.'/output';
+
+$html = <<<'HTML'
+<div tw="flex h-full w-full flex-col justify-end bg-[#16130f] p-20">
+    <div tw="flex flex-col">
+        <h1 tw="m-0 text-8xl font-bold leading-none tracking-tighter text-white">HtmlShot.</h1>
+        <h2 tw="m-0 mt-2 text-8xl font-bold leading-none tracking-tighter text-[#3b82f6]">html in, image out</h2>
+        <p tw="mb-0 mt-10 text-3xl text-[#a8a29a]">HTML to image rendering for PHP, powered by Rust.</p>
+    </div>
+</div>
+HTML;
+
+$png = HtmlShot::render($html, [
+    'width' => 1280,
+    'height' => 630,
+    'format' => 'png',
+    'fonts' => [
+        Font::fromFile("{$fontsPath}/Geist/variable/Geist[wght].ttf", 'Geist'),
+    ],
+]);
+
+save_to_output($png, 'tailwind.png', $outputDir);
diff --git a/tests/fonts/README.md b/tests/fonts/README.md
new file mode 100644
index 0000000..fd6791a
--- /dev/null
+++ b/tests/fonts/README.md
@@ -0,0 +1,5 @@
+# Geist Font
+
+The [Geist font](https://vercel.com/font) is included so that testa and [examples](../../examples/) can be tried without external dependencies.
+
+If you want to use Geist in your project, you should not rely on this font file being present when the package is installed via Composer.
\ No newline at end of file