@vef-framework-react/core 2.1.12 → 2.2.1

package/dist/es/storage/resumable/plan.js

@@ -0,0 +1,35 @@
+/*! @vef-framework-react/core v2.2.1 made by Venus | 2026-05-18T08:55:53.533Z */
+import { abortUpload as e, listParts as t } from "../protocol.js";
+//#region src/storage/resumable/plan.ts
+async function n(n) {
+	let { fingerprint: a, persistence: o, ctx: s, onResumeDetected: c = r, signal: l } = n, u = await o.load(a);
+	if (!u) return { kind: "fresh" };
+	if (i(u.expiresAt)) return await o.remove(a), { kind: "fresh" };
+	let d;
+	try {
+		d = (await t(s, u.claimId, l)).parts;
+	} catch {
+		return await o.remove(a), { kind: "fresh" };
+	}
+	return (await c({
+		record: u,
+		completedParts: d
+	})).kind === "discard" ? (await o.remove(a), await e(s, u.claimId), { kind: "fresh" }) : {
+		kind: "resume",
+		claimId: u.claimId,
+		key: u.key,
+		partSize: u.partSize,
+		partCount: u.partCount,
+		expiresAt: u.expiresAt,
+		completedParts: d
+	};
+}
+function r() {
+	return Promise.resolve({ kind: "discard" });
+}
+function i(e) {
+	let t = Date.parse(e);
+	return Number.isNaN(t) ? !0 : t <= Date.now();
+}
+//#endregion
+export { n as resolveResumePlan };

package/dist/es/storage/types.js

@@ -0,0 +1,5 @@
+/*! @vef-framework-react/core v2.2.1 made by Venus | 2026-05-18T08:55:53.533Z */
+//#region src/storage/types.ts
+var e = "pub/", t = "priv/";
+//#endregion
+export { t as PRIVATE_PREFIX, e as PUBLIC_PREFIX };

package/dist/es/storage/uploader.js

