@vef-framework-react/core 2.1.11 → 2.2.0

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

@@ -0,0 +1,98 @@
+/**
+ * A persisted upload session that can be matched against a re-opened file
+ * to resume from where the previous attempt left off. The record carries
+ * only what the client needs to call `list_parts` and rebuild the
+ * Uploader's plan — the authoritative list of completed parts is always
+ * fetched from the backend, never trusted from disk.
+ */
+export interface ResumeRecord {
+    /**
+     * Stable identifier of the file the session belongs to. Used by the
+     * persistence layer as a lookup key. Computed by the `FileFingerprinter`.
+     */
+    fingerprint: string;
+    /**
+     * Server-assigned claim ID. Replays into `list_parts` / `upload_part`
+     * — every framework RPC routes by claimId, never by the backend's
+     * internal multipart upload ID.
+     */
+    claimId: string;
+    /**
+     * Object key the backend assigned for this upload. Recorded for
+     * diagnostic purposes and parity with `InitUploadResponse`.
+     */
+    key: string;
+    /**
+     * Backend-authoritative part size. Persisted so the client can sanity-
+     * check the saved record against the file size before resuming
+     * (e.g. an out-of-date partSize indicates a configuration drift).
+     */
+    partSize: number;
+    /**
+     * Total number of parts the original `init_upload` planned for.
+     */
+    partCount: number;
+    /**
+     * Wall-clock expiry as an ISO-8601 string (mirrors
+     * `InitUploadResponse.expiresAt`). Reading code MUST compare this
+     * against `Date.now()` and discard expired records — the server-side
+     * sweeper may have deleted the underlying claim already.
+     */
+    expiresAt: string;
+    /**
+     * Local timestamp (`Date.now()`) when the record was last written.
+     * Not used for control flow; useful for diagnostics and future
+     * cleanup policies.
+     */
+    savedAt: number;
+}
+/**
+ * Pluggable persistence for `ResumeRecord` values. The default
+ * implementation (`LocalStoragePersistence`) targets `localStorage`,
+ * but the interface is intentionally async so callers can swap in
+ * IndexedDB, a server-side session store (for cross-device resume),
+ * or a multi-tenant namespaced backend.
+ *
+ * Implementations should be safe to call from any context (including
+ * SSR — see `LocalStoragePersistence` for the typical guard pattern).
+ * `load` MUST return `null` when no record exists; throwing is reserved
+ * for genuine I/O failures the caller would want to surface.
+ */
+export interface ResumablePersistence {
+    load: (fingerprint: string) => Promise<ResumeRecord | null>;
+    save: (record: ResumeRecord) => Promise<void>;
+    remove: (fingerprint: string) => Promise<void>;
+}
+/**
+ * Default `ResumablePersistence` implementation backed by
+ * `window.localStorage`. Keys are namespaced under `keyPrefix` (default
+ * `__VEF_UPLOAD_RESUME__`) so resume records cannot collide with the
+ * project's other localStorage consumers.
+ *
+ * The implementation is intentionally tolerant of structurally invalid
+ * stored payloads — if a record fails to parse it is dropped and `load`
+ * returns `null`, mirroring the "no record" case. This guards against
+ * format drift between releases (we'd rather start a fresh upload than
+ * crash on a stale row).
+ */
+export declare class LocalStoragePersistence implements ResumablePersistence {
+    #private;
+    constructor(keyPrefix?: string);
+    load(fingerprint: string): Promise<ResumeRecord | null>;
+    save(record: ResumeRecord): Promise<void>;
+    remove(fingerprint: string): Promise<void>;
+    /**
+     * Drop every record this persistence instance owns (matched by the
+     * configured key prefix). Call this on logout / account-switch so a
+     * subsequent user does not inherit the previous user's resume
+     * metadata — even though server-side ownership checks prevent
+     * cross-user claim theft, leaving the records around still leaks
+     * which keys the previous user had in flight (and, with the prefix
+     * fingerprint, whether they had ever uploaded any of a given set of
+     * candidate files).
+     *
+     * Foreign records (different prefix, unrelated localStorage entries)
+     * are left untouched.
+     */
+    clearAll(): Promise<void>;
+}

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

