@hitch42/applet 0.1.0-beta.10

package/scaffold/.agents/skills/tanstack-query/references/compositions/query-data-and-forms.md

@@ -0,0 +1,156 @@
+---
+name: compositions/query-data-and-forms
+description: >
+  Use this when integrating TanStack Query data and mutations with forms:
+  initial server state, editable client state, dirty fields, background updates,
+  submit prevention, invalidation, reset-after-save, validation errors, and
+  avoiding blind copies from Query cache into local form state.
+type: composition
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/write-mutations-and-invalidate-related-queries
+  - core/selectors-and-derived-state
+sources:
+  - TanStack/query:docs/framework/react/guides/mutations.md
+  - TanStack/query:docs/framework/react/guides/invalidations-from-mutations.md
+---
+
+## Core Patterns
+
+Treat form state as client state after the user starts editing. Server state can initialize the form, but it should not be copied blindly on every query update.
+
+### Initial data only
+
+Use this when one user owns the form and background updates are not useful while editing.
+
+```tsx
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+function PersonDetail({ id }: { id: string }) {
+  const queryClient = useQueryClient();
+  const person = useQuery({
+    queryKey: ["person", id],
+    queryFn: () => fetchPerson(id),
+    staleTime: Infinity,
+  });
+
+  const updatePerson = useMutation({
+    mutationFn: savePerson,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["person", id] }),
+  });
+
+  if (!person.data) return <p>Loading...</p>;
+  return (
+    <PersonForm
+      person={person.data}
+      isSaving={updatePerson.isPending}
+      onSubmit={updatePerson.mutate}
+    />
+  );
+}
+```
+
+### Derived server plus client state
+
+Use this when background updates should remain visible for untouched fields.
+
+```tsx
+import * as React from "react";
+import { useQuery } from "@tanstack/react-query";
+
+function PersonName({ id }: { id: string }) {
+  const { data } = useQuery({
+    queryKey: ["person", id],
+    queryFn: () => fetchPerson(id),
+  });
+  const [draft, setDraft] = React.useState<{ firstName?: string }>({});
+
+  if (!data) return <p>Loading...</p>;
+
+  return (
+    <input
+      value={draft.firstName ?? data.firstName}
+      onChange={(event) => setDraft({ firstName: event.target.value })}
+    />
+  );
+}
+```
+
+### Reset after awaited invalidation
+
+```tsx
+const mutation = useMutation({
+  mutationFn: savePerson,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ["person", id] }),
+});
+
+function submit(values: PersonFormValues) {
+  mutation.mutate(values, { onSuccess: () => resetFormDraft() });
+}
+```
+
+Return the invalidation promise from `onSuccess` or `onSettled` when the saved server state must be back in the cache before the form resets.
+
+## Common Mistakes
+
+### HIGH Initializing form defaults before query data exists
+
+Wrong:
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["person", id],
+  queryFn: () => fetchPerson(id),
+});
+const [draft, setDraft] = React.useState(data);
+```
+
+Correct:
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["person", id],
+  queryFn: () => fetchPerson(id),
+});
+if (!data) return <p>Loading...</p>;
+return <PersonForm initialPerson={data} />;
+```
+
+The first render usually has no query data. Split the form boundary or derive field values from query data plus draft state.
+
+### HIGH Background refetch overwrites or hides dirty client state
+
+Wrong:
+
+```tsx
+React.useEffect(() => {
+  setDraft(personQuery.data);
+}, [personQuery.data]);
+```
+
+Correct:
+
+```tsx
+const shownFirstName = draft.firstName ?? personQuery.data?.firstName ?? "";
+```
+
+Do not synchronize every server update into the draft. Derive displayed values or intentionally opt out of background updates for initial-only forms.
+
+### MEDIUM Form submit can run twice
+
+Wrong:
+
+```tsx
+<button type="submit">Save</button>
+```
+
+Correct:
+
+```tsx
+<button type="submit" disabled={mutation.isPending}>
+  Save
+</button>
+```
+
+Use mutation state to block duplicate writes while a submission is in flight.

