docs: add image guide to docs example

Author: JoviDeCroock

.changeset/pracht-image-package.md

@@ -14,4 +14,5 @@ exports `createImageHandler()`, a sharp-backed optimization endpoint (sharp is
 an optional peer dependency) mounted as the `src/api/_pracht/image.ts` API
 route: it negotiates WebP/AVIF via `Accept`, only serves allowlisted widths,
 restricts sources to same-origin unless `remotePatterns` opts hosts in, and
-answers with immutable cache headers. See docs/IMAGES.md.
+stream-enforces the source image size cap before optimization. Answers with
+immutable cache headers. See docs/IMAGES.md.

examples/docs/src/routes.ts

@@ -51,6 +51,10 @@ export const app = defineApp({
         id: "styling",
         render: "ssg",
       }),
+      route("/docs/images", () => import("./routes/docs/images.md"), {
+        id: "images",
+        render: "ssg",
+      }),
       route("/docs/cli", () => import("./routes/docs/cli.md"), {
         id: "cli",
         render: "ssg",

examples/docs/src/routes/docs/cli.md

@@ -3,8 +3,8 @@ title: CLI
 lead: The <code>@pracht/cli</code> package provides development, build, scaffolding, and doctor commands for your app.
 breadcrumb: CLI
 prev:
-  href: /docs/styling
-  title: Styling
+  href: /docs/images
+  title: Images
 next:
   href: /docs/deployment
   title: Deployment

examples/docs/src/routes/docs/images.md

@@ -0,0 +1,142 @@
+---
+title: Images
+lead: Use <code>@pracht/image</code> for responsive image markup, reserved layout space, and deployment-specific optimization loaders.
+breadcrumb: Images
+prev:
+  href: /docs/styling
+  title: Styling
+next:
+  href: /docs/cli
+  title: CLI
+---
+
+## Install
+
+```sh
+pnpm add @pracht/image
+
+# Only needed when you use the built-in Node optimization endpoint.
+pnpm add sharp
+```
+
+`@pracht/image` is split into a framework-agnostic component entry and a Node endpoint entry. Import the component from `@pracht/image`; import the optimization handler from `@pracht/image/node`.
+
+---
+
+## Render an Image
+
+```tsx [src/routes/gallery.tsx]
+import { Image } from "@pracht/image";
+
+export function Component() {
+  return (
+    <Image
+      src="/banner.jpg"
+      alt="Pracht banner"
+      width={1200}
+      height={280}
+      sizes="(max-width: 1200px) 100vw, 1200px"
+      priority
+    />
+  );
+}
+```
+
+The component renders plain `<img>` markup, so it works during SSR and SSG without adding client runtime. `loading="lazy"` and `decoding="async"` are the defaults. Use `priority` for above-the-fold images; it switches the image to eager loading and adds `fetchpriority="high"`.
+
+Always provide meaningful `alt` text, or `alt=""` for decorative images.
+
+---
+
+## Reserve Layout Space
+
+Images need either intrinsic dimensions or `fill`:
+
+```tsx
+<Image src="/card.jpg" alt="Product preview" width={640} height={360} />
+```
+
+For background-style images, use `fill` inside a positioned parent:
+
+```tsx
+<div style={{ position: "relative", height: "18rem" }}>
+  <Image
+    src="/hero.jpg"
+    alt="Pracht docs hero"
+    fill
+    sizes="100vw"
+    style={{ objectFit: "cover" }}
+  />
+</div>
+```
+
+`fill` images stretch with `position: absolute; inset: 0`. The parent controls the rendered size, so give the parent a stable height or aspect ratio.
+
+---
+
+## Mount the Default Endpoint
+
+The default loader points at `/api/_pracht/image`. Add an API route at that path to resize and encode same-origin source images with `sharp`:
+
+```ts [src/api/_pracht/image.ts]
+import { createImageHandler } from "@pracht/image/node";
+
+export const GET = createImageHandler();
+```
+
+This endpoint works in `pracht dev`, adapter-node, and Node-compatible runtimes. It returns immutable cache headers, varies on `Accept`, and negotiates modern output formats such as WebP.
+
+---
+
+## Configure Loaders
+
+Loaders turn `{ src, width, quality }` into a URL. Configure one globally when your deployment platform should serve image variants:
+
+```ts [src/routes.ts]
+import { cloudflareLoader, configureImage } from "@pracht/image";
+
+configureImage({
+  loader: cloudflareLoader,
+  quality: 75,
+});
+```
+
+| Loader | Best For |
+| ------ | -------- |
+| `defaultLoader` | The `/api/_pracht/image` endpoint |
+| `cloudflareLoader` | Cloudflare Image Resizing |
+| `vercelLoader` | Vercel Image Optimization |
+| `passthroughLoader` | Static hosts without an image service |
+
+You can also pass a `loader` prop to a single `<Image>` when one image needs different handling.
+
+---
+
+## Remote Images
+
+The Node endpoint accepts same-origin URLs by default. Allow remote hosts explicitly:
+
+```ts [src/api/_pracht/image.ts]
+import { createImageHandler } from "@pracht/image/node";
+
+export const GET = createImageHandler({
+  remotePatterns: [
+    { protocol: "https", hostname: "images.example.com", pathname: "/uploads" },
+  ],
+});
+```
+
+Remote allowlists are rechecked after redirects. Widths are also restricted to configured breakpoints, which keeps attackers from filling your cache with arbitrary image variants.
+
+---
+
+## Platform Notes
+
+| Target | Recommendation |
+| ------ | -------------- |
+| Node | Mount `createImageHandler()` and use the default loader |
+| Cloudflare Workers | Use `cloudflareLoader`; `sharp` does not run in Workers |
+| Vercel | Use `vercelLoader` and keep Vercel image sizes aligned with your Pracht breakpoints |
+| Static hosting | Use `passthroughLoader` so images render without an optimization backend |
+
+See the `examples/basic` gallery route for a complete endpoint plus component example.

examples/docs/src/routes/docs/styling.md

@@ -6,8 +6,8 @@ prev:
   href: /docs/shells
   title: Shells
 next:
-  href: /docs/cli
-  title: CLI
+  href: /docs/images
+  title: Images
 ---
 
 ## Recommended Approaches

examples/docs/src/shells/docs.tsx

@@ -23,6 +23,7 @@ import {
   IconSparkles,
   IconPresentationAnalytics,
   IconActivity,
+  IconPhoto,
 } from "@tabler/icons-preact";
 import "../styles/global.css";
 
@@ -45,6 +46,7 @@ const NAV = [
       { href: "/docs/middleware", Icon: IconShield, title: "Middleware" },
       { href: "/docs/shells", Icon: IconLayout, title: "Shells" },
       { href: "/docs/styling", Icon: IconPalette, title: "Styling" },
+      { href: "/docs/images", Icon: IconPhoto, title: "Images" },
     ],
   },
   {

packages/image/src/node.ts

@@ -113,6 +113,36 @@ function matchesRemotePatterns(url: URL, patterns: RemotePattern[]): boolean {
   });
 }
 