@@ -0,0 +1,105 @@
+import { GenericAbortSignal } from 'axios';
+import { ListedPart, ProtocolContext } from '../protocol';
+import { ResumablePersistence, ResumeRecord } from './persistence';
+/**
+ * Inputs collected for a potential resume; passed to the
+ * `onResumeDetected` callback so the UI layer can decide whether to
+ * continue the previous session or discard it.
+ *
+ * `completedParts` is the live result of `list_parts`, NOT a value
+ * retrieved from disk — the backend is the source of truth. The record
+ * is included so the UI can show context ("you uploaded N MiB of
+ * <filename> two hours ago, resume?").
+ */
+export interface ResumeCandidate {
+    record: ResumeRecord;
+    completedParts: ListedPart[];
+}
+/**
+ * Caller decision on whether to honor a `ResumeCandidate`. A discriminated
+ * union so future intents (e.g. "resume but rename target", "fork into a
+ * new claim") can be added without changing the callback signature.
+ */
+export type ResumeDecision = {
+    kind: "resume";
+} | {
+    kind: "discard";
+};
+/**
+ * Final resume plan handed to `Uploader.start(plan)`. The Uploader
+ * branches on `kind`:
+ *
+ * - `fresh`: behave as before — call `init_upload`, upload every part.
+ * - `resume`: skip `init_upload`, treat `completedParts` as the set of
+ * part numbers (with their server-recorded sizes) to bypass during
+ * the worker loop.
+ *
+ * `expiresAt` is carried through so consumers downstream of the
+ * Uploader (notably `useUpload`'s persistence layer) can refresh the
+ * stored record with the original authoritative expiry rather than
+ * re-deriving it.
+ */
+export type ResumePlan = {
+    kind: "fresh";
+} | {
+    kind: "resume";
+    claimId: string;
+    key: string;
+    partSize: number;
+    partCount: number;
+    expiresAt: string;
+    completedParts: readonly ListedPart[];
+};
+/**
+ * Caller's decision handler. Receives the candidate (record + live
+ * completed parts) and returns the decision. The default — when the
+ * caller does not provide one — is `{ kind: "discard" }`, because a
+ * resume that picks the wrong file is far worse than a redundant
+ * fresh upload.
+ */
+export type ResumeDecisionHandler = (candidate: ResumeCandidate) => Promise<ResumeDecision>;
+/**
+ * Inputs to `resolveResumePlan`. The caller is responsible for
+ * computing the fingerprint (so it can also use it elsewhere, e.g.
+ * to write the resume record after the upload starts) — the planner
+ * only consumes the resulting string.
+ */
+export interface ResolveResumeInputs {
+    fingerprint: string;
+    persistence: ResumablePersistence;
+    /**
+     * Protocol context carrying the HttpClient and RPC routing details.
+     * Same shape as the one passed to `initUpload` / `uploadPart` / etc.
+     */
+    ctx: ProtocolContext;
+    /**
+     * Defaults to `() => ({ kind: "discard" })`. Callers MUST provide a
+     * handler if they want resume to actually happen.
+     */
+    onResumeDetected?: ResumeDecisionHandler;
+    /**
+     * Optional cancellation signal for the in-flight `list_parts` / abort
+     * calls. Without it the planner blocks the caller until the network
+     * request settles — a slow server or hung connection makes
+     * `uploader.abort()` useless during the resume-detection phase.
+     */
+    signal?: GenericAbortSignal;
+}
+/**
+ * Compute the `ResumePlan` for a given fingerprint:
+ *
+ * 1. Look up the persisted record; on miss → `fresh`.
+ * 2. Validate the record's expiry against the wall clock; on expiry →
+ * remove + `fresh`.
+ * 3. Call `list_parts` to get the authoritative completed-parts list;
+ * on protocol error → remove + `fresh` (the claim is likely gone
+ * server-side).
+ * 4. Hand the candidate to `onResumeDetected`; honor the returned
+ * decision.
+ *
+ * A `discard` decision removes the local record first, then issues a
+ * best-effort `abort_upload`. Local-state cleanup is ordered first so
+ * a process crash between the two steps cannot leave a record that
+ * outlives its backend claim.
+ */
+export declare function resolveResumePlan(inputs: ResolveResumeInputs): Promise<ResumePlan>;

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

