@streamscloud/kit 0.30.0 → 0.32.0

package/dist/core/files/app-upload-activity.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { UploadingFile } from './upload-types';
+declare class AppUploadActivityContainer {
+    private _runs;
+    private _nextRunId;
+    /** Files of every in-flight run, including ones that already finished inside a still-running run. Deduplicated by id. */
+    get files(): UploadingFile[];
+    /** True while at least one run is in flight. Flips only on run start / end, never on a progress tick. */
+    get isUploading(): boolean;
+    /**
+     * Register an in-flight upload run and get its id back. `files` is called on every read, so pass
+     * an accessor over live state, not a snapshot. `UploadMediaStore.upload()` registers itself — call
+     * this directly only when uploading outside the store.
+     */
+    beginRun: (files: () => UploadingFile[]) => number;
+    /** End a run started with `beginRun` — always from a `finally`, or the run never leaves the list. */
+    endRun: (id: number) => void;
+}
+/** Reactive, app-wide view of what is uploading right now. Drives `UploadProgressToaster`. */
+export declare const AppUploadActivity: AppUploadActivityContainer;
+export {};

package/dist/core/files/app-upload-activity.svelte.js

@@ -0,0 +1,34 @@
+class AppUploadActivityContainer {
+    _runs = $state.raw([]);
+    _nextRunId = 0;
+    /** Files of every in-flight run, including ones that already finished inside a still-running run. Deduplicated by id. */
+    get files() {
+        const byId = new Map();
+        for (const run of this._runs) {
+            for (const file of run.files()) {
+                byId.set(file.id, file);
+            }
+        }
+        return [...byId.values()];
+    }
+    /** True while at least one run is in flight. Flips only on run start / end, never on a progress tick. */
+    get isUploading() {
+        return this._runs.length > 0;
+    }
+    /**
+     * Register an in-flight upload run and get its id back. `files` is called on every read, so pass
+     * an accessor over live state, not a snapshot. `UploadMediaStore.upload()` registers itself — call
+     * this directly only when uploading outside the store.
+     */
+    beginRun = (files) => {
+        const id = this._nextRunId++;
+        this._runs = [...this._runs, { id, files }];
+        return id;
+    };
+    /** End a run started with `beginRun` — always from a `finally`, or the run never leaves the list. */
+    endRun = (id) => {
+        this._runs = this._runs.filter((run) => run.id !== id);
+    };
+}
+/** Reactive, app-wide view of what is uploading right now. Drives `UploadProgressToaster`. */
+export const AppUploadActivity = new AppUploadActivityContainer();

package/dist/core/files/file-types.d.ts

@@ -13,6 +13,13 @@ export declare class AcceptFileType {
     static readonly webAssetImageOrVideo: string;
     static readonly webAssetIcon = "image/png";
 }
