This page is the storage and processing pipeline. Cropping in the admin is the Image editor. Upload and download routes are the Media API.

The SveltyCMS Media system is a decoupled, performance-first engine. Built with Svelte 5 and Sharp.js, it prioritizes native Node/Bun utilities over heavy third-party dependencies to ensure sub-millisecond latency and reduced bundle size.

🏗️ Layered Architecture

The system follows a strict 4-layer architecture to ensure storage and framework portability.

JSON Path Media Filter

Gallery filtering supports a small JSON-path expression language (client + server + DB).

Syntax

metadata.camera = Canon
metadata.camera ~ canon
metadata.iso >= 400
metadata.tags[0] = nature
metadata.camera = Canon; metadata.iso > 100

Operators: = / ==, !=, ~ / *= (contains), >, <, >=, <=. Multi-clause AND via ; or &&.

Shareable URL example: /mediagallery?folderId=…&jsonPath=metadata.camera%20%3D%20Canon

DB-native pushdown (large libraries)

When options.jsonPath is set on media.files.getByFolder:

Only simple metadata.* paths (no array indices) are pushed to the DB. Array paths (metadata.tags[0]) and non-metadata fields stay as in-memory post-filters so pagination remains correct when every clause is native.

Implementation:

• Parser: src/utils/json-path-filter.ts
• SQL/Mongo builders: src/databases/core/media-json-path.ts
• Unit: tests/unit/utils/json-path-filter.test.ts, tests/unit/databases/media-json-path.test.ts
• Integration: tests/integration/api/media-jsonpath.test.ts (?jsonPath= reduces load payload)

Upload Progress & Cancel

Large batches still use /api/media/stream when over STREAM_UPLOAD_THRESHOLD_BYTES (10 MB).

🛡️ Published-Reference Protection (Media Integrity Gate)

The media system prevents mutation of assets referenced by published content entries. This protects against broken references on live pages.

How It Works

1. Service Layer (media-service.server.ts): getPublishedReferences() scans all collection schemas for entries with status: "publish" that reference a given media ID (by ID, path, URL, or embedded object reference).

2. Handler Layer (handlers/media.ts): A checkMediaNotReferencedByPublishedContent() helper is called in all 6 mutation handlers before performing the operation. Returns 409 Conflict with details identifying which content entries reference the asset.

3. UI Layer (media-grid.svelte, media-table.svelte): Edit/delete buttons are disabled with contextual tooltip “Referenced by published content”. A lock badge appears at the top-left of affected media cards.

4. Server Load (+page.server.ts): Batched Promise.allSettled pre-checks all visible media items for published references before rendering.

Gated Operations

Error Response Format

{
  "error": {
    "message": "Cannot modify asset: referenced by published content - \"Blog Post\" in \"Posts\" (featuredImage) and 2 more",
    "code": "MEDIA_REFERENCED_BY_PUBLISHED_CONTENT"
  }
}

🚀 The Media Pipeline (4-Stage Workflow)

SveltyCMS employs a high-performance ingestion and delivery pipeline designed for massive scale and resilience.

Phase I: Ingestion (Client-Side & Hashing)

