@nomideusz/svelte-media 0.5.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## 1.0.0
+
+### Major Changes
+
+- 1.0.0 — the promise, sized to the proven surface. Two production apps
+  consume the validation, media store, env adapters, storage keys,
+  remote-image fetching and serving daily; 53 tests cover them; that API is
+  now stable, and anything that breaks a consumer costs a major.
+  
+  **Breaking: `ImageUpload` and `ImageGallery` leave the public API.** In two
+  consuming apps neither was ever rendered, and this package's own changelog
+  records that surface shipping broken twice precisely because nothing
+  consumed it (a `config` prop that was never read; a build failure nobody
+  hit). A 1.0 must not promise stability on components without a single real
+  consumer. The files remain in-repo for the demo; if an app one day wants
+  them, re-exporting is an additive minor made against a component that
+  consumer actually exercises.
+
+## 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

package/README.md

@@ -34,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,
+  });
+```
 
-const stored = await processAndStore(storage, file, 'tours', tourId);
+`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.
+
+```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.
@@ -103,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.
 
@@ -152,6 +171,44 @@ 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
@@ -195,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) ──
@@ -211,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/ImageGallery.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">let { images, getUrl, onDelete, size = "thumbnail" } = $props();
 let expanded = $state(null);
+export {};
 </script>
 
 {#if images.length > 0}

package/dist/components/ImageUpload.svelte

@@ -1,36 +1,30 @@
 <script lang="ts">import { validateImageFile } from "../core/media.js";
-let {
-  onUpload,
-  onError,
-  maxFiles = 1,
-  accept = "image/jpeg,image/png,image/webp",
-  config
-} = $props();
+let { onUpload, onError, maxFiles = 1, accept = "image/jpeg,image/png,image/webp", config } = $props();
 let dragging = $state(false);
 let uploading = $state(false);
 let input;
 async function handleFiles(files) {
-  if (!files || files.length === 0) return;
-  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) {
-    onError?.(e instanceof Error ? e.message : "Upload failed");
-  } finally {
-    uploading = false;
-  }
+	if (!files || files.length === 0) return;
+	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) {
+		onError?.(e instanceof Error ? e.message : "Upload failed");
+	} finally {
+		uploading = false;
+	}
 }
 function onDrop(e) {
-  e.preventDefault();
-  dragging = false;
-  handleFiles(e.dataTransfer?.files ?? null);
+	e.preventDefault();
+	dragging = false;
+	handleFiles(e.dataTransfer?.files ?? null);
 }
 </script>
 

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/media.js

@@ -58,6 +58,13 @@ export function generateMediaKey() {
     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}`;
 }

package/dist/core/process.js

@@ -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);
         }

package/dist/core/remote-images.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-images.js

@@ -0,0 +1,109 @@
+// Caching images that come from somewhere else — a paid photo API, a partner
+// CDN, a scraper. Server-only (sharp).
+//
+// kit 3 claims any file named `remote.*` as a remote-functions module
+// (pattern /[/.]remote\.[^/]+$/) and rejects its plain exports — hence
+// `remote-images`, not `remote`.
+//
+// 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/store.d.ts

@@ -1,6 +1,13 @@
 import type { ImageSize, MediaConfig, StorageAdapter, StorageObject, StoredMedia, ValidationResult } from './types.js';
+import { type CachedImageOptions, type ImageBytes } from './remote-images.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
@@ -24,6 +31,17 @@ export interface MediaStore<TDerived = never> {
     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;
 }

package/dist/core/store.js

@@ -1,8 +1,10 @@
 import { validateImageFile, variantKey } from './media.js';
 import { processAndStore, deleteMediaByKey } from './process.js';
 import { serveMedia } from './serve.js';