+/**
+ * Whether a MIME type names media a browser can present on its own — an image, a video or a
+ * sound. `false` for documents and archives, and for a blank type (`.heic`, `.mkv` and files with
+ * no extension often arrive with `file.type === ''`). Drives `UploadMediaStore`'s
+ * `{ preview: 'mime' }` mode.
+ */
+export declare const isPreviewableType: (type: string) => boolean;
 /**
  * `accept`-style matcher. Tokens may be MIMEs (`image/*`, `*\/*`, `application/pdf`) or
  * extensions (`.pdf`), case-insensitive. Empty accept = match anything.

package/dist/core/files/file-types.js

@@ -14,6 +14,14 @@ export class AcceptFileType {
     static webAssetImageOrVideo = [this.webAssetImage, this.webAssetVideo].join(',');
     static webAssetIcon = 'image/png';
 }
+const PREVIEWABLE_TYPE_PREFIXES = ['image/', 'video/', 'audio/'];
+/**
+ * Whether a MIME type names media a browser can present on its own — an image, a video or a
+ * sound. `false` for documents and archives, and for a blank type (`.heic`, `.mkv` and files with
+ * no extension often arrive with `file.type === ''`). Drives `UploadMediaStore`'s
+ * `{ preview: 'mime' }` mode.
+ */
+export const isPreviewableType = (type) => PREVIEWABLE_TYPE_PREFIXES.some((prefix) => type.toLowerCase().startsWith(prefix));
 /**
  * `accept`-style matcher. Tokens may be MIMEs (`image/*`, `*\/*`, `application/pdf`) or
  * extensions (`.pdf`), case-insensitive. Empty accept = match anything.

package/dist/core/files/file-validation-rules.d.ts

@@ -16,6 +16,7 @@ import type { AspectRatioBound, FileValidationRule, VideoOrientationValue } from
  * ```
  */
 export declare const FileRules: {
+    /** Passes when the container reports no duration (e.g. a live-stream WebM) — bitrate cannot be derived without it. */
     AudioBitrate: (maxKbps: number, message?: string) => FileValidationRule;
     AudioDuration: (maxSeconds: number, message?: string) => FileValidationRule;
     AudioOnly: (message?: string) => FileValidationRule;

package/dist/core/files/file-validation-rules.js

@@ -1,3 +1,4 @@
+import { probeVideo } from '../media';
 import { StringHelper } from '../utils';
 import { FileHelper } from './file-helper';
 import { matchesAcceptedFileTypes } from './file-types';
@@ -15,34 +16,26 @@ const readImageDimensions = (file) => new Promise((resolve, reject) => {
     };
     img.src = url;
 });
