fix(appkit-ui): stabilize useAnalyticsQuery params reference to avoid infinite refetch

[jamesbroadhead]

Problem

useAnalyticsQuery(queryKey, params) invalidates its internal payload memo whenever the params object reference changes. A typical call site looks like:

const { data } = useAnalyticsQuery("revenue_by_destination", {
  limit: sql.number(10),
});

{ limit: ... } is a new object literal every render, so the memo invalidates, start re-runs, the SSE connection is torn down and reopened — and on the next render the cycle repeats. Result: infinite refetch.

The previous workaround was for every consumer to wrap params in useMemo. The LLM guide even told users to "always memoize query parameters". That's a pure API tax that every team using AppKit will eventually trip over.

Fix

Stabilize the parameters reference inside the hook using useRef + a shallow structural-equality check. If the new params are structurally equal to the previous render's, reuse the previous reference for downstream dependency comparisons. No public API change.

Analytics query params are produced by the sql.* builders and are always one-level objects keyed to primitives (string | number | boolean | null | undefined), so shallow equality is sufficient — and meaningfully cheaper than a full deep-equal.

Options considered

Option 1 (selected): deep-compare params inside the hook.

• No API change.
• Cost is negligible — params are tiny.
• Structural equality is what users actually want.
• TanStack Query / SWR ship the same approach (deep-equal of query keys / params).

Option 2: stable-stringify params and use the string as the internal cache key.

• Also no API change.
• Slightly more efficient for very large params.
• But adds a JSON.stringify on every render and makes the internal cache-key indirection harder to reason about for the small-param common case.

Option 1 wins on simplicity for the common case.

Changes

• packages/appkit-ui/src/react/hooks/use-analytics-query.ts — add shallowEqualParams + useStableParams helpers; route parameters through useStableParams before the payload memo.
• packages/appkit-ui/src/react/hooks/__tests__/use-analytics-query.test.ts — new test file. Covers: structurally-equal fresh-literal params do NOT refetch, real param changes DO refetch, undefined params are stable, two empty {} literals are stable.
• docs/docs/development/llm-guide.md — replace the stale "always memoize query parameters" guidance with a note that params are now reference-stabilized internally.

Test plan

• pnpm test — all 1757 tests pass, including 4 new tests in use-analytics-query.test.ts.
• pnpm check — Biome lint + format clean.
• pnpm -r typecheck — clean across all packages.

This pull request and its description were written by Isaac.