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

package/scaffold/.agents/skills/react-best-practices/rules/rerender-transitions.md

@@ -0,0 +1,40 @@
+---
+title: Use Transitions for Non-Urgent Updates
+impact: MEDIUM
+impactDescription: maintains UI responsiveness
+tags: rerender, transitions, startTransition, performance
+---
+
+## Use Transitions for Non-Urgent Updates
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect (blocks UI on every scroll):**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0);
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY);
+    window.addEventListener("scroll", handler, { passive: true });
+    return () => window.removeEventListener("scroll", handler);
+  }, []);
+}
+```
+
+**Correct (non-blocking updates):**
+
+```tsx
+import { startTransition } from "react";
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0);
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY));
+    };
+    window.addEventListener("scroll", handler, { passive: true });
+    return () => window.removeEventListener("scroll", handler);
+  }, []);
+}
+```

package/scaffold/.agents/skills/react-best-practices/rules/rerender-use-deferred-value.md

@@ -0,0 +1,59 @@
+---
+title: Use useDeferredValue for Expensive Derived Renders
+impact: MEDIUM
+impactDescription: keeps input responsive during heavy computation
+tags: rerender, useDeferredValue, optimization, concurrent
+---
+
+## Use useDeferredValue for Expensive Derived Renders
+
+When user input triggers expensive computations or renders, use `useDeferredValue` to keep the input responsive. The deferred value lags behind, allowing React to prioritize the input update and render the expensive result when idle.
+
+**Incorrect (input feels laggy while filtering):**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState("");
+  const filtered = items.filter((item) => fuzzyMatch(item, query));
+
+  return (
+    <>
+      <input value={query} onChange={(e) => setQuery(e.target.value)} />
+      <ResultsList results={filtered} />
+    </>
+  );
+}
+```
+
+**Correct (input stays snappy, results render when ready):**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState("");
+  const deferredQuery = useDeferredValue(query);
+  const filtered = useMemo(
+    () => items.filter((item) => fuzzyMatch(item, deferredQuery)),
+    [items, deferredQuery],
+  );
+  const isStale = query !== deferredQuery;
+
+  return (
+    <>
+      <input value={query} onChange={(e) => setQuery(e.target.value)} />
+      <div style={{ opacity: isStale ? 0.7 : 1 }}>
+        <ResultsList results={filtered} />
+      </div>
+    </>
+  );
+}
+```
+
+**When to use:**
+
+- Filtering/searching large lists
+- Expensive visualizations (charts, graphs) reacting to input
+- Any derived state that causes noticeable render delays
+
+**Note:** Wrap the expensive computation in `useMemo` with the deferred value as a dependency, otherwise it still runs on every render.
+
+Reference: [React useDeferredValue](https://react.dev/reference/react/useDeferredValue)

package/scaffold/.agents/skills/react-best-practices/rules/rerender-use-ref-transient-values.md

@@ -0,0 +1,73 @@
+---
+title: Use useRef for Transient Values
+impact: MEDIUM
+impactDescription: avoids unnecessary re-renders on frequent updates
+tags: rerender, useref, state, performance
+---
+
+## Use useRef for Transient Values
+
+When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.
+
+**Incorrect (renders every update):**
+
+```tsx
+function Tracker() {
+  const [lastX, setLastX] = useState(0);
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => setLastX(e.clientX);
+    window.addEventListener("mousemove", onMove);
+    return () => window.removeEventListener("mousemove", onMove);
+  }, []);
+
+  return (
+    <div
+      style={{
+        position: "fixed",
+        top: 0,
+        left: lastX,
+        width: 8,
+        height: 8,
+        background: "black",
+      }}
+    />
+  );
+}
+```
+
+**Correct (no re-render for tracking):**
+
+```tsx
+function Tracker() {
+  const lastXRef = useRef(0);
+  const dotRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      lastXRef.current = e.clientX;
+      const node = dotRef.current;
+      if (node) {
+        node.style.transform = `translateX(${e.clientX}px)`;
+      }
+    };
+    window.addEventListener("mousemove", onMove);
+    return () => window.removeEventListener("mousemove", onMove);
+  }, []);
+
+  return (
+    <div
+      ref={dotRef}
+      style={{
+        position: "fixed",
+        top: 0,
+        left: 0,
+        width: 8,
+        height: 8,
+        background: "black",
+        transform: "translateX(0px)",
+      }}
+    />
+  );
+}
+```

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

@@ -0,0 +1,136 @@
+---
+name: tanstack-query
+description: Build, review, debug, test, or migrate TanStack Query code. Use for server state, query keys, mutations, cache behavior, pagination, hydration, persistence, and framework adapters.
+license: MIT
+---
+
+# TanStack Query
+
+TanStack Query manages server state through a framework-neutral cache, observers, adapters, persistence tools, devtools, lint rules, and migration tools.
+
+TanStack Start and TanStack Router are primary composition targets. Use them for loaders, SSR hydration, streaming, and cache handoff.
+
+## Use
+
+1. Inspect the installed TanStack Query version and framework adapter.
+2. Select one primary reference from the domain index.
+3. Read another reference only when a listed tension or cross-reference applies.
+4. Preserve types from query options, mutation options, and library APIs.
+5. Run the relevant tests, type check, and lint checks after a change.
+
+## Domain Index
+
+### Bootstrapping query clients
+
+- [Set up QueryClient and providers](references/lifecycle/setup-query-client-and-providers.md)
+
+### Reading server state
+
+- [Design query keys and reusable options](references/core/design-query-keys-and-options.md)
+- [Build Query abstractions](references/core/build-query-abstractions.md)
+- [Understand Query internals and observers](references/core/understand-query-internals-and-observers.md)
+- [Fetch and observe queries](references/core/fetch-and-observe-queries.md)
+- [Handle status checks and errors](references/framework/handle-status-and-errors.md)
+
+### Coordinating query execution
+
+- [Tune defaults, freshness, retries, and refetching](references/core/tune-defaults-freshness-retries-and-refetching.md)
+- [Coordinate dependent, parallel, disabled, and background queries](references/core/coordinate-query-execution.md)
+- [Paginate and build infinite queries](references/core/paginate-and-build-infinite-queries.md)
+
+### Writing server state
+
+- [Write mutations and invalidate related queries](references/core/write-mutations-and-invalidate-related-queries.md)
+- [Apply automatic invalidation after mutations](references/compositions/automatic-invalidation-after-mutations.md)
+- [Implement optimistic updates and cache writes](references/core/implement-optimistic-updates-and-cache-writes.md)
+- [Handle concurrent optimistic updates](references/core/concurrent-optimistic-updates.md)
+- [Use Query data in forms](references/compositions/query-data-and-forms.md)
+- [Cancel queries and consume AbortSignals](references/core/cancel-queries-and-consume-abort-signals.md)
+
+### Shaping cache and render behavior
+
+- [Seed, use placeholder data, select, and transform data](references/core/seed-placeholder-select-and-transform-data.md)
+- [Use selectors and derived state](references/core/selectors-and-derived-state.md)
+- [Shape data and render efficiently](references/framework/shape-data-and-render-efficiently.md)
+
+### Rendering across environments
+
+- [Prefetch and remove request waterfalls](references/lifecycle/prefetch-and-remove-request-waterfalls.md)
+- [Compose Query with TanStack Router and Start](references/compositions/compose-query-with-tanstack-router-and-start.md)
+- [Use SSR, hydration, and streaming](references/lifecycle/ssr-hydration-and-streaming.md)
+- [Use Suspense and error boundaries](references/framework/use-suspense-and-error-boundaries.md)
+
+### Persisting and synchronizing caches
+
+- [Persist offline and restore caches](references/compositions/persist-offline-and-restore-caches.md)
+- [Use broadcast, realtime, and multi-tab synchronization](references/compositions/broadcast-realtime-and-multi-tab-synchronization.md)
+
+### Framework adapter idioms
+
+- [Use framework adapter reactivity](references/framework/use-framework-adapter-reactivity.md)
+
+### Operational quality
+
+- [Debug with devtools](references/framework/debug-with-devtools.md)
+- [Test Query code](references/lifecycle/test-query-code.md)
+- [Migrate major versions and codemods](references/lifecycle/migrate-major-versions-and-codemods.md)
+- [Enforce Query best practices with ESLint](references/compositions/enforce-query-best-practices-with-eslint.md)
+
+## Failure Mode Inventory
+
+| Reference                                                                                             | Check for                                                                                                       |
+| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| [QueryClient setup](references/lifecycle/setup-query-client-and-providers.md)                         | A new client on each render; a shared SSR cache between users; an ambiguous Lit fallback client                 |
+| [Query keys and options](references/core/design-query-keys-and-options.md)                            | Missing variables in a query key; key and query function drift; skipToken in a Suspense query                   |
+| [Query abstractions](references/core/build-query-abstractions.md)                                     | A custom hook as the only abstraction; wide options wrappers; hidden Query result state                         |
+| [Query internals](references/core/understand-query-internals-and-observers.md)                        | Cache presence treated as active use; ignored observer options; inactive queries expected to refetch            |
+| [Fetch and observe](references/core/fetch-and-observe-queries.md)                                     | A void query function; pending-only offline checks; queries used for writes                                     |
+| [Status and errors](references/framework/handle-status-and-errors.md)                                 | Hidden stale data on a background error; validation errors sent to a global boundary; duplicate observer toasts |
+| [Defaults and freshness](references/core/tune-defaults-freshness-retries-and-refetching.md)           | gcTime used as freshness; static staleTime blocking invalidation; test delays from retries                      |
+| [Query coordination](references/core/coordinate-query-execution.md)                                   | Imperative disabled queries; duplicate useQueries keys; full-page spinners during background refetch            |
+| [Pagination](references/core/paginate-and-build-infinite-queries.md)                                  | A missing initialPageParam; overlapping infinite fetches; an invalid pages and pageParams shape                 |
+| [Mutations and invalidation](references/core/write-mutations-and-invalidate-related-queries.md)       | Multiple mutate arguments; per-call callbacks after unmount; invalidation that is not awaited                   |
+| [Automatic invalidation](references/compositions/automatic-invalidation-after-mutations.md)           | Full-app invalidation for each mutation; an unreturned invalidation promise; refetches for static data          |
+| [Optimistic updates](references/core/implement-optimistic-updates-and-cache-writes.md)                | A write without cancellation; an in-place mutation; a persisted optimistic write that is lost                   |
+| [Concurrent optimistic updates](references/core/concurrent-optimistic-updates.md)                     | One invalidation that reverts another write; filter mismatch; unstable pending row keys                         |
+| [Query data and forms](references/compositions/query-data-and-forms.md)                               | Form defaults before query data; a refetch that overwrites dirty state; duplicate submission                    |
+| [Cancellation](references/core/cancel-queries-and-consume-abort-signals.md)                           | An ignored AbortSignal; an assumption that unmount cancels work; expected Suspense cancellation                 |
+| [Seed and transform data](references/core/seed-placeholder-select-and-transform-data.md)              | An initialData overwrite assumption; the removed keepPreviousData option; errors thrown in select               |
+| [Selectors](references/core/selectors-and-derived-state.md)                                           | Effect-based state sync; an inline expensive selector; errors thrown in select                                  |
+| [Render efficiency](references/framework/shape-data-and-render-efficiently.md)                        | Rest destructuring; a query result object in hook dependencies; Vue v-model on immutable data                   |
+| [Prefetch](references/lifecycle/prefetch-and-remove-request-waterfalls.md)                            | prefetchQuery expected to return data; staleTime only on prefetch; Suspense prefetch in an effect               |
+| [Router and Start](references/compositions/compose-query-with-tanstack-router-and-start.md)           | Component-only route waterfalls; custom Router hydration; copied Next.js assumptions                            |
+| [SSR and streaming](references/lifecycle/ssr-hydration-and-streaming.md)                              | RSC rendering fetched data twice; an unprefetched Suspense query; a late SvelteKit query                        |
+| [Suspense](references/framework/use-suspense-and-error-boundaries.md)                                 | A disabled Suspense query; a missing reset boundary; query.promise without its feature flag                     |
+| [Persistence](references/compositions/persist-offline-and-restore-caches.md)                          | gcTime below maxAge; rendering before restore; a missing default mutation function                              |
+| [Broadcast and realtime](references/compositions/broadcast-realtime-and-multi-tab-synchronization.md) | Uncontrolled experimental broadcast; over-normalized writes; server-side broadcast                              |
+| [Adapter reactivity](references/framework/use-framework-adapter-reactivity.md)                        | An unwrapped Vue ref; Svelte store syntax in v6; a directly returned Angular Observable                         |
+| [Devtools](references/framework/debug-with-devtools.md)                                               | Eager production devtools; offline simulation treated as network control; devtools outside the provider         |
+| [Tests](references/lifecycle/test-query-code.md)                                                      | A shared test client; retry backoff in tests; assertions before asynchronous success                            |
+| [Migration](references/lifecycle/migrate-major-versions-and-codemods.md)                              | v4 overload syntax; removed query callbacks; cacheTime in v5                                                    |
+| [ESLint](references/compositions/enforce-query-best-practices-with-eslint.md)                         | A missing strict rule; invalid infinite option order; invalid mutation option order                             |
+
+## Tensions
+
+| Tension                                        | Read together                                                                                                                                                                                                                                                                                                                   | Apply                                                                                    |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Declarative cache and imperative fetch control | [Query coordination](references/core/coordinate-query-execution.md), [fetch and observe](references/core/fetch-and-observe-queries.md)                                                                                                                                                                                          | Prefer query keys and enabled state to manual refetch flows.                             |
+| SSR freshness and user data isolation          | [QueryClient setup](references/lifecycle/setup-query-client-and-providers.md), [Router and Start](references/compositions/compose-query-with-tanstack-router-and-start.md), [SSR](references/lifecycle/ssr-hydration-and-streaming.md), [freshness](references/core/tune-defaults-freshness-retries-and-refetching.md)          | Isolate server caches and prevent duplicate hydration fetches.                           |
+| Router loading and component queries           | [Prefetch](references/lifecycle/prefetch-and-remove-request-waterfalls.md), [Router and Start](references/compositions/compose-query-with-tanstack-router-and-start.md), [Query internals](references/core/understand-query-internals-and-observers.md)                                                                         | Prefetch in loaders and keep Query as the server-state owner.                            |
+| Optimistic response and server truth           | [Optimistic updates](references/core/implement-optimistic-updates-and-cache-writes.md), [concurrent updates](references/core/concurrent-optimistic-updates.md), [invalidation](references/core/write-mutations-and-invalidate-related-queries.md), [persistence](references/compositions/persist-offline-and-restore-caches.md) | Include cancellation, rollback, invalidation, concurrency guards, and persistence rules. |
+| Reuse and type preservation                    | [Query keys](references/core/design-query-keys-and-options.md), [abstractions](references/core/build-query-abstractions.md), [selectors](references/core/selectors-and-derived-state.md)                                                                                                                                        | Prefer option factories that preserve selection inference and work in loaders.           |
+| Automatic invalidation and scoped freshness    | [Automatic invalidation](references/compositions/automatic-invalidation-after-mutations.md), [mutations](references/core/write-mutations-and-invalidate-related-queries.md), [freshness](references/core/tune-defaults-freshness-retries-and-refetching.md)                                                                     | Scope invalidation with mutation keys, metadata, and static-data exclusions.             |
+| Form ownership and server freshness            | [Forms](references/compositions/query-data-and-forms.md), [selectors](references/core/selectors-and-derived-state.md), [mutations](references/core/write-mutations-and-invalidate-related-queries.md)                                                                                                                           | Keep dirty fields while useful server updates continue.                                  |
+| Framework idioms and React examples            | [Adapter reactivity](references/framework/use-framework-adapter-reactivity.md), [query keys](references/core/design-query-keys-and-options.md), [SSR](references/lifecycle/ssr-hydration-and-streaming.md)                                                                                                                      | Preserve the selected adapter's reactivity model.                                        |
+
+## Cross-References
+
+- Read [SSR, hydration, and streaming](references/lifecycle/ssr-hydration-and-streaming.md) with [QueryClient setup](references/lifecycle/setup-query-client-and-providers.md). Client lifetime differs between browsers and servers.
+- Read [ESLint](references/compositions/enforce-query-best-practices-with-eslint.md) with [query keys and options](references/core/design-query-keys-and-options.md). The rules detect key and option errors.
+- Read [Query abstractions](references/core/build-query-abstractions.md) with [query keys and options](references/core/design-query-keys-and-options.md). Option factories join reusable keys and query functions.
+- Read [status and errors](references/framework/handle-status-and-errors.md), [Query internals](references/core/understand-query-internals-and-observers.md), and [defaults](references/core/tune-defaults-freshness-retries-and-refetching.md) with [fetch and observe](references/core/fetch-and-observe-queries.md).
+- Read [optimistic updates](references/core/implement-optimistic-updates-and-cache-writes.md), [automatic invalidation](references/compositions/automatic-invalidation-after-mutations.md), and [concurrent updates](references/core/concurrent-optimistic-updates.md) with [mutations](references/core/write-mutations-and-invalidate-related-queries.md).
+- Read [cancellation](references/core/cancel-queries-and-consume-abort-signals.md) before an optimistic write that can conflict with a refetch.
+- Read [selectors](references/core/selectors-and-derived-state.md) with [seed and transform data](references/core/seed-placeholder-select-and-transform-data.md), [forms](references/compositions/query-data-and-forms.md), and [abstractions](references/core/build-query-abstractions.md).
+- Read [Router and Start](references/compositions/compose-query-with-tanstack-router-and-start.md) with [prefetch](references/lifecycle/prefetch-and-remove-request-waterfalls.md), [SSR](references/lifecycle/ssr-hydration-and-streaming.md), and [Suspense](references/framework/use-suspense-and-error-boundaries.md).
+- Read [defaults](references/core/tune-defaults-freshness-retries-and-refetching.md) with [persistence](references/compositions/persist-offline-and-restore-caches.md). Persistence depends on gcTime, networkMode, and retry behavior.

package/scaffold/.agents/skills/tanstack-query/references/compositions/automatic-invalidation-after-mutations.md

@@ -0,0 +1,124 @@
+---
+name: compositions/automatic-invalidation-after-mutations
+description: >
+  Use this when designing automatic invalidation policies for TanStack Query
+  mutations with MutationCache callbacks, mutationKey-to-queryKey matching,
+  mutation meta invalidation tags, awaited invalidation, and exclusions for
+  static or unrelated queries.
+type: composition
+library: TanStack Query
+library_version: "5.101.0"
+requires:
+  - core/write-mutations-and-invalidate-related-queries
+  - core/design-query-keys-and-options
+sources:
+  - TanStack/query:docs/framework/react/guides/invalidations-from-mutations.md
+  - TanStack/query:docs/reference/MutationCache.md
+  - TanStack/query:docs/reference/QueryClient.md
+---
+
+## Core Patterns
+
+Use local mutation callbacks for one-off behavior. Use `MutationCache` callbacks when the app wants a consistent invalidation policy for every mutation.
+
+### Global invalidation after successful mutations
+
+```ts
+import { MutationCache, QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  mutationCache: new MutationCache({
+    onSuccess: (_data, _variables, _context, mutation) => {
+      return queryClient.invalidateQueries({
+        queryKey: mutation.options.mutationKey,
+      });
+    },
+  }),
+});
+```
+
+If a mutation has `mutationKey: ['issues']`, this invalidates matching issue queries. If it has no mutation key, this becomes a broad invalidation policy, so only use that deliberately.
+
+### Use meta for explicit invalidation tags
+
+```ts
+import { matchQuery, MutationCache, QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient({
+  mutationCache: new MutationCache({
+    onSuccess: (_data, _variables, _context, mutation) => {
+      return queryClient.invalidateQueries({
+        predicate: (query) =>
+          mutation.meta?.invalidates?.some((queryKey) => matchQuery({ queryKey }, query)) ?? true,
+      });
+    },
+  }),
+});
+```
+
+## Common Mistakes
+
+### HIGH Invalidating the whole app for every mutation
+
+Wrong:
+
+```ts
+new MutationCache({
+  onSuccess: () => queryClient.invalidateQueries(),
+});
+```
+
+Correct:
+
+```ts
+new MutationCache({
+  onSuccess: (_data, _variables, _context, mutation) =>
+    queryClient.invalidateQueries({ queryKey: mutation.options.mutationKey }),
+});
+```
+
+Global policies need scope. Reach for mutation keys or meta tags before invalidating everything.
+
+### HIGH Not returning invalidation when pending UI depends on refetch
+
+Wrong:
+
+```ts
+onSuccess: () => {
+  queryClient.invalidateQueries({ queryKey: ["todos"] });
+};
+```
+
+Correct:
+
+```ts
+onSuccess: () => queryClient.invalidateQueries({ queryKey: ["todos"] });
+```
+
+Returning the promise keeps the mutation pending until the invalidation refetch completes.
+
+Source: TanStack/query:docs/framework/react/guides/invalidations-from-mutations.md
+
+### MEDIUM Refetching data that should be static
+
+Wrong:
+
+```ts
+useQuery({
+  queryKey: ["build-info"],
+  queryFn: fetchBuildInfo,
+  staleTime: Infinity,
+});
+```
+
+Correct:
+
+```ts
+useQuery({
+  queryKey: ["build-info"],
+  queryFn: fetchBuildInfo,
+  staleTime: "static",
+});
+```
+
+If a query must not refetch even after broad manual invalidation, mark it with `staleTime: 'static'`.

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