@vef-framework-react/core 2.3.0 → 2.4.0

package/dist/es/storage/uploader.js

@@ -1,12 +1,14 @@
-/*! @vef-framework-react/core v2.3.0 made by Venus | 2026-05-22T09:39:47.405Z */
+/*! @vef-framework-react/core v2.4.0 made by Venus | 2026-06-15T15:10:07.347Z */
 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";
+import { createUploaderMachine as c } from "./uploader-machine.js";
+import { createActor as l } from "xstate";
 //#region src/storage/uploader.ts
-var c = 3, l = 3, u = 500, d = 8e3;
-function f(e, t, n, r) {
+var u = 3, d = 3, f = 500, p = 8e3;
+function m(e, t, n, r) {
 	return n < r ? t : e - t * (r - 1);
 }
-function p(t, n) {
+function h(t, n) {
 	return new Promise((r, i) => {
 		if (n.aborted) {
 			i(new e());
@@ -20,7 +22,7 @@ function p(t, n) {
 		n.addEventListener("abort", o, { once: !0 });
 	});
 }
-var m = class {
+var g = class {
 	#e;
 	#t;
 	#n;
@@ -35,13 +37,18 @@ var m = class {
 	#d;
 	#f;
 	#p;
-	#m = "idle";
-	#h;
+	#m;
+	#h = "idle";
 	#g;
-	#_ = 0;
-	#v = /* @__PURE__ */ new Map();
-	#y = 1;
-	#b = /* @__PURE__ */ new Set();
+	#_;
+	#v;
+	#y;
+	#b;
+	#x;
+	#S = 0;
+	#C = /* @__PURE__ */ new Map();
+	#w = 1;
+	#T = /* @__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)");
@@ -50,57 +57,114 @@ var m = class {
 			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 = {
+		}, 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 ?? u), this.#o = Math.max(1, r.maxPartRetries ?? d), this.#s = Math.max(0, r.retryBaseDelay ?? f), this.#c = Math.max(this.#s, r.retryMaxDelay ?? p), this.#l = r.onProgress, this.#u = r.onStatusChange, this.#d = r.onSessionOpened, this.#f = new AbortController(), this.#p = this.#D(r.signal), this.#g = {
 			loaded: 0,
 			total: n.size,
 			partsCompleted: 0,
 			partsTotal: 0,
 			percent: 0
-		};
+		}, this.#m = l(c({
+			prepareSession: (e) => this.#N(e),
+			uploadParts: () => this.#L(this.#A()),
+			completeSession: () => this.#F(),
+			abortSession: () => this.#I(),
+			killTransport: () => {
+				this.#f.abort();
+			},
+			recordFailure: (e) => {
+				this.#b = e;
+			},
+			abortRequested: () => this.#f.signal.aborted
+		})), this.#m.subscribe((e) => {
+			this.#O(e.value), e.status === "done" && this.#k(e.value);
+		}), this.#m.start();
 	}
 	get status() {
-		return this.#m;
+		return this.#h;
 	}
 	get progress() {
-		return this.#h;
+		return this.#g;
 	}
 	start(e) {
-		return this.#g ||= this.#E(e ?? { kind: "fresh" }), this.#g;
+		return this.#_ ? this.#_ : (this.#_ = new Promise((e, t) => {
+			this.#v = {
+				resolve: e,
+				reject: t
+			};
+		}), this.#m.send({
+			type: "START",
+			plan: e ?? { kind: "fresh" }
+		}), this.#_);
 	}
 	async abort() {
-		if (this.#S()) return;
-		this.#f.abort();
-		let e = this.#g;
+		if (this.#m.getSnapshot().status === "done") return;
+		this.#E();
+		let e = this.#_;
 		if (e) try {
 			await e;
 		} catch {}
 	}
-	#x(e) {
+	#E() {
+		this.#m.send({ type: "ABORT" }), this.#f.abort();
+	}
+	#D(e) {
 		if (!e) return;
 		if (e.aborted) {
 			this.#f.abort();
 			return;
 		}
-		let t = () => this.#f.abort();
+		let t = () => this.#E();
 		return e.addEventListener("abort", t, { once: !0 }), () => e.removeEventListener("abort", t);
 	}