@@ -0,0 +1,223 @@
+/*! @vef-framework-react/core v2.2.1 made by Venus | 2026-05-18T08:55:53.533Z */
+import { UploadAbortedError as e, UploadError as t, UploadPartError as n, UploadProtocolError as r } from "./errors.js";
+import { abortUpload as i, completeUpload as a, initUpload as o, uploadPart as s } from "./protocol.js";
+//#region src/storage/uploader.ts
+var c = 3, l = 3, u = 500, d = 8e3;
+function f(e, t, n, r) {
+	return n < r ? t : e - t * (r - 1);
+}
+function p(t, n) {
+	return new Promise((r, i) => {
+		if (n.aborted) {
+			i(new e());
+			return;
+		}
+		let a = setTimeout(() => {
+			n.removeEventListener("abort", o), r();
+		}, t), o = () => {
+			clearTimeout(a), n.removeEventListener("abort", o), i(new e());
+		};
+		n.addEventListener("abort", o, { once: !0 });
+	});
+}
+var m = class {
+	#e;
+	#t;
+	#n;
+	#r;
+	#i;
+	#a;
+	#o;
+	#s;
+	#c;
+	#l;
+	#u;
+	#d;
+	#f;
+	#p;
+	#m = "idle";
+	#h;
+	#g;
+	#_ = 0;
+	#v = /* @__PURE__ */ new Map();
+	#y = 1;
+	#b = /* @__PURE__ */ new Set();
+	constructor(e, n, r = {}) {
+		let i = r.init?.filename ?? (n instanceof File ? n.name : "");
+		if (!i) throw new t("Uploader requires a filename (set options.init.filename for Blob input)");
+		this.#e = {
+			http: e,
+			apiPath: r.apiPath ?? "/api",
+			resource: r.resource ?? "sys/storage",
+			version: r.version ?? "v1"
+		}, this.#t = n, this.#n = i, this.#r = r.init?.contentType ?? (n instanceof File && n.type || void 0), this.#i = r.init?.public, this.#a = Math.max(1, r.partConcurrency ?? c), this.#o = Math.max(1, r.maxPartRetries ?? l), this.#s = Math.max(0, r.retryBaseDelay ?? u), this.#c = Math.max(this.#s, r.retryMaxDelay ?? d), this.#l = r.onProgress, this.#u = r.onStatusChange, this.#d = r.onSessionOpened, this.#f = new AbortController(), this.#p = this.#x(r.signal), this.#h = {
+			loaded: 0,
+			total: n.size,
+			partsCompleted: 0,
+			partsTotal: 0,
+			percent: 0
+		};
+	}
+	get status() {
+		return this.#m;
+	}
+	get progress() {
+		return this.#h;
+	}
+	start(e) {
+		return this.#g ||= this.#E(e ?? { kind: "fresh" }), this.#g;
+	}
+	async abort() {
+		if (this.#S()) return;
+		this.#f.abort();
+		let e = this.#g;
+		if (e) try {
+			await e;
+		} catch {}
+	}
+	#x(e) {
+		if (!e) return;
+		if (e.aborted) {
+			this.#f.abort();
+			return;
+		}
+		let t = () => this.#f.abort();
+		return e.addEventListener("abort", t, { once: !0 }), () => e.removeEventListener("abort", t);
+	}
+	#S() {
+		return this.#m === "succeeded" || this.#m === "failed" || this.#m === "aborted";
+	}
+	#C(e) {
+		this.#m !== e && (this.#m = e, this.#u?.(e));
+	}
+	#w() {
+		let e = 0;
+		for (let t of this.#v.values()) e += t;
+		let t = Math.min(this.#h.total, this.#_ + e), n = this.#h.total === 0 ? 0 : Math.floor(t / this.#h.total * 100);
+		this.#h = {
+			...this.#h,
+			loaded: t,
+			percent: n
+		}, this.#l?.(this.#h);
+	}
+	async #T(e) {
+		if (e.kind === "fresh") return {
+			session: await o(this.#e, {
+				filename: this.#n,
+				size: this.#t.size,
+				contentType: this.#r,
+				public: this.#i
+			}, this.#f.signal),
+			skipParts: /* @__PURE__ */ new Set(),
+			completedBytes: 0
+		};
+		let t = e.partSize * e.partCount, n = e.partSize * (e.partCount - 1) + 1;
+		if (this.#t.size < n || this.#t.size > t) throw new r("resume", `file size ${this.#t.size} does not fit the resumed session (partSize=${e.partSize}, partCount=${e.partCount})`);
+		let i = /* @__PURE__ */ new Set(), a = 0;
+		for (let t of e.completedParts) i.add(t.partNumber), a += t.size;
+		return {
+			session: {
+				key: e.key,
+				claimId: e.claimId,
+				originalFilename: this.#n,
+				partSize: e.partSize,
+				partCount: e.partCount,
+				expiresAt: e.expiresAt
+			},
+			skipParts: i,
+			completedBytes: a
+		};
+	}
+	async #E(t) {
+		let n;
+		try {
+			if (this.#f.signal.aborted) throw new e();
+			this.#C("initializing");
+			let { session: r, skipParts: i, completedBytes: o } = await this.#T(t);
+			({claimId: n} = r), this.#b = i, this.#_ = o, this.#d?.({
+				claimId: r.claimId,
+				key: r.key,
+				partSize: r.partSize,
+				partCount: r.partCount,
+				expiresAt: r.expiresAt
+			}), this.#h = {
+				...this.#h,
+				partsTotal: r.partCount,
+				partsCompleted: i.size
+			}, this.#w(), this.#C("uploading"), await this.#D(r), this.#C("completing");
+			let s = await a(this.#e, r.claimId, this.#f.signal);
+			return this.#C("succeeded"), {
+				bucket: s.bucket,
+				key: s.key,
+				eTag: s.eTag,
+				size: s.size,
+				contentType: s.contentType,
+				lastModified: s.lastModified,
+				originalFilename: s.originalFilename,
+				metadata: s.metadata
+			};
+		} catch (t) {
+			let r = t instanceof e;
+			throw r && this.#C("aborting"), r && n !== void 0 && await i(this.#e, n), this.#C(r ? "aborted" : "failed"), this.#j(t);
+		} finally {
+			this.#p?.();
+		}
+	}
+	async #D(e) {
+		let t = Math.min(this.#a, e.partCount), n = [];
+		for (let r = 0; r < t; r++) n.push(this.#O(e));
+		try {
+			await Promise.all(n);
+		} catch (e) {
+			throw this.#f.abort(), e;
+		}
+	}
+	async #O(e) {
+		for (; !this.#f.signal.aborted;) {
+			let t = this.#k(e.partCount);
+			if (t === null) return;
+			await this.#A(e, t);
+		}
+	}
+	#k(e) {
+		for (; this.#y <= e;) {
+			let e = this.#y++;
+			if (!this.#b.has(e)) return e;
+		}
+		return null;
+	}
+	async #A(t, r) {
+		let i = f(this.#t.size, t.partSize, r, t.partCount), a = (r - 1) * t.partSize, o = this.#t.slice(a, a + i), c = 0, l;
+		for (; c < this.#o;) {
+			if (c++, this.#f.signal.aborted) throw new e();
+			try {
+				this.#v.set(r, 0), await s(this.#e, {
+					claimId: t.claimId,
+					partNumber: r,
+					blob: o,
+					onProgress: (e) => {
+						this.#v.set(r, Math.min(i, e.loaded)), this.#w();
+					},
+					signal: this.#f.signal
+				}), this.#v.delete(r), this.#_ += i, this.#h = {
+					...this.#h,
+					partsCompleted: this.#h.partsCompleted + 1
+				}, this.#w();
+				return;
+			} catch (t) {
+				if (this.#v.delete(r), l = t, this.#f.signal.aborted) throw new e();
+				if (c >= this.#o) break;
+				await p(Math.min(this.#c, this.#s * 2 ** (c - 1)), this.#f.signal);
+			}
+		}
+		throw new n(r, c, { cause: l });
+	}
+	#j(e) {
+		return e instanceof t ? e : e instanceof Error ? new r("unknown", e.message, { cause: e }) : new r("unknown", String(e));
+	}
+};
+function h(e, t, n) {
+	return new m(e, t, n).start();
+}
+//#endregion
+export { m as Uploader, h as uploadFile };

