@hitch42/applet 0.1.0-beta.9 → 0.1.1-beta.10

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

package/scaffold/.agents/skills/tanstack-query/references/core/coordinate-query-execution.md

@@ -0,0 +1,188 @@
+---
+name: core/coordinate-query-execution
+description: >
+  Use this when coordinating enabled, skipToken, dependent queries, useQueries,
+  parallel queries, disabled queries, background fetching indicators, isFetching,
+  fetchStatus, and declarative refetch behavior.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/fetch-and-observe-queries
+  - core/tune-defaults-freshness-retries-and-refetching
+sources:
+  - TanStack/query:docs/framework/react/guides/dependent-queries.md
+  - TanStack/query:docs/framework/react/guides/parallel-queries.md
+  - TanStack/query:docs/framework/react/guides/disabling-queries.md
+  - TanStack/query:docs/framework/react/guides/background-fetching-indicators.md
+  - TanStack/query:docs/framework/react/reference/useQueries.md
+---
+
+## Setup
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+
+export function Projects(props: { userId?: string }) {
+  const projects = useQuery({
+    queryKey: ["projects", props.userId],
+    queryFn: async () => [{ id: "p1", userId: props.userId }],
+    enabled: Boolean(props.userId),
+  });
+
+  return <pre>{JSON.stringify(projects.data ?? [])}</pre>;
+}
+```
+
+## Core Patterns
+
+### Gate by dependency
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useUserProjects(userId: string | undefined) {
+  return useQuery({
+    queryKey: ["projects", userId],
+    queryFn: async () => [{ id: "p1", userId }],
+    enabled: userId !== undefined,
+  });
+}
+```
+
+### Run dynamic parallel queries
+
+```ts
+import { useQueries } from "@tanstack/react-query";
+
+export function useMessages(ids: Array<string>) {
+  return useQueries({
+    queries: ids.map((id) => ({
+      queryKey: ["message", id],
+      queryFn: async () => ({ id, text: "Hello" }),
+    })),
+  });
+}
+```
+
+### Show background refresh separately
+
+```tsx
+import { useIsFetching } from "@tanstack/react-query";
+
+export function GlobalRefreshIndicator() {
+  const count = useIsFetching();
+  return count > 0 ? <p>Refreshing</p> : null;
+}
+```
+
+## Common Mistakes
+
+### HIGH Imperative disabled query
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useSearch(term: string) {
+  return useQuery({
+    queryKey: ["search"],
+    queryFn: async () => [term],
+    enabled: false,
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useSearch(term: string) {
+  return useQuery({
+    queryKey: ["search", term],
+    queryFn: async () => [term],
+    enabled: term.length > 0,
+  });
+}
+```
+
+Permanent disabling opts out of normal invalidation and dependency-driven cache behavior.
+
+Source: TanStack/query:docs/framework/react/guides/disabling-queries.md
+
+### HIGH Duplicate useQueries keys
+
+Wrong:
+
+```ts
+import { useQueries } from "@tanstack/react-query";
+
+export function useUsers(ids: Array<string>) {
+  return useQueries({
+    queries: ids.map((id) => ({
+      queryKey: ["user"],
+      queryFn: async () => ({ id }),
+    })),
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQueries } from "@tanstack/react-query";
+
+export function useUsers(ids: Array<string>) {
+  return useQueries({
+    queries: ids.map((id) => ({
+      queryKey: ["user", id],
+      queryFn: async () => ({ id }),
+    })),
+  });
+}
+```
+
+Duplicate keys can share placeholder, selected, or cached data between different items.
+
+Source: TanStack/query:docs/framework/react/reference/useQueries.md
+
+### MEDIUM Full-page spinner on background refetch
+
+Wrong:
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+
+export function Todos() {
+  const query = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return query.isFetching ? <p>Loading</p> : <pre>{JSON.stringify(query.data)}</pre>;
+}
+```
+
+Correct:
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+
+export function Todos() {
+  const query = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return (
+    <pre>
+      {query.isFetching ? "Refreshing " : ""}
+      {JSON.stringify(query.data ?? [])}
+    </pre>
+  );
+}
+```
+
+`isFetching` also covers background refreshes after data is already available.
+
+Source: TanStack/query:docs/framework/react/guides/background-fetching-indicators.md

package/scaffold/.agents/skills/tanstack-query/references/core/design-query-keys-and-options.md

@@ -0,0 +1,182 @@
+---
+name: core/design-query-keys-and-options
+description: >
+  Use this when designing queryKey arrays, queryFn inputs, queryOptions,
+  infiniteQueryOptions, mutationOptions, skipToken, key factories, or TypeScript
+  inference for TanStack Query reads and writes.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+sources:
+  - TanStack/query:docs/framework/react/guides/query-keys.md
+  - TanStack/query:docs/framework/react/guides/query-options.md
+  - TanStack/query:docs/framework/react/typescript.md
+  - TanStack/query:docs/eslint/exhaustive-deps.md
+  - TanStack/query:docs/eslint/prefer-query-options.md
+---
+
+## Setup
+
+```ts
+import { queryOptions } from "@tanstack/react-query";
+
+export function todoOptions(todoId: string) {
+  return queryOptions({
+    queryKey: ["todo", todoId],
+    queryFn: async () => ({ id: todoId, title: "Ship skills" }),
+    staleTime: 60_000,
+  });
+}
+```
+
+## Core Patterns
+
+### Put every query variable in the key
+
+```ts
+import { queryOptions } from "@tanstack/react-query";
+
+export function projectsOptions(teamId: string, page: number) {
+  return queryOptions({
+    queryKey: ["projects", teamId, page],
+    queryFn: async () => ({ teamId, page, items: [] as Array<{ id: string }> }),
+  });
+}
+```
+
+### Share one options factory
+
+```ts
+import { QueryClient, useQuery, queryOptions } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();
+
+export function userOptions(userId: string) {
+  return queryOptions({
+    queryKey: ["user", userId],
+    queryFn: async () => ({ id: userId, name: "Tanner" }),
+  });
+}
+
+export function useUser(userId: string) {
+  return useQuery(userOptions(userId));
+}
+
+export function preloadUser(userId: string) {
+  return queryClient.ensureQueryData(userOptions(userId));
+}
+```
+
+### Use skipToken for typesafe absence
+
+```ts
+import { skipToken, useQuery } from "@tanstack/react-query";
+
+export function useMaybeTodo(todoId: string | undefined) {
+  return useQuery({
+    queryKey: ["todo", todoId],
+    queryFn: todoId ? async () => ({ id: todoId }) : skipToken,
+  });
+}
+```
+
+## Common Mistakes
+
+### CRITICAL Missing variable in key
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useProject(teamId: string) {
+  return useQuery({
+    queryKey: ["project"],
+    queryFn: async () => ({ teamId }),
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useProject(teamId: string) {
+  return useQuery({
+    queryKey: ["project", teamId],
+    queryFn: async () => ({ teamId }),
+  });
+}
+```
+
+Query keys define cache identity; missing variables merge distinct data.
+
+Source: TanStack/query:docs/framework/react/guides/query-keys.md
+
+### HIGH Key and queryFn drift
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodo(todoId: string) {
+  return useQuery({ queryKey: ["todo"], queryFn: async () => ({ id: todoId }) });
+}
+```
+
+Correct:
+
+```ts
+import { queryOptions, useQuery } from "@tanstack/react-query";
+
+function todoOptions(todoId: string) {
+  return queryOptions({
+    queryKey: ["todo", todoId],
+    queryFn: async () => ({ id: todoId }),
+  });
+}
+
+export function useTodo(todoId: string) {
+  return useQuery(todoOptions(todoId));
+}
+```
+
+Options factories keep identity, fetch behavior, and inference together across hooks and prefetches.
+
+Source: TanStack/query:docs/eslint/prefer-query-options.md
+
+### HIGH skipToken inside suspense query
+
+Wrong:
+
+```ts
+import { skipToken, useSuspenseQuery } from "@tanstack/react-query";
+
+export function useTodo(todoId: string | undefined) {
+  return useSuspenseQuery({
+    queryKey: ["todo", todoId],
+    queryFn: todoId ? async () => ({ id: todoId }) : skipToken,
+  });
+}
+```
+
+Correct:
+
+```ts
+import { skipToken, useQuery } from "@tanstack/react-query";
+
+export function useTodo(todoId: string | undefined) {
+  return useQuery({
+    queryKey: ["todo", todoId],
+    queryFn: todoId ? async () => ({ id: todoId }) : skipToken,
+  });
+}
+```
+
+Suspense queries require a guaranteed query function and cannot be conditionally disabled.
+
+Source: TanStack/query:docs/framework/react/guides/suspense.md
+
+See also: `compositions/enforce-query-best-practices-with-eslint` for rules that enforce key and options mistakes.

package/scaffold/.agents/skills/tanstack-query/references/core/fetch-and-observe-queries.md

@@ -0,0 +1,193 @@
+---
+name: core/fetch-and-observe-queries
+description: >
+  Use this when reading server state with useQuery, useQueries, createQuery,
+  injectQuery, QueryObserver, QueryClient.fetchQuery, ensureQueryData, status,
+  fetchStatus, pending, paused, success, and error states.
+type: core
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - lifecycle/setup-query-client-and-providers
+  - core/design-query-keys-and-options
+sources:
+  - TanStack/query:docs/framework/react/guides/queries.md
+  - TanStack/query:docs/framework/react/guides/query-functions.md
+  - TanStack/query:docs/reference/QueryObserver.md
+  - TanStack/query:docs/reference/QueryClient.md
+  - TanStack/query:docs/eslint/no-void-query-fn.md
+---
+
+## Setup
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+
+export function Todos() {
+  const query = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1, title: "Ship" }],
+  });
+
+  if (query.isPending) return <p>Loading</p>;
+  if (query.isError) return <p>{query.error.message}</p>;
+  return <pre>{JSON.stringify(query.data)}</pre>;
+}
+```
+
+## Core Patterns
+
+### Fetch imperatively through QueryClient
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+export function loadTodo(todoId: string) {
+  return queryClient.fetchQuery({
+    queryKey: ["todo", todoId],
+    queryFn: async () => ({ id: todoId }),
+  });
+}
+```
+
+### Ensure cached data for loaders
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+export function ensureTodos() {
+  return queryClient.ensureQueryData({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+}
+```
+
+### Distinguish status from fetchStatus
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+
+export function TodoCount() {
+  const query = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  const label =
+    query.fetchStatus === "fetching" && query.status === "success" ? "Refreshing" : "Ready";
+  return (
+    <p>
+      {query.data?.length ?? 0} {label}
+    </p>
+  );
+}
+```
+
+## Common Mistakes
+
+### CRITICAL Void query function
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodos() {
+  return useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => {
+      await Promise.resolve([{ id: 1 }]);
+    },
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodos() {
+  return useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => Promise.resolve([{ id: 1 }]),
+  });
+}
+```
+
+Query functions must return data; a missing return caches `undefined`.
+
+Source: TanStack/query:docs/eslint/no-void-query-fn.md
+
+### HIGH Only checking pending offline
+
+Wrong:
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+
+export function Todos() {
+  const query = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+    networkMode: "online",
+  });
+  return query.isPending ? <p>Loading</p> : <p>{query.fetchStatus}</p>;
+}
+```
+
+Correct:
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+
+export function Todos() {
+  const query = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+    networkMode: "online",
+  });
+  return query.fetchStatus === "paused" ? <p>Offline</p> : <p>{query.status}</p>;
+}
+```
+
+`status` describes data state; `fetchStatus` describes whether fetching is paused, fetching, or idle.
+
+Source: TanStack/query:docs/framework/react/guides/queries.md
+
+### HIGH Using queries for writes
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useSaveTodo(title: string) {
+  return useQuery({
+    queryKey: ["saveTodo", title],
+    queryFn: async () => ({ id: 1, title }),
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+
+export function useSaveTodo() {
+  return useMutation({
+    mutationFn: async (title: string) => ({ id: 1, title }),
+  });
+}
+```
+
+Queries are for reads; writes need mutation lifecycle hooks, invalidation, rollback, and mutation state.
+
+Source: TanStack/query:docs/framework/react/guides/mutations.md
+
+See also: `core/tune-defaults-freshness-retries-and-refetching` for how defaults change status behavior.