package/scaffold/.agents/skills/tanstack-query/references/core/build-query-abstractions.md

@@ -0,0 +1,130 @@
+---
+name: core/build-query-abstractions
+description: >
+  Use this when creating TanStack Query abstractions: queryOptions factories,
+  feature-local key modules, custom hooks built on top of options factories,
+  TypeScript inference, avoiding wide UseQueryOptions wrappers, and sharing
+  query configuration across hooks, loaders, prefetches, and QueryClient calls.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/design-query-keys-and-options
+sources:
+  - TanStack/query:docs/framework/react/guides/query-options.md
+  - TanStack/query:docs/framework/react/typescript.md
+---
+
+## Core Patterns
+
+Prefer a `queryOptions` factory as the base abstraction. Hooks, loaders, prefetches, suspense queries, and `QueryClient` calls can all consume it.
+
+```ts
+import { queryOptions, useQuery, useSuspenseQuery } from "@tanstack/react-query";
+
+export function invoiceOptions(id: number) {
+  return queryOptions({
+    queryKey: ["invoice", id],
+    queryFn: () => fetchInvoice(id),
+    staleTime: 60_000,
+  });
+}
+
+export function useInvoice(id: number) {
+  return useQuery(invoiceOptions(id));
+}
+
+export function useSuspenseInvoice(id: number) {
+  return useSuspenseQuery(invoiceOptions(id));
+}
+```
+
+Compose one-off options at the usage site:
+
+```ts
+const invoice = useQuery({
+  ...invoiceOptions(id),
+  select: (data) => data.createdAt,
+  throwOnError: true,
+});
+```
+
+## Common Mistakes
+
+### HIGH Custom hook is the only abstraction
+
+Wrong:
+
+```ts
+export function useInvoice(id: number) {
+  return useQuery({
+    queryKey: ["invoice", id],
+    queryFn: () => fetchInvoice(id),
+  });
+}
+```
+
+Correct:
+
+```ts
+export function invoiceOptions(id: number) {
+  return queryOptions({
+    queryKey: ["invoice", id],
+    queryFn: () => fetchInvoice(id),
+  });
+}
+
+export function useInvoice(id: number) {
+  return useQuery(invoiceOptions(id));
+}
+```
+
+Custom hooks cannot run in route loaders, server prefetches, or event handlers. Options factories can.
+
+### HIGH Wide UseQueryOptions wrapper breaks inference
+
+Wrong:
+
+```ts
+function useInvoice(id: number, options?: Partial<UseQueryOptions<Invoice>>) {
+  return useQuery({
+    queryKey: ["invoice", id],
+    queryFn: () => fetchInvoice(id),
+    ...options,
+  });
+}
+```
+
+Correct:
+
+```ts
+useQuery({
+  ...invoiceOptions(id),
+  select: (invoice) => invoice.createdAt,
+});
+```
+
+Let `queryOptions` and usage-site composition preserve `select` inference.
+
+### MEDIUM Wrapper hides Query result state
+
+Wrong:
+
+```ts
+export function useInvoice(id: number) {
+  const { data } = useQuery(invoiceOptions(id));
+  return data;
+}
+```
+
+Correct:
+
+```ts
+export function useInvoice(id: number) {
+  return useQuery(invoiceOptions(id));
+}
+```
+
+Keep the Query result surface available unless the abstraction owns every loading, error, and refetch behavior.
+
+Source: TanStack/query:docs/framework/react/guides/queries.md

package/scaffold/.agents/skills/tanstack-query/references/core/cancel-queries-and-consume-abort-signals.md