package/dist/es/store/bound.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/core v2.1.12 made by Venus | 2026-05-07T08:00:43.953Z */
+/*! @vef-framework-react/core v2.2.1 made by Venus | 2026-05-18T08:55:53.533Z */
 import { constantCase as e, identity as t } from "@vef-framework-react/shared";
 import { create as n } from "zustand";
 import { createJSONStorage as r, persist as i, subscribeWithSelector as a } from "zustand/middleware";

package/dist/es/store/index.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/core v2.1.12 made by Venus | 2026-05-07T08:00:43.953Z */
+/*! @vef-framework-react/core v2.2.1 made by Venus | 2026-05-18T08:55:53.533Z */
 import "./bound.js";
 import "./unbound.js";
 import "./use-deep.js";

package/dist/es/store/unbound.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/core v2.1.12 made by Venus | 2026-05-07T08:00:43.953Z */
+/*! @vef-framework-react/core v2.2.1 made by Venus | 2026-05-18T08:55:53.533Z */
 import { constantCase as e, identity as t, isPlainObject as n, mergeWith as r } from "@vef-framework-react/shared";
 import { createContext as i, use as a, useRef as o } from "react";
 import { jsx as s } from "@emotion/react/jsx-runtime";

package/dist/es/store/use-deep.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/core v2.1.12 made by Venus | 2026-05-07T08:00:43.953Z */
+/*! @vef-framework-react/core v2.2.1 made by Venus | 2026-05-18T08:55:53.533Z */
 import { isDeepEqual as e } from "@vef-framework-react/shared";
 import { useRef as t } from "react";
 //#region src/store/use-deep.ts

