@calmlens/sdk 0.16.3 → 0.18.0

package/esm/server.js

@@ -1,370 +1,4 @@
-import { a as CALMLENS_ERROR_CODES, c as invalidArgument, i as isReactNativeRuntime, l as invalidConfig, o as CalmLensError, r as isBrowserRuntime, s as SDK_ERROR_CODES, t as SDK_VERSION } from "./CalmLensVersion-DcifRKsx.js";
+import { D as CALMLENS_ERROR_CODES, O as CalmLensError, c as DEFAULT_CDN_BASE_URL, i as SDK_VERSION, n as MODERATION_CONTEXT_USED_ITEMS, r as selectModerationContextItems, t as MODERATION_CONTEXT_USED_CHARACTERS, u as getAssetUrl } from "./ModerationContextLimits-BaX2QnU8.js";
 import "./index.js";
-import { a as parseWebhookEvent, i as WEBHOOK_TIMESTAMP_HEADER, l as stringifyJsonCanonical, n as WEBHOOK_SIGNATURE_HEADER, o as verifyWebhookSignature, r as WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, s as signUploadTokenWithApiKey, t as WEBHOOK_DELIVERY_HEADER } from "./CalmLensWebhooks-BvGyk5d3.js";
-import { f as sleep, l as validateRequestOptions, n as encodePathSegment, o as toTextAssetOptions, r as pollForDecision, s as transformSelector, t as appendCdnSelector, u as validateServerClientOptions } from "./CalmLensUtils-DsF8Aa_x.js";
-import { a as newIdempotencyKey, i as invalidPayload, n as expectAsset, o as prepareSubmitAssetOptions, s as resolveConnectionOptions, t as CalmLensConnection } from "./CalmLensConnection-XTqmlwzG.js";
-const getEnsureLensCacheKey = (options) => stringifyJsonCanonical({
-	identifier: options.identifier,
-	name: options.name,
-	description: options.description ?? null,
-	type: options.type,
-	active: options.active,
-	transforms: options.transforms ?? null,
-	version: options.version
-});
-const requireId = (value, name) => encodePathSegment(value, name);
-const inspectSymbol = Symbol.for("nodejs.util.inspect.custom");
-/**
-* The CalmLens API client for your server, authenticated with a project API key. Create one per
-* project and reuse it; it holds no connections. Every method takes one options object and
-* throws `CalmLensError` on failure. Browsers and apps upload with `CalmLensAppClient` instead.
-*/
-var CalmLensServerClient = class CalmLensServerClient {
-	#apiKey;
-	#settings;
-	#lenses;
-	#connection;
-	/**
-	* Verifies that a webhook delivery came from CalmLens: checks the `v1=` HMAC-SHA256 in
-	* `x-calmlens-signature` over `"<x-calmlens-timestamp>.<raw body>"` and rejects timestamps
-	* more than `toleranceSeconds` (default 300) from now, which stops replayed deliveries.
-	* Also exported as `verifyWebhookSignature`; `parseWebhookEvent` verifies and parses.
-	*
-	* @example
-	* ```ts
-	* const payload = await request.text();
-	* const isValid = await CalmLensServerClient.verifyWebhookSignature({
-	*   payload,
-	*   headers: request.headers,
-	*   secret: process.env.CALMLENS_WEBHOOK_SECRET!,
-	* });
-	* ```
-	*/
-	static async verifyWebhookSignature(options) {
-		return verifyWebhookSignature(options);
-	}
-	constructor(options, lenses) {
-		validateServerClientOptions(options);
-		if ((isBrowserRuntime() || isReactNativeRuntime()) && !options.dangerouslyAllowBrowser) throw invalidConfig("CalmLensServerClient is running in a browser or app, where anyone could read the API key. Call CalmLens from your server, upload from the browser or app with CalmLensAppClient, or set dangerouslyAllowBrowser: true for trusted internal tools.");
-		const { apiKey, ...rest } = options;
-		this.#apiKey = apiKey;
-		this.#settings = {
-			...resolveConnectionOptions(rest),
-			cdnBaseUrl: (rest.cdnBaseUrl ?? `https://cdn.calmlens.com/v1`).replace(/\/+$/, "")
-		};
-		this.#lenses = lenses ?? {
-			ensuredLenses: /* @__PURE__ */ new Map(),
-			pendingEnsureLenses: /* @__PURE__ */ new Map()
-		};
-		this.#connection = new CalmLensConnection(this.#settings, apiKey);
-	}
-	/**
-	* A client with different cancellation, deadlines or retries for the calls made through it,
-	* sharing this client's credentials and lens cache. This client is unchanged.
-	*/
-	withRequestOptions(options) {
-		validateRequestOptions(options);
-		return new CalmLensServerClient({
-			...this.#settings,
-			...options,
-			apiKey: this.#apiKey
-		}, this.#lenses);
-	}
-	/** Keeps the API key out of `console.log`, `util.inspect` and `JSON.stringify`. */
-	[inspectSymbol]() {
-		const { projectId, baseUrl } = this.#settings;
-		return `CalmLensServerClient { projectId: ${JSON.stringify(projectId)}, baseUrl: ${JSON.stringify(baseUrl)} }`;
-	}
-	toJSON() {
-		const { projectId, baseUrl, cdnBaseUrl } = this.#settings;
-		return {
-			projectId,
-			baseUrl,
-			cdnBaseUrl
-		};
-	}
-	get projectPath() {
-		return `/projects/${encodeURIComponent(this.#settings.projectId)}`;
-	}
-	request(method, path, options = {}) {
-		return this.#connection.json(method, path, options);
-	}
-	async submitAsset(options, queue) {
-		const body = prepareSubmitAssetOptions(options);
-		const uploadsPath = `${this.projectPath}/assets`;
-		if ("content" in body || "part" in body) return expectAsset(await this.#connection.submitRawUpload(uploadsPath, body, queue));
-		const { idempotencyKey, ...fields } = body;
-		const data = await this.#connection.json("POST", uploadsPath, {
-			query: { queue },
-			body: fields,
-			idempotencyKey: idempotencyKey ?? newIdempotencyKey()
-		});
-		return expectAsset(data);
-	}
-	get cdn() {
-		return {
-			/**
-			* Builds a CDN URL for asset content or a preview, without a request. Private assets
-			* need a signed URL (`assets.createSignedUrl`) or an authenticated request.
-			*/
-			getAssetUrl: ({ assetIdentifier, ...options }) => {
-				const resource = options.resource ?? "content";
-				const { projectId } = this.#settings;
-				const url = `${this.#settings.cdnBaseUrl}/assets/${encodeURIComponent(projectId)}/${requireId(assetIdentifier, "Asset identifier")}/${resource}`;
-				return appendCdnSelector(url, options);
-			},
-			/**
-			* Fetches asset content or a preview from the CDN with the client's API key, and returns
-			* the `Response` as soon as headers arrive, so the body streams. Non-2xx responses are
-			* returned, not thrown; `timeoutMs` covers only the wait for headers.
-			*/
-			serve: async ({ assetIdentifier, init, ...urlOptions }) => {
-				const url = this.cdn.getAssetUrl({
-					assetIdentifier,
-					...urlOptions
-				});
-				const method = init?.method?.toUpperCase() ?? "GET";
-				const { response } = await this.#connection.transport.send({
-					method,
-					url,
-					init,
-					timeoutMs: this.#connection.timeoutMs,
-					deadline: "headers",
-					fetch: this.#settings.cdnFetch
-				}, { allowHttpErrors: true });
-				return response;
-			}
-		};
-	}
-	get text() {
-		return { 
-		/**
-		* Moderates text and waits for the decision. Sends `text` as `text/plain` content named
-		* `text` unless you pass `name`.
-		*/
-moderate: async (options) => this.buildAssets().moderate(toTextAssetOptions(options)) };
-	}
-	/** Assets: uploads, moderation and management. */
-	get assets() {
-		return this.buildAssets();
-	}
-	/**
-	* Signs upload tokens on your server, so a browser or app can upload through an upload preset
-	* that requires one. Signing happens locally with your API key: it makes no request.
-	*/
-	get uploadTokens() {
-		return { 
-		/**
-		* Signs a single-use token for one upload through `uploadPresetId`. Give `token` to the
-		* browser or app, which passes it to `CalmLensAppClient` as `token`.
-		*/
-sign: async (options) => {
-			return signUploadTokenWithApiKey(this.#apiKey, options);
-		} };
-	}
-	buildAssets() {
-		return {
-			/** Searches accessible assets by keyword or a natural-language description. */
-			search: async (options) => this.request("GET", `${this.projectPath}/assets/search`, { query: options }),
-			/** Lists one page of the project's assets, with optional filter and ordering. */
-			list: async (options = {}) => this.request("GET", `${this.projectPath}/assets/page`, { query: options }),
-			/**
-			* Yields every asset matching `options`, fetching pages as needed. The cursor keeps the position
-			* stable when other assets are inserted or deleted.
-			*/
-			iterate: (options = {}) => this.iteratePages((cursor) => this.buildAssets().list({
-				...options,
-				cursor
-			})),
-			/** Retrieves an asset with its status and moderation report. */
-			retrieve: async ({ assetId }) => this.request("GET", `/assets/${requireId(assetId, "Asset ID")}`),
-			/** Updates an asset's editable fields. */
-			update: async ({ assetId, ...body }) => this.request("PATCH", `/assets/${requireId(assetId, "Asset ID")}`, { body }),
-			/** Lists one page of the assets extracted from a website or multimedia document. */
-			listChildren: async ({ assetId, ...options } = {}) => this.request("GET", `/assets/${requireId(assetId, "Asset ID")}/children`, { query: options }),
-			/** Yields every child of an asset, fetching pages as needed. */
-			iterateChildren: (options) => {
-				requireId(options?.assetId, "Asset ID");
-				return this.iteratePages((cursor) => this.buildAssets().listChildren({
-					...options,
-					cursor
-				}));
-			},
-			/**
-			* Uploads an asset and queues it for moderation, returning immediately with processing
-			* status `processing` (or `uploading` for the first multipart part). Retried safely with an
-			* `Idempotency-Key`.
-			*/
-			create: async (options) => this.submitAsset(options, true),
-			/**
-			* Uploads an asset and waits for its moderation decision. Audio and video still finish
-			* in the background. Retried safely with an `Idempotency-Key`.
-			*/
-			moderate: async (options) => {
-				if (options && "content" in options && "plainText" in options.content && (typeof options.content.plainText !== "string" || !options.content.plainText.trim())) throw invalidPayload("Text to moderate must be a non-empty string");
-				return this.submitAsset(options, false);
-			},
-			/**
-			* Uploads the next part of a multipart upload. The upload's queue mode, chosen when it
-			* started, applies when the final part arrives; pass `queue` to override it.
-			*/
-			uploadPart: async ({ assetId, ...options }) => {
-				const encodedAssetId = requireId(assetId, "Asset ID");
-				return expectAsset(await this.#connection.uploadPart(`/assets/${encodedAssetId}/part`, options));
-			},
-			/**
-			* Creates a short-lived signed CDN URL, so browsers can load private content without
-			* an API key.
-			*/
-			createSignedUrl: async ({ assetId, ...options }) => {
-				const encodedAssetId = requireId(assetId, "Asset ID");
-				return this.request("POST", `/assets/${encodedAssetId}/signed-url`, { body: {
-					resource: options.resource ?? "content",
-					expiresInSeconds: options.expiresInSeconds ?? 900,
-					lens: options.lens,
-					transform: transformSelector(options.transform)
-				} });
-			},
-			/** Moves an asset into a folder, or to the project root with `folderId: null`. */
-			move: async ({ assetId, folderId }) => this.request("POST", `/assets/${requireId(assetId, "Asset ID")}/move`, { body: { folderId } }),
-			/**
-			* Processes an asset that failed (processing status `failed`) again. It returns to
-			* `processing` and is
-			* moderated like a new upload; its content must still be stored.
-			*/
-			retry: async ({ assetId }) => this.request("POST", `/assets/${requireId(assetId, "Asset ID")}/retry`),
-			/**
-			* Waits until an asset's `moderation.status` is `approved` or `rejected`, or its
-			* `processing.status` is `failed`, and returns that asset, checking every few seconds. Rejects with `sdk/timeout` if there is no
-			* decision within `timeoutMs` (default 60000). Webhooks report decisions without polling.
-			*/
-			waitForDecision: async ({ assetId, ...options }) => {
-				requireId(assetId, "Asset ID");
-				const client = options.signal ? this.withRequestOptions({ signal: options.signal }) : this;
-				return pollForDecision(() => client.assets.retrieve({ assetId }), options, sleep);
-			},
-			/**
-			* Removes an asset's stored content (source, preview and retained extracted text) while
-			* keeping the asset record, metadata and moderation report. The returned asset has
-			* `storageDeletedAt` set; the CDN no longer serves it.
-			*/
-			deleteContent: async ({ assetId }) => this.request("DELETE", `/assets/${requireId(assetId, "Asset ID")}/content`),
-			/** Deletes an asset record together with its stored content. */
-			delete: async ({ assetId }) => {
-				await this.request("DELETE", `/assets/${requireId(assetId, "Asset ID")}`);
-			}
-		};
-	}
-	get events() {
-		return {
-			/**
-			* Lists project events after a cursor, oldest first. Call without `after` to get a cursor
-			* for "now", then poll with the returned `cursor`. Webhook deliveries carry the same events
-			* reshaped as `{ id, type, createdAt, projectId, data }`.
-			*/
-			list: async (options = {}) => this.request("GET", `${this.projectPath}/events`, { query: { ...options } }),
-			/**
-			* Yields pages of events after `after` until no more are waiting. Save each page's
-			* `cursor` to resume later. Without `after`, yields one empty page whose cursor is "now".
-			*/
-			pages: (options = {}) => this.iterateEventPages(options)
-		};
-	}
-	async *iterateEventPages(options) {
-		let after = options.after;
-		for (;;) {
-			const page = await this.events.list({
-				...options,
-				after
-			});
-			yield page;
-			if (!page.hasMore || page.cursor === after) return;
-			after = page.cursor;
-		}
-	}
-	async *iteratePages(listPage) {
-		let cursor;
-		for (;;) {
-			const page = await listPage(cursor);
-			yield* page.items;
-			if (!page.nextCursor || !page.hasMore || page.items.length === 0) return;
-			cursor = page.nextCursor;
-		}
-	}
-	get folders() {
-		return {
-			/** Lists every folder in the project. */
-			list: async () => (await this.request("GET", `${this.projectPath}/folders`)).folders,
-			retrieve: async ({ folderId }) => this.request("GET", `/folders/${requireId(folderId, "Folder ID")}`),
-			/** Creates a folder at the project root or inside `parentId`. */
-			create: async (options) => this.request("POST", `${this.projectPath}/folders`, { body: options }),
-			update: async ({ folderId, ...body }) => this.request("PATCH", `/folders/${requireId(folderId, "Folder ID")}`, { body }),
-			/** Deletes an empty folder; throws `folder/not-empty` otherwise. */
-			delete: async ({ folderId }) => {
-				await this.request("DELETE", `/folders/${requireId(folderId, "Folder ID")}`);
-			},
-			/** Moves a folder under `parentId`, or to the project root with `parentId: null`. */
-			move: async ({ folderId, parentId }) => this.request("POST", `/folders/${requireId(folderId, "Folder ID")}/move`, { body: { parentId } })
-		};
-	}
-	/**
-	* Create a named lens at any positive version, or update it with a greater version.
-	* Supplying the same definition and version is idempotent.
-	*/
-	async ensureLens(options) {
-		if (!options?.identifier) throw invalidArgument("Lens identifier is required");
-		const [lens] = await this.ensureLenses({ lenses: [options] });
-		return lens;
-	}
-	/**
-	* Create or update several named lenses. New definitions are sent in one API request, or in
-	* consecutive requests of at most {@link ENSURE_LENSES_MAX_PER_REQUEST} definitions, in order.
-	* Each lens follows the same versioning and idempotency rules as ensureLens().
-	*/
-	async ensureLenses({ lenses }) {
-		if (!Array.isArray(lenses) || lenses.length === 0) throw invalidArgument("At least one lens is required");
-		if (lenses.some((option) => !option?.identifier)) throw invalidArgument("Lens identifier is required");
-		const { ensuredLenses, pendingEnsureLenses } = this.#lenses;
-		const missingOptions = [];
-		const missingKeys = /* @__PURE__ */ new Set();
-		for (const option of lenses) {
-			const cacheKey = getEnsureLensCacheKey(option);
-			if (!ensuredLenses.has(cacheKey) && !missingKeys.has(cacheKey)) {
-				missingKeys.add(cacheKey);
-				missingOptions.push(option);
-			}
-		}
-		if (missingOptions.length > 0) {
-			const batchCacheKey = JSON.stringify([...missingKeys].sort());
-			let pending = pendingEnsureLenses.get(batchCacheKey);
-			if (!pending) {
-				pending = this.submitEnsureLenses(missingOptions);
-				pendingEnsureLenses.set(batchCacheKey, pending);
-				pending.then(() => pendingEnsureLenses.delete(batchCacheKey), () => pendingEnsureLenses.delete(batchCacheKey));
-			}
-			await pending;
-		}
-		return lenses.map((option) => {
-			const lens = ensuredLenses.get(getEnsureLensCacheKey(option));
-			if (!lens) throw new CalmLensError(SDK_ERROR_CODES.INVALID_RESPONSE, { message: `CalmLens did not return lens "${option.identifier}"` });
-			return lens;
-		});
-	}
-	async submitEnsureLenses(options) {
-		for (let start = 0; start < options.length; start += 100) await this.submitEnsureLensesChunk(options.slice(start, start + 100));
-	}
-	async submitEnsureLensesChunk(options) {
-		const result = await this.request("PUT", `${this.projectPath}/lenses`, { body: { lenses: options } });
-		const returned = Array.isArray(result?.lenses) ? result.lenses : [];
-		if (returned.length !== options.length) throw new CalmLensError(SDK_ERROR_CODES.INVALID_RESPONSE, { message: `Expected ${options.length} lenses but CalmLens returned ${returned.length}` });
-		const { ensuredLenses } = this.#lenses;
-		for (const [index, lens] of returned.entries()) {
-			const optionsForLens = options[index];
-			if (lens?.identifier !== optionsForLens.identifier) throw new CalmLensError(SDK_ERROR_CODES.INVALID_RESPONSE, { message: `Expected lens "${optionsForLens.identifier}" at position ${index}` });
-			for (const [cacheKey, cachedLens] of ensuredLenses) if (cachedLens.identifier === optionsForLens.identifier) ensuredLenses.delete(cacheKey);
-			ensuredLenses.set(getEnsureLensCacheKey(optionsForLens), lens);
-		}
-	}
-};
-//#endregion
-export { CALMLENS_ERROR_CODES, CalmLensError, CalmLensServerClient, SDK_VERSION, WEBHOOK_DELIVERY_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, WEBHOOK_TIMESTAMP_HEADER, parseWebhookEvent, verifyWebhookSignature };
+import { a as WEBHOOK_TIMESTAMP_HEADER, c as verifyWebhookSignature, i as WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, n as WEBHOOK_DELIVERY_HEADER, o as isTestWebhookEvent, r as WEBHOOK_SIGNATURE_HEADER, s as parseWebhookEvent, t as CalmLensServerClient } from "./CalmLensServerClient-D80_mKpW.js";
+export { CALMLENS_ERROR_CODES, CalmLensError, CalmLensServerClient, DEFAULT_CDN_BASE_URL, MODERATION_CONTEXT_USED_CHARACTERS, MODERATION_CONTEXT_USED_ITEMS, SDK_VERSION, WEBHOOK_DELIVERY_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, WEBHOOK_TIMESTAMP_HEADER, getAssetUrl, isTestWebhookEvent, parseWebhookEvent, selectModerationContextItems, verifyWebhookSignature };

package/esm/styles.css

@@ -0,0 +1,147 @@
+/* Zero specificity, so a page's own --calmlens-* values win even on the same element. */
+:where(.calmlens-uploader, .calmlens-media) {
+  --calmlens-accent: #635bff;
+  --calmlens-accent-text: #fff;
+  --calmlens-radius: 12px;
+  --calmlens-border: color-mix(in srgb, currentColor 18%, transparent);
+  --calmlens-surface: color-mix(in srgb, currentColor 4%, transparent);
+  --calmlens-background: transparent;
+  --calmlens-muted: color-mix(in srgb, currentColor 72%, transparent);
+  --calmlens-success: #12a26f;
+  --calmlens-warning: #e8a317;
+  --calmlens-danger: #e5484d;
+  --calmlens-focus-ring: var(--calmlens-accent);
+  --calmlens-focus-width: 2px;
+  --calmlens-focus-offset: 2px;
+  box-sizing: border-box;
+  font: inherit;
+}
+.calmlens-uploader *, .calmlens-media * { box-sizing: border-box; }
+.calmlens-uploader { display: grid; gap: 12px; }
+.calmlens-uploader > [hidden] { display: none; }
+.calmlens-dropzone {
+  display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 16px;
+  padding: 40px 24px; text-align: center;
+  border: 1.5px dashed var(--calmlens-border); border-radius: var(--calmlens-radius);
+  background: var(--calmlens-surface); cursor: pointer;
+  transition: border-color 200ms ease-in-out, background-color 200ms ease-in-out;
+}
+.calmlens-dropzone:hover, .calmlens-dropzone:focus-within {
+  border-color: color-mix(in srgb, var(--calmlens-accent) 30%, transparent);
+  background: color-mix(in srgb, var(--calmlens-accent) 4%, transparent);
+}
+.calmlens-dropzone[data-dragging] {
+  border-color: var(--calmlens-accent);
+  background: color-mix(in srgb, var(--calmlens-accent) 9%, transparent);
+}
+.calmlens-dropzone[data-disabled] {
+  cursor: not-allowed; border-color: var(--calmlens-border); background: none; color: var(--calmlens-muted);
+}
+.calmlens-dropzone__icon {
+  display: grid; place-items: center; width: 48px; height: 48px; border-radius: 50%;
+  color: var(--calmlens-accent); background: color-mix(in srgb, var(--calmlens-accent) 10%, transparent);
+  transition: transform 200ms;
+}
+.calmlens-dropzone[data-disabled] .calmlens-dropzone__icon { color: inherit; background: var(--calmlens-surface); }
+.calmlens-dropzone[data-dragging] .calmlens-dropzone__icon { transform: scale(1.1); }
+.calmlens-dropzone__text { display: grid; gap: 4px; }
+.calmlens-dropzone__title { font-weight: 500; margin: 0; }
+.calmlens-dropzone__hint { font-size: 0.875em; margin: 0; color: var(--calmlens-muted); }
+.calmlens-button, .calmlens-icon-button { margin: 0; width: auto; text-transform: none; letter-spacing: normal; }
+.calmlens-button {
+  font: inherit; font-weight: 500; font-size: 0.875em; padding: 7px 14px; border-radius: 8px; cursor: pointer;
+  border: 1px solid var(--calmlens-accent); background: var(--calmlens-accent); color: var(--calmlens-accent-text);
+  white-space: nowrap; transition: background-color 150ms, border-color 150ms;
+}
+.calmlens-button:focus-visible, .calmlens-icon-button:focus-visible {
+  outline: var(--calmlens-focus-width) solid var(--calmlens-focus-ring); outline-offset: var(--calmlens-focus-offset);
+}
+.calmlens-button:hover:not(:disabled) { background: var(--calmlens-accent); filter: brightness(1.08); }
+.calmlens-button[data-variant="outline"] { background: none; color: inherit; border-color: var(--calmlens-border); }
+.calmlens-button[data-variant="outline"]:hover:not(:disabled) {
+  filter: none; background: color-mix(in srgb, var(--calmlens-accent) 8%, transparent); border-color: var(--calmlens-accent);
+}
+.calmlens-button[data-size="small"] { padding: 4px 10px; }
+.calmlens-button:disabled {
+  cursor: not-allowed; border-style: dashed; background: none; color: var(--calmlens-muted); border-color: var(--calmlens-border);
+}
+.calmlens-uploads { list-style: none; margin: 0; padding: 0; display: grid; gap: 8px; }
+.calmlens-upload {
+  display: grid; grid-template-columns: auto minmax(0, 1fr) auto; align-items: center; gap: 12px; padding: 12px;
+  border: 1px solid var(--calmlens-border); border-radius: var(--calmlens-radius); background: var(--calmlens-background);
+}
+/* A finished file's outcome is a dot in its status colour before the message. */
+.calmlens-upload[data-outcome] .calmlens-upload__message::before {
+  content: ""; display: inline-block; width: 8px; height: 8px; margin-right: 8px; border-radius: 50%;
+  vertical-align: 0.05em;
+}
+.calmlens-upload[data-outcome="accepted"] .calmlens-upload__message::before { background: var(--calmlens-success); }
+.calmlens-upload[data-outcome="restricted"] .calmlens-upload__message::before { background: var(--calmlens-warning); }
+.calmlens-upload[data-outcome="rejected"] .calmlens-upload__message::before { background: var(--calmlens-danger); }
+.calmlens-upload__thumb {
+  width: 40px; height: 40px; border-radius: 8px; object-fit: cover; display: grid; place-items: center;
+  background: var(--calmlens-surface); border: 1px solid var(--calmlens-border);
+  font-size: 0.6875em; font-weight: 700; text-transform: uppercase; overflow: hidden;
+}
+.calmlens-upload__thumb[data-kind="file"] { background: none; border: none; }
+.calmlens-upload[data-outcome="rejected"] img.calmlens-upload__thumb { filter: blur(6px); }
+.calmlens-upload__body { min-width: 0; display: grid; gap: 4px; }
+.calmlens-upload__name { font-weight: 500; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.calmlens-upload__size { font-size: 0.875em; color: var(--calmlens-muted); }
+.calmlens-upload__message { font-size: 0.875em; margin: 0; }
+.calmlens-progress {
+  height: 4px; border-radius: 2px; overflow: hidden; background: var(--calmlens-border); position: relative;
+}
+.calmlens-progress__bar {
+  position: absolute; inset: 0 auto 0 0; background: var(--calmlens-accent); border-radius: inherit;
+  transition: width 150ms;
+}
+.calmlens-progress:not([aria-valuenow]) .calmlens-progress__bar {
+  width: 35%; animation: calmlens-indeterminate 1.1s ease-in-out infinite;
+}
+@keyframes calmlens-indeterminate { from { left: -35%; } to { left: 100%; } }
+.calmlens-upload__actions { display: flex; gap: 8px; align-items: center; }
+.calmlens-icon-button {
+  display: grid; place-items: center; width: 30px; height: 30px; padding: 0; border-radius: 8px; cursor: pointer;
+  border: 1px solid transparent; background: none; color: inherit;
+}
+.calmlens-icon-button:hover { background: color-mix(in srgb, var(--calmlens-accent) 8%, transparent); border-color: var(--calmlens-border); }
+@media (prefers-reduced-motion: reduce) {
+  .calmlens-progress__bar, .calmlens-dropzone, .calmlens-dropzone__icon, .calmlens-media__content { transition: none; }
+  .calmlens-progress:not([aria-valuenow]) .calmlens-progress__bar { animation: none; left: 0; width: 100%; }
+}
+
+.calmlens-media {
+  position: relative; display: block; overflow: hidden; margin: 0; border-radius: var(--calmlens-media-radius, 0);
+  background: var(--calmlens-surface);
+}
+.calmlens-media__placeholder, .calmlens-media__content {
+  position: absolute; inset: 0; width: 100%; height: 100%; object-fit: var(--calmlens-fit, cover);
+  object-position: var(--calmlens-position, center);
+}
+.calmlens-media:not([data-sized]) .calmlens-media__content { position: relative; height: auto; }
+.calmlens-media:not([data-sized])[data-kind="gated"], .calmlens-media:not([data-sized])[data-kind="unavailable"],
+.calmlens-media:not([data-sized])[data-state="error"] { min-height: 160px; }
+.calmlens-media__placeholder { transform: scale(1.1); filter: blur(12px); }
+.calmlens-media__content { opacity: 0; transition: opacity 250ms; }
+.calmlens-media[data-state="loaded"] .calmlens-media__content { opacity: 1; }
+.calmlens-media[data-kind="video"] .calmlens-media__content, .calmlens-media[data-kind="audio"] .calmlens-media__content { opacity: 1; }
+.calmlens-media[data-kind="audio"] { background: none; }
+.calmlens-media[data-kind="audio"] .calmlens-media__content { position: static; height: auto; }
+.calmlens-media__notice {
+  position: absolute; inset: 0; display: grid; place-content: center; justify-items: center; gap: 6px;
+  padding: 12px; text-align: center; color: #fff; background: rgba(0, 0, 0, 0.45);
+}
+.calmlens-media__notice p { margin: 0; display: flex; gap: 6px; align-items: center; }
+/* Thumbnails keep the notice's icon and leave its text to screen readers. */
+.calmlens-media[data-sized] { container-type: inline-size; }
+@container (max-width: 119px) {
+  .calmlens-media__label, .calmlens-media__notice > strong, .calmlens-media__notice > p:not(:has(svg)) {
+    position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap;
+  }
+}
+.calmlens-media__notice strong { font-weight: 600; }
+.calmlens-media__notice .calmlens-button { margin-top: 4px; border-color: #fff; background: #fff; color: #111; }
+.calmlens-media[data-state="error"] .calmlens-media__notice, .calmlens-media[data-kind="unavailable"] .calmlens-media__notice {
+  color: inherit; background: var(--calmlens-surface);
+}

package/esm/svelte/CalmLensMedia.svelte

@@ -0,0 +1,134 @@
+<script lang="ts">
+  import { onMount } from "svelte";
+  import {
+    getMediaAspectRatio,
+    getMediaLoadKey,
+    getMediaState,
+    getMediaUnavailableMessage,
+    type MediaOptions,
+    type MediaProps,
+    resolveMediaProps,
+    resolveMessages,
+  } from "../ui.js";
+  import Icon from "./Icon.svelte";
+
+  let {
+    alt = "",
+    aspectRatio,
+    width,
+    height,
+    sizes,
+    averageColor,
+    fit,
+    position,
+    lazy = true,
+    fetchPriority,
+    controls = true,
+    messages: overrides,
+    onReveal,
+    ...options
+  }: MediaProps = $props();
+
+  const messages = $derived(resolveMessages(overrides));
+  // An `asset` fills in what isn't passed: the source, status and type, and its preview's size.
+  const view = $derived(
+    resolveMediaProps({ ...(options as MediaOptions), width, height, averageColor }),
+  );
+  const state = $derived(getMediaState(view));
+  const loadKey = $derived(getMediaLoadKey(state));
+  const ratio = $derived(
+    getMediaAspectRatio({ aspectRatio, width: view.width, height: view.height }),
+  );
+  let load: "loading" | "loaded" | "error" = $state("loading");
+  let image: HTMLImageElement | undefined = $state();
+
+  $effect.pre(() => {
+    void loadKey;
+    load = "loading";
+  });
+  onMount(() => {
+    // An image that loaded before hydration fires no load event.
+    if (image?.complete && image.naturalWidth > 0) load = "loaded";
+  });
+
+  const onError = () => {
+    load = "error";
+  };
+  const placeholderUrl = $derived(
+    state.kind === "audio" || state.kind === "unavailable" ? undefined : state.placeholderUrl,
+  );
+  const showPlaceholder = $derived(
+    placeholderUrl && (state.kind === "gated" || (state.kind === "image" && load !== "loaded")),
+  );
+  const failed = $derived(load === "error");
+</script>
+
+<figure
+  class="calmlens-media"
+  data-kind={state.kind}
+  data-state={load}
+  data-sized={ratio ? "" : undefined}
+  style:aspect-ratio={ratio}
+  style:background-color={view.averageColor}
+  style:--calmlens-fit={fit}
+  style:--calmlens-position={position}
+>
+  {#if showPlaceholder}
+    <img class="calmlens-media__placeholder" src={placeholderUrl} alt="" aria-hidden="true" />
+  {/if}
+  {#if state.kind === "image" && !failed}
+    {#key loadKey}
+      <img
+        bind:this={image}
+        class="calmlens-media__content"
+        src={state.src}
+        srcset={state.srcSet}
+        {sizes}
+        {alt}
+        width={view.width}
+        height={view.height}
+        loading={lazy ? "lazy" : undefined}
+        decoding="async"
+        fetchpriority={fetchPriority}
+        onload={() => (load = "loaded")}
+        onerror={onError}
+      />
+    {/key}
+  {:else if state.kind === "video" && !failed}
+    <!-- svelte-ignore a11y_media_has_caption -->
+    <!-- biome-ignore lint/a11y/useMediaCaption: captions are your app's to add -->
+    <video
+      class="calmlens-media__content"
+      src={state.src}
+      {controls}
+      playsinline
+      preload="metadata"
+      aria-label={alt || undefined}
+      onerror={() => (load = "error")}
+    ></video>
+  {:else if state.kind === "audio" && !failed}
+    <!-- biome-ignore lint/a11y/useMediaCaption: audio has no captions track to add here -->
+    <audio
+      class="calmlens-media__content"
+      src={state.src}
+      {controls}
+      preload="metadata"
+      aria-label={alt || undefined}
+      onerror={() => (load = "error")}
+    ></audio>
+  {/if}
+  {#if state.kind === "gated"}
+    <figcaption class="calmlens-media__notice">
+      <strong>{messages.sensitiveTitle}</strong>
+      <p>{messages.sensitiveBody}</p>
+      {#if onReveal}
+        <button type="button" class="calmlens-button" onclick={onReveal}>{messages.reveal}</button>
+      {/if}
+    </figcaption>
+  {/if}
+  {#if state.kind === "unavailable" || failed}
+    <figcaption class="calmlens-media__notice">
+      <p><Icon name="unavailable" /><span class="calmlens-media__label">{getMediaUnavailableMessage(state, messages)}</span></p>
+    </figcaption>
+  {/if}
+</figure>