@alexkroman1/aai-ui 6.8.0 → 6.10.0

package/dist/_upload-files.d.ts

@@ -27,17 +27,33 @@ import type { WorkflowApi } from "./workflow-client.ts";
  * minted per attempt would make each round a fresh upload of the whole file.
  */
 export type UploadSession = {
+    /**
+     * What this form's remembered ids are filed under (`_upload-recall.ts`).
+     *
+     * The workflow's name, so two forms on one page do not read each other's
+     * entries. It is not a SAFETY boundary and does not need to be — a recalled id
+     * is checked against the agent before anything is sent to it — it just keeps a
+     * form from spending a round trip on another form's upload.
+     */
+    scope: string;
     /** The id each file is being stored under, minted once. */
     ids: Map<File, string>;
     /** Files whose every byte has landed, by the id they landed under. */
     stored: Map<File, string>;
-    /** Files that have had an attempt, so the next one must claim the id as its own. */
+    /**
+     * Files that have had an attempt, so the next one must claim the id as its own.
+     *
+     * `sendThroughGate` tracks this itself WITHIN one file's attempts. What this
+     * carries is the attempt made by a page load that is gone: an id recalled from
+     * storage was claimed by whoever minted it, so the first attempt of this load is
+     * a resume even though this load has sent nothing.
+     */
     tried: Set<File>;
     /** The person's pause. */
     gate: UploadGate;
 };
-/** A fresh session for one submission. */
-export declare function createUploadSession(): UploadSession;
+/** A fresh session for one submission of `workflow`. */
+export declare function createUploadSession(workflow: string): UploadSession;
 /**
  * Replace every `File` in a submitted form with the id of a stored upload,
  * reporting how far each one has got.

package/dist/_upload-recall.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Where an upload's ID survives a page RELOAD.
+ *
+ * A streamed upload is resumable because its id outlives the attempt that began
+ * it — `_upload-files.ts` says so, and `_upload-session.ts` turns that into a
+ * pause a person can press. Both of them hold the id in MEMORY: the walk's
+ * `UploadSession` lives in a `useRef`, so a reload was the one interruption the
+ * mechanism could not survive. Everything else was already in place — the windows
+ * were still in the store, the agent could still name them
+ * (`UploadInfo.ranges`), and the id was minted in the browser — and the browser
+ * had thrown away the only name for them. So a person who refreshed at 90% of a
+ * 200 MB recording sent the whole file again, which is the one interruption they
+ * are most likely to cause on purpose.
+ *
+ * This is that name, written down. It is what tus-js-client's `urlStorage` and
+ * Uppy's Golden Retriever sell, in the shape `session-resume-store.ts` already
+ * uses for a session id.
+ *
+ * ## A FINGERPRINT, because a `File` has no name a page can address
+ *
+ * A file from a picker carries no path and no handle, so the key is what
+ * tus-js-client fingerprints on: size, last-modified, type and name. Two
+ * different files agreeing on all four is the case this cannot tell apart — and
+ * the reason NOTHING here decides to resume. `_upload-files.ts` asks the agent
+ * what the id actually holds before sending a byte to it, so a wrong hit costs
+ * one `GET` and a fresh id rather than a corrupted upload.
+ *
+ * ## `sessionStorage`, deliberately
+ *
+ * The same call `session-resume-store.ts` makes, for a reason that happens to be
+ * stronger here: a reload and a same-tab navigation are exactly what this is for,
+ * and an id from yesterday names an upload the agent's sweep has very likely
+ * already collected. A tab is also the boundary the walk itself has — two tabs
+ * uploading the same recording are two submissions.
+ *
+ * Every access is guarded. Storage throws outright in Safari private mode and
+ * under a blocking policy, and an upload that cannot be REMEMBERED must degrade
+ * to the upload we would have done anyway rather than failing to start.
+ */
+/**
+ * The id this file was last being stored under in this tab, if any.
+ *
+ * A hit is a CANDIDATE and never a decision — see the module doc.
+ *
+ * @internal
+ */
+export declare function recallUploadId(scope: string, file: File): string | undefined;
+/**
+ * Remember the id this file is being stored under.
+ *
+ * Called before the first byte leaves rather than after the last one lands: the
+ * reload this exists for happens in between, and an id written at the end is an
+ * id written for the one case that did not need it.
+ *
+ * @internal
+ */
+export declare function rememberUploadId(scope: string, file: File, id: string): void;
+/**
+ * Forget it: the agent holds nothing resumable under this id.
+ *
+ * The other half of the agent deciding. Without it a swept upload is re-read on
+ * every submission of the same file for the life of the tab, which is a round
+ * trip spent learning the same 404.
+ *
+ * @internal
+ */
+export declare function forgetUploadId(scope: string, file: File): void;

