@classytic/arc-next 0.6.0 → 0.7.1

package/dist/hooks.js

@@ -1,9 +1,9 @@
 "use client";
 
-import { getAuthMode, getClientAuthContext } from "./client.js";
+import { getAuthMode, getClientAuthContext, hasGlobalStaticAuth } from "./client.js";
 import { isKeysetPagination, isOffsetPagination } from "./api.js";
-import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, updateListCache } from "./cache.js";
-import { useDetailQuery, useInfiniteListQuery, useListQuery } from "./query.js";
+import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, syncDetailToLists, updateListCache } from "./cache.js";
+import { findItemInListCache, useDetailQuery, useInfiniteListQuery, useListQuery } from "./query.js";
 import { useMutationWithTransition, useOptimisticMutation } from "./mutation.js";
 import { subscribeToEvents } from "./sse.js";
 import { connectWs } from "./ws.js";
@@ -33,8 +33,19 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 	const pluralName = plural ?? `${singular}s`;
 	/** Resolve auth context — per-client auth takes priority over global */
 	const resolveAuth = () => getClientAuthContext(client);
-	/** Whether auth is provided via static config (headers, internalApiKey, per-client auth) — no token needed for enablement */
-	const hasStaticAuth = !!(client?.config?.defaultHeaders || client?.config?.internalApiKey || client?.auth);
+	/**
+	* Whether auth is provided via static config — no per-request token needed.
+	* Sources (in priority order):
+	*   1. Per-client `defaultHeaders` / `internalApiKey` (when `client` is passed in).
+	*   2. Per-client custom auth (e.g. `createClient({ getToken })`).
+	*   3. Global `configureClient({ internalApiKey | defaultHeaders | authMode: 'cookie' })`.
+	*
+	* Resolved lazily on every render so that an app calling `configureClient`
+	* inside a "use client" provider after factory creation still picks up the
+	* global static-auth signal — previously a global `internalApiKey` was
+	* ignored, leaving every protected query stuck in a permanently-disabled state.
+	*/
+	const resolveHasStaticAuth = () => !!(client?.config?.defaultHeaders || client?.config?.internalApiKey || client?.auth) || hasGlobalStaticAuth();
 	/** Extract ID from an item using configured idField, falling back to _id → id */
 	function resolveItemId(item) {
 		if (!item || typeof item !== "object") return null;
@@ -99,7 +110,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime,
@@ -108,9 +119,6 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				refetchInterval: queryOpts.refetchInterval,
 				refetchIntervalInBackground: queryOpts.refetchIntervalInBackground
 			},
-			prefillDetailCache: queryOpts.prefillDetailCache ?? true,
-			detailKeyBuilder: (id) => KEYS.scopedDetail(id, organizationId ?? null),
-			itemIdResolver: resolveItemId,
 			select: queryOpts.select
 		});
 	}
@@ -131,8 +139,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		}
 		const { organizationId, params: queryParams, request: requestOpts, ...restOptions } = options;
 		const detailKey = KEYS.scopedDetail(id || "", organizationId ?? null);
