@hitch42/applet 0.1.1-beta.1 → 0.1.1-beta.10

package/scaffold/.agents/skills/tanstack-query/references/framework/handle-status-and-errors.md

@@ -0,0 +1,119 @@
+---
+name: framework/handle-status-and-errors
+description: >
+  Use this when designing TanStack Query loading, empty, stale, background error,
+  retry, toast, throwOnError, and Error Boundary flows. Covers status versus
+  fetchStatus, stale data after failed refetches, global QueryCache or
+  MutationCache error callbacks, and local versus boundary-level error handling.
+type: framework
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/fetch-and-observe-queries
+  - framework/use-suspense-and-error-boundaries
+sources:
+  - TanStack/query:docs/framework/react/guides/queries.md
+  - TanStack/query:docs/framework/react/reference/QueryErrorResetBoundary.md
+---
+
+## Core Patterns
+
+Prefer data-first rendering when stale data is useful. A failed background refetch can produce `isError` while `data` is still available.
+
+```tsx
+const todos = useQuery({ queryKey: ["todos"], queryFn: fetchTodos });
+
+if (todos.data) return <TodoList todos={todos.data} isRefreshing={todos.isFetching} />;
+if (todos.isPending) return <Spinner />;
+if (todos.isError) return <ErrorMessage error={todos.error} />;
+return null;
+```
+
+Use `throwOnError` when render-time Error Boundaries should own the fallback:
+
+```tsx
+useQuery({
+  queryKey: ["todos"],
+  queryFn: fetchTodos,
+  throwOnError: (error) => error.status >= 500,
+});
+```
+
+Use global cache callbacks for cross-cutting notifications:
+
+```ts
+import { QueryCache, QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient({
+  queryCache: new QueryCache({
+    onError: (error, query) => {
+      if (query.state.data !== undefined) showToast(error.message);
+    },
+  }),
+});
+```
+
+## Common Mistakes
+
+### HIGH Hiding stale data on background error
+
+Wrong:
+
+```tsx
+if (query.isError) return <ErrorMessage error={query.error} />;
+if (query.data) return <Todos todos={query.data} />;
+```
+
+Correct:
+
+```tsx
+if (query.data) return <Todos todos={query.data} staleError={query.isError ? query.error : null} />;
+if (query.isError) return <ErrorMessage error={query.error} />;
+```
+
+Background refetch failures should not necessarily erase already-rendered data.
+
+### HIGH Sending validation errors to a global boundary
+
+Wrong:
+
+```ts
+useMutation({ mutationFn: submitForm, throwOnError: true });
+```
+
+Correct:
+
+```ts
+useMutation({
+  mutationFn: submitForm,
+  throwOnError: (error) => error.status >= 500,
+});
+```
+
+Handle expected 4xx validation errors near the form. Send unexpected server failures to the boundary.
+
+### MEDIUM Duplicating toast notifications per observer
+
+Wrong:
+
+```ts
+useQuery({
+  queryKey: ["todos"],
+  queryFn: fetchTodos,
+  onError: toastError,
+});
+```
+
+Correct:
+
+```ts
+new QueryClient({
+  queryCache: new QueryCache({
+    onError: (error, query) => {
+      if (query.state.data !== undefined) toastError(error);
+    },
+  }),
+});
+```
+
+Observer-level callbacks can duplicate notifications across components. Use cache-level callbacks for global side effects.

package/scaffold/.agents/skills/tanstack-query/references/framework/shape-data-and-render-efficiently.md