+import { cachedImage } from './remote-images.js';
 export function createMediaStore(config) {
-    const { adapter, ...media } = config;
+    const { adapter, basePath, ...media } = config;
+    const signer = adapter.getSignedUrl?.bind(adapter);
     return {
         adapter,
         store: (file, prefix, entityId) => processAndStore(adapter, file, prefix, entityId, media),
@@ -11,12 +13,21 @@ export function createMediaStore(config) {
         serve: (key) => serveMedia(adapter, key),
         url: (key, size = 'original') => adapter.getUrl(variantKey(key, size)),
         signedUrl: (key, size = 'original', expiresIn) => {
-            const s3 = adapter;
-            if (!s3.getSignedUrl) {
+            if (!signer) {
                 return Promise.reject(new Error('signedUrl needs an S3 adapter (getSignedUrl)'));
             }
-            return s3.getSignedUrl(variantKey(key, size), expiresIn);
+            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,3 +1,4 @@
+/// <reference types="node" preserve="true" />
 export type ImageSize = 'original' | 'thumbnail' | 'medium' | 'large';
 /** What `StorageAdapter.get` resolves for an existing object. */
 export interface StorageObject {
@@ -75,6 +76,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,2 +1,3 @@
 // packages/svelte-media/src/lib/core/types.ts
+/// <reference types="node" preserve="true" />
 export {};

package/dist/index.d.ts

@@ -1,4 +1,2 @@
 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

@@ -2,5 +2,7 @@
 // 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, 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';
+// ImageUpload / ImageGallery left the public API at 1.0: in two consuming
+// apps neither was ever rendered, and this package's own changelog records
+// the surface shipping broken twice precisely because nothing consumed it.
+// The files remain for the demo; re-exporting later is an additive minor.

package/dist/server/index.d.ts

@@ -1,6 +1,10 @@
 export type { LocalConfig } from '../core/local-adapter.js';
 export { createS3Adapter } from '../core/adapter.js';
 export { createLocalAdapter } from '../core/local-adapter.js';
+export { adapterFromEnv } from '../core/env.js';
+export type { EnvAdapterOptions, EnvSource } from '../core/env.js';
+export { cachedImage, fetchImage, toWebp } from '../core/remote-images.js';
+export type { CachedImageOptions, FetchImageOptions, ImageBytes } from '../core/remote-images.js';
 export { processAndStore, deleteMedia, deleteMediaByKey, getMediaUrl } from '../core/process.js';
 export { serveMedia } from '../core/serve.js';
 export { createMediaStore } from '../core/store.js';

package/dist/server/index.js

@@ -1,6 +1,8 @@
 // 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 { adapterFromEnv } from '../core/env.js';
+export { cachedImage, fetchImage, toWebp } from '../core/remote-images.js';
 export { processAndStore, deleteMedia, deleteMediaByKey, getMediaUrl } from '../core/process.js';
 export { serveMedia } from '../core/serve.js';
 export { createMediaStore } from '../core/store.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomideusz/svelte-media",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "description": "Image upload, processing, and S3-compatible storage for Svelte 5 apps.",
   "type": "module",
   "sideEffects": false,
@@ -24,19 +24,12 @@
     "!dist/**/*.test.*",
     "!dist/**/*.spec.*"
   ],
-  "scripts": {
-    "dev": "vite dev",
-    "build": "vite build",
-    "package": "svelte-kit sync && svelte-package",
-    "prepublishOnly": "npm run package",
-    "preview": "vite preview",
-    "prepare": "svelte-kit sync || echo ''",
-    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
-    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
-    "test": "vitest run --passWithNoTests",
-    "test:watch": "vitest"
+  "imports": {
+    "#lib": "./src/lib",
+    "#lib/*": "./src/lib/*"
   },
   "peerDependencies": {
+    "@types/node": ">=20",
     "svelte": "^5.0.0"
   },
   "dependencies": {
@@ -46,16 +39,17 @@
     "sharp": "^0.34.5"
   },
   "devDependencies": {
-    "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.69.1",
-    "@sveltejs/package": "^2.5.8",
-    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@sveltejs/adapter-auto": "8.0.0-next.3",
+    "@sveltejs/adapter-vercel": "7.0.0-next.6",
+    "@sveltejs/kit": "3.0.0-next.23",
+    "@sveltejs/package": "3.0.0-next.7",
+    "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "@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"
+    "typescript": "^6.0.3",
+    "vite": "^8.2.1",
+    "vitest": "^4.1.10"
   },
   "keywords": [
     "svelte",
@@ -69,5 +63,20 @@
     "type": "git",
     "url": "https://github.com/nomideusz/svelte-media"
   },
-  "homepage": "https://svelte-media-gamma.vercel.app/"
-}
+  "homepage": "https://svelte-media-gamma.vercel.app/",
+  "peerDependenciesMeta": {
+    "@types/node": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "package": "svelte-kit sync && svelte-package",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}