-	#S() {
-		return this.#m === "succeeded" || this.#m === "failed" || this.#m === "aborted";
+	#O(e) {
+		this.#h !== e && (this.#h = e, this.#u?.(e));
+	}
+	#k(t) {
+		this.#p?.();
+		let n = this.#v;
+		if (n) switch (t) {
+			case "succeeded":
+				n.resolve(this.#j());
+				return;
+			case "aborted":
+				n.reject(new e());
+				return;
+			default: n.reject(this.#V(this.#b));
+		}
+	}
+	#A() {
+		if (!this.#y) throw new t("upload session is not open");
+		return this.#y;
 	}
-	#C(e) {
-		this.#m !== e && (this.#m = e, this.#u?.(e));
+	#j() {
+		if (!this.#x) throw new t("upload result missing after completion");
+		return this.#x;
 	}
-	#w() {
+	#M() {
 		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,
+		for (let t of this.#C.values()) e += t;
+		let t = Math.min(this.#g.total, this.#S + e), n = this.#g.total === 0 ? 0 : Math.floor(t / this.#g.total * 100);
+		this.#g = {
+			...this.#g,
 			loaded: t,
 			percent: n
-		}, this.#l?.(this.#h);
+		}, this.#l?.(this.#g);
 	}
-	async #T(e) {
+	async #N(e) {
+		let { session: t, skipParts: n, completedBytes: r } = await this.#P(e);
+		this.#y = t, this.#T = n, this.#S = r, this.#d?.({
+			claimId: t.claimId,
+			key: t.key,
+			partSize: t.partSize,
+			partCount: t.partCount,
+			expiresAt: t.expiresAt
+		}), this.#g = {
+			...this.#g,
+			partsTotal: t.partCount,
+			partsCompleted: n.size
+		}, this.#M();
+	}
+	async #P(e) {
 		if (e.kind === "fresh") return {
 			session: await o(this.#e, {
 				filename: this.#n,
@@ -128,96 +192,78 @@ var m = class {
 			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 #F() {
+		let e = this.#A(), t = await a(this.#e, e.claimId, this.#f.signal);
+		this.#x = {
+			bucket: t.bucket,
+			key: t.key,
+			eTag: t.eTag,
+			size: t.size,
+			contentType: t.contentType,
+			lastModified: t.lastModified,
+			originalFilename: t.originalFilename,
+			metadata: t.metadata
+		};
+	}
+	async #I() {
+		let e = this.#y?.claimId;
+		e !== void 0 && await i(this.#e, e);
 	}
-	async #D(e) {
+	async #L(e) {
 		let t = Math.min(this.#a, e.partCount), n = [];
-		for (let r = 0; r < t; r++) n.push(this.#O(e));
+		for (let r = 0; r < t; r++) n.push(this.#R(e));
 		try {
 			await Promise.all(n);
 		} catch (e) {
 			throw this.#f.abort(), e;
 		}
 	}
-	async #O(e) {
+	async #R(e) {
 		for (; !this.#f.signal.aborted;) {
-			let t = this.#k(e.partCount);
+			let t = this.#z(e.partCount);
 			if (t === null) return;
-			await this.#A(e, t);
+			await this.#B(e, t);
 		}
 	}
-	#k(e) {
-		for (; this.#y <= e;) {
-			let e = this.#y++;
-			if (!this.#b.has(e)) return e;
+	#z(e) {
+		for (; this.#w <= e;) {
+			let e = this.#w++;
+			if (!this.#T.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;
+	async #B(t, r) {
+		let i = m(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, {
+				this.#C.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();
+						this.#C.set(r, Math.min(i, e.loaded)), this.#M();
 					},
 					signal: this.#f.signal
-				}), this.#v.delete(r), this.#_ += i, this.#h = {
-					...this.#h,
-					partsCompleted: this.#h.partsCompleted + 1
-				}, this.#w();
+				}), this.#C.delete(r), this.#S += i, this.#g = {
+					...this.#g,
+					partsCompleted: this.#g.partsCompleted + 1
+				}, this.#M();
 				return;
 			} catch (t) {
-				if (this.#v.delete(r), l = t, this.#f.signal.aborted) throw new e();
+				if (this.#C.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);
+				await h(Math.min(this.#c, this.#s * 2 ** (c - 1)), this.#f.signal);
 			}
 		}
 		throw new n(r, c, { cause: l });
 	}
-	#j(e) {
+	#V(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();
+function _(e, t, n) {
+	return new g(e, t, n).start();
 }
 //#endregion
-export { m as Uploader, h as uploadFile };
+export { g as Uploader, _ as uploadFile };

package/dist/es/store/bound.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/core v2.3.0 made by Venus | 2026-05-22T09:39:47.405Z */
+/*! @vef-framework-react/core v2.4.0 made by Venus | 2026-06-15T15:10:07.347Z */
 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.3.0 made by Venus | 2026-05-22T09:39:47.405Z */
+/*! @vef-framework-react/core v2.4.0 made by Venus | 2026-06-15T15:10:07.347Z */
 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.3.0 made by Venus | 2026-05-22T09:39:47.405Z */
+/*! @vef-framework-react/core v2.4.0 made by Venus | 2026-06-15T15:10:07.347Z */
 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.3.0 made by Venus | 2026-05-22T09:39:47.405Z */
+/*! @vef-framework-react/core v2.4.0 made by Venus | 2026-06-15T15:10:07.347Z */
 import { isDeepEqual as e } from "@vef-framework-react/shared";
 import { useRef as t } from "react";
 //#region src/store/use-deep.ts

package/dist/types/{dnd → src/dnd}/index.d.ts

@@ -1,12 +1,13 @@
+export { CollisionPriority } from '@dnd-kit/abstract';
 export { AxisModifier, restrictShapeToBoundingRectangle, RestrictToHorizontalAxis, RestrictToVerticalAxis, SnapModifier } from '@dnd-kit/abstract/modifiers';
 export { closestCenter, closestCorners, defaultCollisionDetection, directionBiased, pointerDistance, pointerIntersection, shapeIntersection } from '@dnd-kit/collision';
 export type { CollisionDetector } from '@dnd-kit/collision';
-export { defaultPreset, Feedback } from '@dnd-kit/dom';
+export { defaultPreset, Feedback, PointerActivationConstraints } from '@dnd-kit/dom';
 export type { FeedbackInput, FeedbackOptions, FeedbackType } from '@dnd-kit/dom';
 export { RestrictToElement, RestrictToWindow } from '@dnd-kit/dom/modifiers';
 export { arrayMove as moveArrayItem, move as moveDragItem, arraySwap as swapArrayItem, swap as swapDragItem } from '@dnd-kit/helpers';
 export type { BeforeDragStartEvent, CollisionEvent, DragDropEventHandlers, DragEndEvent, DragMoveEvent, DragOverEvent, DragStartEvent } from '@dnd-kit/react';
-export { DragDropProvider, DragOverlay, KeyboardSensor, PointerSensor, useDragDropMonitor, useDraggable, useDroppable } from '@dnd-kit/react';
+export { DragDropProvider, DragOverlay, KeyboardSensor, PointerSensor, useDragDropMonitor, useDraggable, useDragOperation, useDroppable } from '@dnd-kit/react';
 export { useSortable } from '@dnd-kit/react/sortable';
 export type { DragDropContextProps, DraggableChildrenFn, DraggableId, DraggableLocation, DraggableProps, DraggableProvided, DraggableProvidedDraggableProps, DraggableProvidedDragHandleProps, DraggableRubric, DraggableStateSnapshot, DroppableId, DroppableProps, DroppableProvided, DroppableProvidedProps, DroppableStateSnapshot, DropResult, OnBeforeCaptureResponder, OnBeforeDragStartResponder, OnDragEndResponder, OnDragStartResponder, OnDragUpdateResponder } from '@hello-pangea/dnd';
 export { DragDropContext, Draggable, Droppable } from '@hello-pangea/dnd';

package/dist/types/{index.d.ts → src/index.d.ts}

@@ -2,7 +2,7 @@ export { ApiClient, createApiClient, createApiRequest, HTTP_CLIENT, QUERY_CLIENT
 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';
-export { AxisModifier, closestCenter, closestCorners, defaultCollisionDetection, defaultPreset, directionBiased, DragDropContext, DragDropProvider, Draggable, DragOverlay, Droppable, Feedback, KeyboardSensor, moveArrayItem, moveDragItem, pointerDistance, pointerIntersection, PointerSensor, restrictShapeToBoundingRectangle, RestrictToElement, RestrictToHorizontalAxis, RestrictToVerticalAxis, RestrictToWindow, shapeIntersection, SnapModifier, swapArrayItem, swapDragItem, useDragDropMonitor, useDraggable, useDroppable, useSortable, type BeforeDragStartEvent, type CollisionDetector, type CollisionEvent, type DragDropContextProps, type DragDropEventHandlers, type DragEndEvent, type DraggableChildrenFn, type DraggableId, type DraggableLocation, type DraggableProps, type DraggableProvided, type DraggableProvidedDraggableProps, type DraggableProvidedDragHandleProps, type DraggableRubric, type DraggableStateSnapshot, type DragMoveEvent, type DragOverEvent, type DragStartEvent, type DroppableId, type DroppableProps, type DroppableProvided, type DroppableProvidedProps, type DroppableStateSnapshot, type DropResult, type FeedbackInput, type FeedbackOptions, type FeedbackType, type OnBeforeCaptureResponder, type OnBeforeDragStartResponder, type OnDragEndResponder, type OnDragStartResponder, type OnDragUpdateResponder } from './dnd';
+export { AxisModifier, closestCenter, closestCorners, CollisionPriority, defaultCollisionDetection, defaultPreset, directionBiased, DragDropContext, DragDropProvider, Draggable, DragOverlay, Droppable, Feedback, KeyboardSensor, moveArrayItem, moveDragItem, PointerActivationConstraints, pointerDistance, pointerIntersection, PointerSensor, restrictShapeToBoundingRectangle, RestrictToElement, RestrictToHorizontalAxis, RestrictToVerticalAxis, RestrictToWindow, shapeIntersection, SnapModifier, swapArrayItem, swapDragItem, useDragDropMonitor, useDraggable, useDragOperation, useDroppable, useSortable, type BeforeDragStartEvent, type CollisionDetector, type CollisionEvent, type DragDropContextProps, type DragDropEventHandlers, type DragEndEvent, type DraggableChildrenFn, type DraggableId, type DraggableLocation, type DraggableProps, type DraggableProvided, type DraggableProvidedDraggableProps, type DraggableProvidedDragHandleProps, type DraggableRubric, type DraggableStateSnapshot, type DragMoveEvent, type DragOverEvent, type DragStartEvent, type DroppableId, type DroppableProps, type DroppableProvided, type DroppableProvidedProps, type DroppableStateSnapshot, type DropResult, type FeedbackInput, type FeedbackOptions, type FeedbackType, type OnBeforeCaptureResponder, type OnBeforeDragStartResponder, type OnDragEndResponder, type OnDragStartResponder, type OnDragUpdateResponder } from './dnd';
 export type { ApiResult, AuthTokens, BusinessError, HttpClient, HttpClientOptions, isBusinessError, ProgressEvent, RequestOptions } from './http';
 export { skipAuthenticationHeader, skipAuthenticationValue } from './http';
 export { applyPatches, currentState, originalState, produce, produceWithPatches, useImmer, useImmerReducer } from './immer';

package/dist/types/{query → src/query}/hooks.d.ts

@@ -1,4 +1,4 @@
-import { DefinedInitialDataInfiniteOptions, DefinedInitialDataOptions, DefinedUseInfiniteQueryResult, DefinedUseQueryResult, InfiniteData, MutationFilters, MutationState, NoInfer, QueriesResults, QueryFilters, UndefinedInitialDataInfiniteOptions, UndefinedInitialDataOptions, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult, useMutationState as useMutationStateInternal, useQueries as useQueriesInternal } from '@tanstack/react-query';
+import { DefinedInitialDataInfiniteOptions, DefinedInitialDataOptions, DefinedUseInfiniteQueryResult, DefinedUseQueryResult, InfiniteData, MutationFilters, MutationState, QueriesResults, QueryFilters, UndefinedInitialDataInfiniteOptions, UndefinedInitialDataOptions, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult, useMutationState as useMutationStateInternal, useQueries as useQueriesInternal } from '@tanstack/react-query';
 import { QueryKey } from '../api';
 export declare function useQuery<TQueryFnData = unknown, TData = TQueryFnData, TParams = never>(options: DefinedInitialDataOptions<TQueryFnData, Error, TData, QueryKey<TParams>>): DefinedUseQueryResult<NoInfer<TData>, Error>;
 export declare function useQuery<TQueryFnData = unknown, TData = TQueryFnData, TParams = never>(options: UndefinedInitialDataOptions<TQueryFnData, Error, TData, QueryKey<TParams>> | UseQueryOptions<TQueryFnData, Error, TData, QueryKey<TParams>>): UseQueryResult<NoInfer<TData>, Error>;

package/dist/types/src/sse/client.d.ts

@@ -0,0 +1,24 @@
+import { SseClientOptions, SseEventHandlers, SseRequestConfig } from './types';
+/**
+ * SSE client wrapper around @microsoft/fetch-event-source.
+ *
+ * Each `stream()` call runs the session statechart in `./stream-machine.ts`
+ * (attempt → token refresh → one retry); this class supplies the connection
+ * attempt itself and the token-refresh callback. Reconnects *within* an
+ * attempt stay inside `fetch-event-source`, which owns `Last-Event-ID`
+ * continuity and server-driven retry intervals.
+ */
+export declare class SseClient {
+    #private;
+    constructor(options?: SseClientOptions);
+    /**
+     * Start an SSE stream request. Resolves when the stream ends — normally,
+     * by abort, or after a reported auth failure; rejects with the original
+     * error when the stream fails past its retry budget.
+     */
+    stream(config: SseRequestConfig, handlers: SseEventHandlers): Promise<void>;
+    /**
+     * Abort all active stream requests.
+     */
+    abort(): void;
+}

package/dist/types/src/sse/stream-machine.d.ts

@@ -0,0 +1,104 @@
+import { StateMachine, MachineContext, AnyEventObject, ActorRefFromLogic, PromiseActorLogic, NonReducibleUnknown, EventObject, MetaObject } from 'xstate';
+/**
+ * Internal signal: the backend answered 401, so the attempt must stop and
+ * the session may retry once after a token refresh. Thrown by the client's
+ * `onopen` handler; routed (never surfaced) by the session statechart.
+ */
+export declare class TokenExpiredError extends Error {
+    constructor();
+}
+/**
+ * Side-effect surface the stream-session statechart drives. Every dep
+ * closes over one `stream()` call's config and handlers.
+ */
+export interface StreamMachineDeps {
+    /**
+     * One full connection attempt: prepare headers, open the event source,
+     * pump events until the stream ends. In-connection reconnects stay
+     * delegated to `fetch-event-source` (it owns `Last-Event-ID` continuity
+     * and server-driven retry intervals); a rejection here means the attempt
+     * is over — `TokenExpiredError` asks for the refresh path.
+     */
+    runAttempt: () => Promise<void>;
+    /**
+     * Ask the host app to refresh the token. Total by contract: resolves
+     * `false` instead of rejecting when the refresh fails.
+     */
+    refreshToken: () => Promise<boolean>;
+    /**
+     * Deliver the "authentication failed" outcome to the caller's handlers.
+     * The session still ends as `completed` — auth failure is reported, not
+     * thrown (the caller already got the error through `onError`).
+     */
+    reportAuthFailure: () => void;
+    /**
+     * Record the error the `stream()` promise rejects with (the original
+     * instance, untouched) once the machine reaches `failed`.
+     */
+    recordFailure: (error: unknown) => void;
+}
+/**
+ * Session statechart behind `SseClient.stream()`: at most two connection
+ * attempts bridged by a single token refresh.
+ *
+ * ```
+ * streaming ──ok/abort──▶ completed
+ * │ token expired
+ * ▼
+ * refreshingToken ──refresh failed──▶ completed (auth failure reported)
+ * │ refreshed
+ * ▼
+ * retrying ──ok/abort──▶ completed
+ * │ any error (including a second 401)
+ * ▼
+ * failed
+ * ```
+ *
+ * The chart replaces the previous recursion (`#executeStream` calling
+ * itself) and its scattered closure flags (`tokenRefreshAttempted`,
+ * `cleanedUp`): "the refresh has been spent" is now the `retrying` state
+ * itself, not a boolean threaded through call frames.
+ */
+export declare function createStreamMachine(deps: StreamMachineDeps): StateMachine<MachineContext, AnyEventObject, {
+    [x: string]: ActorRefFromLogic<PromiseActorLogic<boolean, NonReducibleUnknown, EventObject>> | ActorRefFromLogic<PromiseActorLogic<void, NonReducibleUnknown, EventObject>> | undefined;
+}, {
+    src: "refreshToken";
+    logic: PromiseActorLogic<boolean, NonReducibleUnknown, EventObject>;
+    id: string | undefined;
+} | {
+    src: "runAttempt";
+    logic: PromiseActorLogic<void, NonReducibleUnknown, EventObject>;
+    id: string | undefined;
+}, {
+    type: "recordFailure";
+    params: {
+        error: unknown;
+    };
+} | {
+    type: "reportAuthFailure";
+    params: unknown;
+}, {
+    type: "wasAborted";
+    params: {
+        error: unknown;
+    };
+} | {
+    type: "wasTokenExpired";
+    params: {
+        error: unknown;
+    };
+} | {
+    type: "refreshSucceeded";
+    params: {
+        refreshed: boolean;
+    };
+}, never, "streaming" | "completed" | "refreshingToken" | "failed" | "retrying", string, NonReducibleUnknown, NonReducibleUnknown, EventObject, MetaObject, {
+    id: "sseStream";
+    states: {
+        readonly streaming: {};
+        readonly refreshingToken: {};
+        readonly retrying: {};
+        readonly completed: {};
+        readonly failed: {};
+    };
+}>;

package/dist/types/src/storage/uploader-machine.d.ts

@@ -0,0 +1,108 @@
+import { ResumePlan } from './resumable/plan';
+import { StateMachine, MachineContext, ActorRefFromLogic, PromiseActorLogic, NonReducibleUnknown, EventObject, MetaObject } from 'xstate';
+/**
+ * Side-effect surface the uploader statechart drives. The machine owns the
+ * lifecycle only — every phase runner closes over the `Uploader` instance
+ * that supplies it, so the chart stays a pure, domain-free transition table.
+ */
+export interface UploaderMachineDeps {
+    /**
+     * Open (fresh) or synthesise (resume) the multipart session and seed the
+     * uploader's bookkeeping. Rejection means the session never opened.
+     */
+    prepareSession: (plan: ResumePlan) => Promise<void>;
+    /**
+     * Stream every pending part through the worker pool. Rejection carries the
+     * first terminal worker error.
+     */
+    uploadParts: () => Promise<void>;
+    /**
+     * Finalize the multipart session and capture the upload result.
+     */
+    completeSession: () => Promise<void>;
+    /**
+     * Best-effort backend `abort_upload`. Must never reject for control flow —
+     * the machine lands in `aborted` either way.
+     */
+    abortSession: () => Promise<void>;
+    /**
+     * Abort the shared transport controller so in-flight HTTP requests and
+     * pending retry backoffs unwind immediately.
+     */
+    killTransport: () => void;
+    /**
+     * Record the error a phase rejected with; `start()` rejects with it once
+     * the machine reaches `failed`.
+     */
+    recordFailure: (error: unknown) => void;
+    /**
+     * Whether an abort was latched before the run started (external signal
+     * already aborted, or `abort()` called while still idle).
+     */
+    abortRequested: () => boolean;
+}
+export type UploaderEvent = {
+    type: "START";
+    plan: ResumePlan;
+} | {
+    type: "ABORT";
+};
+/**
+ * Lifecycle statechart behind `Uploader`. State names are exactly the public
+ * `UploadStatus` values — the chart IS the documented contract in
+ * `./types.ts`, and `Uploader` maps snapshots to statuses by name.
+ *
+ * Cancellation is an *event channel* (`ABORT`), not an error-instance check:
+ * a phase rejection always means failure (`onError` → `failed`, session kept
+ * alive for resume), while a caller abort always transitions to `aborting`
+ * (backend session torn down). The two can no longer be confused, even when
+ * the worker pool trips the shared controller itself to stop sibling workers
+ * after a terminal part failure.
+ */
+export declare function createUploaderMachine(deps: UploaderMachineDeps): StateMachine<MachineContext, {
+    type: "START";
+    plan: ResumePlan;
+} | {
+    type: "ABORT";
+}, {
+    [x: string]: ActorRefFromLogic<PromiseActorLogic<void, NonReducibleUnknown, EventObject>> | ActorRefFromLogic<PromiseActorLogic<void, ResumePlan, EventObject>> | undefined;
+}, {
+    src: "prepareSession";
+    logic: PromiseActorLogic<void, ResumePlan, EventObject>;
+    id: string | undefined;
+} | {
+    src: "uploadParts";
+    logic: PromiseActorLogic<void, NonReducibleUnknown, EventObject>;
+    id: string | undefined;
+} | {
+    src: "completeSession";
+    logic: PromiseActorLogic<void, NonReducibleUnknown, EventObject>;
+    id: string | undefined;
+} | {
+    src: "abortSession";
+    logic: PromiseActorLogic<void, NonReducibleUnknown, EventObject>;
+    id: string | undefined;
+}, {
+    type: "recordFailure";
+    params: {
+        error: unknown;
+    };
+} | {
+    type: "killTransport";
+    params: unknown;
+}, {
+    type: "abortRequested";
+    params: unknown;
+}, never, "idle" | "failed" | "aborted" | "initializing" | "uploading" | "completing" | "aborting" | "succeeded", string, NonReducibleUnknown, NonReducibleUnknown, EventObject, MetaObject, {
+    id: "uploader";
+    states: {
+        readonly idle: {};
+        readonly initializing: {};
+        readonly uploading: {};
+        readonly completing: {};
+        readonly aborting: {};
+        readonly succeeded: {};
+        readonly failed: {};
+        readonly aborted: {};
+    };
+}>;

package/dist/types/{storage → src/storage}/uploader.d.ts

@@ -4,8 +4,14 @@ import { UploaderOptions, UploadProgress, UploadResult, UploadStatus } from './t
 /**
  * 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.
+ * `sys/storage` resource. A caller abort triggers a best-effort
+ * `abort_upload`; non-abort failures leave the session intact so the upload
+ * can resume.
+ *
+ * The lifecycle is governed by the statechart in `./uploader-machine.ts`:
+ * this class supplies the phase runners (session prep, worker pool,
+ * completion, backend abort) and bridges actor snapshots onto the public
+ * `status` / `onStatusChange` / `start()`-promise surface.
  *
  * The instance is one-shot: a successful or failed run cannot be restarted.
  * Create a fresh `Uploader` for each file.