@@ -0,0 +1,166 @@
+/**
+ * Object key namespace prefixes used by the framework. Mirrors the constants
+ * declared on the Go side; clients embed them in object keys to communicate
+ * the intended visibility.
+ *
+ * - `PUBLIC_PREFIX`: anonymous-readable via the backend's direct URL.
+ * - `PRIVATE_PREFIX`: authenticated reads through `/storage/files/<key>`.
+ */
+export declare const PUBLIC_PREFIX = "pub/";
+export declare const PRIVATE_PREFIX = "priv/";
+/**
+ * The lifecycle status of an Uploader instance. Transitions are linear up to
+ * a terminal state (`succeeded`, `failed`, `aborted`).
+ *
+ * - `idle`: created but `start()` has not been called yet.
+ * - `initializing`: opening the multipart session against the backend.
+ * - `uploading`: streaming parts to the backend.
+ * - `completing`: assembling the multipart session on the backend.
+ * - `aborting`: caller requested cancellation and cleanup is in flight.
+ * - `succeeded`: terminal — final ObjectInfo is available on the result.
+ * - `failed`: terminal — the original error is stored on the instance.
+ * - `aborted`: terminal — `abort()` (or the external signal) completed.
+ */
+export type UploadStatus = "idle" | "initializing" | "uploading" | "completing" | "aborting" | "succeeded" | "failed" | "aborted";
+/**
+ * Initialization parameters forwarded to the backend's `init_upload`. Either
+ * supply these explicitly via `UploaderOptions.init` or rely on the defaults
+ * derived from the `File`'s `name`, `type`, and `size`.
+ */
+export interface UploadInit {
+    /**
+     * Override the original filename. Defaults to `file.name`.
+     */
+    filename?: string;
+    /**
+     * Override the declared MIME type. Defaults to `file.type`.
+     */
+    contentType?: string;
+    /**
+     * Land the object under `pub/` (`true`) or `priv/` (`false`/omitted).
+     */
+    public?: boolean;
+}
+/**
+ * Aggregated upload progress emitted by the Uploader.
+ *
+ * `loaded` aggregates bytes acknowledged across **completed** parts, plus the
+ * latest in-flight progress for each part that has not yet finished. The
+ * value is monotonically non-decreasing within a single upload session.
+ */
+export interface UploadProgress {
+    /**
+     * Bytes acknowledged so far. Never exceeds `total`.
+     */
+    loaded: number;
+    /**
+     * Total file size in bytes (mirrors the declared `size`).
+     */
+    total: number;
+    /**
+     * Number of parts that have been fully accepted by the backend.
+     */
+    partsCompleted: number;
+    /**
+     * Total number of parts in the upload plan.
+     */
+    partsTotal: number;
+    /**
+     * Convenience field: `loaded / total` rounded to an integer percentage.
+     */
+    percent: number;
+}
+/**
+ * The final result of a successful upload. Combines the backend `ObjectInfo`
+ * with the framework-tracked `originalFilename`.
+ */
+export interface UploadResult {
+    bucket: string;
+    key: string;
+    eTag: string;
+    size: number;
+    contentType: string;
+    lastModified: string;
+    originalFilename: string;
+    metadata?: Record<string, string>;
+}
+/**
+ * Construction options for `Uploader`. Defaults match the server's documented
+ * conventions; override only when you have a concrete reason.
+ */
+export interface UploaderOptions {
+    /**
+     * RPC entrypoint URL. Defaults to `/api`.
+     */
+    apiPath?: string;
+    /**
+     * RPC resource name. Defaults to `sys/storage`.
+     */
+    resource?: string;
+    /**
+     * RPC version. Defaults to `v1`.
+     */
+    version?: string;
+    /**
+     * Init-time overrides for the backend session.
+     */
+    init?: UploadInit;
+    /**
+     * Maximum number of parts uploaded in parallel. The backend can already
+     * absorb high concurrency; the practical cap is the client's outbound
+     * bandwidth and the browser's per-origin connection budget. Defaults to 3.
+     */
+    partConcurrency?: number;
+    /**
+     * Per-part retry budget for transient failures. The initial attempt counts
+     * as 1, so a value of 3 yields up to 2 retries before the part is treated
+     * as fatal. Defaults to 3.
+     */
+    maxPartRetries?: number;
+    /**
+     * Base delay (ms) for exponential per-part retry backoff. Defaults to 500.
+     */
+    retryBaseDelay?: number;
+    /**
+     * Maximum delay (ms) any single retry will wait. Defaults to 8000.
+     */
+    retryMaxDelay?: number;
+    /**
+     * External abort signal. Combined with the internal controller so any of
+     * `signal.abort()`, `uploader.abort()`, or a fatal protocol error will
+     * tear down in-flight parts and trigger a best-effort `abort_upload`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Invoked after every part progress tick.
+     */
+    onProgress?: (progress: UploadProgress) => void;
+    /**
+     * Invoked on every `UploadStatus` transition.
+     */
+    onStatusChange?: (status: UploadStatus) => void;
+    /**
+     * Invoked once after the backend has confirmed an upload session.
+     * Carries the fields needed to persist a resumable record. Fires on
+     * the fresh path (after `init_upload` returns) and on the resume path
+     * (synthesized immediately from the supplied `ResumePlan`) so a
+     * consumer like `useUpload` can write the localStorage record at the
+     * earliest opportunity in either case.
+     */
+    onSessionOpened?: (session: UploadSessionSnapshot) => void;
+}
+/**
+ * Minimal session description handed to `onSessionOpened`. Mirrors the
+ * subset of `InitUploadResponse` that downstream resume-persistence
+ * code cares about. The Uploader carries the original `expiresAt`
+ * through both the fresh path (returned by `init_upload`) and the
+ * resume path (sourced from the persisted record) so consumers can
+ * always parse it directly.
+ */
+export interface UploadSessionSnapshot {
+    claimId: string;
+    key: string;
+    partSize: number;
+    partCount: number;
+    expiresAt: string;
+}

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