• Canvas 2D Optimization: [Client-Only] Large images are downscaled to a 1920×1080 bounding box and re-encoded to WebP directly in the browser before upload, saving bandwidth (local-upload.svelte → canvas-image-optimizer.ts). No GPU API is involved; browser WebGPU is only used by the LiteRT.js AI client.
• Smart Upload Routing (upload-client.ts): The gallery and dedicated upload page route payloads automatically — files or batches under 10 MB use the SvelteKit form action (?/upload); larger payloads stream to POST /api/media/stream with the folder field preserved. Both paths share one hard ceiling: the dispatcher bounds the request at API_MAX_BODY_SIZE_BYTES (15 MB, Content-Length and chunked alike) and parseMultipartStream receives the same cap for maxFileSize/maxTotalSize, aborting incrementally with 413 PAYLOAD_TOO_LARGE instead of buffering toward the parser defaults. Files between 6 MB and 15 MB take the TUS resumable lane (POST /api/media/tus + PATCH) so a reload or network drop resumes from the last committed offset; resumable: false restores the legacy routing.
• Direct-to-storage (S3 / R2): POST /api/media/upload-instructions issues a 15-minute SigV4 presigned PUT for a tenant-scoped staging key plus an HMAC token; POST /api/media/direct-upload/complete downloads the staged object, enforces the declared size, re-sniffs MIME (polyglot rejection), and runs the normal ingestion path. Local and Cloudinary installs fall back to TUS because no privileged storage endpoint is exposed. Contract: Direct & Resumable Uploads.
• Hash-First Approach: Every file is identified by the full 64-character hex SHA-256 digest of its bytes (hashFileContent() in src/utils/media/media-processing.server.ts). The hash is both the deduplication key and the storage directory of the file: {tenantId}/{hash}/original/<name>-<hash>.<ext>. The lookup happens before any derivative work and is scoped to the tenant — see Storage & Deduplication below.
• SlimSniffer + unified allowlist: slim-sniffer.server.ts (~2KB, no mime-types/mrmime) inspects magic bytes. Uploads use isAllowedUploadMime() (from MIME_MAP, minus scriptable/office types) and assertMimeAgreement() at write time. /files resolves Content-Type via extension → stored MIME → 512-byte sniff. Remote imports and saveRemoteMedia share resolveRemoteAssetMime(). All media responses send X-Content-Type-Options: nosniff.

Phase II: Processing (Deep Metadata & AI)

• Deep Metadata Extraction (opt-in): EXIF/IPTC/XMP, dominant colour and the 32 px WebP placeholder are extracted by MediaProcessingService.getMetadata() — called by POST /api/media/process and the SDK, not on every serve. The deep pass is more than a header read: metadata() plus stats() and a resize(32,32).webp() thumbnail (a full decode). Results are cached 24 h per file hash; fastPath: true returns the header-only fields (format, width, height, space, channels) without the decode.
• Derivative ladder (SIZES): saveResized() (media-storage.server.ts) writes one output per configured SIZES step into {tenantId}/{size}/<name>-<hash>.<ext> — JPEG by default, see Derivative output format for the setting, the opt-ins and the measured cost. Two invariants hold: a step wider than the decoded source is dropped (plus withoutEnlargement at the encoder), so a 400 px icon produces the 200 px step only, and each resolved path is written once — a source that is already WebP no longer encodes its own primary twice. The thumbnails map records the encoder’s real output dimensions; steps that were clamped away are simply absent, which mediaUrl/mediaDisplayUrl fall back from. Measured 2026-09-22: a 400 px source went from 8 files / 16,984 B to 2 files / 600 B.
• Responsive variants (deferred coalescer): after the record exists, deferred jobs derive thumbnail/card/default presets under {tenantId}/{hash}/variants/{preset}-{width}.{format} through a single-flight FIFO coalescer (variant-job-scheduler.server.ts, bounded by SVELTY_VARIANT_JOBS, default 2). Concurrent uploads of identical bytes share a single preset pipeline run, and bulk imports queue in waves to protect memory and CPU. Every upload lands with metadata.processingStatus: "processing"; the job flips it to ready (or failed, with processingError) in the media document. Full consolidation of this pass into the SIZES ladder is tracked in 2026 Roadmap.
• AI-Native Tagging [WIP]: A conceptual background task that hooks into local Ollama (llava) for privacy-first image analysis.
• Document Thumbnails: Automated extraction of PDF first-pages (requires imagemagick).

Phase III: Storage & Deduplication