-const readMediaDuration = (file, kind) => new Promise((resolve, reject) => {
+const readMedia = async (file) => {
     const url = URL.createObjectURL(file);
-    const el = kind === 'video' ? document.createElement('video') : document.createElement('audio');
-    el.preload = 'metadata';
-    el.onloadedmetadata = () => {
-        URL.revokeObjectURL(url);
-        resolve(el.duration);
-    };
-    el.onerror = () => {
-        URL.revokeObjectURL(url);
-        reject(new Error(`Failed to read ${kind} duration`));
-    };
-    el.src = url;
-});
-const readVideoDimensions = (file) => new Promise((resolve, reject) => {
-    const url = URL.createObjectURL(file);
-    const video = document.createElement('video');
-    video.preload = 'metadata';
-    video.onloadedmetadata = () => {
-        URL.revokeObjectURL(url);
-        resolve({ width: video.videoWidth, height: video.videoHeight });
-    };
-    video.onerror = () => {
+    try {
+        const probe = await probeVideo(url, { cover: false });
+        if (!probe.readable) {
+            throw new Error('Failed to read media metadata');
+        }
+        return probe;
+    }
+    finally {
         URL.revokeObjectURL(url);
-        reject(new Error('Failed to read video dimensions'));
-    };
-    video.src = url;
-});
+    }
+};
+const readDuration = async (file) => {
+    const { durationSec } = await readMedia(file);
+    if (durationSec === null) {
+        throw new Error('Media duration is not reported by the container');
+    }
+    return durationSec;
+};
 const parseRatio = (value) => {
     if (typeof value === 'number') {
         return Number.isFinite(value) && value > 0 ? value : NaN;
@@ -81,20 +74,21 @@ const messages = new FileValidationLocalization();
  * ```
  */
 export const FileRules = {
+    /** Passes when the container reports no duration (e.g. a live-stream WebM) — bitrate cannot be derived without it. */
     AudioBitrate: (maxKbps, message) => async (file) => {
-        const duration = await readMediaDuration(file, 'audio');
-        if (!duration) {
+        const { durationSec } = await readMedia(file);
+        if (durationSec === null || durationSec === 0) {
             return null;
         }
-        const kbps = (file.size * 8) / duration / 1000;
+        const kbps = (file.size * 8) / durationSec / 1000;
         return kbps > maxKbps ? (message ?? messages.maxBitrate(maxKbps)) : null;
     },
     AudioDuration: (maxSeconds, message) => async (file) => {
-        const duration = await readMediaDuration(file, 'audio');
-        return duration > maxSeconds ? (message ?? messages.maxDuration(maxSeconds)) : null;
+        const durationSec = await readDuration(file);
+        return durationSec > maxSeconds ? (message ?? messages.maxDuration(maxSeconds)) : null;
     },
     AudioOnly: (message) => async (file) => {
-        const { width, height } = await readVideoDimensions(file);
+        const { width, height } = await readMedia(file);
         return width > 0 || height > 0 ? (message ?? messages.audioOnly) : null;
     },
     Extensions: (extensions, message) => (file) => {
@@ -117,7 +111,7 @@ export const FileRules = {
         return rule;
     },
     VideoAspectRatio: (ratios, message, tolerancePercent = 1) => async (file) => {
-        const { width, height } = await readVideoDimensions(file);
+        const { width, height } = await readMedia(file);
         if (!width || !height) {
             return message ?? messages.aspectRatio(ratios.join(', '));
         }
@@ -135,7 +129,7 @@ export const FileRules = {
      * interval outward on both edges. An empty `{}` specifies no constraint and accepts everything.
      */
     VideoAspectRatioRange: (range, message, tolerancePercent = 1) => async (file) => {
-        const { width, height } = await readVideoDimensions(file);
+        const { width, height } = await readMedia(file);
         if (!width || !height) {
             return message ?? messages.aspectRatioRange(formatBound(range.min), formatBound(range.max));
         }
@@ -148,7 +142,7 @@ export const FileRules = {
         return okLo && okHi ? null : (message ?? messages.aspectRatioRange(formatBound(range.min), formatBound(range.max)));
     },
     VideoOrientation: (orientation, message, tolerancePercent = 1) => async (file) => {
-        const { width, height } = await readVideoDimensions(file);
+        const { width, height } = await readMedia(file);
         if (!width || !height) {
             return message ?? messages.orientation(orientation);
         }
@@ -158,11 +152,11 @@ export const FileRules = {
         return ok ? null : (message ?? messages.orientation(orientation));
     },
     VideoDimensions: (max, message) => async (file) => {
-        const { width, height } = await readVideoDimensions(file);
+        const { width, height } = await readMedia(file);
         return width > max.width || height > max.height ? (message ?? messages.maxDimensions(max.width, max.height)) : null;
     },
     VideoDuration: (maxSeconds, message) => async (file) => {
-        const duration = await readMediaDuration(file, 'video');
-        return duration > maxSeconds ? (message ?? messages.maxDuration(maxSeconds)) : null;
+        const durationSec = await readDuration(file);
+        return durationSec > maxSeconds ? (message ?? messages.maxDuration(maxSeconds)) : null;
     }
 };

package/dist/core/files/index.d.ts

@@ -1,13 +1,13 @@
 export type { BlobWithName, FileWithBlobUrl, FileWithUploadUrl } from './types';
 export type { AspectRatioBound, FileValidationResult, FileValidationRule, FileValidationRuleSets, VideoOrientationValue } from './file-validation-types';
-export type { BlobUpload, BlobUploadStrategy, UploadingFile, UploadingFileStatus } from './upload-types';
-export type { UploadMediaStoreOptions } from './upload-media-store.svelte';
+export type { BlobUpload, BlobUploadStrategy, PreviewableUploadingFile, UploadPreviewMode, UploadingFile, UploadingFileStatus } from './upload-types';
+export type { AddOptions, UploadMediaStoreOptions } from './upload-media-store.svelte';
 export { toBlobWithName, toFileWithUploadUrl } from './types';
 export { uploadBlob } from './blob-storage';
 export { openFile } from './open-file';
 export { FileHelper } from './file-helper';
 export { downloadBlob, downloadFromUrl, downloadJson, fetchFile } from './file-service';
-export { AcceptFileType, matchesAcceptedFileTypes } from './file-types';
+export { AcceptFileType, isPreviewableType, matchesAcceptedFileTypes } from './file-types';
 export { deriveAccept } from './file-validation-rule-sets';
 export { resizeBlob, resizeImage } from './image-resizer';
 export { FileWithBlobDataHelper } from './file-with-blob-data-helper';
@@ -15,3 +15,4 @@ export { FilesProvider } from './files-provider';
 export { FileValidator } from './file-validator';
 export { FileRules } from './file-validation-rules';
 export { UploadMediaStore } from './upload-media-store.svelte';
+export { AppUploadActivity } from './app-upload-activity.svelte';

package/dist/core/files/index.js

@@ -4,7 +4,7 @@ export { uploadBlob } from './blob-storage';
 export { openFile } from './open-file';
 export { FileHelper } from './file-helper';
 export { downloadBlob, downloadFromUrl, downloadJson, fetchFile } from './file-service';
-export { AcceptFileType, matchesAcceptedFileTypes } from './file-types';
+export { AcceptFileType, isPreviewableType, matchesAcceptedFileTypes } from './file-types';
 export { deriveAccept } from './file-validation-rule-sets';
 export { resizeBlob, resizeImage } from './image-resizer';
 export { FileWithBlobDataHelper } from './file-with-blob-data-helper';
@@ -12,3 +12,4 @@ export { FilesProvider } from './files-provider';
 export { FileValidator } from './file-validator';
 export { FileRules } from './file-validation-rules';
 export { UploadMediaStore } from './upload-media-store.svelte';
+export { AppUploadActivity } from './app-upload-activity.svelte';

package/dist/core/files/upload-media-store.svelte.d.ts

@@ -1,10 +1,14 @@
-import type { BlobUploadStrategy, UploadingFile } from './upload-types';
+import type { BlobUploadStrategy, PreviewableUploadingFile, UploadPreviewMode, UploadingFile } from './upload-types';
 type SuccessfulUpload = Extract<UploadingFile, {
     status: 'success';
 }>;
 type FailedUpload = Extract<UploadingFile, {
     status: 'error';
 }>;
+export type AddOptions = {
+    /** Stage an object URL for local preview. @default 'never' */
+    preview?: UploadPreviewMode;
+};
 export type UploadMediaStoreOptions = {
     /**
      * Auto-resize images before upload. Pass `false` to disable; pass an object to override the
@@ -48,25 +52,51 @@ export type UploadMediaStoreOptions = {
  */
 export declare class UploadMediaStore {
     private _files;
+    private _inFlight;
+    private _nextRunId;
     private _strategy;
     private opts;
     constructor(strategy: BlobUploadStrategy, opts?: UploadMediaStoreOptions);
     /** Reactive read of the queue. */
     get files(): UploadingFile[];
-    /** Append a raw `File`, returns its `UploadingFile` wrapper (with a stable `id`). */
-    add(file: File): UploadingFile;
-    /** Append multiple raw files at once. */
-    addMany(files: File[]): UploadingFile[];
-    /** Remove a file from the queue by its `UploadingFile.id`. Does NOT cancel an in-flight upload. */
+    /**
+     * Append a raw `File`, returns its `UploadingFile` wrapper with a stable `id`. Pass
+     * `{ preview: 'always' }` when the caller knows this file gets previewed — the returned wrapper is
+     * then typed with a non-null `previewUrl`. The wrapper is a snapshot: `previewUrl` never changes,
+     * but read `status` / `progress` back from `files` rather than from it.
+     *
+     * `'always'` is the only mode that narrows the type — `'mime'` resolves against `file.type` at
+     * runtime, so its `previewUrl` stays `string | null` however previewable the file looks.
+     */
+    add(file: File, options: AddOptions & {
+        preview: 'always';
+    }): PreviewableUploadingFile;
+    add(file: File, options?: AddOptions): UploadingFile;
+    /** Append multiple raw files at once, with the same `preview` semantics as `add()` — only `'always'` narrows the returned type. */
+    addMany(files: File[], options: AddOptions & {
+        preview: 'always';
+    }): PreviewableUploadingFile[];
+    addMany(files: File[], options?: AddOptions): UploadingFile[];
+    /** Remove a file from the queue by its `UploadingFile.id`, revoking its `previewUrl`. Does NOT cancel an in-flight upload. */
     remove(id: string): void;
-    /** Clear all queued / completed files. Does NOT cancel any in-flight uploads. */
+    /** Clear all queued / completed files, revoking their `previewUrl`s. Does NOT cancel any in-flight uploads. */
     clear(): void;
+    /** Resolved blob for a file id — `null` while it is still queued / uploading, or if it failed. */
+    resolve(id: string): {
+        blobId: string;
+        readUrl: string;
+    } | null;
     /**
      * Run the upload pipeline for every file currently in `'queued'` status. Files already
-     * `uploading` / `success` / `error` are skipped. Resolves once every targeted file has a
-     * terminal status.
+     * `uploading` / `success` / `error` are skipped. Resolves once **every** run of this store —
+     * including ones started by earlier `upload()` calls — has reached a terminal status, so
+     * `await store.upload()` always means "nothing of mine is in flight any more". Each run registers
+     * itself in `AppUploadActivity` for its duration, so a mounted `UploadProgressToaster` picks it up
+     * with no extra wiring.
      */
     upload(): Promise<void>;
+    private settled;
+    private runQueued;
     private maybeResize;
     private fail;
     private failAll;

package/dist/core/files/upload-media-store.svelte.js

@@ -1,9 +1,17 @@
+import { AppUploadActivity } from './app-upload-activity.svelte';
 import { uploadBlob } from './blob-storage';
+import { isPreviewableType } from './file-types';
 import { resizeBlob } from './image-resizer';
 import { nanoid } from 'nanoid';
 import { default as pLimit } from 'p-limit';
 const DEFAULT_RESIZE_LIMITS = { max1: 1600, max2: 1000 };
 const DEFAULT_CONCURRENCY = 20;
+const toPreviewUrl = (file, mode) => mode === 'always' || (mode === 'mime' && isPreviewableType(file.type)) ? URL.createObjectURL(file) : null;
+const revokePreviewUrl = (file) => {
+    if (file.previewUrl !== null) {
+        URL.revokeObjectURL(file.previewUrl);
+    }
+};
 /**
  * Queue-and-upload coordinator. Pure logic — no UI. Pair with `FileRow` / `FileUploadProgress`
  * for visual progress, both of which consume the `files: UploadingFile[]` array reactively.
@@ -26,6 +34,8 @@ const DEFAULT_CONCURRENCY = 20;
  */
 export class UploadMediaStore {
     _files = $state.raw([]);
+    _inFlight = new Map();
+    _nextRunId = 0;
     _strategy;
     opts;
     constructor(strategy, opts = {}) {
@@ -36,36 +46,76 @@ export class UploadMediaStore {
     get files() {
         return this._files;
     }
-    /** Append a raw `File`, returns its `UploadingFile` wrapper (with a stable `id`). */
-    add(file) {
-        const uploadingFile = { id: nanoid(), file, progress: 0, status: 'queued' };
+    add(file, options = {}) {
+        const uploadingFile = { id: nanoid(), file, progress: 0, previewUrl: toPreviewUrl(file, options.preview ?? 'never'), status: 'queued' };
         this._files = [...this._files, uploadingFile];
         return uploadingFile;
     }
-    /** Append multiple raw files at once. */
-    addMany(files) {
-        const wrappers = files.map((file) => ({ id: nanoid(), file, progress: 0, status: 'queued' }));
+    addMany(files, options = {}) {
+        const preview = options.preview ?? 'never';
+        const wrappers = files.map((file) => ({ id: nanoid(), file, progress: 0, previewUrl: toPreviewUrl(file, preview), status: 'queued' }));
         this._files = [...this._files, ...wrappers];
         return wrappers;
     }
-    /** Remove a file from the queue by its `UploadingFile.id`. Does NOT cancel an in-flight upload. */
+    /** Remove a file from the queue by its `UploadingFile.id`, revoking its `previewUrl`. Does NOT cancel an in-flight upload. */
     remove(id) {
-        this._files = this._files.filter((f) => f.id !== id);
+        this._files = this._files.filter((f) => {
+            if (f.id !== id) {
+                return true;
+            }
+            revokePreviewUrl(f);
+            return false;
+        });
     }
-    /** Clear all queued / completed files. Does NOT cancel any in-flight uploads. */
+    /** Clear all queued / completed files, revoking their `previewUrl`s. Does NOT cancel any in-flight uploads. */
     clear() {
+        this._files.forEach(revokePreviewUrl);
         this._files = [];
     }
+    /** Resolved blob for a file id — `null` while it is still queued / uploading, or if it failed. */
+    resolve(id) {
+        const file = this._files.find((f) => f.id === id);
+        return file?.status === 'success' ? { blobId: file.blobId, readUrl: file.readUrl } : null;
+    }
     /**
      * Run the upload pipeline for every file currently in `'queued'` status. Files already
-     * `uploading` / `success` / `error` are skipped. Resolves once every targeted file has a
-     * terminal status.
+     * `uploading` / `success` / `error` are skipped. Resolves once **every** run of this store —
+     * including ones started by earlier `upload()` calls — has reached a terminal status, so
+     * `await store.upload()` always means "nothing of mine is in flight any more". Each run registers
+     * itself in `AppUploadActivity` for its duration, so a mounted `UploadProgressToaster` picks it up
+     * with no extra wiring.
      */
     async upload() {
         const queued = this._files.filter((f) => f.status === 'queued');
         if (queued.length === 0) {
+            await this.settled();
             return;
         }
+        // Claim before the first await, or a second upload() during the strategy call re-claims the same files.
+        for (const entry of queued) {
+            this.transition(entry.id, (f) => ({ id: f.id, file: f.file, progress: 0, previewUrl: f.previewUrl, status: 'uploading' }));
+        }
+        const fileIds = new Set(queued.map((f) => f.id));
+        const activityRunId = AppUploadActivity.beginRun(() => this._files.filter((f) => fileIds.has(f.id)));
+        const runId = this._nextRunId++;
+        const run = (async () => {
+            try {
+                await this.runQueued(queued);
+            }
+            finally {
+                AppUploadActivity.endRun(activityRunId);
+                this._inFlight.delete(runId);
+            }
+        })();
+        this._inFlight.set(runId, run);
+        await this.settled();
+    }
+    async settled() {
+        while (this._inFlight.size > 0) {
+            await Promise.all([...this._inFlight.values()]);
+        }
+    }
+    async runQueued(queued) {
         let presigned;
         try {
             presigned = await this._strategy(queued.length);
@@ -81,14 +131,21 @@ export class UploadMediaStore {
         const limit = pLimit(this.opts.concurrency ?? DEFAULT_CONCURRENCY);
         const resizeOpt = this.opts.resize;
         await Promise.all(queued.map((entry, i) => limit(async () => {
-            this.transition(entry.id, (f) => ({ id: f.id, file: f.file, progress: 0, status: 'uploading' }));
             try {
                 const blob = resizeOpt === false ? entry.file : await this.maybeResize(entry.file, resizeOpt ?? DEFAULT_RESIZE_LIMITS);
                 const slot = presigned[i];
                 await uploadBlob(slot.uploadUrl, blob, (loaded, total) => {
                     this.transition(entry.id, (f) => (f.status === 'uploading' ? { ...f, progress: total > 0 ? loaded / total : 0 } : f));
                 });
-                const done = this.transition(entry.id, (f) => ({ id: f.id, file: f.file, progress: 1, status: 'success', blobId: slot.id, readUrl: slot.readUrl }));
+                const done = this.transition(entry.id, (f) => ({
+                    id: f.id,
+                    file: f.file,
+                    progress: 1,
+                    previewUrl: f.previewUrl,
+                    status: 'success',
+                    blobId: slot.id,
+                    readUrl: slot.readUrl
+                }));
                 if (done?.status === 'success') {
                     this.opts.on?.blobId?.(done, slot.id);
                 }
@@ -114,7 +171,7 @@ export class UploadMediaStore {
     }
     fail(id, error) {
         const message = error instanceof Error ? error.message : 'Upload failed';
-        const failed = this.transition(id, (f) => ({ id: f.id, file: f.file, progress: f.progress, status: 'error', error: message }));
+        const failed = this.transition(id, (f) => ({ id: f.id, file: f.file, progress: f.progress, previewUrl: f.previewUrl, status: 'error', error: message }));
         if (failed?.status === 'error') {
             this.opts.on?.error?.(failed, error);
         }

package/dist/core/files/upload-types.d.ts

@@ -20,6 +20,12 @@ type UploadingFileBase = {
     file: File;
     /** 0..1 — fraction uploaded. 1 on success. */
     progress: number;
+    /**
+     * Object URL for local preview, or `null` when none was staged. Controlled per call by
+     * `add()` / `addMany()`'s `preview` option, which defaults to `'never'`. Revoked by `remove()` /
+     * `clear()`; never revoke it yourself.
+     */
+    previewUrl: string | null;
 };
 /**
  * Canonical shape passed to `FileRow` / `FileUploadProgress` and emitted by `UploadMediaStore`,
@@ -39,4 +45,14 @@ export type UploadingFile = (UploadingFileBase & {
     status: 'error';
     error: string;
 });
+/** What `add()` / `addMany()` return for `{ preview: 'always' }` — a `previewUrl` that needs no null check. */
+export type PreviewableUploadingFile = UploadingFile & {
+    previewUrl: string;
+};
+/**
+ * Whether `add()` / `addMany()` stage an object URL for local preview: `'always'` regardless of
+ * type, `'never'`, or `'mime'` to let `isPreviewableType(file.type)` decide (images, videos and
+ * audio get one). @default 'never'
+ */
+export type UploadPreviewMode = 'always' | 'never' | 'mime';
 export {};

package/dist/core/media/index.d.ts

@@ -1,2 +1,4 @@
 export { ImageHelper } from './image-helper';
 export type { ImageSize } from './image-helper';
+export { probeVideo } from './video-probe';
+export type { VideoProbe, VideoProbeOptions } from './video-probe';

package/dist/core/media/index.js

@@ -1 +1,2 @@
 export { ImageHelper } from './image-helper';
+export { probeVideo } from './video-probe';

package/dist/core/media/video-probe.d.ts

@@ -0,0 +1,28 @@
+export type VideoProbe = {
+    /** `false` when the browser could not read the media at all (decode error / timeout before metadata) — every other field is then meaningless. */
+    readable: boolean;
+    /** `0` for a readable file with no video track (e.g. an audio-only container). */
+    width: number;
+    height: number;
+    /** Exact, unrounded seconds, or `null` when the container reports no usable duration (`Infinity` for MediaRecorder WebM, `NaN` for broken metadata). */
+    durationSec: number | null;
+    /** First readable frame as a JPEG blob. `null` when `cover` was not requested, or the browser could not decode / export one. */
+    cover: Blob | null;
+};
+export type VideoProbeOptions = {
+    /** Grab the first frame as a JPEG. Off means metadata-only — no full buffering, no decode, no canvas encode. @default true */
+    cover?: boolean;
+    /** @default 10000 */
+    timeoutMs?: number;
+};
+/**
+ * Read dimensions, duration and (optionally) a first-frame cover out of a local media URL — an
+ * object URL from `UploadingFile.previewUrl` or `URL.createObjectURL`. Always resolves: media the
+ * browser cannot decode comes back as `readable: false` with zeroed metrics, and a readable file
+ * whose cover cannot be exported comes back `readable: true` with `cover: null`.
+ *
+ * The single media-probing primitive in the kit — every `FileRules` audio / video rule reads through
+ * it with `cover: false`. Audio-only containers are read by the same `<video>` element (same media
+ * pipeline, same codec support) and come back `readable` with `width` / `height` of `0`.
+ */
+export declare const probeVideo: (url: string, options?: VideoProbeOptions) => Promise<VideoProbe>;

package/dist/core/media/video-probe.js

@@ -0,0 +1,82 @@
+const READ_TIMEOUT_MS = 10000;
+const COVER_SEEK_SEC = 0.001;
+const COVER_QUALITY = 0.85;
+/**
+ * Read dimensions, duration and (optionally) a first-frame cover out of a local media URL — an
+ * object URL from `UploadingFile.previewUrl` or `URL.createObjectURL`. Always resolves: media the
+ * browser cannot decode comes back as `readable: false` with zeroed metrics, and a readable file
+ * whose cover cannot be exported comes back `readable: true` with `cover: null`.
+ *
+ * The single media-probing primitive in the kit — every `FileRules` audio / video rule reads through
+ * it with `cover: false`. Audio-only containers are read by the same `<video>` element (same media
+ * pipeline, same codec support) and come back `readable` with `width` / `height` of `0`.
+ */
+export const probeVideo = (url, options = {}) => new Promise((resolve) => {
+    const { cover: withCover = true, timeoutMs = READ_TIMEOUT_MS } = options;
+    const video = document.createElement('video');
+    video.preload = withCover ? 'auto' : 'metadata';
+    video.muted = true;
+    video.crossOrigin = 'anonymous';
+    let settled = false;
+    let metadataRead = false;
+    let corsRetried = false;
+    const finish = (readable, cover) => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        clearTimeout(timeoutId);
+        const duration = video.duration;
+        const probe = {
+            readable,
+            width: video.videoWidth,
+            height: video.videoHeight,
+            durationSec: Number.isFinite(duration) ? duration : null,
+            cover
+        };
+        video.pause();
+        video.removeAttribute('src');
+        video.load();
+        resolve(probe);
+    };
+    // Unseekable containers fire neither seeked nor error — without the timeout the promise never settles.
+    const timeoutId = setTimeout(() => finish(metadataRead, null), timeoutMs);
+    video.onerror = () => {
+        // Without this retry a non-CORS remote URL never loads at all while crossOrigin is set.
+        if (!corsRetried && video.crossOrigin !== null) {
+            corsRetried = true;
+            video.crossOrigin = null;
+            video.src = url;
+            return;
+        }
+        finish(false, null);
+    };
+    video.onloadedmetadata = () => {
+        metadataRead = true;
+        if (!withCover) {
+            finish(true, null);
+        }
+    };
+    video.onloadeddata = () => {
+        video.currentTime = COVER_SEEK_SEC;
+    };
+    video.onseeked = () => {
+        try {
+            const canvas = document.createElement('canvas');
+            canvas.width = video.videoWidth;
+            canvas.height = video.videoHeight;
+            const context = canvas.getContext('2d');
+            if (!context || !canvas.width || !canvas.height) {
+                finish(true, null);
+                return;
+            }
+            context.drawImage(video, 0, 0);
+            canvas.toBlob((blob) => finish(true, blob), 'image/jpeg', COVER_QUALITY);
+        }
+        catch {
+            // toBlob throws on a tainted canvas; uncaught here it would leave the promise pending until the timeout.
+            finish(true, null);
+        }
+    };
+    video.src = url;
+});