@@ -0,0 +1,58 @@
+import { HttpClient } from '../http';
+import { ResumePlan } from './resumable/plan';
+import { UploaderOptions, UploadProgress, UploadResult, UploadStatus } from './types';
+/**
+ * Drives a single file through the four-step chunked upload protocol
+ * (`init_upload → upload_part* → complete_upload`) exposed by the framework's
+ * `sys/storage` resource. Errors trigger a best-effort `abort_upload` so the
+ * backend never retains a dangling multipart session.
+ *
+ * The instance is one-shot: a successful or failed run cannot be restarted.
+ * Create a fresh `Uploader` for each file.
+ */
+export declare class Uploader {
+    #private;
+    constructor(http: Readonly<HttpClient>, file: Blob, options?: UploaderOptions);
+    /**
+     * Current lifecycle status.
+     */
+    get status(): UploadStatus;
+    /**
+     * Latest aggregated progress snapshot.
+     */
+    get progress(): UploadProgress;
+    /**
+     * Start the upload. Returns the eventual `UploadResult` on success or
+     * rejects with an `UploadError` (use `instanceof UploadAbortedError` /
+     * `UploadProtocolError` / `UploadPartError` to discriminate). Calling
+     * `start()` more than once returns the original promise.
+     *
+     * When called with a `plan` of kind `"resume"`, the uploader skips
+     * `init_upload` and synthesises the session from the plan's
+     * `claimId`/`partSize`/`partCount`. Workers will skip every part
+     * number in `plan.completedParts`. The default behaviour
+     * (no plan, or `kind: "fresh"`) is unchanged.
+     */
+    start(plan?: ResumePlan): Promise<UploadResult>;
+    /**
+     * Cancel an in-flight upload and best-effort abort the backend session.
+     * Safe to call from any state — terminal states are a no-op. Returns when
+     * the backend has been notified (or never reachable in the first place).
+     */
+    abort(): Promise<void>;
+}
+/**
+ * Convenience wrapper that constructs an Uploader and immediately starts it.
+ * Use the class directly when you need to expose `abort()` to the UI or
+ * observe status transitions externally.
+ */
+export declare function uploadFile(http: Readonly<HttpClient>, file: Blob, options?: UploaderOptions): Promise<UploadResult>;
+/**
+ * Exposed for test seams; not part of the stable public surface.
+ */
+export declare const _internals: {
+    DEFAULT_PART_CONCURRENCY: number;
+    DEFAULT_MAX_PART_RETRIES: number;
+    DEFAULT_RETRY_BASE_DELAY: number;
+    DEFAULT_RETRY_MAX_DELAY: number;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vef-framework-react/core",
   "type": "module",
-  "version": "2.1.11",
+  "version": "2.2.0",
   "private": false,
   "description": "Core features for VEF framework",
   "author": {
@@ -49,27 +49,27 @@
   },
   "dependencies": {
     "@dnd-kit/abstract": "^0.4.0",
+    "@dnd-kit/collision": "^0.4.0",
     "@dnd-kit/dom": "^0.4.0",
     "@dnd-kit/helpers": "^0.4.0",
     "@dnd-kit/react": "^0.4.0",
     "@emotion/react": "^11.14.0",
     "@hello-pangea/dnd": "^18.0.1",
     "@microsoft/fetch-event-source": "^2.0.1",
-    "@tanstack/react-query": "^5.100.1",
+    "@tanstack/react-query": "^5.100.9",
     "@xstate/react": "^6.1.0",
-    "ai": "6.0.168",
-    "axios": "^1.15.2",
+    "axios": "^1.16.0",
     "clsx": "^2.1.1",
-    "immer": "^11.1.4",
-    "jotai": "^2.19.1",
+    "immer": "^11.1.7",
+    "jotai": "^2.20.0",
     "motion": "^12.38.0",
     "use-immer": "^0.11.0",
-    "xstate": "^5.30.0",
-    "zustand": "^5.0.12",
-    "@vef-framework-react/shared": "2.1.11"
+    "xstate": "^5.31.0",
+    "zustand": "^5.0.13",
+    "@vef-framework-react/shared": "2.2.0"
   },
   "devDependencies": {
-    "react": "^19.2.5"
+    "react": "^19.2.6"
   },
   "scripts": {
     "clean": "rimraf dist",

package/dist/cjs/ai/index.cjs

@@ -1 +0,0 @@
-require(`../_internal/_rolldown/runtime.cjs`),require(`ai`);

package/dist/es/ai/index.js

@@ -1,3 +0,0 @@
-/*! @vef-framework-react/core v2.1.11 made by Venus | 2026-04-29T08:23:47.448Z */
-import { DefaultChatTransport as e, TextStreamChatTransport as t, getToolName as n, getToolOrDynamicToolName as r, isDataUIPart as i, isDeepEqualData as a, isFileUIPart as o, isReasoningUIPart as s, isTextUIPart as c, isToolOrDynamicToolUIPart as l, isToolUIPart as u, parsePartialJson as d } from "ai";
-export { e as DefaultChatTransport, t as TextStreamChatTransport, n as getToolName, r as getToolOrDynamicToolName, i as isDataUIPart, a as isDeepEqualData, o as isFileUIPart, s as isReasoningUIPart, c as isTextUIPart, l as isToolOrDynamicToolUIPart, u as isToolUIPart, d as parsePartialJson };

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

@@ -1,6 +0,0 @@
-export { DefaultChatTransport, TextStreamChatTransport, type ChatTransport } from 'ai';
-export type { DataUIPart, DynamicToolUIPart, FileUIPart, ReasoningUIPart, SourceDocumentUIPart, SourceUrlUIPart, StepStartUIPart, TextUIPart, ToolUIPart, UIMessage, UIMessageChunk, UIMessagePart } from 'ai';
-export type { UIToolInvocation, UITools } from 'ai';
-export { getToolName, getToolOrDynamicToolName } from 'ai';
-export { isDataUIPart, isFileUIPart, isReasoningUIPart, isTextUIPart, isToolOrDynamicToolUIPart, isToolUIPart } from 'ai';
-export { isDeepEqualData, parsePartialJson } from 'ai';