@nomideusz/svelte-media 0.3.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,128 @@
 # Changelog
 
+## 0.6.0 — 2026-08-14
+
+Second pass of the same job 0.5.0 started: the parts of "handling images" both
+apps still owned move here, so an app keeps only what is actually its own —
+bucket names, copy, and (for yoga) what a Google Places reference costs.
+
+### Added
+- **`adapterFromEnv(env, options?)`** — the S3_*/`MEDIA_ROOT` wiring both apps
+  had hand-written, including the lazy singleton each carried. Reads
+  `S3_ENDPOINT` / `S3_REGION` / `S3_BUCKET` / `S3_ACCESS_KEY_ID` /
+  `S3_SECRET_ACCESS_KEY`, falls back to a local adapter on `MEDIA_ROOT`, and
+  otherwise throws naming what is missing — a media surface that silently
+  no-ops is worse than a boot failure. Memoized per resolved config, so
+  per-request calls reuse one client and its signed-URL cache. Takes any
+  `Record<string, string | undefined>`, so no `$env` import enters the package.
+- **`cachedImage(adapter, key, produce, options?)`** and
+  **`store.cached(...)`** — bucket-as-cache in front of a remote image source.
+  Stored copy first (the producer is never called on a hit), one producer call
+  per stampede, immutable headers, `onStoreError` for the write that would
+  otherwise silently make you pay twice. Extracted from yoga's Google Places
+  hero proxy, which had grown all of it inline.
+- **`fetchImage(url, options?)`** — GET an image from a remote URL, rejecting
+  failed and non-image responses (an error page's HTML must never land in the
+  cache as a photo), transcoded to WebP by default.
+- **`toWebp(bytes, quality?)`** — the transcode on its own; returns the input
+  untouched when sharp cannot read it, because an optimisation must never lose
+  an image you already hold.
+- **`store.resolveUrl(key, size?, expiresIn?)`** + `basePath` on
+  `MediaStoreConfig` — presigned when the adapter can sign, else
+  `basePath/<variant key>` for the same-origin route. thebest had this fallback
+  written by hand across two modules.
+- **`DeriveSource` gains `prefix` and `entityId`** (additive), so a `derive`
+  hook and its `onDeriveError` can name the entity they failed on. yoga was
+  closing over the id to log it.
+
+### Fixed
+- **`getStorageKey` rejects filenames containing `/`, `\\` or `..`.** Filenames
+  are generated, but they round-trip through DB rows and form fields before
+  coming back to be deleted — thebest's delete action passes one straight from
+  `formData`, so a crafted value reached outside the entity's own folder.
+  `serveMedia` already guarded the read path; this is the write/delete one.
+
+### Changed
+- `ImageBytes.body` is `Uint8Array<ArrayBuffer>` — the concrete view `Response`
+  and `Blob` accept.
+- README caught up with 0.5.0: `get()` on the adapter interface, `serveMedia`,
+  `createMediaStore`, `getSignedUrl`.
+
+### Adopted by the apps
+- yoga: `photo-storage.ts` is now bucket names + Polish copy + the placeholder
+  hook (−40 lines); `/api/photo` keeps the Google policy (budget guard, ref
+  self-heal, negative caches) and nothing else (−60 lines, no more sharp, no
+  more hand-rolled in-flight map).
+- thebest: `media.ts` + `image-urls.ts` lost the adapter singleton, the
+  presign-or-fallback branch and the split-brain addressing; the tour upload
+  action no longer re-states the 15 MB limit it shares with `MEDIA_CONFIG`.
+
+## 0.5.0 — 2026-08-09
+
+### Added
+- **The read half of the pipeline.** `StorageAdapter` gains
+  `get(key): Promise<StorageObject | null>` (null = not found; real failures
+  reject), implemented by both adapters. Every deployment of this package was
+  serving from a private bucket, and both source apps had built parallel raw
+  S3 clients — three across the two apps — to work around the adapter being
+  write-only.
+- **`getSignedUrl(key, expiresIn?)` on the S3 adapter** (the `S3Adapter`
+  type), with expiry-buffered caching and in-flight dedupe — absorbed from
+  thebest's hand-rolled presign layer. This is what the previously-dead
+  `@aws-sdk/s3-request-presigner` dependency is now for.
+- **`serveMedia(adapter, key): Promise<Response>`** — the whole body of a
+  same-origin `/photos/[...key]`-style route: key validation (incl. `..`
+  traversal — one app's hand-written copy lacked the check), 404 on missing,
+  immutable cache headers.
+- **`createMediaStore({ adapter, ...limits, derive? })`** — the per-app
+  binding factory both apps had hand-built (`photo-storage.ts`, `media.ts`),
+  returning bound `store/remove/get/serve/url/signedUrl/validate`. Env reading
+  stays in the app; the adapter is the seam.
+
+### Changed
+- **Breaking for external adapter implementations:** `get` is now a required
+  `StorageAdapter` method. (Both in-repo apps consume the built-in adapters.)
+- `S3Config.publicUrl` is now optional — both real deployments serve private
+  buckets and were passing dummy values to satisfy the field. `getUrl()`
+  throws without it.
+
+## 0.4.0 — 2026-08-09
+
+### Added
+- **`SIZE_PREFIXES` and `SIZE_QUALITY` are now exported** (root and `/server`).
+  Both source apps had re-copied the prefix table by hand (one script copied the
+  quality values too) because the package kept them private — and the README had
+  already drifted from the code once (`lg_` vs `large_`). The variant naming is a
+  cross-app contract; now it has one home.
+- **Joined-key helpers** for apps that persist the single original key rather
+  than the (prefix, entityId, filename) triple: `variantKey(key, size)`,
+  `parseStorageKey(key)` (null for keys that don't fit the layout, e.g. legacy
+  ids), and `deleteMediaByKey(adapter, key)` on `/server`. Also
+  `sizeForWidth(width?)` — the smallest pre-generated variant that still fills a
+  display width (moved in from yoga's hand-rolled copy).
+- **Machine-readable validation.** `ValidationResult` gains
+  `code: 'empty' | 'file-too-large' | 'invalid-type'` plus `maxBytes` /
+  `allowedTypes`, and `processAndStore` now throws a typed
+  `MediaValidationError` carrying them — so a PL/EN/UK app maps `code` to its
+  own copy instead of surfacing the English `message`. Both apps had
+  re-implemented validation in 4 places purely to localize the strings.
+  The `empty` code also covers the zero-byte file every form action was
+  checking by hand.
+
+### Fixed
+- `ImageUpload`'s declared `config` prop was never read, so the client-side
+  pre-validation it implied never ran. It now validates each file before
+  `onUpload` and routes failures to `onError`.
+- README documented the large-variant prefix as `lg_`; the code writes
+  `large_`.
+
+### Changed
+- `generateMediaKey()` no longer takes the ignored `originalName` parameter.
+- The dead duplicate `DEFAULT_MAX_SIZE`/`DEFAULT_ALLOWED_TYPES` constants and
+  the unused `MediaValidation`/`MediaValidationOk` types in `core/types.ts` are
+  gone. (`MediaValidationError` is now the thrown error class instead of an
+  unused interface — technically a change to `/server`'s type surface.)
+
 ## 0.3.0 — 2026-08-03
 
 ### Added

package/README.md

@@ -1,5 +1,7 @@
 # @nomideusz/svelte-media
 
+[![npm](https://badgen.net/npm/v/@nomideusz/svelte-media)](https://www.npmjs.com/package/@nomideusz/svelte-media) [![license](https://badgen.net/badge/license/MIT/blue)](https://github.com/nomideusz/svelte-media/blob/main/LICENSE)
+
 Image upload, resizing and multi-size storage for Svelte 5 apps. One call takes
 a `File`, validates it, renders four sizes with sharp, and writes them through a
 pluggable storage adapter — S3-compatible or local disk.
@@ -32,25 +34,37 @@ the seam.
 
 ## Quick Start
 
+Bind the pipeline once per app, then call it from anywhere:
+
 ```ts
-import { createS3Adapter, processAndStore, getMediaUrl } from '@nomideusz/svelte-media/server';
-
-const storage = createS3Adapter({
-  endpoint:        process.env.S3_ENDPOINT!,     // https://xxx.r2.cloudflarestorage.com
-  region:          'auto',                        // 'auto' for R2, 'us-east-1' for AWS
-  bucket:          process.env.S3_BUCKET!,
-  accessKeyId:     process.env.S3_KEY!,
-  secretAccessKey: process.env.S3_SECRET!,
-  publicUrl:       process.env.S3_PUBLIC_URL!,   // https://pub-xxx.r2.dev
-  forcePathStyle:  true,                          // true for MinIO/R2, false for Railway/AWS
-});
+// lib/server/media.ts
+import { adapterFromEnv, createMediaStore } from '@nomideusz/svelte-media/server';
+
+export const media = () =>
+  createMediaStore({
+    adapter: adapterFromEnv(process.env, { forcePathStyle: false }),
+    basePath: '/api/images',          // your same-origin serving route
+    maxFileSize: 15 * 1024 * 1024,
+  });
+```
+
+`adapterFromEnv` reads `S3_ENDPOINT` / `S3_REGION` / `S3_BUCKET` /
+`S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY`, falls back to local files when only
+`MEDIA_ROOT` is set, and throws naming what is missing otherwise. It memoizes
+per config, so calling it every request reuses one client (and its signed-URL
+cache). Pass any `{ [key]: string | undefined }` — SvelteKit's
+`$env/dynamic/private` works as-is.
 
-const stored = await processAndStore(storage, file, 'tours', tourId);
+```ts
+const stored = await media().store(file, 'tours', tourId);
 // { filename, originalName, prefix, entityId, sizes: { original, thumbnail, medium, large } }
 
-const src = getMediaUrl(storage, stored.prefix, stored.entityId, stored.filename, 'medium');
+const src = await media().resolveUrl(stored.sizes.original, 'medium');
 ```
 
+Prefer the lower-level `createS3Adapter` / `processAndStore` when you want the
+adapter built from something other than env vars.
+
 Store `stored` on your row — the helpers below all take
 `(prefix, entityId, filename)`, so keep those three. Nothing in the package
 touches a database.
@@ -93,7 +107,7 @@ from the callback's return type.
 | `original` | unchanged | — | *(none)* |
 | `thumbnail` | 300×300 | `cover` | `thumb_` |
 | `medium` | 800×600 | `inside` | `med_` |
-| `large` | 1200×900 | `inside` | `lg_` |
+| `large` | 1200×900 | `inside` | `large_` |
 
 `cover` crops to fill; `inside` fits within the box and preserves aspect ratio,
 so `medium` and `large` are upper bounds rather than exact dimensions. The table
@@ -101,25 +115,32 @@ is exported as `IMAGE_SIZES`.
 
 ## Storage adapters
 
-The seam is three methods:
+The seam is four methods:
 
 ```ts
 interface StorageAdapter {
   put(key: string, buffer: Buffer, contentType: string): Promise<void>;
+  get(key: string): Promise<StorageObject | null>;   // null = missing; rejects on real failures
   delete(key: string): Promise<void>;
-  getUrl(key: string): string;
+  getUrl(key: string): string;                       // throws without a publicUrl
 }
 ```
 
-Two ship with the package:
+Two ship with the package, plus the env-driven picker:
 
 ```ts
-import { createS3Adapter, createLocalAdapter } from '@nomideusz/svelte-media/server';
+import {
+  adapterFromEnv, createS3Adapter, createLocalAdapter,
+} from '@nomideusz/svelte-media/server';
 
-createS3Adapter({ /* S3Config, above */ });   // R2, MinIO, Tigris, AWS
+adapterFromEnv(process.env, { bucket: 'photos', region: 'garage' }); // S3, else MEDIA_ROOT
+createS3Adapter({ /* S3Config, above */ });   // R2, MinIO, Garage, Tigris, AWS
 createLocalAdapter({ root: '/data/images' }); // writes under root, mkdir -p
 ```
 
+`createS3Adapter` also returns `getSignedUrl(key, expiresIn?)` for private
+buckets, with expiry-buffered caching and in-flight dedupe.
+
 Anything satisfying the interface works — write your own for a CDN or a test
 double.
 
@@ -150,8 +171,51 @@ import { deleteMedia } from '@nomideusz/svelte-media/server';
 await deleteMedia(storage, stored.prefix, stored.entityId, stored.filename);
 ```
 
+## Serving
+
+A same-origin route is the whole of `serveMedia` — key validation (including
+`..` traversal), 404 on missing, immutable cache headers:
+
+```ts
+// routes/photos/[...key]/+server.ts
+export const GET = ({ params }) => media().serve(params.key);
+```
+
+`store.resolveUrl(key, size?)` picks the right URL for whichever storage you
+ended up with: a presigned URL when the adapter can sign, else
+`basePath/<variant key>` pointing at that route.
+
+## Caching remote images
+
+For images that come from somewhere else — a billed photo API, a partner CDN —
+`cached()` turns your bucket into the cache in front of it:
+
+```ts
+import { fetchImage } from '@nomideusz/svelte-media/server';
+
+const res = await media().cached(
+  `schools/${id}/hero.webp`,
+  () => fetchImage(`https://api.example/photo/${ref}`),   // only on a miss
+  { onStoreError: (e, key) => log.error(`write failed for ${key}`, e) },
+);
+if (!res) error(404, 'No photo');
+return res;
+```
+
+A stored copy is streamed without calling the producer at all; concurrent misses
+for one key share a single producer call, so a CDN stampede buys one copy rather
+than one per PoP. `fetchImage` rejects non-image and failed responses (an error
+page's HTML must never land in the cache as a photo) and transcodes to WebP —
+`toWebp` on its own does that half, returning the input untouched if sharp
+cannot read it.
+
 ## Components
 
+> **Demo-grade.** Both production apps built on this package hand-roll their
+> upload UI (multi-file queues, form-action submission, brand styling, i18n)
+> and import only the server half. Treat these as starters to copy from, not
+> primitives to build on.
+
 ```svelte
 <script lang="ts">
   import { ImageUpload, ImageGallery } from '@nomideusz/svelte-media';
@@ -188,10 +252,18 @@ the same reason: it renders on the client, where the adapter cannot go.
 
 ```ts
 // ── @nomideusz/svelte-media/server ──
-createS3Adapter(config: S3Config): StorageAdapter
+adapterFromEnv(env, options?): StorageAdapter            // S3_* / MEDIA_ROOT, memoized
+createS3Adapter(config: S3Config): S3Adapter
 createLocalAdapter(config: LocalConfig): StorageAdapter
+createMediaStore({ adapter, basePath?, ...limits, derive? }): MediaStore
+  // .store .remove .get .serve .url .signedUrl .resolveUrl .cached .validate
 processAndStore(adapter, file, prefix, entityId, config?): Promise<StoredMedia>
 deleteMedia(adapter, prefix, entityId, filename): Promise<void>
+deleteMediaByKey(adapter, key): Promise<void>            // joined original key
+serveMedia(adapter, key): Promise<Response>
+cachedImage(adapter, key, produce, options?): Promise<Response | null>
+fetchImage(url, options?): Promise<ImageBytes | null>
+toWebp(bytes, quality = 80): Promise<ImageBytes>
 getMediaUrl(adapter, prefix, entityId, filename, size = 'medium'): string
 
 // ── @nomideusz/svelte-media (client-safe) ──
@@ -204,8 +276,10 @@ ImageUpload, ImageGallery
 
 Key helpers are exported from both entries, so server code needs only one import.
 
-Types: `StorageAdapter`, `S3Config`, `LocalConfig`, `StoredMedia`, `ImageSize`,
-`MediaConfig`, `ValidationResult`.
+Types: `StorageAdapter`, `S3Adapter`, `StorageObject`, `S3Config`,
+`LocalConfig`, `MediaStore`, `MediaStoreConfig`, `StoredMedia`, `ImageSize`,
+`MediaConfig`, `ValidationResult`, `ValidationErrorCode`, `DeriveSource`,
+`ImageBytes`, `EnvAdapterOptions`.
 
 ## Development
 

package/dist/components/ImageUpload.svelte

@@ -1,8 +1,10 @@
-<script lang="ts">let {
+<script lang="ts">import { validateImageFile } from "../core/media.js";
+let {
   onUpload,
   onError,
   maxFiles = 1,
-  accept = "image/jpeg,image/png,image/webp"
+  accept = "image/jpeg,image/png,image/webp",
+  config
 } = $props();
 let dragging = $state(false);
 let uploading = $state(false);
@@ -12,6 +14,11 @@ async function handleFiles(files) {
   uploading = true;
   try {
     for (const file of Array.from(files).slice(0, maxFiles)) {
+      const validation = validateImageFile(file, config);
+      if (!validation.valid) {
+        onError?.(validation.error ?? "Invalid file");
+        continue;
+      }
       await onUpload(file);
     }
   } catch (e) {

package/dist/components/ImageUpload.svelte.d.ts

@@ -4,6 +4,7 @@ interface Props {
     onError?: (message: string) => void;
     maxFiles?: number;
     accept?: string;
+    /** Pre-validates each file before onUpload; failures go to onError. */
     config?: MediaConfig;
 }
 declare const ImageUpload: import("svelte").Component<Props, {}, "">;

package/dist/core/adapter.d.ts

@@ -1,2 +1,2 @@
-import type { S3Config, StorageAdapter } from './types.js';
-export declare function createS3Adapter(config: S3Config): StorageAdapter;
+import type { S3Adapter, S3Config } from './types.js';
+export declare function createS3Adapter(config: S3Config): S3Adapter;

package/dist/core/adapter.js

@@ -1,4 +1,8 @@
-import { S3Client, PutObjectCommand, DeleteObjectCommand, } from '@aws-sdk/client-s3';
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, } from '@aws-sdk/client-s3';
+import { getSignedUrl as presignGetObject } from '@aws-sdk/s3-request-presigner';
+// Refresh signed URLs a minute before they actually expire, so a URL handed to
+// a browser never dies mid-request.
+const SIGNED_TTL_BUFFER_MS = 60_000;
 export function createS3Adapter(config) {
     const client = new S3Client({
         endpoint: config.endpoint,
@@ -9,6 +13,9 @@ export function createS3Adapter(config) {
         },
         forcePathStyle: config.forcePathStyle ?? true,
     });
+    // ponytail: unbounded caches — media keys are a finite catalog; add LRU if that changes.
+    const signedCache = new Map();
+    const signedInflight = new Map();
     return {
         async put(key, buffer, contentType) {
             await client.send(new PutObjectCommand({
@@ -20,6 +27,27 @@ export function createS3Adapter(config) {
                 CacheControl: 'public, max-age=31536000, immutable',
             }));
         },
+        async get(key) {
+            let res;
+            try {
+                res = await client.send(new GetObjectCommand({ Bucket: config.bucket, Key: key }));
+            }
+            catch (e) {
+                const err = e;
+                if (err.name === 'NoSuchKey' || err.name === 'NotFound' || err.$metadata?.httpStatusCode === 404) {
+                    return null;
+                }
+                throw e;
+            }
+            const body = res.Body?.transformToWebStream();
+            if (!body)
+                return null;
+            return {
+                body,
+                contentType: res.ContentType ?? 'application/octet-stream',
+                contentLength: res.ContentLength ?? null,
+            };
+        },
         async delete(key) {
             await client.send(new DeleteObjectCommand({
                 Bucket: config.bucket,
@@ -27,7 +55,34 @@ export function createS3Adapter(config) {
             }));
         },
         getUrl(key) {
+            if (!config.publicUrl) {
+                throw new Error('publicUrl not configured — serve private buckets via get() or getSignedUrl()');
+            }
             return `${config.publicUrl.replace(/\/$/, '')}/${key}`;
         },
+        async getSignedUrl(key, expiresIn = 3600) {
+            const cacheKey = `${expiresIn}:${key}`;
+            const cached = signedCache.get(cacheKey);
+            if (cached && cached.expiresAt > Date.now())
+                return cached.url;
+            if (cached)
+                signedCache.delete(cacheKey);
+            const inflight = signedInflight.get(cacheKey);
+            if (inflight)
+                return inflight;
+            const signing = presignGetObject(client, new GetObjectCommand({ Bucket: config.bucket, Key: key }), { expiresIn })
+                .then((url) => {
+                signedCache.set(cacheKey, {
+                    url,
+                    expiresAt: Date.now() + Math.max(expiresIn * 1000 - SIGNED_TTL_BUFFER_MS, 1_000),
+                });
+                return url;
+            })
+                .finally(() => {
+                signedInflight.delete(cacheKey);
+            });
+            signedInflight.set(cacheKey, signing);
+            return signing;
+        },
     };
 }

package/dist/core/env.d.ts

@@ -0,0 +1,23 @@
+import type { StorageAdapter } from './types.js';
+/** Anything with string values — `process.env`, or SvelteKit's `$env/dynamic/private`. */
+export type EnvSource = Record<string, string | undefined>;
+export interface EnvAdapterOptions {
+    /** Fallback when `S3_BUCKET` is unset. */
+    bucket?: string;
+    /** Fallback when `S3_REGION` is unset. Default `'auto'`. */
+    region?: string;
+    /** Base public URL for `getUrl()` — omit for private buckets. */
+    publicUrl?: string;
+    /** Default true (MinIO/Garage/R2); false for Railway/AWS virtual-hosted. */
+    forcePathStyle?: boolean;
+}
+/**
+ * The storage adapter this deployment is configured for:
+ *
+ *   - S3 when `S3_ENDPOINT` + `S3_ACCESS_KEY_ID` + `S3_SECRET_ACCESS_KEY` and a
+ *     bucket (`S3_BUCKET` or `options.bucket`) are all present
+ *   - local files when `MEDIA_ROOT` is set (dev machines, no bucket)
+ *   - otherwise it throws, naming what is missing — a media surface that
+ *     silently no-ops is worse than a boot failure.
+ */
+export declare function adapterFromEnv(env: EnvSource, options?: EnvAdapterOptions): StorageAdapter;

package/dist/core/env.js

@@ -0,0 +1,59 @@
+// Storage wiring from environment variables — server-only.
+//
+// Both source apps had hand-written this: read S3_*, build one lazy adapter,
+// fall back (or throw) when the vars are absent. They drifted — one defaulted
+// to path-style addressing for uploads while signing reads virtual-hosted, and
+// each carried its own singleton. The env NAMES are the shared part; the
+// defaults that differ per deployment (bucket, region, addressing) stay
+// arguments.
+import { createS3Adapter } from './adapter.js';
+import { createLocalAdapter } from './local-adapter.js';
+// One adapter per distinct config, so repeated calls (every request) reuse the
+// S3 client and its signed-URL cache. Keyed by the resolved config, so a
+// changed env var in dev builds a new one instead of serving a stale client.
+const adapters = new Map();
+/**
+ * The storage adapter this deployment is configured for:
+ *
+ *   - S3 when `S3_ENDPOINT` + `S3_ACCESS_KEY_ID` + `S3_SECRET_ACCESS_KEY` and a
+ *     bucket (`S3_BUCKET` or `options.bucket`) are all present
+ *   - local files when `MEDIA_ROOT` is set (dev machines, no bucket)
+ *   - otherwise it throws, naming what is missing — a media surface that
+ *     silently no-ops is worse than a boot failure.
+ */
+export function adapterFromEnv(env, options = {}) {
+    const endpoint = env.S3_ENDPOINT;
+    const accessKeyId = env.S3_ACCESS_KEY_ID;
+    const secretAccessKey = env.S3_SECRET_ACCESS_KEY;
+    const bucket = env.S3_BUCKET ?? options.bucket;
+    if (endpoint && accessKeyId && secretAccessKey && bucket) {
+        const config = {
+            endpoint,
+            region: env.S3_REGION ?? options.region ?? 'auto',
+            bucket,
+            accessKeyId,
+            secretAccessKey,
+            publicUrl: options.publicUrl,
+            forcePathStyle: options.forcePathStyle,
+        };
+        return memo(`s3:${JSON.stringify(config)}`, () => createS3Adapter(config));
+    }
+    const root = env.MEDIA_ROOT;
+    if (root)
+        return memo(`local:${root}`, () => createLocalAdapter({ root }));
+    const missing = [
+        !endpoint && 'S3_ENDPOINT',
+        !accessKeyId && 'S3_ACCESS_KEY_ID',
+        !secretAccessKey && 'S3_SECRET_ACCESS_KEY',
+        !bucket && 'S3_BUCKET',
+    ].filter(Boolean);
+    throw new Error(`svelte-media: no storage configured — missing ${missing.join(', ')} (or set MEDIA_ROOT for local files)`);
+}
+function memo(key, build) {
+    let adapter = adapters.get(key);
+    if (!adapter) {
+        adapter = build();
+        adapters.set(key, adapter);
+    }
+    return adapter;
+}

package/dist/core/local-adapter.js

@@ -1,5 +1,11 @@
-import { writeFile, unlink, mkdir } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
+import { join, dirname, extname } from 'node:path';
+const MIME_BY_EXT = {
+    '.webp': 'image/webp',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+};
 export function createLocalAdapter(config) {
     return {
         async put(key, buffer, contentType) {
@@ -7,6 +13,22 @@ export function createLocalAdapter(config) {
             await mkdir(dirname(filePath), { recursive: true });
             await writeFile(filePath, buffer);
         },
+        async get(key) {
+            let buffer;
+            try {
+                buffer = await readFile(join(config.root, key));
+            }
+            catch (e) {
+                if (e.code === 'ENOENT')
+                    return null;
+                throw e;
+            }
+            return {
+                body: new Blob([new Uint8Array(buffer)]).stream(),
+                contentType: MIME_BY_EXT[extname(key).toLowerCase()] ?? 'application/octet-stream',
+                contentLength: buffer.length,
+            };
+        },
         async delete(key) {
             await unlink(join(config.root, key)).catch(() => { });
         },

package/dist/core/media.d.ts

@@ -1,4 +1,4 @@
-import type { ImageSize, ValidationConfig, ValidationResult } from './types.js';
+import type { ImageSize, ValidationConfig, ValidationErrorCode, ValidationResult } from './types.js';
 export declare const DEFAULT_MAX_SIZE: number;
 export declare const DEFAULT_ALLOWED_TYPES: string[];
 export declare const IMAGE_SIZES: {
@@ -21,5 +21,34 @@ export declare const IMAGE_SIZES: {
 export declare const SIZE_PREFIXES: Record<ImageSize, string>;
 export declare const SIZE_QUALITY: Record<ImageSize, number>;
 export declare function validateImageFile(file: File, config?: ValidationConfig): ValidationResult;
-export declare function generateMediaKey(_originalName?: string): string;
+/**
+ * What `processAndStore` throws on a failed validation. Carries the
+ * machine-readable `code` (+ limits) so form actions can map it to their own
+ * copy instead of surfacing the English `message`.
+ */
+export declare class MediaValidationError extends Error {
+    readonly code: ValidationErrorCode;
+    readonly maxBytes?: number;
+    readonly allowedTypes?: string[];
+    constructor(result: ValidationResult);
+}
+export declare function generateMediaKey(): string;
 export declare function getStorageKey(prefix: string, entityId: string, filename: string, size: ImageSize): string;
+/**
+ * The variant key for a stored ORIGINAL key (`prefix/entityId/filename`) —
+ * for apps that persist the single joined key rather than the
+ * (prefix, entityId, filename) triple.
+ */
+export declare function variantKey(key: string, size: ImageSize): string;
+/** The smallest pre-generated variant that still fills `width` display pixels. */
+export declare function sizeForWidth(width?: number): ImageSize;
+/**
+ * Inverse of `getStorageKey` for an original key. Returns null for keys that
+ * don't fit the `prefix/entityId/filename` layout (e.g. legacy ids), so
+ * callers can treat those as "nothing to do".
+ */
+export declare function parseStorageKey(key: string): {
+    prefix: string;
+    entityId: string;
+    filename: string;
+} | null;

package/dist/core/media.js

@@ -24,20 +24,79 @@ export const SIZE_QUALITY = {
 export function validateImageFile(file, config) {
     const maxSize = config?.maxFileSize ?? DEFAULT_MAX_SIZE;
     const allowed = config?.allowedTypes ?? DEFAULT_ALLOWED_TYPES;
+    if (file.size === 0) {
+        return { valid: false, code: 'empty', error: 'No file provided' };
+    }
     if (file.size > maxSize) {
         const mb = Math.round(maxSize / 1024 / 1024);
-        return { valid: false, error: `File too large (max ${mb}MB)` };
+        return { valid: false, code: 'file-too-large', maxBytes: maxSize, error: `File too large (max ${mb}MB)` };
     }
     if (!allowed.includes(file.type)) {
-        return { valid: false, error: `Invalid file type. Allowed: JPEG, PNG, WebP` };
+        return { valid: false, code: 'invalid-type', allowedTypes: allowed, error: `Invalid file type. Allowed: JPEG, PNG, WebP` };
     }
     return { valid: true };
 }
-export function generateMediaKey(_originalName) {
+/**
+ * What `processAndStore` throws on a failed validation. Carries the
+ * machine-readable `code` (+ limits) so form actions can map it to their own
+ * copy instead of surfacing the English `message`.
+ */
+export class MediaValidationError extends Error {
+    code;
+    maxBytes;
+    allowedTypes;
+    constructor(result) {
+        super(result.error ?? 'Invalid file');
+        this.name = 'MediaValidationError';
+        this.code = result.code ?? 'invalid-type';
+        this.maxBytes = result.maxBytes;
+        this.allowedTypes = result.allowedTypes;
+    }
+}
+export function generateMediaKey() {
     // All processed output is WebP regardless of the uploaded format.
     return `${createId()}.webp`;
 }
 export function getStorageKey(prefix, entityId, filename, size) {
+    // Filenames are generated (`<cuid2>.webp`), but they round-trip through rows
+    // and form fields before they come back here to be deleted — a `..` segment
+    // would reach outside the entity's own folder. serveMedia guards the read
+    // path; this is the write/delete one.
+    if (filename.includes('/') || filename.includes('\\') || filename.includes('..')) {
+        throw new Error(`Invalid media filename: ${filename}`);
+    }
     const sizePrefix = SIZE_PREFIXES[size];
     return `${prefix}/${entityId}/${sizePrefix}${filename}`;
 }
+/**
+ * The variant key for a stored ORIGINAL key (`prefix/entityId/filename`) —
+ * for apps that persist the single joined key rather than the
+ * (prefix, entityId, filename) triple.
+ */
+export function variantKey(key, size) {
+    const idx = key.lastIndexOf('/');
+    return `${key.slice(0, idx + 1)}${SIZE_PREFIXES[size]}${key.slice(idx + 1)}`;
+}
+/** The smallest pre-generated variant that still fills `width` display pixels. */
+export function sizeForWidth(width) {
+    if (!width)
+        return 'medium';
+    if (width <= IMAGE_SIZES.thumbnail.width)
+        return 'thumbnail';
+    if (width <= IMAGE_SIZES.medium.width)
+        return 'medium';
+    return 'large';
+}
+/**
+ * Inverse of `getStorageKey` for an original key. Returns null for keys that
+ * don't fit the `prefix/entityId/filename` layout (e.g. legacy ids), so
+ * callers can treat those as "nothing to do".
+ */
+export function parseStorageKey(key) {
+    const parts = key.split('/');
+    if (parts.length < 3)
+        return null;
+    const filename = parts.pop();
+    const entityId = parts.pop();
+    return { prefix: parts.join('/'), entityId, filename };
+}

package/dist/core/process.d.ts

@@ -1,4 +1,10 @@
 import type { StorageAdapter, StoredMedia, ImageSize, MediaConfig } from './types.js';
 export declare function processAndStore<TDerived = never>(adapter: StorageAdapter, file: File, prefix: string, entityId: string, config?: MediaConfig<TDerived>): Promise<StoredMedia<TDerived>>;
 export declare function deleteMedia(adapter: StorageAdapter, prefix: string, entityId: string, filename: string): Promise<void>;
+/**
+ * `deleteMedia` for apps that persist the single joined original key.
+ * Keys that don't parse (legacy ids from a previous storage system) are a
+ * silent no-op — there is nothing in object storage to delete.
+ */
+export declare function deleteMediaByKey(adapter: StorageAdapter, key: string): Promise<void>;
 export declare function getMediaUrl(adapter: StorageAdapter, prefix: string, entityId: string, filename: string, size?: ImageSize): string;

package/dist/core/process.js

@@ -2,12 +2,12 @@
 // browser bundle will fail — the client-safe helpers live in core/media.ts and
 // are re-exported from the package root.
 import sharp from 'sharp';
-import { IMAGE_SIZES, SIZE_QUALITY, generateMediaKey, getStorageKey, validateImageFile, } from './media.js';
+import { IMAGE_SIZES, SIZE_QUALITY, MediaValidationError, generateMediaKey, getStorageKey, parseStorageKey, validateImageFile, } from './media.js';
 export async function processAndStore(adapter, file, prefix, entityId, config) {
     const validation = validateImageFile(file, config);
     if (!validation.valid)
-        throw new Error(validation.error);
-    const filename = generateMediaKey(file.name);
+        throw new MediaValidationError(validation);
+    const filename = generateMediaKey();
     const arrayBuffer = await file.arrayBuffer();
     const buffer = Buffer.from(arrayBuffer);
     const sizes = {
@@ -34,7 +34,7 @@ export async function processAndStore(adapter, file, prefix, entityId, config) {
     // make the caller retry a completed upload.
     let derived;
     if (config?.derive) {
-        const source = { buffer, filename, mimeType: file.type };
+        const source = { buffer, filename, mimeType: file.type, prefix, entityId };
         try {
             derived = await config.derive(source);
         }
@@ -48,6 +48,17 @@ export async function deleteMedia(adapter, prefix, entityId, filename) {
     const keys = ['original', 'thumbnail', 'medium', 'large'].map((size) => getStorageKey(prefix, entityId, filename, size));
     await Promise.all(keys.map((key) => adapter.delete(key).catch(() => { })));
 }
+/**
+ * `deleteMedia` for apps that persist the single joined original key.
+ * Keys that don't parse (legacy ids from a previous storage system) are a
+ * silent no-op — there is nothing in object storage to delete.
+ */
+export async function deleteMediaByKey(adapter, key) {
+    const parsed = parseStorageKey(key);
+    if (!parsed)
+        return;
+    await deleteMedia(adapter, parsed.prefix, parsed.entityId, parsed.filename);
+}
 export function getMediaUrl(adapter, prefix, entityId, filename, size = 'medium') {
     return adapter.getUrl(getStorageKey(prefix, entityId, filename, size));
 }

package/dist/core/remote.d.ts

@@ -0,0 +1,42 @@
+import type { StorageAdapter } from './types.js';
+export interface ImageBytes {
+    /** Concrete ArrayBuffer view — `Response` and `Blob` reject the SharedArrayBuffer-wide type. */
+    body: Uint8Array<ArrayBuffer>;
+    contentType: string;
+}
+/**
+ * Re-encode to WebP (~30-50% smaller than the JPEG most photo APIs serve).
+ * Returns the input untouched when sharp cannot read it — a transcode is an
+ * optimisation, never a reason to lose an image we already hold.
+ */
+export declare function toWebp(bytes: Uint8Array<ArrayBuffer>, quality?: number): Promise<ImageBytes>;
+export interface FetchImageOptions extends RequestInit {
+    /** WebP quality, or `false` to keep the upstream encoding. Default 80. */
+    webp?: number | false;
+}
+/**
+ * GET an image from a remote URL, transcoded to WebP by default.
+ * `null` when the response fails or isn't an image — an error page's HTML must
+ * never reach the cache as if it were a photo.
+ */
+export declare function fetchImage(url: string, options?: FetchImageOptions): Promise<ImageBytes | null>;
+export interface CachedImageOptions {
+    /**
+     * Called when the fetched bytes could not be stored. The response still goes
+     * out; the next request will produce them again (i.e. pay again), so wire
+     * this to your logger.
+     */
+    onStoreError?(error: unknown, key: string): void;
+}
+/**
+ * Serve `key` from storage, producing it once on the first miss.
+ *
+ * Cheapest path first: a stored copy is streamed without calling `produce` at
+ * all. Concurrent misses for the same key share one `produce` call — a CDN
+ * stampede across PoPs, or a crawler, otherwise buys one copy each.
+ *
+ * `null` means `produce` had nothing (the caller decides: 404, placeholder,
+ * fall through). A storage read that throws is treated as a miss: an
+ * unreachable bucket must not blank an image it could still fetch.
+ */
+export declare function cachedImage(adapter: StorageAdapter, key: string, produce: () => Promise<ImageBytes | null>, options?: CachedImageOptions): Promise<Response | null>;

package/dist/core/remote.js

@@ -0,0 +1,105 @@
+// Caching images that come from somewhere else — a paid photo API, a partner
+// CDN, a scraper. Server-only (sharp).
+//
+// Extracted from yoga's Google Places hero proxy, which was paying Google per
+// origin miss until it grew a bucket cache, a stampede lock and a transcode
+// step around it. All three are storage plumbing, not Places knowledge: what
+// stays in the app is which URL to call, what it costs and when to give up.
+import sharp from 'sharp';
+// Cached objects are keyed by content and never rewritten in place, so the
+// bytes behind a URL never change — same header serveMedia sends.
+const IMMUTABLE = 'public, max-age=31536000, immutable';
+/**
+ * Re-encode to WebP (~30-50% smaller than the JPEG most photo APIs serve).
+ * Returns the input untouched when sharp cannot read it — a transcode is an
+ * optimisation, never a reason to lose an image we already hold.
+ */
+export async function toWebp(bytes, quality = 80) {
+    try {
+        const webp = await sharp(Buffer.from(bytes)).webp({ quality }).toBuffer();
+        return { body: new Uint8Array(webp), contentType: 'image/webp' };
+    }
+    catch {
+        return { body: bytes, contentType: 'application/octet-stream' };
+    }
+}
+/**
+ * GET an image from a remote URL, transcoded to WebP by default.
+ * `null` when the response fails or isn't an image — an error page's HTML must
+ * never reach the cache as if it were a photo.
+ */
+export async function fetchImage(url, options = {}) {
+    const { webp = 80, ...init } = options;
+    const res = await fetch(url, { redirect: 'follow', ...init });
+    if (!res.ok)
+        return null;
+    const contentType = res.headers.get('content-type') ?? '';
+    if (!contentType.startsWith('image/'))
+        return null;
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    if (webp === false)
+        return { body: bytes, contentType };
+    const encoded = await toWebp(bytes, webp);
+    // sharp failed — keep the upstream type rather than toWebp's octet-stream.
+    return encoded.contentType === 'image/webp' ? encoded : { body: bytes, contentType };
+}
+// Per-adapter, so two stores in one process cannot collide on a shared key.
+const inflight = new WeakMap();
+/**
+ * Serve `key` from storage, producing it once on the first miss.
+ *
+ * Cheapest path first: a stored copy is streamed without calling `produce` at
+ * all. Concurrent misses for the same key share one `produce` call — a CDN
+ * stampede across PoPs, or a crawler, otherwise buys one copy each.
+ *
+ * `null` means `produce` had nothing (the caller decides: 404, placeholder,
+ * fall through). A storage read that throws is treated as a miss: an
+ * unreachable bucket must not blank an image it could still fetch.
+ */
+export async function cachedImage(adapter, key, produce, options = {}) {
+    const stored = await adapter.get(key).catch(() => null);
+    if (stored) {
+        return new Response(stored.body, {
+            headers: {
+                'Content-Type': stored.contentType,
+                ...(stored.contentLength != null
+                    ? { 'Content-Length': String(stored.contentLength) }
+                    : {}),
+                'Cache-Control': IMMUTABLE,
+            },
+        });
+    }
+    let pending = inflight.get(adapter);
+    if (!pending) {
+        pending = new Map();
+        inflight.set(adapter, pending);
+    }
+    let work = pending.get(key);
+    if (!work) {
+        work = (async () => {
+            const image = await produce();
+            if (!image)
+                return null;
+            // Awaited: a silent write failure means paying for these bytes again on
+            // the next request, which is the whole point of the cache.
+            try {
+                await adapter.put(key, Buffer.from(image.body), image.contentType);
+            }
+            catch (error) {
+                options.onStoreError?.(error, key);
+            }
+            return image;
+        })().finally(() => pending.delete(key));
+        pending.set(key, work);
+    }
+    const image = await work;
+    if (!image)
+        return null;
+    return new Response(image.body, {
+        headers: {
+            'Content-Type': image.contentType,
+            'Content-Length': String(image.body.byteLength),
+            'Cache-Control': IMMUTABLE,
+        },
+    });
+}

package/dist/core/serve.d.ts

@@ -0,0 +1,8 @@
+import type { StorageAdapter } from './types.js';
+/**
+ * Same-origin media serving: the whole body of a
+ * `/photos/[...key]`-style route. Key validation, 404 on missing, immutable
+ * cache headers (keys are content-addressed and never change in place).
+ * Returns a standard `Response` — return it directly from a SvelteKit handler.
+ */
+export declare function serveMedia(adapter: StorageAdapter, key: string): Promise<Response>;

package/dist/core/serve.js

@@ -0,0 +1,26 @@
+// Media keys are `prefix/entityId/(sizePrefix)filename.ext` — reject anything
+// else (especially `..` traversal) before it reaches the adapter. Both source
+// apps had written this route by hand; the copy without the guard had a path
+// traversal, which is why the validation lives here now.
+const MEDIA_KEY = /^[a-zA-Z0-9_/.-]+\.(webp|jpe?g|png)$/;
+/**
+ * Same-origin media serving: the whole body of a
+ * `/photos/[...key]`-style route. Key validation, 404 on missing, immutable
+ * cache headers (keys are content-addressed and never change in place).
+ * Returns a standard `Response` — return it directly from a SvelteKit handler.
+ */
+export async function serveMedia(adapter, key) {
+    if (!MEDIA_KEY.test(key) || key.includes('..')) {
+        return new Response('Not found', { status: 404 });
+    }
+    const obj = await adapter.get(key);
+    if (!obj)
+        return new Response('Not found', { status: 404 });
+    return new Response(obj.body, {
+        headers: {
+            'Content-Type': obj.contentType,
+            ...(obj.contentLength != null ? { 'Content-Length': String(obj.contentLength) } : {}),
+            'Cache-Control': 'public, max-age=31536000, immutable',
+        },
+    });
+}

package/dist/core/store.d.ts

@@ -0,0 +1,48 @@
+import type { ImageSize, MediaConfig, StorageAdapter, StorageObject, StoredMedia, ValidationResult } from './types.js';
+import { type CachedImageOptions, type ImageBytes } from './remote.js';
+export interface MediaStoreConfig<TDerived = never> extends MediaConfig<TDerived> {
+    adapter: StorageAdapter;
+    /**
+     * Where the same-origin serving route lives, e.g. `'/photos'` or
+     * `'/api/images'` — what `resolveUrl` falls back to when the adapter cannot
+     * presign (local dev, public buckets).
+     */
+    basePath?: string;
+}
+/**
+ * The per-app binding — adapter, limits and derive hook bound once, so call
+ * sites pass only what varies per upload. Both source apps had hand-built this
+ * module (and one ended up configuring the same bucket two different ways);
+ * app #3 starts here instead.
+ *
+ * Env reading stays in the app: build the adapter from your own env names and
+ * hand it in.
+ */
+export interface MediaStore<TDerived = never> {
+    adapter: StorageAdapter;
+    /** `processAndStore` with the bound adapter + config. */
+    store(file: File, prefix: string, entityId: string): Promise<StoredMedia<TDerived>>;
+    /** Deletes all variants by the joined original key; unparseable keys are a no-op. */
+    remove(key: string): Promise<void>;
+    get(key: string): Promise<StorageObject | null>;
+    /** `serveMedia` with the bound adapter — a complete same-origin route body. */
+    serve(key: string): Promise<Response>;
+    /** Public URL for a size variant (adapters with a publicUrl only). */
+    url(key: string, size?: ImageSize): string;
+    /** Presigned URL for a size variant — rejects unless the adapter is S3. */
+    signedUrl(key: string, size?: ImageSize, expiresIn?: number): Promise<string>;
+    /**
+     * The URL to hand a browser: presigned when the adapter can sign (a private
+     * bucket in production), else `basePath/key` for the same-origin route.
+     * Both apps had written that fallback by hand.
+     */
+    resolveUrl(key: string, size?: ImageSize, expiresIn?: number): Promise<string>;
+    /**
+     * `cachedImage` with the bound adapter — serve a key from storage, buying it
+     * from `produce` once on the first miss.
+     */
+    cached(key: string, produce: () => Promise<ImageBytes | null>, options?: CachedImageOptions): Promise<Response | null>;
+    /** `validateImageFile` with the bound limits. */
+    validate(file: File): ValidationResult;
+}
+export declare function createMediaStore<TDerived = never>(config: MediaStoreConfig<TDerived>): MediaStore<TDerived>;

package/dist/core/store.js

@@ -0,0 +1,33 @@
+import { validateImageFile, variantKey } from './media.js';
+import { processAndStore, deleteMediaByKey } from './process.js';
+import { serveMedia } from './serve.js';
+import { cachedImage } from './remote.js';
+export function createMediaStore(config) {
+    const { adapter, basePath, ...media } = config;
+    const signer = adapter.getSignedUrl?.bind(adapter);
+    return {
+        adapter,
+        store: (file, prefix, entityId) => processAndStore(adapter, file, prefix, entityId, media),
+        remove: (key) => deleteMediaByKey(adapter, key),
+        get: (key) => adapter.get(key),
+        serve: (key) => serveMedia(adapter, key),
+        url: (key, size = 'original') => adapter.getUrl(variantKey(key, size)),
+        signedUrl: (key, size = 'original', expiresIn) => {
+            if (!signer) {
+                return Promise.reject(new Error('signedUrl needs an S3 adapter (getSignedUrl)'));
+            }
+            return signer(variantKey(key, size), expiresIn);
+        },
+        resolveUrl: async (key, size = 'original', expiresIn) => {
+            const variant = variantKey(key, size);
+            if (signer)
+                return signer(variant, expiresIn);
+            if (!basePath) {
+                throw new Error('resolveUrl needs an S3 adapter or a basePath for the serving route');
+            }
+            return `${basePath.replace(/\/$/, '')}/${variant}`;
+        },
+        cached: (key, produce, options) => cachedImage(adapter, key, produce, options),
+        validate: (file) => validateImageFile(file, media),
+    };
+}

package/dist/core/types.d.ts

@@ -1,9 +1,27 @@
 export type ImageSize = 'original' | 'thumbnail' | 'medium' | 'large';
+/** What `StorageAdapter.get` resolves for an existing object. */
+export interface StorageObject {
+    body: ReadableStream<Uint8Array>;
+    contentType: string;
+    contentLength: number | null;
+}
 export interface StorageAdapter {
     put(key: string, buffer: Buffer, contentType: string): Promise<void>;
+    /** null when the object doesn't exist; rejects on real failures (network, auth). */
+    get(key: string): Promise<StorageObject | null>;
     delete(key: string): Promise<void>;
+    /** Public-URL serving only — throws when the adapter has no public base URL. */
     getUrl(key: string): string;
 }
+/** What `createS3Adapter` actually returns — a StorageAdapter that can presign. */
+export interface S3Adapter extends StorageAdapter {
+    /**
+     * Presigned GET URL for a private bucket. Cached until shortly before
+     * expiry and deduped in flight, so page loads with many images cost one
+     * signing pass per key.
+     */
+    getSignedUrl(key: string, expiresIn?: number): Promise<string>;
+}
 export interface S3Config {
     /** Full endpoint URL, e.g. https://xxx.r2.cloudflarestorage.com */
     endpoint: string;
@@ -12,8 +30,12 @@ export interface S3Config {
     bucket: string;
     accessKeyId: string;
     secretAccessKey: string;
-    /** Base public URL for getUrl(), e.g. https://pub-xxx.r2.dev */
-    publicUrl: string;
+    /**
+     * Base public URL for getUrl(), e.g. https://pub-xxx.r2.dev. Optional —
+     * private buckets serve via `get()` (same-origin proxy) or `getSignedUrl()`
+     * instead, and `getUrl()` throws without it.
+     */
+    publicUrl?: string;
     /** Use path-style access (default: true for MinIO/R2, set false for Railway/AWS) */
     forcePathStyle?: boolean;
 }
@@ -32,18 +54,17 @@ export interface StoredMedia<TDerived = never> {
      */
     derived?: TDerived;
 }
-export interface MediaValidationError {
-    isValid: false;
-    error: string;
-}
-export interface MediaValidationOk {
-    isValid: true;
-}
-export type MediaValidation = MediaValidationOk | MediaValidationError;
-export declare const DEFAULT_MAX_SIZE: number;
-export declare const DEFAULT_ALLOWED_TYPES: string[];
+/** Machine-readable validation failure — map it to your own copy/i18n. */
+export type ValidationErrorCode = 'empty' | 'file-too-large' | 'invalid-type';
 export interface ValidationResult {
     valid: boolean;
+    /** Set when `valid` is false. */
+    code?: ValidationErrorCode;
+    /** The limit that produced a 'file-too-large', for message interpolation. */
+    maxBytes?: number;
+    /** The allow-list that produced an 'invalid-type'. */
+    allowedTypes?: string[];
+    /** Human-readable English fallback; apps with i18n should map `code` instead. */
     error?: string;
 }
 /** What a `derive` hook receives — the image as uploaded, before any resizing. */
@@ -54,6 +75,10 @@ export interface DeriveSource {
     filename: string;
     /** The uploaded file's MIME type. */
     mimeType: string;
+    /** Storage prefix this upload went to, e.g. 'schools'. */
+    prefix: string;
+    /** The owning entity — what a failing hook needs to name in a log line. */
+    entityId: string;
 }
 /** The validation half of MediaConfig — all `validateImageFile` needs. */
 export interface ValidationConfig {

package/dist/core/types.js

@@ -1,3 +1,2 @@
 // packages/svelte-media/src/lib/core/types.ts
-export const DEFAULT_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
-export const DEFAULT_ALLOWED_TYPES = ['image/jpeg', 'image/jpg', 'image/png', 'image/webp'];
+export {};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { StorageAdapter, S3Config, StoredMedia, ImageSize, MediaConfig, ValidationResult, ValidationConfig, DeriveSource, } from './core/types.js';
-export { validateImageFile, generateMediaKey, getStorageKey, IMAGE_SIZES, DEFAULT_MAX_SIZE, DEFAULT_ALLOWED_TYPES, } from './core/media.js';
+export type { StorageAdapter, S3Adapter, S3Config, StorageObject, StoredMedia, ImageSize, MediaConfig, ValidationResult, ValidationConfig, ValidationErrorCode, DeriveSource, } from './core/types.js';
+export { validateImageFile, MediaValidationError, generateMediaKey, getStorageKey, variantKey, sizeForWidth, parseStorageKey, IMAGE_SIZES, SIZE_PREFIXES, SIZE_QUALITY, DEFAULT_MAX_SIZE, DEFAULT_ALLOWED_TYPES, } from './core/media.js';
 export { default as ImageUpload } from './components/ImageUpload.svelte';
 export { default as ImageGallery } from './components/ImageGallery.svelte';

package/dist/index.js

@@ -1,6 +1,6 @@
 // Client-safe entry. The image pipeline and storage adapters need sharp,
 // node:fs and Buffer, so they live behind '@nomideusz/svelte-media/server' —
 // importing them here would break any browser bundle that touches a component.
-export { validateImageFile, generateMediaKey, getStorageKey, IMAGE_SIZES, DEFAULT_MAX_SIZE, DEFAULT_ALLOWED_TYPES, } from './core/media.js';
+export { validateImageFile, MediaValidationError, generateMediaKey, getStorageKey, variantKey, sizeForWidth, parseStorageKey, IMAGE_SIZES, SIZE_PREFIXES, SIZE_QUALITY, DEFAULT_MAX_SIZE, DEFAULT_ALLOWED_TYPES, } from './core/media.js';
 export { default as ImageUpload } from './components/ImageUpload.svelte';
 export { default as ImageGallery } from './components/ImageGallery.svelte';

package/dist/server/index.d.ts

@@ -1,6 +1,13 @@
 export type { LocalConfig } from '../core/local-adapter.js';
 export { createS3Adapter } from '../core/adapter.js';
 export { createLocalAdapter } from '../core/local-adapter.js';
-export { processAndStore, deleteMedia, getMediaUrl } from '../core/process.js';
-export { validateImageFile, generateMediaKey, getStorageKey, IMAGE_SIZES, } from '../core/media.js';
+export { adapterFromEnv } from '../core/env.js';
+export type { EnvAdapterOptions, EnvSource } from '../core/env.js';
+export { cachedImage, fetchImage, toWebp } from '../core/remote.js';
+export type { CachedImageOptions, FetchImageOptions, ImageBytes } from '../core/remote.js';
+export { processAndStore, deleteMedia, deleteMediaByKey, getMediaUrl } from '../core/process.js';
+export { serveMedia } from '../core/serve.js';
+export { createMediaStore } from '../core/store.js';
+export type { MediaStore, MediaStoreConfig } from '../core/store.js';
+export { validateImageFile, MediaValidationError, generateMediaKey, getStorageKey, variantKey, sizeForWidth, parseStorageKey, IMAGE_SIZES, SIZE_PREFIXES, SIZE_QUALITY, } from '../core/media.js';
 export type * from '../core/types.js';

package/dist/server/index.js

@@ -1,6 +1,10 @@
 // Server-only entry: sharp, node:fs and Buffer live behind here.
 export { createS3Adapter } from '../core/adapter.js';
 export { createLocalAdapter } from '../core/local-adapter.js';
-export { processAndStore, deleteMedia, getMediaUrl } from '../core/process.js';
+export { adapterFromEnv } from '../core/env.js';
+export { cachedImage, fetchImage, toWebp } from '../core/remote.js';
+export { processAndStore, deleteMedia, deleteMediaByKey, getMediaUrl } from '../core/process.js';
+export { serveMedia } from '../core/serve.js';
+export { createMediaStore } from '../core/store.js';
 // Re-exported so server code needs only one import.
-export { validateImageFile, generateMediaKey, getStorageKey, IMAGE_SIZES, } from '../core/media.js';
+export { validateImageFile, MediaValidationError, generateMediaKey, getStorageKey, variantKey, sizeForWidth, parseStorageKey, IMAGE_SIZES, SIZE_PREFIXES, SIZE_QUALITY, } from '../core/media.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomideusz/svelte-media",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "Image upload, processing, and S3-compatible storage for Svelte 5 apps.",
   "type": "module",
   "sideEffects": false,
@@ -47,15 +47,15 @@
   },
   "devDependencies": {
     "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.69.1",
+    "@sveltejs/kit": "^2.70.2",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@types/node": "^25.9.4",
-    "svelte": "^5.56.4",
+    "svelte": "^5.56.9",
     "svelte-check": "^4.7.1",
     "typescript": "^5.9.3",
     "vite": "^7.3.6",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
   },
   "keywords": [
     "svelte",