-		return useDetailQuery({
-			queryKey: queryParams ? [...detailKey, queryParams] : detailKey,
+		const fullDetailKey = queryParams ? [...detailKey, queryParams] : detailKey;
+		const queryClient = useQueryClient();
+		const listPlaceholder = useCallback(() => id ? findItemInListCache(queryClient, KEYS.lists(), id, idField) : void 0, [queryClient, id]);
+		const detailResult = useDetailQuery({
+			queryKey: fullDetailKey,
 			queryFn: ({ signal }) => api.getById({
 				id,
 				token,
@@ -143,7 +154,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: !!id && createEnabledRule(token, restOptions, resolveAuthMode(), hasStaticAuth),
+			enabled: !!id && createEnabledRule(token, restOptions, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
@@ -152,8 +163,18 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				refetchInterval: restOptions.refetchInterval,
 				refetchIntervalInBackground: restOptions.refetchIntervalInBackground
 			},
-			select: restOptions.select
+			select: restOptions.select,
+			placeholderData: listPlaceholder
 		});
+		useEffect(() => {
+			if (!detailResult.item || detailResult.isPlaceholderData) return;
+			syncDetailToLists(queryClient, KEYS.lists(), detailResult.item, idField ? { idField } : {});
+		}, [
+			detailResult.item,
+			detailResult.isPlaceholderData,
+			queryClient
+		]);
+		return detailResult;
 	}
 	function useActions() {
 		const queryClient = useQueryClient();
@@ -413,7 +434,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			initialPageParam: restParams.after ? restParams.after : 1,
 			getNextPageParam: (lastPage) => {
 				const page = lastPage;
@@ -498,7 +519,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getDeleted && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: !!api.getDeleted && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -512,7 +533,9 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const resolvedOptions = options ?? {};
 		const organizationId = resolvedOptions.organizationId ?? auth.organizationId;
 		const { params: queryParams, request: requestOpts, ...restOptions } = resolvedOptions;
-		return useDetailQuery({
+		const queryClient = useQueryClient();
+		const listPlaceholder = useCallback(() => slug ? findItemInListCache(queryClient, KEYS.lists(), slug, "slug") : void 0, [queryClient, slug]);
+		const slugResult = useDetailQuery({
 			queryKey: queryParams ? KEYS.custom("slug", slug, queryParams) : KEYS.custom("slug", slug),
 			queryFn: ({ signal }) => {
 				if (!api.getBySlug) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a getBySlug method`));
@@ -527,15 +550,25 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getBySlug && !!slug && createEnabledRule(token, restOptions, resolveAuthMode(), hasStaticAuth),
+			enabled: !!api.getBySlug && !!slug && createEnabledRule(token, restOptions, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
 				refetchOnWindowFocus: restOptions.refetchOnWindowFocus ?? config.refetchOnWindowFocus,
 				structuralSharing: restOptions.structuralSharing ?? config.structuralSharing
 			},
-			select: restOptions.select
+			select: restOptions.select,
+			placeholderData: listPlaceholder
 		});
+		useEffect(() => {
+			if (!slugResult.item || slugResult.isPlaceholderData) return;
+			syncDetailToLists(queryClient, KEYS.lists(), slugResult.item, idField ? { idField } : {});
+		}, [
+			slugResult.item,
+			slugResult.isPlaceholderData,
+			queryClient
+		]);
+		return slugResult;
 	}
 	function useTree(params, options) {
 		const auth = resolveAuth();
@@ -561,7 +594,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getTree && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: !!api.getTree && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -594,14 +627,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getChildren && !!parentId && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: !!api.getChildren && !!parentId && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
 			},
-			prefillDetailCache: queryOpts.prefillDetailCache ?? true,
-			detailKeyBuilder: (id) => KEYS.scopedDetail(id, organizationId ?? null),
-			itemIdResolver: resolveItemId,
 			select: queryOpts.select
 		});
 	}
@@ -806,7 +836,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			enabled: !!name && !!api.aggregate && createEnabledRule(auth.token, {
 				public: isPublic,
 				enabled
-			}, resolveAuthMode(), hasStaticAuth),
+			}, resolveAuthMode(), resolveHasStaticAuth()),
 			staleTime,
 			gcTime,
 			refetchOnWindowFocus,
@@ -912,8 +942,8 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			const id = resolveItemId(item);
 			if (id) {
 				const orgId = resolveAuth().organizationId;
-				queryClient.setQueryData(KEYS.scopedDetail(id, orgId), { data: item });
-				if (orgId) queryClient.setQueryData(KEYS.detail(id), { data: item });
+				queryClient.setQueryData(KEYS.scopedDetail(id, orgId), item);
+				if (orgId) queryClient.setQueryData(KEYS.detail(id), item);
 			}
 			if (!router) return;
 			const { scroll = true, replace = false } = options;

package/dist/query.d.ts

@@ -1,5 +1,5 @@
 import { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache } from "./cache.js";
-import { InfiniteData, QueryKey } from "@tanstack/react-query";
+import { InfiniteData, QueryClient, QueryKey } from "@tanstack/react-query";
 
 //#region src/query.d.ts
 /** Request-level options passed through to the fetch call */
@@ -17,6 +17,17 @@ interface ListQueryOptions<TData = unknown> {
   gcTime?: number;
   refetchOnWindowFocus?: boolean;
   structuralSharing?: boolean;
+  /**
+   * @deprecated No-op since 0.7. The old setQueryData-based prefill was
+   * removed because it (1) stored a `{ data: ... }` envelope that didn't
+   * match arc 2.13+'s raw doc wire, (2) blocked subsequent detail GETs from
+   * firing (fresh staleTime), and (3) clobbered detail responses every
+   * render due to an unstable effect dep. `useDetail` / `useDetailBySlug`
+   * now read list cache via `placeholderData` — the canonical TanStack
+   * pattern — so the GET always fires while consumers see an instant
+   * preview. Safe to remove from caller code. Retained for compile-time
+   * compatibility; will be deleted in a future major.
+   */
   prefillDetailCache?: boolean;
   refetchInterval?: number | false;
   refetchIntervalInBackground?: boolean;
@@ -46,8 +57,28 @@ interface DetailQueryOptions<TData = unknown> {
   /** Pass-through options for the underlying fetch request (cache, revalidate, tags, headers) */
   request?: RequestPassthrough;
 }
+/**
+ * Result of `useList` (and `useListQuery`). Matches the same typed-end-to-end
+ * shape `repo-core` uses for its server-side result interfaces (`AggResult`,
+ * `OffsetPaginationResult`, etc.) — no raw-cache escape hatch on the public
+ * surface, just the typed extracted view.
+ *
+ * Need the raw cache entry? Use `useQueryClient().getQueryData(KEYS.list(...))`
+ * — it's typed against whatever `setQueryData` last wrote, and it makes the
+ * "I'm reaching past the SDK" intent explicit.
+ */
 interface ListQueryResult<T> {
+  /**
+   * Extracted items array — `T[]`. Always typed, always flat (infinite-list
+   * pages are pre-flattened), always consistent across response-shape
+   * variants (`data` / `items` / `results` / any-array fallback).
+   */
   items: T[];
+  /**
+   * Normalized pagination snapshot — offset / keyset / aggregate all map
+   * onto the same `{ method, total, pages, page, limit, hasNext, hasPrev, next? }`
+   * shape. `null` when the response carries no pagination signal.
+   */
   pagination: PaginationData | null;
   isLoading: boolean;
   isFetching: boolean;
@@ -56,18 +87,37 @@ interface ListQueryResult<T> {
   isStale: boolean;
   error: Error | null;
   refetch: () => Promise<unknown>;
-  data: unknown;
 }
+/**
+ * Result of `useDetail` (and `useDetailQuery`). Matches the typed-end-to-end
+ * shape repo-core uses for its result interfaces — no raw-cache escape
+ * hatch on the public surface, just the typed extracted view.
+ *
+ * Need the raw cache entry? `useQueryClient().getQueryData(KEYS.detail(id))`
+ * — typed against whatever `setQueryData` last wrote, and the explicit
+ * `getQueryData` call signals "I'm reaching past the SDK" at the call site.
+ */
 interface DetailQueryResult<T> {
+  /**
+   * The extracted entity — `T | null`. Always typed, always the raw doc
+   * (not a wrapper), always consistent with what `prefetchDetail` /
+   * `cache.getDetail` / `useNavigation` write back.
+   */
   item: T | null;
   isLoading: boolean;
   isFetching: boolean;
   isError: boolean;
   isSuccess: boolean;
   isStale: boolean;
+  /**
+   * `true` while the detail GET is in flight and the consumer is seeing a
+   * preview derived from a list cache entry (or any other `placeholderData`).
+   * Use to dim or label the preview, e.g. `<article aria-busy={isPlaceholderData}>`.
+   * Flips to `false` once the real detail payload resolves.
+   */
+  isPlaceholderData: boolean;
   error: Error | null;
   refetch: () => Promise<unknown>;
-  data: unknown;
 }
 interface CreateListQueryConfig {
   queryKey: QueryKey;
@@ -76,23 +126,52 @@ interface CreateListQueryConfig {
   }) => Promise<unknown>;
   enabled?: boolean;
   options?: Record<string, unknown>;
-  prefillDetailCache?: boolean;
-  detailKeyBuilder?: (id: string) => QueryKey;
-  /** Custom ID extractor for cache prefill. Falls back to getItemId (_id → id). */
-  itemIdResolver?: (item: unknown) => string | null;
   select?: (data: unknown) => unknown;
 }
+/**
+ * List query hook. Returns the canonical `{ items, pagination, ... }` shape
+ * derived from arc's `PaginatedResult` wire envelope.
+ *
+ * **No detail-cache prefill.** Older revisions of this hook wrote each list
+ * item into the detail cache via `setQueryData`. That pattern was wrong on
+ * three counts: (1) it stored a `{ data: ... }` envelope that didn't match
+ * arc 2.13+'s raw doc wire shape, (2) the fresh-default `staleTime` made
+ * subsequent `useDetail` calls reuse the partial list payload and never fetch
+ * the rich detail response, and (3) the unstable `detailKeyBuilder` ref made
+ * the prefill effect re-run on every render, clobbering successful detail
+ * fetches. The clean fix is on the read side: `useDetail` now reads list cache
+ * directly via `placeholderData`, so the detail GET still fires while the
+ * consumer sees an instant list-shaped preview. See `findItemInListCache`.
+ */
 declare function useListQuery<T>({
   queryKey,
   queryFn,
   enabled,
   options,
-  prefillDetailCache,
-  detailKeyBuilder,
-  itemIdResolver,
   select
 }: CreateListQueryConfig): ListQueryResult<T>;
-interface CreateDetailQueryConfig {
+/**
+ * Find an item in any list cache for this entity by ID.
+ *
+ * Walks every `[entity, 'list', ...]` query (including scoped variants and
+ * infinite-list page arrays) and extracts items via the permissive list
+ * detector. Returns the first match — list payloads are subsets of detail
+ * payloads, so the consumer sees an instant preview while the real detail
+ * GET runs in the background.
+ *
+ * This is the canonical TanStack pattern for "show list data while fetching
+ * detail": pass the returned value as `placeholderData` to `useDetail`. The
+ * value isn't persisted to the detail cache (no pollution), `staleTime`
+ * doesn't apply to it (always refetches), and `isPlaceholderData` is `true`
+ * until the GET resolves.
+ *
+ * @param qc TanStack QueryClient (typically from `useQueryClient()`)
+ * @param listsKey Prefix key for this entity's lists (e.g. `KEYS.lists()`)
+ * @param id Item ID being requested
+ * @param idField Optional custom ID field (matches `createCrudHooks({ idField })`)
+ */
+declare function findItemInListCache<T>(qc: QueryClient, listsKey: QueryKey, id: string, idField?: string): T | undefined;
+interface CreateDetailQueryConfig<T = unknown> {
   queryKey: QueryKey;
   queryFn: (context: {
     signal?: AbortSignal;
@@ -100,14 +179,22 @@ interface CreateDetailQueryConfig {
   enabled?: boolean;
   options?: Record<string, unknown>;
   select?: (data: unknown) => unknown;
+  /**
+   * Lazy placeholder. Returns a value (or `undefined`) on each render to show
+   * before the detail GET resolves. Use with `findItemInListCache` to derive
+   * an instant preview from list cache without polluting the detail cache —
+   * the canonical TanStack pattern for "show list data while fetching detail."
+   */
+  placeholderData?: () => T | undefined;
 }
 declare function useDetailQuery<T>({
   queryKey,
   queryFn,
   enabled,
   options,
-  select
-}: CreateDetailQueryConfig): DetailQueryResult<T>;
+  select,
+  placeholderData
+}: CreateDetailQueryConfig<T>): DetailQueryResult<T>;
 interface InfiniteListQueryOptions {
   public?: boolean;
   enabled?: boolean;
@@ -250,4 +337,4 @@ declare function useApiQuery<TResponse = unknown, TData = ExtractData<TResponse>
   options
 }: UseApiQueryConfig<TResponse, TData>): UseApiQueryResult<TData>;
 //#endregion
-export { type CacheUtils, CreateDetailQueryConfig, CreateInfiniteListQueryConfig, CreateListQueryConfig, DEFAULT_QUERY_CONFIG, DetailQueryOptions, DetailQueryResult, ExtractData, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, type PaginationData, QUERY_CONFIGS, QueryFreshness, type QueryKeys, RequestPassthrough, UseApiQueryConfig, UseApiQueryOptions, UseApiQueryResult, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery };
+export { type CacheUtils, CreateDetailQueryConfig, CreateInfiniteListQueryConfig, CreateListQueryConfig, DEFAULT_QUERY_CONFIG, DetailQueryOptions, DetailQueryResult, ExtractData, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, type PaginationData, QUERY_CONFIGS, QueryFreshness, type QueryKeys, RequestPassthrough, UseApiQueryConfig, UseApiQueryOptions, UseApiQueryResult, createCacheUtils, createQueryKeys, extractItem, extractItems, findItemInListCache, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery };

package/dist/query.js

@@ -1,12 +1,26 @@
 "use client";
 
 import { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache } from "./cache.js";
-import { keepPreviousData, useInfiniteQuery, useQuery, useQueryClient } from "@tanstack/react-query";
-import { useCallback, useEffect, useMemo, useRef } from "react";
+import { keepPreviousData, useInfiniteQuery, useQuery } from "@tanstack/react-query";
+import { useCallback, useMemo, useRef } from "react";
 
 //#region src/query.ts
-function useListQuery({ queryKey, queryFn, enabled = true, options = {}, prefillDetailCache = true, detailKeyBuilder, itemIdResolver, select }) {
-	const queryClient = useQueryClient();
+/**
+* List query hook. Returns the canonical `{ items, pagination, ... }` shape
+* derived from arc's `PaginatedResult` wire envelope.
+*
+* **No detail-cache prefill.** Older revisions of this hook wrote each list
+* item into the detail cache via `setQueryData`. That pattern was wrong on
+* three counts: (1) it stored a `{ data: ... }` envelope that didn't match
+* arc 2.13+'s raw doc wire shape, (2) the fresh-default `staleTime` made
+* subsequent `useDetail` calls reuse the partial list payload and never fetch
+* the rich detail response, and (3) the unstable `detailKeyBuilder` ref made
+* the prefill effect re-run on every render, clobbering successful detail
+* fetches. The clean fix is on the read side: `useDetail` now reads list cache
+* directly via `placeholderData`, so the detail GET still fires while the
+* consumer sees an instant list-shaped preview. See `findItemInListCache`.
+*/
+function useListQuery({ queryKey, queryFn, enabled = true, options = {}, select }) {
 	const query = useQuery({
 		queryKey,
 		queryFn: ({ signal }) => queryFn({ signal }),
@@ -16,42 +30,62 @@ function useListQuery({ queryKey, queryFn, enabled = true, options = {}, prefill
 		...select ? { select } : {},
 		placeholderData: keepPreviousData
 	});
-	const items = useMemo(() => extractItems(query.data), [query.data]);
-	const pagination = useMemo(() => normalizePagination(query.data), [query.data]);
-	useEffect(() => {
-		if (!prefillDetailCache || !detailKeyBuilder || items.length === 0) return;
-		const resolveId = itemIdResolver ?? getItemId;
-		items.forEach((item) => {
-			const id = resolveId(item);
-			if (id) queryClient.setQueryData(detailKeyBuilder(id), { data: item });
-		});
-	}, [
-		items,
-		prefillDetailCache,
-		detailKeyBuilder,
-		queryClient
-	]);
 	return {
-		items,
-		pagination,
+		items: useMemo(() => extractItems(query.data), [query.data]),
+		pagination: useMemo(() => normalizePagination(query.data), [query.data]),
 		isLoading: query.isLoading,
 		isFetching: query.isFetching,
 		isError: query.isError,
 		isSuccess: query.isSuccess,
 		isStale: query.isStale,
 		error: query.error,
-		refetch: query.refetch,
-		data: query.data
+		refetch: query.refetch
 	};
 }
-function useDetailQuery({ queryKey, queryFn, enabled = true, options = {}, select }) {
+/**
+* Find an item in any list cache for this entity by ID.
+*
+* Walks every `[entity, 'list', ...]` query (including scoped variants and
+* infinite-list page arrays) and extracts items via the permissive list
+* detector. Returns the first match — list payloads are subsets of detail
+* payloads, so the consumer sees an instant preview while the real detail
+* GET runs in the background.
+*
+* This is the canonical TanStack pattern for "show list data while fetching
+* detail": pass the returned value as `placeholderData` to `useDetail`. The
+* value isn't persisted to the detail cache (no pollution), `staleTime`
+* doesn't apply to it (always refetches), and `isPlaceholderData` is `true`
+* until the GET resolves.
+*
+* @param qc TanStack QueryClient (typically from `useQueryClient()`)
+* @param listsKey Prefix key for this entity's lists (e.g. `KEYS.lists()`)
+* @param id Item ID being requested
+* @param idField Optional custom ID field (matches `createCrudHooks({ idField })`)
+*/
+function findItemInListCache(qc, listsKey, id, idField) {
+	if (!id) return void 0;
+	const entries = qc.getQueriesData({ queryKey: listsKey });
+	for (const [, raw] of entries) {
+		if (!raw) continue;
+		const pages = typeof raw === "object" && raw !== null && Array.isArray(raw.pages) ? raw.pages : [raw];
+		for (const page of pages) {
+			const items = extractItems(page);
+			for (const item of items) {
+				const got = idField ? item?.[idField] : getItemId(item);
+				if (got != null && String(got) === id) return item;
+			}
+		}
+	}
+}
+function useDetailQuery({ queryKey, queryFn, enabled = true, options = {}, select, placeholderData }) {
 	const query = useQuery({
 		queryKey,
 		queryFn: ({ signal }) => queryFn({ signal }),
 		enabled,
 		...DEFAULT_QUERY_CONFIG,
 		...options,
-		...select ? { select } : {}
+		...select ? { select } : {},
+		...placeholderData ? { placeholderData } : {}
 	});
 	return {
 		item: extractItem(query.data),
@@ -60,9 +94,9 @@ function useDetailQuery({ queryKey, queryFn, enabled = true, options = {}, selec
 		isError: query.isError,
 		isSuccess: query.isSuccess,
 		isStale: query.isStale,
+		isPlaceholderData: query.isPlaceholderData,
 		error: query.error,
-		refetch: query.refetch,
-		data: query.data
+		refetch: query.refetch
 	};
 }
 function useInfiniteListQuery({ queryKey, queryFn, enabled = true, options = {}, initialPageParam = 1, getNextPageParam, getPreviousPageParam, maxPages }) {
@@ -155,4 +189,4 @@ function useApiQuery({ queryKey, queryFn, enabled = true, freshness, select, opt
 }
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery };
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, findItemInListCache, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery };

package/dist/sse.js

@@ -1,6 +1,6 @@
 "use client";
 
-import { buildStreamUrl, getAuthMode } from "./client.js";
+import { ArcApiError, _getAuthErrorHandler, _runAuthRecovery, buildStreamUrl, getAuthMode } from "./client.js";
 import { useQueryClient } from "@tanstack/react-query";
 import { useEffect, useMemo, useRef, useState } from "react";
 
@@ -21,6 +21,35 @@ function buildSseUrl(path, params = {}) {
 	return buildStreamUrl(path, params, "http");
 }
 /**
+* Send a minimal HEAD/GET probe to the SSE URL to classify an EventSource
+* failure as either an auth failure (401, or 403 when `retryOn403`) or
+* something transient (network, 5xx, CORS). EventSource itself doesn't
+* expose status codes — this is the only cross-browser way to route SSE
+* close events through `onAuthError`.
+*
+* The probe uses HEAD when supported (cheaper); falls back to GET with
+* `Range: bytes=0-0` for servers that 405 on HEAD. Either way, the body
+* is never read — only the status code matters.
+*/
+async function probeForAuthFailure(url, retryOn403) {
+	try {
+		let res = await fetch(url, {
+			method: "HEAD",
+			credentials: "include"
+		});
+		if (res.status === 405) res = await fetch(url, {
+			method: "GET",
+			credentials: "include",
+			headers: { Range: "bytes=0-0" }
+		});
+		if (res.status === 401) return "auth-failure";
+		if (retryOn403 && res.status === 403) return "auth-failure";
+		return "not-auth";
+	} catch {
+		return "not-auth";
+	}
+}
+/**
 * Subscribe to an Arc SSE stream from any JS context (React, Node, Bun, tests).
 * Pure function — no React hook required. Returns a handle with `close()` /
 * `reconnect()` / `isConnected()`.
@@ -68,6 +97,7 @@ function subscribeToEvents(options) {
 		es = new EventSource(buildUrl(), { withCredentials: credentials });
 		es.onopen = () => {
 			reconnectAttempts = 0;
+			sseAuthRetries = 0;
 			connected = true;
 			options.onConnectionChange?.(true);
 		};
@@ -98,13 +128,49 @@ function subscribeToEvents(options) {
 			connected = false;
 			options.onConnectionChange?.(false);
 			if (manualClose) return;
-			if (reconnectAttempts < maxReconnectAttempts) {
-				reconnectAttempts += 1;
-				const delay = Math.min(reconnectDelay * Math.pow(1.5, reconnectAttempts - 1), 3e4);
-				reconnectTimer = setTimeout(connect, delay);
+			const { handler, retryOn403, maxAuthRetries } = _getAuthErrorHandler();
+			if (handler && sseAuthRetries < maxAuthRetries) {
+				sseAuthRetries += 1;
+				probeForAuthFailure(buildUrl(), retryOn403).then(async (status) => {
+					if (status === "auth-failure") {
+						const { decision } = await _runAuthRecovery(handler, {
+							error: new ArcApiError("SSE pre-flight auth failure", {
+								status: 401,
+								statusText: "SSE auth failure",
+								json: { code: "arc.sse.unauthorized" },
+								endpoint: ssePath,
+								method: "GET"
+							}),
+							request: {
+								method: "GET",
+								endpoint: ssePath
+							},
+							attempt: sseAuthRetries
+						});
+						if (decision === "retry") {
+							reconnectAttempts = 0;
+							connect();
+							return;
+						}
+					}
+					scheduleReconnect();
+				}).catch(() => {
+					scheduleReconnect();
+				});
+				return;
 			}
+			scheduleReconnect();
 		};
 	};
+	/** Standard backoff-reconnect — shared between non-auth errors and skipped recoveries. */
+	const scheduleReconnect = () => {
+		if (reconnectAttempts < maxReconnectAttempts) {
+			reconnectAttempts += 1;
+			const delay = Math.min(reconnectDelay * Math.pow(1.5, reconnectAttempts - 1), 3e4);
+			reconnectTimer = setTimeout(connect, delay);
+		}
+	};
+	let sseAuthRetries = 0;
 	connect();
 	return {
 		close: () => {

package/dist/upload.js

@@ -1,4 +1,4 @@
-import { ArcApiError, getAuthMode, getBaseUrl, getClientAuthContext } from "./client.js";
+import { ArcApiError, _getAuthErrorHandler, _isAuthRecoverable, _resolveRefreshedToken, _runAuthRecovery, getAuthMode, getBaseUrl, getClientAuthContext } from "./client.js";
 import { getToastHandler } from "./mutation.js";
 import { useQueryClient } from "@tanstack/react-query";
 import { useCallback, useRef, useState } from "react";
@@ -78,7 +78,38 @@ import { useCallback, useRef, useState } from "react";
 *   onProgress: ({ percent }) => setUiProgress(percent),
 * });
 */
-function uploadWithProgress(options) {
+async function uploadWithProgress(options) {
+	const { handler, retryOn403, maxAuthRetries } = _getAuthErrorHandler();
+	if (!handler) return uploadAttempt(options);
+	let currentOptions = options;
+	for (let attempt = 0; attempt <= maxAuthRetries; attempt++) try {
+		return await uploadAttempt(currentOptions);
+	} catch (error) {
+		if (attempt >= maxAuthRetries || !_isAuthRecoverable(error, retryOn403)) throw error;
+		if (currentOptions.signal?.aborted) throw error;
+		const { decision, overrideToken } = await _runAuthRecovery(handler, {
+			error,
+			request: {
+				method: currentOptions.method ?? "POST",
+				endpoint: currentOptions.url
+			},
+			attempt: attempt + 1
+		});
+		if (decision !== "retry") throw error;
+		currentOptions = {
+			...currentOptions,
+			token: _resolveRefreshedToken(overrideToken)
+		};
+	}
+	throw new Error("arc-next: upload auth retry loop terminated without resolution");
+}
+/**
+* Single XHR attempt. Identical to the pre-0.7 body of `uploadWithProgress`
+* — extracted so the auth-retry loop above can re-run it with a refreshed
+* token without duplicating the XHR setup. All auth-recovery semantics live
+* in the outer loop; this function just performs one upload.
+*/
+function uploadAttempt(options) {
 	const { url, formData, method = "POST", onProgress, signal, client, headers: extraHeaders, elevated, idempotencyKey, responseType = "json" } = options;
 	return new Promise((resolve, reject) => {
 		if (signal?.aborted) {