package/dist/types/api/helpers.d.ts

@@ -1,4 +1,4 @@
-import { ApiClientOptions } from './types';
+import { ApiClientOptions, ApiRequest } from './types';
 import { ApiClient } from './client';
 /**
  * Creates a new API client.
@@ -7,3 +7,18 @@ import { ApiClient } from './client';
  * @returns The API client.
  */
 export declare function createApiClient(options: ApiClientOptions): ApiClient;
+/**
+ * Build an `ApiRequest` envelope. The three-arg form defaults `version` to
+ * `"v1"`; the four-arg form lets callers pin a non-default version.
+ *
+ * @example Default version
+ * ```ts
+ * createApiRequest("sys/storage", "abort_upload", { claimId });
+ * ```
+ * @example Explicit version
+ * ```ts
+ * createApiRequest("sys/storage", "init_upload", "v2", { filename, size });
+ * ```
+ */
+export declare function createApiRequest<P extends object, M extends object>(resource: string, action: string, params?: P, meta?: M): ApiRequest<P, M>;
+export declare function createApiRequest<P extends object, M extends object>(resource: string, action: string, version: string, params?: P, meta?: M): ApiRequest<P, M>;

package/dist/types/api/index.d.ts

@@ -1,4 +1,4 @@
 export { ApiClient } from './client';
 export { HTTP_CLIENT, QUERY_CLIENT } from './constants';
-export { createApiClient } from './helpers';
+export { createApiClient, createApiRequest } from './helpers';
 export type * from './types';

package/dist/types/api/types.d.ts

@@ -46,3 +46,33 @@ export interface MutationFunction<TData = unknown, TParams = never> extends Muta
      */
     key: Key;
 }
+/**
+ * The wire-level envelope every framework RPC call shares. `resource` and
+ * `action` identify the target operation on the Go side; `version` pins the
+ * action's compatibility profile (defaults to `v1`); `params` and `meta`
+ * carry the per-call payload and metadata.
+ */
+export interface ApiRequest<P extends object = Record<string, unknown>, M extends object = Record<string, unknown>> {
+    /**
+     * The resource the action targets (e.g. `"sys/storage"`).
+     */
+    resource: string;
+    /**
+     * The action to invoke on the resource (e.g. `"init_upload"`).
+     */
+    action: string;
+    /**
+     * The action's compatibility version. Defaults to `"v1"` when omitted at
+     * the helper level.
+     */
+    version: string;
+    /**
+     * Per-call parameters. Shape is defined by the target action.
+     */
+    params?: P;
+    /**
+     * Per-call metadata (e.g. pagination). Shape is defined by the target
+     * action.
+     */
+    meta?: M;
+}

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export { ApiClient, createApiClient, HTTP_CLIENT, QUERY_CLIENT, type ApiClientOptions, type MutationFunction, type QueryFunction, type QueryKey } from './api';
+export { ApiClient, createApiClient, createApiRequest, HTTP_CLIENT, QUERY_CLIENT, type ApiClientOptions, type ApiRequest, type MutationFunction, type QueryFunction, type QueryKey } from './api';
 export { checkPermission, type PermissionCheckMode } from './auth';
 export { type DataOption, type DataOptionWithPinyin, type PaginationParams, type PaginationResult } from './common';
 export { ApiClientProvider, AppContextProvider, createContextWithSelector, DisabledProvider, useApiClient, useAppContext, useDisabled, type AppContext, type SelectorContextProviderProps, type SelectorContextResult, type UseSelectorContext } from './context';