@@ -0,0 +1,176 @@
+---
+name: core/cancel-queries-and-consume-abort-signals
+description: >
+  Use this when handling query cancellation, AbortSignal, cancelQueries,
+  CancelledError, rollback after consumed signals, fetch cancellation, axios
+  cancellation, and optimistic update overwrite prevention.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/fetch-and-observe-queries
+sources:
+  - TanStack/query:docs/framework/react/guides/query-cancellation.md
+  - TanStack/query:docs/reference/QueryClient.md
+  - TanStack/query:packages/query-core/src/retryer.ts
+---
+
+## Setup
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodo(todoId: string) {
+  return useQuery({
+    queryKey: ["todo", todoId],
+    queryFn: async ({ signal }) => {
+      const response = await fetch(`/api/todos/${todoId}`, { signal });
+      return response.json() as Promise<{ id: string; title: string }>;
+    },
+  });
+}
+```
+
+## Core Patterns
+
+### Cancel before optimistic writes
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+export async function prepareTodoWrite() {
+  await queryClient.cancelQueries({ queryKey: ["todos"] });
+}
+```
+
+### Consume one signal across nested fetches
+
+```ts
+import { queryOptions } from "@tanstack/react-query";
+
+export const todosWithDetailsOptions = queryOptions({
+  queryKey: ["todos-with-details"],
+  queryFn: async ({ signal }) => {
+    const todos = await fetch("/api/todos", { signal }).then(
+      (response) => response.json() as Promise<Array<{ id: string }>>,
+    );
+    return Promise.all(
+      todos.map((todo) =>
+        fetch(`/api/todos/${todo.id}`, { signal }).then((response) => response.json()),
+      ),
+    );
+  },
+});
+```
+
+### Cancel by query key
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+export function cancelTodos() {
+  return queryClient.cancelQueries({ queryKey: ["todos"] });
+}
+```
+
+## Common Mistakes
+
+### HIGH Ignoring AbortSignal
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodo(id: string) {
+  return useQuery({
+    queryKey: ["todo", id],
+    queryFn: async () => fetch(`/api/todos/${id}`).then((r) => r.json()),
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodo(id: string) {
+  return useQuery({
+    queryKey: ["todo", id],
+    queryFn: async ({ signal }) => fetch(`/api/todos/${id}`, { signal }).then((r) => r.json()),
+  });
+}
+```
+
+TanStack Query provides an AbortSignal; the request is only cancelled if the query function consumes it.
+
+Source: TanStack/query:docs/framework/react/guides/query-cancellation.md
+
+### HIGH Assuming unmount cancels
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useReport() {
+  return useQuery({
+    queryKey: ["report"],
+    queryFn: async () => fetch("/api/report").then((r) => r.json()),
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useReport() {
+  return useQuery({
+    queryKey: ["report"],
+    queryFn: async ({ signal }) => fetch("/api/report", { signal }).then((r) => r.json()),
+  });
+}
+```
+
+Unused queries can continue and populate cache unless the signal is consumed.
+
+Source: TanStack/query:docs/framework/react/guides/query-cancellation.md
+
+### HIGH Suspense cancellation expected
+
+Wrong:
+
+```ts
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+export function useTodo(id: string) {
+  return useSuspenseQuery({
+    queryKey: ["todo", id],
+    queryFn: async ({ signal }) => fetch(`/api/todos/${id}`, { signal }).then((r) => r.json()),
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodo(id: string) {
+  return useQuery({
+    queryKey: ["todo", id],
+    queryFn: async ({ signal }) => fetch(`/api/todos/${id}`, { signal }).then((r) => r.json()),
+  });
+}
+```
+
+Cancellation limitations apply to Suspense hooks; use non-suspense queries when cancellation behavior is required.
+
+Source: TanStack/query:docs/framework/react/guides/query-cancellation.md

package/scaffold/.agents/skills/tanstack-query/references/core/concurrent-optimistic-updates.md

@@ -0,0 +1,135 @@
+---
+name: core/concurrent-optimistic-updates
+description: >
+  Use this when multiple optimistic mutations can overlap: mutation variables,
+  submittedAt keys, scoped mutationKey filters, isMutating guards, cancellation,
+  rollback context, filtered list updates, and avoiding windows of inconsistent
+  UI during concurrent writes.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/implement-optimistic-updates-and-cache-writes
+  - core/cancel-queries-and-consume-abort-signals
+sources:
+  - TanStack/query:docs/framework/react/guides/optimistic-updates.md
+  - TanStack/query:docs/framework/react/reference/useMutationState.md
+---
+
+## Core Patterns
+
+Concurrent optimistic updates need per-mutation identity and scoped invalidation. A rollback or invalidation from one mutation should not erase another mutation that is still pending.
+
+### Scope related mutations
+
+```tsx
+const mutation = useMutation({
+  mutationKey: ["items"],
+  mutationFn: toggleItem,
+  onMutate: async ({ id }) => {
+    await queryClient.cancelQueries({ queryKey: ["items", "detail", id] });
+    const previousItem = queryClient.getQueryData<Item>(["items", "detail", id]);
+
+    queryClient.setQueryData<Item>(["items", "detail", id], (item) =>
+      item ? { ...item, isActive: !item.isActive } : item,
+    );
+
+    return { previousItem };
+  },
+  onError: (_error, variables, context) => {
+    queryClient.setQueryData(["items", "detail", variables.id], context?.previousItem);
+  },
+  onSettled: () => {
+    if (queryClient.isMutating({ mutationKey: ["items"] }) === 1) {
+      return queryClient.invalidateQueries({ queryKey: ["items"] });
+    }
+  },
+});
+```
+
+Use `queryClient.isMutating()` imperatively inside the callback so the count is current at the moment invalidation would run.
+
+### Render pending variables with stable keys
+
+```tsx
+const pendingAdds = useMutationState<string>({
+  filters: { mutationKey: ["todos", "add"], status: "pending" },
+  select: (mutation) => `${mutation.state.submittedAt}:${mutation.state.variables}`,
+});
+```
+
+`submittedAt` distinguishes multiple pending mutations with the same variables.
+
+## Common Mistakes
+
+### CRITICAL One mutation invalidation reverts another optimistic update
+
+Wrong:
+
+```ts
+onSettled: () => queryClient.invalidateQueries({ queryKey: ["items"] });
+```
+
+Correct:
+
+```ts
+onSettled: () => {
+  if (queryClient.isMutating({ mutationKey: ["items"] }) === 1) {
+    return queryClient.invalidateQueries({ queryKey: ["items"] });
+  }
+};
+```
+
+Skip intermediate invalidations while related optimistic mutations are still in flight.
+
+### HIGH Optimistic list update ignores current filters
+
+Wrong:
+
+```ts
+queryClient.setQueryData(["items", "list", filters], (items) =>
+  items?.map((item) => (item.id === updated.id ? updated : item)),
+);
+```
+
+Correct:
+
+```ts
+queryClient.setQueryData(["items", "list", filters], (items) =>
+  items
+    ?.map((item) => (item.id === updated.id ? updated : item))
+    .filter((item) => matchesFilters(item, filters)),
+);
+```
+
+If the server would remove the updated item from the filtered list, the optimistic cache update should do the same.
+
+### HIGH Pending optimistic rows share unstable keys
+
+Wrong:
+
+```tsx
+{
+  variables.map((title) => <li key={title}>{title}</li>);
+}
+```
+
+Correct:
+
+```tsx
+const pending = useMutationState({
+  filters: { mutationKey: ["todos", "add"], status: "pending" },
+  select: (mutation) => ({
+    variables: mutation.state.variables,
+    submittedAt: mutation.state.submittedAt,
+  }),
+});
+
+{
+  pending.map((todo) => <li key={todo.submittedAt}>{todo.variables.title}</li>);
+}
+```
+
+Use mutation metadata to keep concurrent optimistic rows distinct.
+
+Source: TanStack/query:docs/framework/react/guides/optimistic-updates.md