package/dist/hooks.d.ts

@@ -1,4 +1,4 @@
-import type { DefaultToolResult } from "@alexkroman1/aai";
+import type { DefaultToolResult, StateProjection } from "@alexkroman1/aai";
 import type { ToolCallInfo } from "./types.ts";
 /**
  * Fire a callback when a tool call settles, with the tool's JSON result.
@@ -39,6 +39,42 @@ export declare function useToolResult<R = DefaultToolResult>(callback: (name: st
  * @public
  */
 export declare function useAgentState<S = DefaultToolResult>(): S | null;
+/**
+ * The agent's projected session state, typed and defaulted by the SAME
+ * projection the agent pushes — pass `slot.projection(view)` and there is no
+ * type argument to restate and no empty frame to derive.
+ *
+ * This is the overload to reach for whenever `syncState` is a slot projection,
+ * because it closes the round-trip the other two leave open. A projection is
+ * callable, so the pre-first-push frame is what `projection()` returns — the
+ * `fallback` overload's own doc tells you to build it that way — and the
+ * projection's return type is the state's type, so `useAgentState<CartView>`
+ * was restating what `cartView` already knew. Both halves came out of the same
+ * declaration and both were written by hand:
+ *
+ * ```tsx no-check
+ * // `no-check`: the projection lives with the agent, in another file.
+ * // Before — the empty frame derived by hand, the type named three times:
+ * const EMPTY: CartView = cartSlot.projection(cartView)(undefined);
+ * const cart = useAgentState<CartView>(EMPTY);
+ *
+ * // After — `shared.ts` exports the projection once, both ends import it:
+ * const cart = useAgentState(cartProjection);
+ * ```
+ *
+ * The empty frame is memoized on the projection's identity, so a module-scope
+ * projection (the normal case) produces ONE frame for the life of the
+ * component — which the `fallback` overload can only ask you to arrange by
+ * hoisting, and which a `slot.projection(view)` spelled inline in the render
+ * body silently got wrong.
+ *
+ * @param projection - The same `slot.projection(view)` the agent declares as
+ *   `syncState`. Export it from the module that declares the slot so the two
+ *   ends cannot drift.
+ *
+ * @public
+ */
+export declare function useAgentState<V>(projection: StateProjection<V>): V;
 /**
  * The agent's projected session state, falling back to `fallback` before the
  * first push — so the return is never `null` and a sidebar needs no branch for

package/dist/hooks.js

@@ -1,6 +1,6 @@
 import { useSessionSelector } from "./context.js";
 import { i as tryParseJSON } from "./_utils-B6498_bm.js";
-import { useEffect, useRef } from "react";
+import { useEffect, useMemo, useRef } from "react";
 //#region hooks.ts
 /** Index of the first item whose sequence number is above the watermark (tail scan from the end). */
 function tailStart(items, seqOf, watermark) {
@@ -80,7 +80,10 @@ function useToolResult(...args) {
 }
 function useAgentState(fallback) {
 	const state = useSessionSelector((snapshot) => snapshot.agentState);
+	const isProjection = typeof fallback === "function";
+	const projected = useMemo(() => isProjection ? fallback() : void 0, [fallback, isProjection]);
 	if (state !== null) return state;
+	if (isProjection) return projected;
 	return fallback === void 0 ? null : fallback;
 }
 /**

package/dist/index.js

@@ -675,6 +675,131 @@ function UploadProgressBar({ upload, onPause, onResume, className }) {
 	});
 }
 //#endregion
+//#region _upload-recall.ts
+/**
+* Where an upload's ID survives a page RELOAD.
+*
+* A streamed upload is resumable because its id outlives the attempt that began
+* it — `_upload-files.ts` says so, and `_upload-session.ts` turns that into a
+* pause a person can press. Both of them hold the id in MEMORY: the walk's
+* `UploadSession` lives in a `useRef`, so a reload was the one interruption the
+* mechanism could not survive. Everything else was already in place — the windows
+* were still in the store, the agent could still name them
+* (`UploadInfo.ranges`), and the id was minted in the browser — and the browser
+* had thrown away the only name for them. So a person who refreshed at 90% of a
+* 200 MB recording sent the whole file again, which is the one interruption they
+* are most likely to cause on purpose.
+*
+* This is that name, written down. It is what tus-js-client's `urlStorage` and
+* Uppy's Golden Retriever sell, in the shape `session-resume-store.ts` already
+* uses for a session id.
+*
+* ## A FINGERPRINT, because a `File` has no name a page can address
+*
+* A file from a picker carries no path and no handle, so the key is what
+* tus-js-client fingerprints on: size, last-modified, type and name. Two
+* different files agreeing on all four is the case this cannot tell apart — and
+* the reason NOTHING here decides to resume. `_upload-files.ts` asks the agent
+* what the id actually holds before sending a byte to it, so a wrong hit costs
+* one `GET` and a fresh id rather than a corrupted upload.
+*
+* ## `sessionStorage`, deliberately
+*
+* The same call `session-resume-store.ts` makes, for a reason that happens to be
+* stronger here: a reload and a same-tab navigation are exactly what this is for,
+* and an id from yesterday names an upload the agent's sweep has very likely
+* already collected. A tab is also the boundary the walk itself has — two tabs
+* uploading the same recording are two submissions.
+*
+* Every access is guarded. Storage throws outright in Safari private mode and
+* under a blocking policy, and an upload that cannot be REMEMBERED must degrade
+* to the upload we would have done anyway rather than failing to start.
+*/
+const PREFIX = "aai:upload:";
+/**
+* How many ids one form keeps.
+*
+* A cap rather than an expiry, because `sessionStorage` already expires with the
+* tab and an entry is ~80 bytes. What it bounds is the long-lived tab that
+* submits a hundred files: the oldest go first, and the id most likely to be
+* worth resuming is the one written last.
+*/
+const MAX_REMEMBERED = 32;
+/** One form's slot in storage. */
+function keyFor(scope) {
+	return `${PREFIX}${scope}`;
+}
+/**
+* What names this file across a reload.
+*
+* The four fields a browser gives a picked file that do not change between loads.
+* `name` last because it is the one a person can read in a debugger.
+*/
+function fingerprint(file) {
+	return `${file.size}:${file.lastModified}:${file.type}:${file.name}`;
+}
+/** This scope's remembered ids, or nothing at all — a parse failure is nothing. */
+function read(scope) {
+	try {
+		const raw = globalThis.sessionStorage?.getItem(keyFor(scope));
+		if (raw === null || raw === void 0) return {};
+		const parsed = JSON.parse(raw);
+		return isRecord(parsed) ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+function write(scope, entries) {
+	try {
+		globalThis.sessionStorage?.setItem(keyFor(scope), JSON.stringify(entries));
+	} catch {}
+}
+/**
+* The id this file was last being stored under in this tab, if any.
+*
+* A hit is a CANDIDATE and never a decision — see the module doc.
+*
+* @internal
+*/
+function recallUploadId(scope, file) {
+	const found = read(scope)[fingerprint(file)];
+	return typeof found === "string" ? found : void 0;
+}
+/**
+* Remember the id this file is being stored under.
+*
+* Called before the first byte leaves rather than after the last one lands: the
+* reload this exists for happens in between, and an id written at the end is an
+* id written for the one case that did not need it.
+*
+* @internal
+*/
+function rememberUploadId(scope, file, id) {
+	const entries = read(scope);
+	const key = fingerprint(file);
+	delete entries[key];
+	entries[key] = id;
+	const keys = Object.keys(entries);
+	for (const stale of keys.slice(0, Math.max(0, keys.length - MAX_REMEMBERED))) delete entries[stale];
+	write(scope, entries);
+}
+/**
+* Forget it: the agent holds nothing resumable under this id.
+*
+* The other half of the agent deciding. Without it a swept upload is re-read on
+* every submission of the same file for the life of the tab, which is a round
+* trip spent learning the same 404.
+*
+* @internal
+*/
+function forgetUploadId(scope, file) {
+	const entries = read(scope);
+	const key = fingerprint(file);
+	if (!(key in entries)) return;
+	delete entries[key];
+	write(scope, entries);
+}
+//#endregion
 //#region _upload-session.ts
 /** Whether this rejection is an abort, in either of the two shapes runtimes throw. */
 function isAbortError(err) {
@@ -822,9 +947,10 @@ function fileFields(input) {
 * one file rather than walking an input and shares only the gate underneath both
 * (`_upload-session.ts`).
 */
-/** A fresh session for one submission. */
-function createUploadSession() {
+/** A fresh session for one submission of `workflow`. */
+function createUploadSession(workflow) {
 	return {
+		scope: workflow,
 		ids: /* @__PURE__ */ new Map(),
 		stored: /* @__PURE__ */ new Map(),
 		tried: /* @__PURE__ */ new Set(),
@@ -832,6 +958,52 @@ function createUploadSession() {
 	};
 }
 /**
+* The id to store this file under: the one a previous page load was using, or a
+* fresh one.
+*
+* **The AGENT decides, never the fingerprint.** Two files can agree on every
+* field `_upload-recall.ts` keys by, so the recalled id is a candidate that has to
+* be checked before a byte is sent to it — and the check is cheap and exact,
+* because `uploadInfo` is the same record a resume already reads.
+*
+* Three answers, and the third is why this is not just a storage lookup:
+*
+* - **Complete.** Every byte is in from a load that is gone, so there is nothing
+*   to send: the caller takes the id and starts the run. This is the refresh that
+*   costs one `GET` instead of a second 200 MB upload.
+* - **Unfinished, with windows.** `UploadInfo.ranges` is what makes an
+*   upload resumable at all, so the id is reused and the attempt claims it.
+* - **Anything else.** A 404 (swept, or never seen), a failure, or an unfinished
+*   upload reporting NO windows — which is a partial single `PUT`, and a second
+*   `PUT` to that id is a 409 rather than an append (`streamUploadFile`). Reusing
+*   it would turn a reload into a failure the person cannot clear, so the entry is
+*   dropped and the file gets a fresh id.
+*/
+async function claimId(api, session, file) {
+	const remembered = recallUploadId(session.scope, file);
+	if (remembered === void 0) return {
+		id: randomUploadId(),
+		complete: false
+	};
+	const info = await api.uploadInfo(remembered).catch(() => void 0);
+	if (info?.complete === true) return {
+		id: remembered,
+		complete: true
+	};
+	if (info !== void 0 && (info.ranges?.length ?? 0) > 0) {
+		session.tried.add(file);
+		return {
+			id: remembered,
+			complete: false
+		};
+	}
+	forgetUploadId(session.scope, file);
+	return {
+		id: randomUploadId(),
+		complete: false
+	};
+}
+/**
 * Replace every `File` in a submitted form with the id of a stored upload,
 * reporting how far each one has got.
 *
@@ -866,16 +1038,32 @@ async function uploadFiles(api, input, report, parallel, session) {
 		index += 1;
 		const done = session.stored.get(file);
 		if (done !== void 0) return done;
-		let id = session.ids.get(file);
-		if (id === void 0) {
-			id = randomUploadId();
-			session.ids.set(file, id);
-		}
 		const position = {
 			name: file.name,
 			index,
 			count
 		};
+		const known = session.ids.get(file);
+		const claimed = known === void 0 ? await claimId(api, session, file) : {
+			id: known,
+			complete: false
+		};
+		const id = claimed.id;
+		if (known === void 0) {
+			session.ids.set(file, id);
+			rememberUploadId(session.scope, file, id);
+		}
+		if (claimed.complete) {
+			report({
+				...position,
+				loaded: file.size,
+				total: file.size,
+				fraction: 1,
+				paused: false
+			});
+			session.stored.set(file, id);
+			return id;
+		}
 		await sendThroughGate(session.gate, async (resume) => {
 			await api.uploadStream(id, file, {
 				name: file.name,
@@ -887,7 +1075,7 @@ async function uploadFiles(api, input, report, parallel, session) {
 				}),
 				...omitUndefined({
 					parallel,
-					resume: resume ? true : void 0
+					resume: resume || session.tried.has(file) ? true : void 0
 				})
 			});
 		});
@@ -1427,7 +1615,7 @@ function useWorkflowSubmit(workflow, opts = {}) {
 			setStartError(void 0);
 			setRunId(void 0);
 			session.current?.gate.cancel();
-			const current = createUploadSession();
+			const current = createUploadSession(workflow);
 			session.current = current;
 			try {
 				const options = omitUndefined({ key });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-ui",
-  "version": "6.8.0",
+  "version": "6.10.0",
   "type": "module",
   "files": [
     "dist",
@@ -29,7 +29,7 @@
     "remark-gfm": "^4.0.1",
     "use-stick-to-bottom": "^1.1.6",
     "use-sync-external-store": "^1.6.0",
-    "@alexkroman1/aai": "6.8.0"
+    "@alexkroman1/aai": "6.10.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",