+async function readCappedBody(response: Response, maxBytes: number): Promise<Uint8Array | null> {
+  if (!response.body) {
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      return null;
+    }
+    chunks.push(value);
+  }
+
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return body;
+}
+
 /**
  * Create the pracht image optimization endpoint.
  *
@@ -254,8 +284,8 @@ export function createImageHandler(
       return errorResponse(415, `Source "${source}" is not an image (got "${sourceType}").`);
     }
 
-    const sourceBytes = new Uint8Array(await upstream.arrayBuffer());
-    if (sourceBytes.byteLength > maxSourceBytes) {
+    const sourceBytes = await readCappedBody(upstream, maxSourceBytes);
+    if (sourceBytes == null) {
       return errorResponse(413, `Source image "${source}" exceeds ${maxSourceBytes} bytes.`);
     }
 

packages/image/test/node-handler.test.ts

@@ -218,6 +218,27 @@ describe("createImageHandler optimization", () => {
     expect(response.status).toBe(413);
   });
 
+  it("stops reading the source body after the size cap is exceeded", async () => {
+    let canceled = false;
+    const body = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        controller.enqueue(new Uint8Array(8));
+      },
+      cancel() {
+        canceled = true;
+      },
+    });
+    const handler = createImageHandler({
+      fetchImage: async () => new Response(body, { headers: { "content-type": "image/png" } }),
+      maxSourceBytes: 10,
+    });
+
+    const response = await handler(imageRequest("url=%2Fhero.png&w=640"));
+
+    expect(response.status).toBe(413);
+    expect(canceled).toBe(true);
+  });
+
   it("explains how to install sharp when it is missing", async () => {
     const handler = createImageHandler({
       fetchImage: pngFetcher(),