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

package/scaffold/.agents/skills/tanstack-query/references/lifecycle/ssr-hydration-and-streaming.md

@@ -0,0 +1,209 @@
+---
+name: lifecycle/ssr-hydration-and-streaming
+description: >
+  Use this when implementing SSR, hydration, dehydrate, hydrate,
+  HydrationBoundary, TanStack Start, TanStack Router SSR Query, Next.js app
+  router, Next.js pages router, React Server Components, SvelteKit, Nuxt,
+  SolidStart, Lit SSR, ReactQueryStreamedHydration, or streamedQuery.
+type: lifecycle
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - lifecycle/setup-query-client-and-providers
+  - lifecycle/prefetch-and-remove-request-waterfalls
+sources:
+  - TanStack/query:docs/framework/react/guides/ssr.md
+  - TanStack/query:docs/framework/react/guides/advanced-ssr.md
+  - TanStack/query:docs/framework/react/reference/hydration.md
+  - TanStack/query:docs/reference/environmentManager.md
+  - TanStack/query:docs/reference/streamedQuery.md
+  - TanStack/query:docs/framework/vue/guides/ssr.md
+  - TanStack/query:docs/framework/svelte/ssr.md
+  - TanStack/query:docs/framework/solid/guides/ssr.md
+  - TanStack/query:docs/framework/lit/guides/ssr.md
+---
+
+## Setup
+
+```tsx
+import { HydrationBoundary, QueryClient, dehydrate } from "@tanstack/react-query";
+
+export async function PostsPage() {
+  const queryClient = new QueryClient();
+  await queryClient.prefetchQuery({
+    queryKey: ["posts"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <Posts />
+    </HydrationBoundary>
+  );
+}
+
+function Posts() {
+  return <p>Hydrated posts render here</p>;
+}
+```
+
+## Core Patterns
+
+### Put TanStack Start and Router first
+
+```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 });
+```
+
+### Use per-request clients
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export function createSsrQueryClient() {
+  return new QueryClient({
+    defaultOptions: { queries: { staleTime: 60_000 } },
+  });
+}
+```
+
+### Hydrate only prefetched data
+
+```tsx
+import { HydrationBoundary, QueryClient, dehydrate } from "@tanstack/react-query";
+
+export async function Page() {
+  const queryClient = new QueryClient();
+  await queryClient.prefetchQuery({
+    queryKey: ["profile"],
+    queryFn: async () => ({ name: "Tanner" }),
+  });
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <main>Profile</main>
+    </HydrationBoundary>
+  );
+}
+```
+
+## Common Mistakes
+
+### CRITICAL RSC renders fetched data twice
+
+Wrong:
+
+```tsx
+import { HydrationBoundary, QueryClient, dehydrate } from "@tanstack/react-query";
+
+export async function Page() {
+  const queryClient = new QueryClient();
+  const posts = await queryClient.fetchQuery({
+    queryKey: ["posts"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return (
+    <>
+      <p>{posts.length}</p>
+      <HydrationBoundary state={dehydrate(queryClient)}>
+        <main>Posts</main>
+      </HydrationBoundary>
+    </>
+  );
+}
+```
+
+Correct:
+
+```tsx
+import { HydrationBoundary, QueryClient, dehydrate } from "@tanstack/react-query";
+
+export async function Page() {
+  const queryClient = new QueryClient();
+  await queryClient.prefetchQuery({
+    queryKey: ["posts"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <main>Posts</main>
+    </HydrationBoundary>
+  );
+}
+```
+
+Server-rendered derived data can desynchronize from client-refetched Query data.
+
+Source: TanStack/query:docs/framework/react/guides/advanced-ssr.md
+
+### CRITICAL Suspense query not prefetched on server
+
+Wrong:
+
+```tsx
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+export function Posts() {
+  const { data } = useSuspenseQuery({
+    queryKey: ["posts"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return <pre>{JSON.stringify(data)}</pre>;
+}
+```
+
+Correct:
+
+```tsx
+import { HydrationBoundary, QueryClient, dehydrate } from "@tanstack/react-query";
+
+export async function Page() {
+  const queryClient = new QueryClient();
+  await queryClient.prefetchQuery({
+    queryKey: ["posts"],
+    queryFn: async () => [{ id: 1 }],
+  });
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <main>Posts</main>
+    </HydrationBoundary>
+  );
+}
+```
+
+A suspense query that is not prefetched can fetch on the server, fail to hydrate, then fetch again on the client.
+
+Source: TanStack/query:docs/framework/react/guides/ssr.md
+
+### HIGH SvelteKit query runs after SSR response
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/svelte-query";
+
+export const queryClient = new QueryClient();
+```
+
+Correct:
+
+```ts
+import { browser } from "$app/environment";
+import { QueryClient } from "@tanstack/svelte-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: { queries: { enabled: browser } },
+});
+```
+
+SvelteKit SSR needs browser-gated default query execution unless server data is explicitly prefetched.
+
+Source: TanStack/query:docs/framework/svelte/ssr.md
+
+See also: `compositions/compose-query-with-tanstack-router-and-start` for TanStack-owned SSR routing.

package/scaffold/.agents/skills/tanstack-query/references/lifecycle/test-query-code.md

@@ -0,0 +1,160 @@
+---
+name: lifecycle/test-query-code
+description: >
+  Use this when testing TanStack Query code with isolated QueryClient instances,
+  test providers, retry false, cache cleanup, async assertions, hook testing,
+  React/Vue/Solid/Angular harnesses, and deterministic query state.
+type: lifecycle
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - lifecycle/setup-query-client-and-providers
+  - core/tune-defaults-freshness-retries-and-refetching
+sources:
+  - TanStack/query:docs/framework/react/guides/testing.md
+  - TanStack/query:docs/framework/solid/guides/testing.md
+  - TanStack/query:docs/framework/vue/guides/testing.md
+  - TanStack/query:docs/framework/angular/guides/testing.md
+  - TanStack/query:packages/query-core/src/__tests__/queryClient.test.tsx
+  - TanStack/query:packages/react-query/src/__tests__/useQuery.test.tsx
+---
+
+## Setup
+
+```tsx
+import * as React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+export function createTestWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+
+  return function TestWrapper(props: { children: React.ReactNode }) {
+    return <QueryClientProvider client={queryClient}>{props.children}</QueryClientProvider>;
+  };
+}
+```
+
+## Core Patterns
+
+### Create a client per test
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export function createTestQueryClient() {
+  return new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+}
+```
+
+### Await async state
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export async function loadTodosForTest() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return queryClient.fetchQuery({
+    queryKey: ["todos"],
+    queryFn: async () => [{ id: 1 }],
+  });
+}
+```
+
+### Clear after direct client tests
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export function dispose(queryClient: QueryClient) {
+  queryClient.clear();
+}
+```
+
+## Common Mistakes
+
+### CRITICAL Shared test client
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient();
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+export function createQueryClient() {
+  return new QueryClient({ defaultOptions: { queries: { retry: false } } });
+}
+```
+
+A shared client leaks cache and mutation state across tests.
+
+Source: TanStack/query:docs/framework/react/guides/testing.md
+
+### HIGH Retry backoff in tests
+
+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 delay failure and make tests look hung.
+
+Source: TanStack/query:docs/framework/react/guides/testing.md
+
+### HIGH Asserting before async success
+
+Wrong:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+const promise = queryClient.fetchQuery({
+  queryKey: ["todos"],
+  queryFn: async () => [{ id: 1 }],
+});
+console.log(queryClient.getQueryData(["todos"]));
+await promise;
+```
+
+Correct:
+
+```ts
+import { QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+await queryClient.fetchQuery({
+  queryKey: ["todos"],
+  queryFn: async () => [{ id: 1 }],
+});
+console.log(queryClient.getQueryData(["todos"]));
+```
+
+Query state is asynchronous; assert after the query promise resolves or the UI wait completes.
+
+Source: TanStack/query:docs/framework/react/guides/testing.md

package/scaffold/.agents/skills/tanstack-router/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: tanstack-router
+description: Build, review, debug, or test React applications with TanStack Router. Use for route trees, file routes, navigation, search parameters, loaders, guards, SSR, code splitting, and Query integration.
+license: MIT
+---
+
+# TanStack Router
+
+TanStack Router is a type-safe router for React and Solid applications. It provides SWR caching, JSON-first search parameters, file routes, and end-to-end type inference.
+
+The router is client-first and isomorphic. Loaders run on the client by default and also run on the server with TanStack Start.
+
+## Critical Rules
+
+- Preserve inferred Router types. Do not cast or annotate inferred route values.
+- Do not treat loaders as server-only code.
+- Change a file route through its file. Do not edit its generated route path.
+- Regenerate `routeTree.gen.ts` after route file changes.
+- Run type tests and a production build after route structure changes.
+
+## Use
+
+1. Inspect the installed Router version and framework binding.
+2. Select one primary reference from the domain index.
+3. Read another reference only when a listed tension or cross-reference applies.
+4. Read the React binding reference when the task uses React hooks or components.
+5. Validate generated route files, types, tests, and the production build.
+
+## Domain Index
+
+### Defining routes
+
+- [Set up Router Core](references/router-core/index.md)
+- [Configure route generation](references/router-plugin.md)
+- [Define virtual file routes](references/virtual-file-routes.md)
+- [Use the React binding](references/react-router.md)
+
+### Navigating
+
+- [Use links, navigation, preloading, and blocking](references/router-core/navigation.md)
+
+### Managing URL state
+
+- [Validate and transform search parameters](references/router-core/search-params.md)
+- [Use path parameters, splats, and optional parameters](references/router-core/path-params.md)
+
+### Loading data
+
+- [Use route loaders, cache settings, context, and deferred data](references/router-core/data-loading.md)
+- [Coordinate Router with TanStack Query](references/compositions/router-query.md)
+
+### Protecting routes
+
+- [Use authentication and route guards](references/router-core/auth-and-guards.md)
+
+### Rendering and layout
+
+- [Split route code](references/router-core/code-splitting.md)
+- [Handle missing routes, errors, and route masks](references/router-core/not-found-and-errors.md)
+
+### Type safety
+
+- [Preserve inference and narrow route types](references/router-core/type-safety.md)
+
+### Server rendering
+
+- [Use SSR, hydration, streaming, and head management](references/router-core/ssr.md)
+
+## Failure Mode Inventory
+
+| Area                                                                        | Check for                                                             |
+| --------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [Route setup](references/router-core/index.md)                              | Missing Router type registration                                      |
+| [Route setup](references/router-core/index.md)                              | An uncommitted `routeTree.gen.ts` file                                |
+| [Route setup](references/router-core/index.md)                              | Route properties in an order that breaks inference                    |
+| [Route generation](references/router-plugin.md)                             | A Router plugin placed after the framework plugin                     |
+| [Route setup](references/router-core/index.md)                              | Incorrect `getParentRoute` use in code routes                         |
+| [Navigation](references/router-core/navigation.md)                          | Path parameters interpolated into the `to` string                     |
+| [Navigation](references/router-core/navigation.md)                          | `useNavigate` used for a clickable element instead of `Link`          |
+| [Navigation](references/router-core/navigation.md)                          | Relative navigation without `from`                                    |
+| [Navigation](references/router-core/navigation.md)                          | A search object that replaces parameters instead of a search function |
+| [Search parameters](references/router-core/search-params.md)                | Zod `.catch()` used instead of the adapter `fallback()`               |
+| [Search parameters](references/router-core/search-params.md)                | The full search object returned from `loaderDeps`                     |
+| [Search parameters](references/router-core/search-params.md)                | `Date` objects passed as search parameters                            |
+| [Search parameters](references/router-core/search-params.md)                | A parent route without `validateSearch` when inheritance is required  |
+| [Path parameters](references/router-core/path-params.md)                    | Path parameters interpolated into the `to` string                     |
+| [Path parameters](references/router-core/path-params.md)                    | `*` used for a splat route instead of `$`                             |
+| [Path parameters](references/router-core/path-params.md)                    | Curly braces used for a basic dynamic segment                         |
+| [Data loading](references/router-core/data-loading.md)                      | A loader treated as server-only code                                  |
+| [Data loading](references/router-core/data-loading.md)                      | The default `staleTime` of zero ignored                               |
+| [Data loading](references/router-core/data-loading.md)                      | `reset()` used instead of `router.invalidate()` in an error component |
+| [Data loading](references/router-core/data-loading.md)                      | Missing factory parentheses on `createRootRouteWithContext`           |
+| [Data loading](references/router-core/data-loading.md)                      | React hooks used in `beforeLoad` or `loader`                          |
+| [Router and Query](references/compositions/router-query.md)                 | A missing `defaultPreloadStaleTime: 0` setting                        |
+| [Router and Query](references/compositions/router-query.md)                 | A module-level `QueryClient` used during SSR                          |
+| [Router and Query](references/compositions/router-query.md)                 | An awaited `prefetchQuery` that blocks rendering                      |
+| [Authentication](references/router-core/auth-and-guards.md)                 | An authentication check in a component instead of `beforeLoad`        |
+| [Authentication](references/router-core/auth-and-guards.md)                 | A redirect caught without rethrow                                     |
+| [Authentication](references/router-core/auth-and-guards.md)                 | Conditional rendering of the root route component                     |
+| [Code splitting](references/router-core/code-splitting.md)                  | Exported route property functions that prevent code splitting         |
+| [Code splitting](references/router-core/code-splitting.md)                  | An attempt to split the root route                                    |
+| [Code splitting](references/router-core/code-splitting.md)                  | A split loader that adds a second asynchronous step                   |
+| [Code splitting](references/router-core/code-splitting.md)                  | A `Route` import in a split file instead of `getRouteApi`             |
+| [Missing routes and errors](references/router-core/not-found-and-errors.md) | The deprecated `NotFoundRoute` API                                    |
+| [Missing routes and errors](references/router-core/not-found-and-errors.md) | `useLoaderData` expected to work in `notFoundComponent`               |
+| [Missing routes and errors](references/router-core/not-found-and-errors.md) | A leaf route expected to handle a missing route                       |
+| [Route masking](references/router-core/not-found-and-errors.md)             | A masked URL expected to remain after sharing                         |
+| [Type safety](references/router-core/type-safety.md)                        | Type annotations or casts on inferred values                          |
+| [Type safety](references/router-core/type-safety.md)                        | An unnarrowed `LinkProps` type                                        |
+| [Type safety](references/router-core/type-safety.md)                        | A `Link` or `useNavigate` call without `from` narrowing               |
+| [SSR](references/router-core/ssr.md)                                        | Browser APIs in loaders without an environment check                  |
+| [SSR](references/router-core/ssr.md)                                        | Hash fragments used for server-rendered content                       |
+| [SSR](references/router-core/ssr.md)                                        | Next.js or Remix SSR patterns used with TanStack Router               |
+
+## Tensions
+
+| Tension                                   | Read together                                                                                                       | Apply                                                                                           |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Type safety and fast prototyping          | [Router Core](references/router-core/index.md), [type safety](references/router-core/type-safety.md)                | Add the `Register` declaration and fix the inferred type. Do not silence the error with a cast. |
+| Client-first loaders and SSR expectations | [Data loading](references/router-core/data-loading.md), [SSR](references/router-core/ssr.md)                        | Keep loader code safe in each environment where it runs.                                        |
+| Router cache and Query cache              | [Data loading](references/router-core/data-loading.md), [Router and Query](references/compositions/router-query.md) | Give data ownership to one cache and prevent duplicate fetches.                                 |
+| Split size and loader performance         | [Code splitting](references/router-core/code-splitting.md), [data loading](references/router-core/data-loading.md)  | Keep critical loader work out of avoidable split steps.                                         |
+
+## Cross-References
+
+- Read [type safety](references/router-core/type-safety.md) with [Router Core](references/router-core/index.md). Type registration and route property order control inference.
+- Read [search parameters](references/router-core/search-params.md) with [navigation](references/router-core/navigation.md). The `search` property uses validated search state.
+- Read [search parameters](references/router-core/search-params.md) with [data loading](references/router-core/data-loading.md). `loaderDeps` uses validated search state as cache keys.
+- Read [data loading](references/router-core/data-loading.md) before [Router and Query](references/compositions/router-query.md). The built-in cache affects external cache coordination.
+- Read [data loading](references/router-core/data-loading.md) with [authentication](references/router-core/auth-and-guards.md). `beforeLoad` supplies route context before the loader runs.
+- Read [data loading](references/router-core/data-loading.md) with [code splitting](references/router-core/code-splitting.md). Loader splitting changes request latency.
+- Read [data loading](references/router-core/data-loading.md) with [SSR](references/router-core/ssr.md). SSR changes the loader execution environment.
+- Read [Router and Query](references/compositions/router-query.md) with [SSR](references/router-core/ssr.md). SSR requires per-request cache isolation and hydration.
+- Read [data loading](references/router-core/data-loading.md) with [missing routes and errors](references/router-core/not-found-and-errors.md). Loader errors select route error boundaries.