@hitch42/applet 0.1.1-beta.7 → 0.1.1-beta.9

package/scaffold/.agents/skills/tanstack-query/references/core/tune-defaults-freshness-retries-and-refetching.md

@@ -0,0 +1,172 @@
+---
+name: core/tune-defaults-freshness-retries-and-refetching
+description: >
+  Use this when configuring staleTime, gcTime, cache lifetime, retry, retryDelay,
+  refetchOnWindowFocus, refetchOnReconnect, refetchInterval, networkMode,
+  focusManager, onlineManager, timeoutManager, or QueryClient defaultOptions.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/fetch-and-observe-queries
+sources:
+  - TanStack/query:docs/framework/react/guides/important-defaults.md
+  - TanStack/query:docs/framework/react/guides/caching.md
+  - TanStack/query:docs/framework/react/guides/query-retries.md
+  - TanStack/query:docs/framework/react/guides/window-focus-refetching.md
+  - TanStack/query:docs/framework/react/guides/network-mode.md
+  - TanStack/query:docs/reference/focusManager.md
+  - TanStack/query:docs/reference/onlineManager.md
+  - TanStack/query:docs/reference/timeoutManager.md
+---
+
+## Setup
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60_000,
+      gcTime: 10 * 60_000,
+      retry: 2,
+      refetchOnWindowFocus: true,
+    },
+  },
+});
+```
+
+## Core Patterns
+
+### Set freshness close to the data source
+
+```ts
+import { queryOptions } from "@tanstack/react-query";
+
+export const settingsOptions = queryOptions({
+  queryKey: ["settings"],
+  queryFn: async () => ({ theme: "system" }),
+  staleTime: 5 * 60_000,
+});
+```
+
+### Disable retries in tests
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export function createTestQueryClient() {
+  return new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+}
+```
+
+### Use networkMode deliberately
+
+```ts
+import { queryOptions } from "@tanstack/react-query";
+
+export const metricsOptions = queryOptions({
+  queryKey: ["metrics"],
+  queryFn: async () => ({ count: 1 }),
+  networkMode: "online",
+});
+```
+
+## Common Mistakes
+
+### HIGH Confusing gcTime with freshness
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useProfile() {
+  return useQuery({
+    queryKey: ["profile"],
+    queryFn: async () => ({ name: "Tanner" }),
+    gcTime: 60_000,
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useProfile() {
+  return useQuery({
+    queryKey: ["profile"],
+    queryFn: async () => ({ name: "Tanner" }),
+    staleTime: 60_000,
+  });
+}
+```
+
+`gcTime` controls unused cache retention; `staleTime` controls whether cached data is considered fresh.
+
+Source: TanStack/query:docs/framework/react/guides/important-defaults.md
+
+### HIGH static staleTime blocks invalidation expectations
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodos() {
+  return useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+    staleTime: "static",
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodos() {
+  return useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+    staleTime: 60_000,
+  });
+}
+```
+
+`staleTime: 'static'` opts out of refetching even when the query is invalidated.
+
+Source: TanStack/query:docs/framework/react/guides/important-defaults.md
+
+### HIGH Tests hang on retries
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: { queries: { retry: false } },
+});
+```
+
+Default retries add delay and can make failing tests wait before surfacing errors.
+
+Source: TanStack/query:docs/framework/react/guides/testing.md
+
+See also: `compositions/persist-offline-and-restore-caches` for persistence rules that depend on gcTime and networkMode.

package/scaffold/.agents/skills/tanstack-query/references/core/understand-query-internals-and-observers.md

@@ -0,0 +1,104 @@
+---
+name: core/understand-query-internals-and-observers
+description: >
+  Use this when explaining or debugging TanStack Query internals: QueryClient,
+  QueryCache, MutationCache, Query, QueryObserver, active versus inactive
+  queries, observer-level options, subscriptions, stale timers, and why loaders
+  or imperative cache reads are not the same as observed queries.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/fetch-and-observe-queries
+sources:
+  - TanStack/query:docs/reference/QueryClient.md
+  - TanStack/query:docs/reference/QueryCache.md
+  - TanStack/query:docs/reference/QueryObserver.md
+  - TanStack/query:docs/reference/MutationCache.md
+---
+
+## Mental Model
+
+`QueryClient` owns the caches. `QueryCache` stores `Query` instances. Hooks and adapter APIs create `QueryObserver` instances that subscribe components to one query. Observer-level options like `select`, `staleTime`, polling, and tracked result access shape what each component sees.
+
+An inactive query can exist in the cache without active observers. It can be read imperatively, hydrated, invalidated, or garbage collected, but it is not the same as a component actively observing query state.
+
+## Core Patterns
+
+### Use observers for UI reads
+
+```tsx
+function TodoPage({ id }: { id: string }) {
+  const todo = useQuery({
+    queryKey: ["todo", id],
+    queryFn: () => fetchTodo(id),
+  });
+
+  if (todo.isPending) return <p>Loading...</p>;
+  if (todo.isError) return <p>{todo.error.message}</p>;
+  return <h1>{todo.data.title}</h1>;
+}
+```
+
+### Use QueryClient for cache orchestration
+
+```ts
+await queryClient.ensureQueryData(todoOptions(id));
+queryClient.invalidateQueries({ queryKey: ["todo", id] });
+queryClient.setQueryData(["todo", id], (old) => old && { ...old, title });
+```
+
+## Common Mistakes
+
+### HIGH Treating cache presence as active usage
+
+Wrong:
+
+```tsx
+const todo = queryClient.getQueryData(["todo", id]);
+return <TodoView todo={todo} />;
+```
+
+Correct:
+
+```tsx
+const todo = useQuery(todoOptions(id));
+return <TodoView todo={todo.data} />;
+```
+
+UI reads should create observers so invalidation, refetch triggers, stale status, and garbage collection behave as expected.
+
+### MEDIUM Expecting one query to have one option set
+
+Wrong:
+
+```ts
+// assume staleTime is stored only on the Query
+queryClient.getQueryCache().find({ queryKey })?.options.staleTime;
+```
+
+Correct:
+
+```ts
+const query = queryClient.getQueryCache().find({ queryKey });
+const observerStaleTimes = query?.observers.map((observer) => observer.options.staleTime);
+```
+
+Several options are observer-level, so multiple components can observe the same query with different selectors or freshness behavior.
+
+### MEDIUM Debugging without checking observer count
+
+Wrong:
+
+```ts
+queryClient.invalidateQueries({ queryKey: ["todos"] });
+// expect every cached todo query to refetch immediately
+```
+
+Correct:
+
+```ts
+queryClient.invalidateQueries({ queryKey: ["todos"], refetchType: "active" });
+```
+
+Inactive queries are not automatically the same as mounted queries. Check observer count in devtools when invalidation or garbage collection looks surprising.

package/scaffold/.agents/skills/tanstack-query/references/core/write-mutations-and-invalidate-related-queries.md

@@ -0,0 +1,183 @@
+---
+name: core/write-mutations-and-invalidate-related-queries
+description: >
+  Use this when writing server state with useMutation, mutationFn, mutate,
+  mutateAsync, mutationKey, useMutationState, invalidateQueries, setMutationDefaults,
+  awaited invalidation, and mutation callbacks.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/design-query-keys-and-options
+  - core/fetch-and-observe-queries
+sources:
+  - TanStack/query:docs/framework/react/guides/mutations.md
+  - TanStack/query:docs/framework/react/guides/query-invalidation.md
+  - TanStack/query:docs/framework/react/guides/invalidations-from-mutations.md
+  - TanStack/query:docs/framework/react/guides/updates-from-mutation-responses.md
+  - TanStack/query:docs/framework/react/reference/useMutation.md
+  - TanStack/query:docs/framework/react/reference/useMutationState.md
+  - TanStack/query:docs/reference/MutationCache.md
+---
+
+## Setup
+
+```ts
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+export function useAddTodo() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (title: string) => ({ id: Date.now(), title }),
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({ queryKey: ["todos"] });
+    },
+  });
+}
+```
+
+## Core Patterns
+
+### Update from mutation response
+
+```ts
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+export function useSaveTodo() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (todo: { id: string; title: string }) => todo,
+    onSuccess: (todo) => {
+      queryClient.setQueryData(["todo", todo.id], todo);
+    },
+  });
+}
+```
+
+### Track related mutations
+
+```ts
+import { useMutationState } from "@tanstack/react-query";
+
+export function usePendingTodoTitles() {
+  return useMutationState<string>({
+    filters: { mutationKey: ["addTodo"], status: "pending" },
+    select: (mutation) => mutation.state.variables as string,
+  });
+}
+```
+
+### Scope defaults by mutation key
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();
+
+queryClient.setMutationDefaults(["addTodo"], {
+  mutationFn: async (title: string) => ({ id: Date.now(), title }),
+});
+```
+
+## Common Mistakes
+
+### HIGH Multiple mutate arguments
+
+Wrong:
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+
+export function useUpdateTodo() {
+  return useMutation({
+    mutationFn: async (input: { id: string; title: string }) => input,
+  });
+}
+
+useUpdateTodo().mutate("1", "Ship");
+```
+
+Correct:
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+
+export function useUpdateTodo() {
+  return useMutation({
+    mutationFn: async (input: { id: string; title: string }) => input,
+  });
+}
+
+useUpdateTodo().mutate({ id: "1", title: "Ship" });
+```
+
+Mutation variables are one value; pass an object when multiple fields are needed.
+
+Source: TanStack/query:docs/framework/react/guides/mutations.md
+
+### HIGH Per-call callback after unmount
+
+Wrong:
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+
+export function useSave() {
+  return useMutation({ mutationFn: async (title: string) => title });
+}
+
+useSave().mutate("Ship", { onSuccess: () => console.log("saved") });
+```
+
+Correct:
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+
+export function useSave() {
+  return useMutation({
+    mutationFn: async (title: string) => title,
+    onSuccess: () => console.log("saved"),
+  });
+}
+```
+
+Hook-level callbacks are tied to the mutation lifecycle; per-call callbacks may not run if the observer unmounts.
+
+Source: TanStack/query:docs/framework/react/guides/mutations.md
+
+### HIGH Not awaiting invalidation
+
+Wrong:
+
+```ts
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+export function useAddTodo() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (title: string) => title,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["todos"] }),
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+export function useAddTodo() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (title: string) => title,
+    onSuccess: async () => queryClient.invalidateQueries({ queryKey: ["todos"] }),
+  });
+}
+```
+
+Returning the invalidation promise keeps the mutation pending until dependent data is refreshed.
+
+Source: TanStack/query:docs/framework/react/guides/invalidations-from-mutations.md
+
+See also: `core/implement-optimistic-updates-and-cache-writes` for mutation side effects that update the cache before the server returns.