@@ -11,5 +11,6 @@ export { keepPreviousData, matchMutation, matchQuery, skipQueryToken, useInfinit
 export { createSseClient, SseClient, type SseClientOptions, type SseEventHandlers, type SseMessageEvent, type SseRequestConfig } from './sse';
 export { atom, AtomStoreProvider, createAtomStore, getDefaultAtomStore, useAtom, useAtomStore, useAtomValue, useSetAtom, type Atom, type AtomGetter, type AtomSetter, type ExtractAtomArgs, type ExtractAtomResult, type ExtractAtomValue, type PrimitiveAtom, type SetStateAction, type WritableAtom } from './state';
 export { Actor, createActor, createMachine, updateContext, useActor, useActorRef, type ActorLogic, type ActorOptions, type AnyActorLogic, type AnyMachineSnapshot, type AnyStateMachine, type MachineConfig, type MachineContext, type MachineSnapshot, type RequiredActorOptionsKeys, type SnapshotFrom, type StateMachine } from './state-machine';
+export { abortUpload, completeUpload, initUpload, listParts, LocalStoragePersistence, PrefixFingerprinter, PRIVATE_PREFIX, PUBLIC_PREFIX, resolveResumePlan, DEFAULT_API_PATH as STORAGE_API_PATH, DEFAULT_RESOURCE as STORAGE_RESOURCE, DEFAULT_VERSION as STORAGE_VERSION, UploadAbortedError, Uploader, UploadError, uploadFile, uploadPart, UploadPartError, UploadProtocolError, WeakFingerprinter, type CompleteUploadResponse, type FileFingerprinter, type InitUploadParams, type InitUploadResponse, type ListedPart, type ListPartsResponse, type ObjectInfo, type ProtocolContext, type ResolveResumeInputs, type ResumablePersistence, type ResumeCandidate, type ResumeDecision, type ResumeDecisionHandler, type ResumePlan, type ResumeRecord, type UploaderOptions, type UploadInit, type UploadPartResponse, type UploadProgress, type UploadResult, type UploadSessionSnapshot, type UploadStatus } from './storage';
 export { createComponentStore, createPersistedStore, createStore, useDeep, useShallow, type PersistenceOptions, type ComponentStoreResult as ReturnedComponentStoreResult, type SliceStateCreator, type StoreProviderProps, type UnboundStore, type UseBoundStore, type UseBoundStoreWithPersist, type UseStore } from './store';
 export { clsx, type ClassArray, type ClassDictionary, type ClassValue } from 'clsx';

package/dist/types/storage/errors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Base class for every error surfaced by the storage upload pipeline.
+ * Tests and callers should use `instanceof UploadError` to discriminate
+ * uploader failures from unrelated runtime errors.
+ */
+export declare class UploadError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when the caller (or external signal) cancels an in-flight upload.
+ * Surfaces from the `start()` promise so callers can distinguish a manual
+ * cancellation from a genuine protocol failure.
+ */
+export declare class UploadAbortedError extends UploadError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the backend rejects a protocol RPC (init_upload,
+ * complete_upload, abort_upload) in a way that is not recoverable through
+ * the upload's own retry mechanism.
+ *
+ * `cause` preserves the underlying axios / `BusinessError` for caller
+ * diagnostics; do not parse `cause` for control flow.
+ */
+export declare class UploadProtocolError extends UploadError {
+    /**
+     * The protocol action that produced the error.
+     */
+    readonly action: string;
+    constructor(action: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a single part fails repeatedly past `maxPartRetries`. Carries
+ * the part number so the caller can surface a specific failure to the user.
+ */
+export declare class UploadPartError extends UploadError {
+    /**
+     * The 1-indexed part number that failed.
+     */
+    readonly partNumber: number;
+    /**
+     * The number of attempts made before giving up.
+     */
+    readonly attempts: number;
+    constructor(partNumber: number, attempts: number, options?: ErrorOptions);
+}

package/dist/types/storage/index.d.ts

@@ -0,0 +1,5 @@
+export { UploadAbortedError, UploadError, UploadPartError, UploadProtocolError } from './errors';
+export { abortUpload, completeUpload, DEFAULT_API_PATH, DEFAULT_RESOURCE, DEFAULT_VERSION, initUpload, listParts, uploadPart, type CompleteUploadResponse, type InitUploadParams, type InitUploadResponse, type ListedPart, type ListPartsResponse, type ObjectInfo, type ProtocolContext, type UploadPartResponse } from './protocol';
+export { LocalStoragePersistence, PrefixFingerprinter, resolveResumePlan, WeakFingerprinter, type FileFingerprinter, type ResolveResumeInputs, type ResumablePersistence, type ResumeCandidate, type ResumeDecision, type ResumeDecisionHandler, type ResumePlan, type ResumeRecord } from './resumable';
+export { PRIVATE_PREFIX, PUBLIC_PREFIX, type UploaderOptions, type UploadInit, type UploadProgress, type UploadResult, type UploadSessionSnapshot, type UploadStatus } from './types';
+export { Uploader, uploadFile } from './uploader';

package/dist/types/storage/protocol.d.ts

@@ -0,0 +1,102 @@
+import { AxiosProgressEvent, GenericAbortSignal } from 'axios';
+import { HttpClient } from '../http';
+/**
+ * Default RPC entrypoint, resource, and version. Match the conventions used
+ * by `vef-framework-go`'s storage resource.
+ */
+export declare const DEFAULT_API_PATH = "/api";
+export declare const DEFAULT_RESOURCE = "sys/storage";
+export declare const DEFAULT_VERSION = "v1";
+/**
+ * Shared identifying fields for every storage RPC call. The protocol allows
+ * overriding `resource` / `version` per call site so callers running against
+ * a customized backend resource name stay supported without re-wiring the
+ * Uploader.
+ */
+export interface ProtocolContext {
+    http: Readonly<HttpClient>;
+    apiPath: string;
+    resource: string;
+    version: string;
+}
+export interface InitUploadParams {
+    filename: string;
+    size: number;
+    contentType?: string;
+    public?: boolean;
+}
+export interface InitUploadResponse {
+    key: string;
+    claimId: string;
+    originalFilename: string;
+    partSize: number;
+    partCount: number;
+    expiresAt: string;
+}
+export interface UploadPartResponse {
+    partNumber: number;
+    size: number;
+}
+export interface ObjectInfo {
+    bucket: string;
+    key: string;
+    eTag: string;
+    size: number;
+    contentType: string;
+    lastModified: string;
+    metadata?: Record<string, string>;
+}
+export interface CompleteUploadResponse extends ObjectInfo {
+    originalFilename: string;
+}
+/**
+ * Open a multipart upload session on the backend. The returned `partSize`
+ * and `partCount` are authoritative — callers must slice the file using
+ * exactly these values.
+ */
+export declare function initUpload(ctx: ProtocolContext, params: InitUploadParams, signal?: GenericAbortSignal): Promise<InitUploadResponse>;
+/**
+ * Upload a single part. Streams the blob through `HttpClient.upload` so
+ * axios surfaces progress events for the in-flight transfer.
+ */
+export declare function uploadPart(ctx: ProtocolContext, args: {
+    claimId: string;
+    partNumber: number;
+    blob: Blob;
+    onProgress?: (event: AxiosProgressEvent) => void;
+    signal?: GenericAbortSignal;
+}): Promise<UploadPartResponse>;
+/**
+ * One row of `list_parts`. Mirrors the backend's `ListedPart` struct —
+ * ETag is intentionally omitted server-side and therefore never appears
+ * here either: complete_upload assembles the parts list from the
+ * database, not from client-supplied state.
+ */
+export interface ListedPart {
+    partNumber: number;
+    size: number;
+}
+export interface ListPartsResponse {
+    parts: ListedPart[];
+}
+/**
+ * Enumerate parts the backend has already accepted for an active claim.
+ * Drives the resume path: callers feed the result into a `ResumePlan`
+ * so the Uploader knows which slots to skip. Errors map to
+ * `UploadProtocolError("list_parts", ...)` so callers can fold the
+ * "cannot resume" case into the storage error hierarchy and fall back
+ * to a fresh init.
+ */
+export declare function listParts(ctx: ProtocolContext, claimId: string, signal?: GenericAbortSignal): Promise<ListPartsResponse>;
+/**
+ * Finalize a multipart session. The backend reconstructs the part list from
+ * its `upload_part` table — the client never replays ETags.
+ */
+export declare function completeUpload(ctx: ProtocolContext, claimId: string, signal?: GenericAbortSignal): Promise<CompleteUploadResponse>;
+/**
+ * Best-effort cancellation of an in-flight session. Errors are swallowed —
+ * `abort_upload` is idempotent on the server, and a failure here must not
+ * mask the original cause that triggered the abort. Caller code can log via
+ * the optional `onError` hook.
+ */
+export declare function abortUpload(ctx: ProtocolContext, claimId: string, onError?: (error: unknown) => void): Promise<void>;

package/dist/types/storage/resumable/fingerprint.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Stable identifier for a file. Two `File` instances should produce the
+ * same fingerprint iff a sensible resume policy can treat them as the
+ * "same upload" — name, size, lastModified, and (for the default
+ * implementation) the first 4 MiB of content.
+ *
+ * The fingerprint is used as a `ResumablePersistence` lookup key. It is
+ * never sent to the server: resume detection is purely client-side, and
+ * the backend's authority is the claim ID stored alongside the
+ * fingerprint, not the fingerprint itself.
+ */
+export interface FileFingerprinter {
+    fingerprint: (file: File) => Promise<string>;
+}
+/**
+ * Fast, deterministic fingerprint derived from `name`, `size`, and
+ * `lastModified`. Synchronous (wrapped in a resolved promise) and
+ * always available — no `crypto.subtle`, no I/O.
+ *
+ * Trade-off: a user who replaces a file with different content but
+ * keeps the same name, size, and mtime will collide. Use only when
+ * the surrounding UI guarantees file identity by other means (e.g.
+ * a controlled upload widget that locks the file once selected).
+ */
+export declare class WeakFingerprinter implements FileFingerprinter {
+    fingerprint(file: File): Promise<string>;
+}
+/**
+ * Default fingerprinter for the framework. Combines metadata
+ * (name + size + lastModified) with the SHA-256 of the file's first
+ * 4 MiB. Catches the common "same metadata, different content" case
+ * (e.g. saving a new export over an old one) while keeping the hash
+ * window small enough to run on the main thread (<50 ms for large
+ * files) — no Web Worker needed.
+ *
+ * Requires `crypto.subtle`, which is available in all modern browsers
+ * over HTTPS (including `localhost`). When `crypto.subtle` is not
+ * available the constructor throws synchronously — callers should
+ * fall back to `WeakFingerprinter` at that point.
+ */
+export declare class PrefixFingerprinter implements FileFingerprinter {
+    #private;
+    static readonly defaultPrefixBytes: number;
+    /**
+     * @param prefixBytes - Override the prefix window size. The default
+     * (4 MiB) is a balance between collision resistance and main-thread
+     * cost; reducing it makes fingerprinting faster but more likely to
+     * miss small content changes near the file's tail.
+     */
+    constructor(prefixBytes?: number);
+    fingerprint(file: File): Promise<string>;
+}

package/dist/types/storage/resumable/index.d.ts

@@ -0,0 +1,3 @@
+export { PrefixFingerprinter, WeakFingerprinter, type FileFingerprinter } from './fingerprint';
+export { LocalStoragePersistence, type ResumablePersistence, type ResumeRecord } from './persistence';
+export { resolveResumePlan, type ResolveResumeInputs, type ResumeCandidate, type ResumeDecision, type ResumeDecisionHandler, type ResumePlan } from './plan';