• Deduplication Engine: After the hash is computed (and before any derivative work), the service looks the hash up scoped to the tenant (media.files.getByHash with tenantId — no cross-tenant reuse). On a hit it verifies that the record’s original and every derivative path it advertises still exist; when they do, the existing record is reused, the deferred variant job is never scheduled, and the upload returns after at most one plain file copy (only when the same bytes arrive under a different filename, so the patched path stays truthful). When a file is missing — remove() unlinks files rather than directories, and a GC sweep can drop them — the row is repaired in place (original rewritten, ladder re-derived, metadata merged) instead of being returned with URLs that 404, and never duplicated into a second row.
• Hybrid Storage: Supports Local, S3, and R2 storage backends via the CloudStorage abstraction.
• ETag/304 Handling: Unified ETag strategy ensures high-performance browser caching. Cloud backends answer /files/** with a 302 redirect to the CDN public URL (with the object ETag when available, so If-None-Match can still 304); local storage streams the bytes itself. Because a dedupe hit writes nothing, the W/"size-mtime" ETag of an unchanged asset survives a re-upload — clients are not forced to re-download identical bytes.

Phase IV: Delivery & Transformation

• On-Demand Transforms: /files/**?w=&h=&q=&fmt= produces cached raster variants on the delivery route (no separate /api/media/* transform endpoint exists). See On-Demand Image Transforms below for the parameter contract, clamps, cache layout and fallback rules.
• Focal Points: Visual crosshair coordinates are injected into delivery APIs to support art-directed cropping in the frontend.
• Lazy Loading: lazy thumbnail decoding in media-grid.svelte / media-table.svelte keeps the gallery responsive with thousands of files using Svelte 5 runes.

Processing status, version retention & cleanup

Derivatives are content-addressed ({tenantId}/{hash}/…), so replacing a source with new bytes always produces a new key — a cached transform can never serve a stale original. The lifecycle layer (src/utils/media/media-lifecycle.server.ts) makes the surrounding metadata and storage collection honest:

The cleanup pass is dry-run first by design: { "dryRun": true } reports the version count and hash list it would release without touching the DB or storage.

Derivative output format

Upload-time derivatives (the SIZES ladder) are written in JPEG by default: the encoder — not the resize — dominates ladder cost, and JPEG is the cheapest encode of the three formats this pipeline can write.

Self-measured, 2026-09-27, this machine. The ladder runs its steps in parallel, so its wall time is the slowest single encode: JPEG at every step costs the same as the JPEG 1920 row, while AVIF is the most expensive option — 102–143 ms at 640 px alone, before any other step finishes.

The format comes from the public setting MEDIA_OUTPUT_FORMAT_QUALITY ({ format, quality }, quality default 80):

• Opting into WebP/AVIF — set the same record, e.g. { "format": "webp", "quality": 80 } or { "format": "avif", "quality": 50 }. The setup wizard seeds { "format": "jpeg", "quality": 80 } for new installs; the value is stored per tenant with the other public settings (setPublicSetting / cms.system.settings.set). Nested-object settings such as this one and IMAGE_SIZES are not part of the System Settings form yet.
• Existing installs keep what they stored. A site that already saved { "format": "webp" } keeps producing WebP until the value is changed — a stored setting always wins over the default.
• Fail safe: an absent or unrecognised format (e.g. heic) falls back to JPEG (normalizeDerivativeFormat() in media-models.ts), so derivatives are never skipped over a typo.
• Transparency is preserved: JPEG has no alpha channel, so a source whose decoded hasAlpha is true is written as WebP for that ladder instead of being flattened onto the encoder’s background.
• WebP sidecars belong to original mode — the pre-2026-09 pairing of a source-format primary with a modern-format alternative. An explicit jpeg/webp/avif writes exactly one file per step; a per-request alternative is available from the delivery route (/files/**?fmt=webp, or Accept negotiation).
• Unchanged: the original upload is stored byte-for-byte and never re-encoded, and the 32 px LQIP lives on its own rule (metadata.placeholder stays a WebP data-URI, media-processing.server.ts).

🚀 On-Demand Image Transforms

Added 2026-09-22 — /files/** honours w/h/q/fmt again with a real resize. Before this, the route ignored those parameters entirely and transferred the full original under any URL.

Transforms are cached: the variant is generated exactly once (single-flight), written next to the original, and every later request streams it from disk with an ETag + Cache-Control: immutable. Without w/h the route streams the original byte-for-byte — the parameters are opt-in and never change a plain asset URL.

Parameters

• Dimension ladder (TRANSFORM_DIMENSION_STEPS): 16, 24, 32, 48, 64, 96, 128, 160, 192, 240, 320, 384, 480, 640, 768, 960, 1280, 1600, 1920, 2560, 3840, filtered by MAX_OUTPUT_DIMENSION (6000 px default). Requests are clamped down to a step and never upscaled (withoutEnlargement), so a caller cannot allocate an arbitrary resolution or fill the variant cache with one file per pixel width.
• Quality ladder (TRANSFORM_QUALITY_STEPS): 50, 60, 70, 75, 80, 82, 85, 90. Encoder settings are shared with the upload-time variants (applyEncoder() in src/services/media/image-processor.ts), so quality stays consistent.
• Both ladders live in src/services/media/image-processor.ts; parsing is the pure parseTransformParams(searchParams, accept, sourceMime) helper.

/files/global/<hash>/original/photo-<hash>.jpg?w=300          → 240 px wide, source format
/files/global/<hash>/original/photo-<hash>.jpg?w=640&h=480&q=75
/files/global/<hash>/original/photo-<hash>.jpg?w=1280&fmt=avif
/files/global/<hash>/original/photo-<hash>.jpg?w=320          + Accept: image/webp → WebP variant

Cache layout

Variants reuse the existing variant store (src/services/media/image-variant-storage.ts):

{tenantId}/{hash}/variants/t{height}q{quality}-{width}.{format}
# e.g. global/9f2c…/variants/t0q82-320.webp

• The key is (hash, width, height, quality, format) — t0 means “height derived from the source aspect ratio”. hash is the content hash of the original bytes, so a variant can never belong to another asset.
• The key is derived from the original’s tenant-scoped path, never from a signed URL’s signature: authorization stays with the route’s tenant gate + signature validation (both run before any transform work), and differently-signed requests for the same tenant safely share one entry.
• Variant responses carry their own weak ETag, Last-Modified, immutable, Vary: Accept (the negotiated format depends on the request header) and X-Media-Transform: w{width}h{height}q{quality}.{format} for observability.

What is never transformed

Every skip logs at debug level and falls back to streaming the original — a broken or hostile ?w= can never fail the request (encoder errors, disk errors, oversized sources included).

Storage backends

• Local storage: transforms are generated and cached in Node (Sharp), one generation per variant, single-flight coalesced.
• s3 / r2 / cloudinary: unchanged — the route keeps its 302 redirect to the CDN public URL before any byte work, so transform parameters never pull the object through Node; on Cloudinary/Fastly-style CDNs the equivalent transform is applied CDN-side.

Where the code lives

📁 Virtual Folders & Drag-and-Drop Moves

Assets live in virtual folders: a logical folderId on each media row, not a physical directory tree. Folder definitions are stored as system virtual folders (/api/system-virtual-folder). Moving media updates metadata only — blobs and share URLs stay put.

Folder-tree mutations are cycle-guarded server-side: PATCH reorder rejects a move into the folder itself or one of its descendants, and the recursive path updater carries a visited set so a corrupt hierarchy cannot cause unbounded recursion.

Data model

Move pipeline

Equivalent drop targets

On desktop, sidebar and breadcrumb are first-class peers — same payload, same API, same result:

Mobile: limited room for the sidebar — users drag (or select + tap) onto breadcrumb parents. Desktop users may use either surface interchangeably.

Shared client module: src/utils/media/media-dnd.ts

• MIME: application/x-sveltycms-media-ids
• resolveMediaDragIds — Windows Explorer–style selection expansion
• beginMediaDrag / endMediaDrag — DataTransfer + multi-item ghost
• moveMediaToFolder — POST /api/media/move + mediaMoved document event

Server: handleMediaMove → MediaNamespace.move → dbAdapter.media.files.move.

Left sidebar context

On /mediagallery, the left sidebar shows virtual folders and a back-to-collections control (not dual Collections + Media section headers). On collection routes, only the collections tree is shown. See left-sidebar.svelte.

The folder list is owned by mediaFolderTree (src/stores/media-folder-tree.svelte.ts), a module singleton:

• One fetch per session. ensureLoaded() is used for first paint; moving between folders only updates ?folderId/the selected row, so the tree never refetches on navigation. load() is reserved for folderCreated / folderUpdated / folderDeleted events and the error-state retry.
• No two-stage paint. media-folders.svelte renders the loading state until hasLoaded, so a cold session never paints a childless “Media Root” that then expands.
• One tree chrome. media-folders.svelte and collections.svelte both consume the same TreeView styling (row surface, primary selection, indent, chevrons, compact rail) — media no longer has a separate visual variant.
• SPA navigation. Tree rows render as <a> for hover preload; the row handler cancels the anchor default when the node’s onClick owns navigation, otherwise stopPropagation() lets the browser fall back to a full document reload (which used to wipe the cached tree on every folder click).

🗂️ DAM Admin UI Integration

The DAM API endpoints are wired into native Svelte 5 admin surfaces — no third-party asset browser required.

Media Details Modal

media-details-modal.svelte is the asset control center with four tabs:

1. Info — Inline editable name, alt text, caption, and tags (PATCH /api/media/{id}).
2. Versions — Upload new version, restore historical copies, compare two versions with field-level diffs.
3. References — Live scan of collection entries referencing the asset (GET /api/media/references/{id}).
4. Share — Generate expiring, password-protected public links and revoke active tokens.

🔄 Asynchronous Processing & Job Queue

Heavy processing tasks (AI analysis, bulk variant generation, video transcoding) are decoupled from the main request/response cycle.

1. Immediate Success: The API returns a 202 Accepted status along with an OperationID.
2. Background Execution: The Job Queue Service picks up the task and executes it across multiple worker threads.
3. Polling/SSE: The client polls the /api/media/jobs/:id endpoint or listens via SSE for the completion event.
4. Metadata Update: Once complete, the MediaItem metadata in the database is atomically updated.
5. Crash recovery: Every polling worker reaps jobs that have been stuck in running for 15 minutes. They are requeued with pending, or marked failed once their attempts are exhausted, so a killed worker cannot strand a job forever.

🎨 Image Editor Integration

The gallery is deeply integrated with the canvas-based Image Editor:

• Non-Destructive Editing: Originals are preserved; edits are saved as linked variants.
• Interactive Focal Points: Visual crosshair selection for art-directed cropping.
• Watermark Caching: Pre-rendered watermark buffers are cached in-memory to avoid redundant re-scaling.
• Bounded Output: editor saves are capped at MAX_OUTPUT_DIMENSION (6000 px default, env-overridable). Normal-size edits still encode once; only oversized results take a second downscale pass so watermark/annotation coordinates stay correct.

⚡ Performance Benchmarks

For comprehensive performance details regarding media hashing, metadata extraction, and multi-scale resizing block times, please reference the SQLite Benchmarks.

📚 API Reference

For detailed developer endpoints (upload, transform, move, job polling, focal points), read the comprehensive Media Reference.

🔍 Media Reference Reverse-Index

Added 2026-07-16 — replaces O(n × entries) full-scan with O(1) indexed lookups.

Problem

getMediaReferences() and getPublishedReferences() previously scanned every entry in every collection for each query — O(n × entries) per call. On a CMS with 50 collections and 10,000 entries, this meant 500,000 field traversals per reference check.

Solution

MediaReferenceIndex (src/utils/media/media-reference-index.ts) is an in-memory reverse-index that maps media identifiers to the entries that reference them:

// First query triggers a full rebuild (lazy)
// Subsequent queries are O(1) Map lookups
const refs = await mediaService.getMediaReferences(mediaId);

Architecture

Content mutation (create/update/delete)
  → eventBus.emit(CONTENT_UPDATE)
    → referenceIndex.clear()  (cache invalidated)

Next getMediaReferences() call
  → lazy rebuildReferenceIndex()  (one full scan)
    → O(1) lookups for all subsequent queries

Design note: The index is in-memory only. On first query it performs a full scan (rebuild), then subsequent queries are O(1). For production with thousands of entries, consider a periodic rebuild via setInterval or stale-while-revalidate. The eventBus listener ensures the cache is invalidated on any content update.

📤 Streaming Upload Parser

Added 2026-07-16 — true streaming multipart parser with backpressure, replacing the previous TextDecoder→TextEncoder implementation that corrupted binary uploads.

Problem {#streaming-upload-problem}

The previous streaming-upload.ts had two critical bugs:

1. Binary corruption: TextDecoder→TextEncoder round-trip replaced non-UTF8 bytes with replacement characters
2. Not streaming: Read the entire request body into RAM before parsing — OOM on large files

Solution {#streaming-upload-solution}

A byte-level state machine (streaming-upload.ts) that processes ReadableStream chunks incrementally:

// Real consumer (routes/api/[...path]/handlers/media.ts): the parser surfaces each part's
// ReadableStream; the route accumulates it under the 15 MB cap and writes one buffer —
// the StorageAdapter interface is `upload(data, relativePath)`, there is no uploadStream().
await parseMultipartStream(request, {
  onFile: async ({ filename, stream }) => {
    const chunks: Uint8Array[] = [];
    // …read with a running size check, then:
    await getStorageAdapter().upload(Buffer.concat(chunks), `global/${hash}/original/${filename}`);
  },
});

🛡️ Type-Safe Media Models

Refactored 2026-07-16 — discriminated union with type guards, DTO types, and exhaustiveness checking.

Design

media-models.ts uses as const maps (not enums) for tree-shakable, JSON-safe value lists. Each map doubles as the runtime valid-value list:

// Type guards — narrow discriminated union at runtime
if (isMediaImage(item)) item.width;           // MediaImage
if (isStoredMedia(item)) item.hash;           // StoredMedia (excludes remote video)
if (isMediaOfType(item, MediaType.Video)) item.duration; // MediaVideo

// DTO types — server-assigned fields rejected at compile time
const draft: NewMedia<MediaImage> = { ... };  // no _id, hash, url, createdBy
const patch: MediaPatch = { alt: "photo" };   // PATCH-safe fields only

// Exhaustiveness — add a new media type and every switch fails to compile
switch (item.type) {
  case MediaType.Image:    return item.width;
  case MediaType.RemoteVideo: return item.provider;
  // ...
  default: return assertNever(item);
}

🚀 Media Caching Layer

The media engine uses process-local TTL caches for repeated deterministic operations. These are separate from the global dual-layer cache (L1 LRU + L2 Redis) — media caches are smaller, shorter-lived, and scoped to their module.

Design decisions

• URL cache: Deterministic — same path always produces same URL. 10k entries covers all thumbnails + variants in a typical gallery view. LRU eviction via oldest-entry deletion at threshold.
• Metadata cache: File hash → metadata map. 24h TTL because image metadata never changes for the same bytes. Callers that already computed the hash (e.g., upload pipeline) pass it via options.hash to skip re-hashing.
• Negative existence cache: Short 10s TTL — prevents repeated adapter calls during upload validation without stale false negatives. Paths a dedupe hit depends on (the original and every derivative it advertises) are verified with refresh: true, so a cached positive can never mask a file that a GC sweep removed.
• Watermark cache: Watermarks rarely change. 5min TTL avoids re-fetching on every watermark tool open.

All caches use plain Map with timestamp-based expiry — no external dependencies, no serialization overhead, zero allocation on hit.

🧪 Verification & Benchmarks

The media pipeline’s correctness and latency properties are asserted through dedicated unit suites, integration tests, and benchmark rows:

Related

• Architecture Overview
• Media Reference (API) — POST /api/media/move, folders, DAM endpoints
• Media Sharing Endpoint — share links survive virtual folder moves
• Security Overview
• State Management