@@ -0,0 +1,184 @@
+---
+name: framework/shape-data-and-render-efficiently
+description: >
+  Use this when optimizing TanStack Query rendering with structuralSharing,
+  tracked properties, select, notifyOnChangeProps, stable hook deps, immutable
+  data, Vue reactivity, and no-rest-destructuring or no-unstable-deps lint rules.
+type: framework
+library: TanStack Query
+framework: cross-adapter
+library_version: "5.101.0"
+requires:
+  - core/fetch-and-observe-queries
+  - core/seed-placeholder-select-and-transform-data
+sources:
+  - TanStack/query:docs/framework/react/guides/render-optimizations.md
+  - TanStack/query:docs/eslint/no-rest-destructuring.md
+  - TanStack/query:docs/eslint/no-unstable-deps.md
+  - TanStack/query:docs/framework/vue/reactivity.md
+---
+
+This skill builds on `core/fetch-and-observe-queries` and `core/seed-placeholder-select-and-transform-data`.
+
+## Setup
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+
+export function TodoCount() {
+  const { data } = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }, { id: 2 }],
+    select: (todos) => todos.length,
+  });
+  return <p>{data ?? 0}</p>;
+}
+```
+
+## Hooks and Components
+
+### Destructure only used result fields
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+
+export function Todos() {
+  const { data, isFetching } = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return (
+    <pre>
+      {isFetching ? "Refreshing " : ""}
+      {JSON.stringify(data ?? [])}
+    </pre>
+  );
+}
+```
+
+### Keep Vue query data immutable
+
+```ts
+import { ref } from "vue";
+
+export function editableTodo(todo: { id: number; title: string }) {
+  return ref({ ...todo });
+}
+```
+
+### Use stable members in deps
+
+```tsx
+import * as React from "react";
+import { useQuery } from "@tanstack/react-query";
+
+export function TodosEffect() {
+  const { data } = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  React.useEffect(() => console.log(data?.length ?? 0), [data]);
+  return null;
+}
+```
+
+## Common Mistakes
+
+### MEDIUM Rest destructuring
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodos() {
+  const { data, ...rest } = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return { data, rest };
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodos() {
+  const { data, isFetching, error } = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return { data, isFetching, error };
+}
+```
+
+Rest destructuring touches every tracked property and disables fine-grained render tracking.
+
+Source: TanStack/query:docs/eslint/no-rest-destructuring.md
+
+### HIGH Query result in hook deps
+
+Wrong:
+
+```tsx
+import * as React from "react";
+import { useQuery } from "@tanstack/react-query";
+
+export function Todos() {
+  const query = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  React.useEffect(() => console.log(query.data), [query]);
+  return null;
+}
+```
+
+Correct:
+
+```tsx
+import * as React from "react";
+import { useQuery } from "@tanstack/react-query";
+
+export function Todos() {
+  const { data } = useQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  React.useEffect(() => console.log(data), [data]);
+  return null;
+}
+```
+
+The top-level query result object is not referentially stable; destructured members are tracked.
+
+Source: TanStack/query:docs/eslint/no-unstable-deps.md
+
+### HIGH Vue v-model mutates query result
+
+Wrong:
+
+```vue
+<script setup lang="ts">
+const todo = { id: 1, title: "Ship" };
+</script>
+<template><input v-model="todo.title" /></template>
+```
+
+Correct:
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+const editableTodo = ref({ id: 1, title: "Ship" });
+</script>
+<template><input v-model="editableTodo.title" /></template>
+```
+
+Vue Query results are immutable; make a mutable copy for form state.
+
+Source: TanStack/query:docs/framework/vue/reactivity.md
+
+See also: `compositions/enforce-query-best-practices-with-eslint` for lint rules that protect render tracking.

package/scaffold/.agents/skills/tanstack-query/references/framework/use-framework-adapter-reactivity.md

@@ -0,0 +1,185 @@
+---
+name: framework/use-framework-adapter-reactivity
+description: >
+  Use this when translating Query patterns across React, Preact, Vue, Solid,
+  Svelte, Angular, and Lit adapters: Vue refs/getters, Solid signals, Svelte
+  stores/runes, Angular signals and HttpClient promises, Lit QueryController,
+  adapter option helpers, and provider APIs.
+type: framework
+library: TanStack Query
+framework: cross-adapter
+library_version: "5.101.0"
+requires:
+  - lifecycle/setup-query-client-and-providers
+  - core/design-query-keys-and-options
+sources:
+  - TanStack/query:docs/framework/vue/reactivity.md
+  - TanStack/query:docs/framework/vue/guides/query-options.md
+  - TanStack/query:docs/framework/solid/guides/query-options.md
+  - TanStack/query:docs/framework/svelte/overview.md
+  - TanStack/query:docs/framework/svelte/migrate-from-v5-to-v6.md
+  - TanStack/query:docs/framework/angular/overview.md
+  - TanStack/query:docs/framework/angular/zoneless.md
+  - TanStack/query:docs/framework/lit/guides/reactive-controllers-vs-hooks.md
+---
+
+This skill builds on `lifecycle/setup-query-client-and-providers` and `core/design-query-keys-and-options`.
+
+## Setup
+
+```ts
+import { queryOptions } from "@tanstack/react-query";
+
+export function todoOptions(id: string) {
+  return queryOptions({
+    queryKey: ["todo", id],
+    queryFn: async () => ({ id }),
+  });
+}
+```
+
+## Hooks and Components
+
+### Keep Vue refs in the key
+
+```ts
+import { computed, toRef } from "vue";
+import { useQuery } from "@tanstack/vue-query";
+
+export function useTodo(props: { id: string }) {
+  const id = toRef(props, "id");
+  return useQuery(
+    computed(() => ({
+      queryKey: ["todo", id.value],
+      queryFn: async () => ({ id: id.value }),
+    })),
+  );
+}
+```
+
+### Use Solid option functions
+
+```ts
+import { createQuery } from "@tanstack/solid-query";
+
+export function useTodo(id: () => string) {
+  return createQuery(() => ({
+    queryKey: ["todo", id()],
+    queryFn: async () => ({ id: id() }),
+  }));
+}
+```
+
+### Convert Angular Observable clients to promises
+
+```ts
+import { injectQuery } from "@tanstack/angular-query-experimental";
+import { firstValueFrom, of } from "rxjs";
+
+export class TodosQuery {
+  todos = injectQuery(() => ({
+    queryKey: ["todos"],
+    queryFn: () => firstValueFrom(of([{ id: 1 }])),
+  }));
+}
+```
+
+## Common Mistakes
+
+### HIGH Vue ref unwrapped
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/vue-query";
+
+export function useTodo(id: { value: string }) {
+  return useQuery({
+    queryKey: ["todo", id.value],
+    queryFn: async () => ({ id: id.value }),
+  });
+}
+```
+
+Correct:
+
+```ts
+import { computed } from "vue";
+import { useQuery } from "@tanstack/vue-query";
+
+export function useTodo(id: { value: string }) {
+  return useQuery(
+    computed(() => ({
+      queryKey: ["todo", id.value],
+      queryFn: async () => ({ id: id.value }),
+    })),
+  );
+}
+```
+
+Vue reactive inputs need to stay reactive through the options object or query key.
+
+Source: TanStack/query:docs/framework/vue/reactivity.md
+
+### HIGH Svelte store syntax in v6
+
+Wrong:
+
+```svelte
+<script lang="ts">
+  import { createQuery } from '@tanstack/svelte-query'
+  const query = createQuery({ queryKey: ['todos'], queryFn: async () => [] })
+</script>
+```
+
+Correct:
+
+```svelte
+<script lang="ts">
+  import { createQuery } from '@tanstack/svelte-query'
+  const query = createQuery(() => ({
+    queryKey: ['todos'],
+    queryFn: async () => [],
+  }))
+</script>
+```
+
+Svelte Query v6 uses rune-compatible option functions rather than the older store shape.
+
+Source: TanStack/query:docs/framework/svelte/migrate-from-v5-to-v6.md
+
+### HIGH Angular Observable returned directly
+
+Wrong:
+
+```ts
+import { injectQuery } from "@tanstack/angular-query-experimental";
+import { of } from "rxjs";
+
+export class TodosQuery {
+  todos = injectQuery(() => ({
+    queryKey: ["todos"],
+    queryFn: () => of([{ id: 1 }]),
+  }));
+}
+```
+
+Correct:
+
+```ts
+import { injectQuery } from "@tanstack/angular-query-experimental";
+import { firstValueFrom, of } from "rxjs";
+
+export class TodosQuery {
+  todos = injectQuery(() => ({
+    queryKey: ["todos"],
+    queryFn: () => firstValueFrom(of([{ id: 1 }])),
+  }));
+}
+```
+
+Query functions must resolve data; Angular HttpClient Observables need conversion to promises.
+
+Source: TanStack/query:docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md
+
+See also: `core/design-query-keys-and-options` for key identity across adapters.

package/scaffold/.agents/skills/tanstack-query/references/framework/use-suspense-and-error-boundaries.md

@@ -0,0 +1,208 @@
+---
+name: framework/use-suspense-and-error-boundaries
+description: >
+  Use this when using useSuspenseQuery, useSuspenseQueries,
+  useSuspenseInfiniteQuery, QueryErrorResetBoundary, throwOnError,
+  useQueryErrorResetBoundary, React.use query.promise, streamed hydration, and
+  Suspense constraints in Query adapters.
+type: framework
+library: TanStack Query
+framework: cross-adapter
+library_version: "5.101.0"
+requires:
+  - core/fetch-and-observe-queries
+  - lifecycle/prefetch-and-remove-request-waterfalls
+sources:
+  - TanStack/query:docs/framework/react/guides/suspense.md
+  - TanStack/query:docs/framework/react/reference/QueryErrorResetBoundary.md
+  - TanStack/query:docs/framework/react/reference/useSuspenseQuery.md
+  - TanStack/query:docs/framework/react/reference/useSuspenseQueries.md
+  - TanStack/query:docs/framework/react/reference/useSuspenseInfiniteQuery.md
+  - TanStack/query:docs/framework/solid/guides/suspense.md
+  - TanStack/query:docs/framework/vue/guides/suspense.md
+---
+
+This skill builds on `core/fetch-and-observe-queries` and `lifecycle/prefetch-and-remove-request-waterfalls`.
+
+## Setup
+
+```tsx
+import { Suspense } from "react";
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+function Todos() {
+  const { data } = useSuspenseQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return <pre>{JSON.stringify(data)}</pre>;
+}
+
+export function App() {
+  return (
+    <Suspense fallback={<p>Loading</p>}>
+      <Todos />
+    </Suspense>
+  );
+}
+```
+
+## Hooks and Components
+
+### Reset query errors with the boundary
+
+```tsx
+import { QueryErrorResetBoundary } from "@tanstack/react-query";
+import { ErrorBoundary } from "react-error-boundary";
+
+export function QueryErrorBoundary(props: { children: React.ReactNode }) {
+  return (
+    <QueryErrorResetBoundary>
+      {({ reset }) => (
+        <ErrorBoundary
+          onReset={reset}
+          fallbackRender={({ resetErrorBoundary }) => (
+            <button onClick={resetErrorBoundary}>Retry</button>
+          )}
+        >
+          {props.children}
+        </ErrorBoundary>
+      )}
+    </QueryErrorResetBoundary>
+  );
+}
+```
+
+### Use suspense when data must be defined
+
+```ts
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+export function useTodos() {
+  return useSuspenseQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+}
+```
+
+### Use normal queries for disabled flows
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useMaybeTodo(id: string | undefined) {
+  return useQuery({
+    queryKey: ["todo", id],
+    queryFn: async () => ({ id }),
+    enabled: Boolean(id),
+  });
+}
+```
+
+## Common Mistakes
+
+### HIGH Disabled suspense query
+
+Wrong:
+
+```ts
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+export function useTodo(id: string | undefined) {
+  return useSuspenseQuery({
+    queryKey: ["todo", id],
+    queryFn: async () => ({ id }),
+    enabled: Boolean(id),
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodo(id: string | undefined) {
+  return useQuery({
+    queryKey: ["todo", id],
+    queryFn: async () => ({ id }),
+    enabled: Boolean(id),
+  });
+}
+```
+
+Suspense hooks guarantee `data` and do not support conditional disabling like normal queries.
+
+Source: TanStack/query:docs/framework/react/guides/suspense.md
+
+### HIGH Missing reset boundary
+
+Wrong:
+
+```tsx
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+export function Todos() {
+  const { data } = useSuspenseQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return <pre>{JSON.stringify(data)}</pre>;
+}
+```
+
+Correct:
+
+```tsx
+import { QueryErrorResetBoundary } from "@tanstack/react-query";
+import { ErrorBoundary } from "react-error-boundary";
+
+export function WrappedTodos(props: { children: React.ReactNode }) {
+  return (
+    <QueryErrorResetBoundary>
+      {({ reset }) => (
+        <ErrorBoundary onReset={reset} fallback={<p>Error</p>}>
+          {props.children}
+        </ErrorBoundary>
+      )}
+    </QueryErrorResetBoundary>
+  );
+}
+```
+
+Error boundaries need Query reset coordination so failed queries can retry after reset.
+
+Source: TanStack/query:docs/framework/react/reference/QueryErrorResetBoundary.md
+
+### MEDIUM query.promise without flag
+
+Wrong:
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+
+export function useTodoPromise() {
+  return useQuery({ queryKey: ["todo", 1], queryFn: async () => ({ id: 1 }) }).promise;
+}
+```
+
+Correct:
+
+```ts
+import { QueryClient, useQuery } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: { queries: { experimental_prefetchInRender: true } },
+});
+
+export function useTodoPromise() {
+  return useQuery({ queryKey: ["todo", 1], queryFn: async () => ({ id: 1 }) }).promise;
+}
+```
+
+The stable `promise` property requires the experimental prefetch-in-render flag.
+
+Source: TanStack/query:docs/framework/react/guides/suspense.md
+
+See also: `lifecycle/ssr-hydration-and-streaming` for streamed hydration constraints.