package/scaffold/.agents/skills/tanstack-query/references/framework/debug-with-devtools.md

@@ -0,0 +1,169 @@
+---
+name: framework/debug-with-devtools
+description: >
+  Use this when adding, lazy-loading, or debugging TanStack Query devtools:
+  ReactQueryDevtools, VueQueryDevtools, SolidQueryDevtools, SvelteQueryDevtools,
+  Angular devtools panel, embedded panels, production imports, cache inspection,
+  and offline misconceptions.
+type: framework
+library: TanStack Query
+framework: cross-adapter
+library_version: "5.101.0"
+requires:
+  - lifecycle/setup-query-client-and-providers
+sources:
+  - TanStack/query:docs/framework/react/devtools.md
+  - TanStack/query:docs/framework/preact/devtools.md
+  - TanStack/query:docs/framework/vue/devtools.md
+  - TanStack/query:docs/framework/solid/devtools.md
+  - TanStack/query:docs/framework/svelte/devtools.md
+  - TanStack/query:docs/framework/angular/devtools.md
+---
+
+This skill builds on `lifecycle/setup-query-client-and-providers`.
+
+## Setup
+
+```tsx
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+
+export function Devtools() {
+  return <ReactQueryDevtools initialIsOpen={false} />;
+}
+```
+
+## Hooks and Components
+
+### Lazy-load production devtools
+
+```tsx
+import * as React from "react";
+
+const ReactQueryDevtoolsProduction = React.lazy(() =>
+  import("@tanstack/react-query-devtools/production").then((module) => ({
+    default: module.ReactQueryDevtools,
+  })),
+);
+
+export function LazyDevtools() {
+  return (
+    <React.Suspense fallback={null}>
+      <ReactQueryDevtoolsProduction />
+    </React.Suspense>
+  );
+}
+```
+
+### Embed a panel
+
+```tsx
+import { ReactQueryDevtoolsPanel } from "@tanstack/react-query-devtools";
+
+export function DevtoolsPanel() {
+  return <ReactQueryDevtoolsPanel />;
+}
+```
+
+### Use adapter-specific packages
+
+```ts
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+import { VueQueryDevtools } from "@tanstack/vue-query-devtools";
+
+export const devtools = { ReactQueryDevtools, VueQueryDevtools };
+```
+
+## Common Mistakes
+
+### MEDIUM Eager production devtools
+
+Wrong:
+
+```tsx
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+
+export function AppDevtools() {
+  return <ReactQueryDevtools />;
+}
+```
+
+Correct:
+
+```tsx
+import * as React from "react";
+
+const Devtools = React.lazy(() =>
+  import("@tanstack/react-query-devtools/production").then((module) => ({
+    default: module.ReactQueryDevtools,
+  })),
+);
+export function AppDevtools() {
+  return (
+    <React.Suspense fallback={null}>
+      <Devtools />
+    </React.Suspense>
+  );
+}
+```
+
+Production devtools should be lazy-loaded from the production entry.
+
+Source: TanStack/query:docs/framework/react/devtools.md
+
+### MEDIUM Mock offline misconception
+
+Wrong:
+
+```tsx
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+
+export function Devtools() {
+  return <ReactQueryDevtools initialIsOpen />;
+}
+```
+
+Correct:
+
+```ts
+import { onlineManager } from "@tanstack/react-query";
+
+export function setOfflineForTest() {
+  onlineManager.setOnline(false);
+}
+```
+
+Devtools inspect state; use Query managers or browser tooling to model network state.
+
+Source: TanStack/query:docs/reference/onlineManager.md
+
+### HIGH Devtools outside provider
+
+Wrong:
+
+```tsx
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+
+export function Root() {
+  return <ReactQueryDevtools />;
+}
+```
+
+Correct:
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+
+const queryClient = new QueryClient();
+export function Root() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <ReactQueryDevtools />
+    </QueryClientProvider>
+  );
+}
+```
+
+Devtools need the same QueryClient context as the app.
+
+Source: TanStack/query:docs/framework/react/devtools.md