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

package/scaffold/.agents/skills/tanstack-query/references/compositions/broadcast-realtime-and-multi-tab-synchronization.md

@@ -0,0 +1,150 @@
+---
+name: compositions/broadcast-realtime-and-multi-tab-synchronization
+description: >
+  Use this when synchronizing TanStack Query caches with broadcastQueryClient,
+  BroadcastChannel, multi-tab cache sync, realtime invalidation, WebSocket
+  events, server/browser boundaries, and experimental broadcast behavior.
+type: composition
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - lifecycle/setup-query-client-and-providers
+  - core/write-mutations-and-invalidate-related-queries
+  - compositions/persist-offline-and-restore-caches
+sources:
+  - TanStack/query:docs/framework/react/plugins/broadcastQueryClient.md
+  - TanStack/query:docs/framework/react/guides/query-invalidation.md
+  - TanStack/query:examples/react/chat/package.json
+---
+
+## Setup
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+import { broadcastQueryClient } from "@tanstack/query-broadcast-client-experimental";
+
+export const queryClient = new QueryClient();
+
+if (typeof window !== "undefined") {
+  broadcastQueryClient({ queryClient, broadcastChannel: "app-query-cache" });
+}
+```
+
+## Core Integration Patterns
+
+### Invalidate from realtime events
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+export function onTodoChanged(todoId: number) {
+  return queryClient.invalidateQueries({ queryKey: ["todo", todoId] });
+}
+```
+
+### Update narrow cache slices
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+export function onTodoTitle(todo: { id: number; title: string }) {
+  queryClient.setQueryData(["todo", todo.id], todo);
+}
+```
+
+### Keep broadcast client-side
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+import { broadcastQueryClient } from "@tanstack/query-broadcast-client-experimental";
+
+export function installBroadcast(queryClient: QueryClient) {
+  if (typeof window === "undefined") return;
+  broadcastQueryClient({ queryClient, broadcastChannel: "query-cache" });
+}
+```
+
+## Common Mistakes
+
+### MEDIUM Unlocked experimental broadcast
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+import { broadcastQueryClient } from "@tanstack/query-broadcast-client-experimental";
+
+broadcastQueryClient({ queryClient: new QueryClient() });
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+import { broadcastQueryClient } from "@tanstack/query-broadcast-client-experimental";
+
+if (typeof window !== "undefined") {
+  broadcastQueryClient({
+    queryClient: new QueryClient(),
+    broadcastChannel: "query-cache-v1",
+  });
+}
+```
+
+The broadcast package is experimental and should be deliberately isolated behind browser-only setup.
+
+Source: TanStack/query:docs/framework/react/plugins/broadcastQueryClient.md
+
+### MEDIUM Over-normalized realtime writes
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+queryClient.setQueryData(["todos"], { byId: { 1: { id: 1 } }, allIds: [1] });
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+queryClient.invalidateQueries({ queryKey: ["todos"] });
+```
+
+Query is not a normalized cache; invalidation is often safer than duplicating server state models.
+
+Source: TanStack/query:docs/framework/react/guides/query-invalidation.md
+
+### HIGH Broadcast on server
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+import { broadcastQueryClient } from "@tanstack/query-broadcast-client-experimental";
+
+export const queryClient = new QueryClient();
+broadcastQueryClient({ queryClient });
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+import { broadcastQueryClient } from "@tanstack/query-broadcast-client-experimental";
+
+export const queryClient = new QueryClient();
+if (typeof window !== "undefined") broadcastQueryClient({ queryClient });
+```
+
+BroadcastChannel is a browser primitive; server setup should not install it.
+
+Source: TanStack/query:docs/framework/react/plugins/broadcastQueryClient.md

package/scaffold/.agents/skills/tanstack-query/references/compositions/compose-query-with-tanstack-router-and-start.md

@@ -0,0 +1,248 @@
+---
+name: compositions/compose-query-with-tanstack-router-and-start
+description: >
+  Use this when combining TanStack Query with TanStack Router or TanStack Start:
+  router context QueryClient, createFileRoute loaders, ensureQueryData,
+  @tanstack/react-router-ssr-query, setupRouterSsrQueryIntegration, SSR hydration,
+  streaming, redirects, and Start server functions.
+type: composition
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - lifecycle/setup-query-client-and-providers
+  - core/design-query-keys-and-options
+  - lifecycle/prefetch-and-remove-request-waterfalls
+sources:
+  - TanStack/router:https://tanstack.com/router/latest/docs/integrations/query
+  - TanStack/router:https://tanstack.com/router/latest/docs/how-to/setup-ssr
+  - TanStack/start:https://tanstack.com/start/latest/docs/framework/react/overview
+  - TanStack/query:docs/framework/react/guides/prefetching.md
+  - TanStack/query:docs/framework/react/guides/ssr.md
+---
+
+## Setup
+
+```tsx
+import { QueryClient, QueryClientProvider, useSuspenseQuery } from "@tanstack/react-query";
+import { createFileRoute, createRouter, RouterProvider } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+
+const queryClient = new QueryClient();
+
+const postsQuery = {
+  queryKey: ["posts"],
+  queryFn: async () => [{ id: 1, title: "Router first" }],
+};
+
+export const Route = createFileRoute("/posts")({
+  loader: ({ context }) => context.queryClient.ensureQueryData(postsQuery),
+  component: PostsPage,
+});
+
+function PostsPage() {
+  const { data } = useSuspenseQuery(postsQuery);
+  return <pre>{JSON.stringify(data)}</pre>;
+}
+
+const router = createRouter({ routeTree, context: { queryClient } });
+
+export function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <RouterProvider router={router} />
+    </QueryClientProvider>
+  );
+}
+```
+
+## Core Integration Patterns
+
+### Put QueryClient in router context
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+import { createRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+
+const queryClient = new QueryClient();
+
+export const router = createRouter({
+  routeTree,
+  context: { queryClient },
+  defaultPreloadStaleTime: 0,
+});
+```
+
+Set `defaultPreloadStaleTime: 0` when Query owns server-state freshness. Router still preloads and runs loaders, but Query is the cache authority.
+
+### Use loader ensureQueryData for route data
+
+```ts
+import { createFileRoute } from "@tanstack/react-router";
+
+const todoQuery = (todoId: string) => ({
+  queryKey: ["todo", todoId],
+  queryFn: async () => ({ id: todoId, title: "Loaded" }),
+});
+
+export const Route = createFileRoute("/todos/$todoId")({
+  loader: ({ context, params }) => context.queryClient.ensureQueryData(todoQuery(params.todoId)),
+});
+```
+
+Treat loaders as event handlers that prime the Query cache. Components should still call `useQuery` or `useSuspenseQuery` so the route has an active Query observer.
+
+### Prefer Router SSR Query integration for Router SSR
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+import { createRouter } from "@tanstack/react-router";
+import { setupRouterSsrQueryIntegration } from "@tanstack/react-router-ssr-query";
+import { routeTree } from "./routeTree.gen";
+
+const queryClient = new QueryClient();
+const router = createRouter({ routeTree, context: { queryClient } });
+
+setupRouterSsrQueryIntegration({ router, queryClient });
+```
+
+## Common Mistakes
+
+### CRITICAL Component-only Query creates route waterfall
+
+Wrong:
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+export const Route = createFileRoute("/posts")({ component: PostsPage });
+function PostsPage() {
+  const { data } = useSuspenseQuery({
+    queryKey: ["posts"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return <pre>{JSON.stringify(data)}</pre>;
+}
+```
+
+Correct:
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+const postsQuery = { queryKey: ["posts"], queryFn: async () => [{ id: 1 }] };
+export const Route = createFileRoute("/posts")({
+  loader: ({ context }) => context.queryClient.ensureQueryData(postsQuery),
+  component: PostsPage,
+});
+function PostsPage() {
+  const { data } = useSuspenseQuery(postsQuery);
+  return <pre>{JSON.stringify(data)}</pre>;
+}
+```
+
+The router can load route-critical data before component render.
+
+Source: TanStack/router:https://tanstack.com/router/latest/docs/integrations/query
+
+### CRITICAL Hand-rolled Router hydration
+
+Wrong:
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createRouter, RouterProvider } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+
+const queryClient = new QueryClient();
+const router = createRouter({ routeTree });
+export function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <RouterProvider router={router} />
+    </QueryClientProvider>
+  );
+}
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+import { createRouter } from "@tanstack/react-router";
+import { setupRouterSsrQueryIntegration } from "@tanstack/react-router-ssr-query";
+import { routeTree } from "./routeTree.gen";
+
+const queryClient = new QueryClient();
+const router = createRouter({ routeTree, context: { queryClient } });
+setupRouterSsrQueryIntegration({ router, queryClient });
+```
+
+The Router SSR Query integration handles dehydration, hydration, streamed query results, redirects, and provider wrapping.
+
+Source: TanStack/router:https://tanstack.com/router/latest/docs/integrations/query
+
+### HIGH Next.js mental model copied into Start
+
+Wrong:
+
+```tsx
+export default async function Page() {
+  const posts = await Promise.resolve([{ id: 1 }]);
+  return <pre>{JSON.stringify(posts)}</pre>;
+}
+```
+
+Correct:
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/posts")({
+  loader: ({ context }) =>
+    context.queryClient.ensureQueryData({
+      queryKey: ["posts"],
+      queryFn: async () => [{ id: 1 }],
+    }),
+  component: () => <p>Posts loaded by the route</p>,
+});
+```
+
+Start is powered by TanStack Router; use file routes, loaders, server functions, and Router SSR before Next-specific app/pages APIs.
+
+Source: TanStack/start:https://tanstack.com/start/latest/docs/framework/react/overview
+
+### HIGH Reading loader data instead of observing Query
+
+Wrong:
+
+```tsx
+import { createFileRoute, useLoaderData } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/posts")({
+  loader: ({ context }) => context.queryClient.ensureQueryData(postsQuery),
+  component: PostsPage,
+});
+
+function PostsPage() {
+  const posts = useLoaderData({ from: "/posts" });
+  return <pre>{JSON.stringify(posts)}</pre>;
+}
+```
+
+Correct:
+
+```tsx
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+function PostsPage() {
+  const { data } = useSuspenseQuery(postsQuery);
+  return <pre>{JSON.stringify(data)}</pre>;
+}
+```
+
+The loader primes the cache. The component still needs an active Query observer for refetch triggers, invalidation, and garbage collection semantics.
+
+See also: `lifecycle/ssr-hydration-and-streaming` for framework SSR recipes.

package/scaffold/.agents/skills/tanstack-query/references/compositions/enforce-query-best-practices-with-eslint.md

@@ -0,0 +1,167 @@
+---
+name: compositions/enforce-query-best-practices-with-eslint
+description: >
+  Use this when configuring @tanstack/eslint-plugin-query, flat/recommended,
+  flat/recommended-strict, exhaustive-deps, no-rest-destructuring,
+  no-unstable-deps, no-void-query-fn, stable-query-client, prefer-query-options,
+  infinite-query-property-order, and mutation-property-order.
+type: composition
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/design-query-keys-and-options
+  - core/fetch-and-observe-queries
+  - framework/shape-data-and-render-efficiently
+sources:
+  - TanStack/query:docs/eslint/eslint-plugin-query.md
+  - TanStack/query:docs/eslint/exhaustive-deps.md
+  - TanStack/query:docs/eslint/no-rest-destructuring.md
+  - TanStack/query:docs/eslint/no-unstable-deps.md
+  - TanStack/query:docs/eslint/no-void-query-fn.md
+  - TanStack/query:docs/eslint/prefer-query-options.md
+  - TanStack/query:docs/eslint/stable-query-client.md
+  - TanStack/query:docs/eslint/infinite-query-property-order.md
+  - TanStack/query:docs/eslint/mutation-property-order.md
+---
+
+## Setup
+
+```js
+import pluginQuery from "@tanstack/eslint-plugin-query";
+
+export default [...pluginQuery.configs["flat/recommended"]];
+```
+
+## Core Integration Patterns
+
+### Use strict when generating Query-heavy code
+
+```js
+import pluginQuery from "@tanstack/eslint-plugin-query";
+
+export default [...pluginQuery.configs["flat/recommended-strict"]];
+```
+
+### Prefer option factories
+
+```ts
+import { queryOptions, useQuery } from "@tanstack/react-query";
+
+const todosOptions = queryOptions({
+  queryKey: ["todos"],
+  queryFn: async () => [{ id: 1 }],
+});
+
+export function useTodos() {
+  return useQuery(todosOptions);
+}
+```
+
+### Keep inference-sensitive property order
+
+```ts
+import { useInfiniteQuery } from "@tanstack/react-query";
+
+export function useFeed() {
+  return useInfiniteQuery({
+    queryKey: ["feed"],
+    queryFn: async ({ pageParam }) => ({ nextCursor: pageParam + 1 }),
+    initialPageParam: 0,
+    getNextPageParam: (page) => page.nextCursor,
+  });
+}
+```
+
+## Common Mistakes
+
+### MEDIUM Strict rule not enabled
+
+Wrong:
+
+```js
+import pluginQuery from "@tanstack/eslint-plugin-query";
+
+export default [...pluginQuery.configs["flat/recommended"]];
+```
+
+Correct:
+
+```js
+import pluginQuery from "@tanstack/eslint-plugin-query";
+
+export default [...pluginQuery.configs["flat/recommended-strict"]];
+```
+
+Strict mode catches option-factory and inference patterns that agents commonly miss.
+
+Source: TanStack/query:docs/eslint/eslint-plugin-query.md
+
+### MEDIUM Infinite option property order
+
+Wrong:
+
+```ts
+import { useInfiniteQuery } from "@tanstack/react-query";
+
+export function useFeed() {
+  return useInfiniteQuery({
+    queryFn: async () => ({ nextCursor: 1 }),
+    queryKey: ["feed"],
+    getNextPageParam: (page) => page.nextCursor,
+    initialPageParam: 0,
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useInfiniteQuery } from "@tanstack/react-query";
+
+export function useFeed() {
+  return useInfiniteQuery({
+    queryKey: ["feed"],
+    queryFn: async ({ pageParam }) => ({ nextCursor: pageParam + 1 }),
+    initialPageParam: 0,
+    getNextPageParam: (page) => page.nextCursor,
+  });
+}
+```
+
+Some infinite-query inference depends on stable option ordering.
+
+Source: TanStack/query:docs/eslint/infinite-query-property-order.md
+
+### MEDIUM Mutation option property order
+
+Wrong:
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+
+export function useSave() {
+  return useMutation({
+    onSuccess: () => console.log("saved"),
+    mutationFn: async (title: string) => title,
+  });
+}
+```
+
+Correct:
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+
+export function useSave() {
+  return useMutation({
+    mutationFn: async (title: string) => title,
+    onSuccess: () => console.log("saved"),
+  });
+}
+```
+
+The mutation property order rule preserves inference for mutation options.
+
+Source: TanStack/query:docs/eslint/mutation-property-order.md
+
+See also: `core/design-query-keys-and-options` for the patterns these rules protect.