gemi 0.59.0 → 0.61.0

package/dist/testing/index.js

@@ -1,4 +1,5 @@
-import { A as Action, E as ServerDataContext, F as toVariantKey, H as Subject, I as applyParams, P as RouteStateProvider, R as QueryManagerContext, T as I18nProvider, a as m, c as ClientRouterContext, j as createMemoryHistory, k as ProgressManager, o as RouteTransitionProvider, r as WebSocketContext, t as ThemeProvider, z as QueryManagerProvider } from "../chunks/ThemeProvider-ByU4BQdL.js";
+import { A as Action, E as ServerDataContext, F as QueryManagerContext, I as QueryManagerProvider, M as toVariantKey, N as applyParams, T as I18nProvider, a as m, c as ClientRouterContext, j as createMemoryHistory, k as ProgressManager, o as RouteTransitionProvider, r as WebSocketContext, t as ThemeProvider, z as Subject } from "../chunks/ThemeProvider-BZ2SsSZ3.js";
+import { r as RouteStateProvider } from "../chunks/useParams-BN3XXfmG.js";
 import { Suspense, useContext, useMemo, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region testing/Page.tsx

package/dist/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../testing/Page.tsx"],"sourcesContent":["import {\n  Suspense,\n  useContext,\n  useMemo,\n  useRef,\n  useState,\n  type ComponentType,\n  type PropsWithChildren,\n  type ReactNode,\n} from \"react\";\nimport { ErrorBoundary, type FallbackProps } from \"react-error-boundary\";\nimport { Action, createMemoryHistory } from \"history\";\n\nimport type { User } from \"../auth/types\";\nimport { ClientRouterContext } from \"../client/ClientRouterContext\";\nimport { I18nProvider } from \"../client/I18nContext\";\nimport { ProgressManager } from \"../client/ProgressManager\";\nimport {\n  QueryManagerContext,\n  QueryManagerProvider,\n  type QueryConfig,\n} from \"../client/QueryManagerContext\";\nimport {\n  RouteStateProvider,\n  type PageData,\n  type RouteState,\n} from \"../client/RouteStateContext\";\nimport { RouteTransitionProvider } from \"../client/RouteTransitionProvider\";\nimport {\n  ServerDataContext,\n  type ServerDataContextValue,\n} from \"../client/ServerDataProvider\";\nimport { ThemeProvider } from \"../client/ThemeProvider\";\nimport type { ClientFeatureKey } from \"../client/rpc\";\nimport type { Breadcrumb } from \"../client/useBreadcrumbs\";\nimport { WebSocketContext } from \"../client/WebsocketContext\";\nimport { applyParams } from \"../utils/applyParams\";\nimport { Subject } from \"../utils/Subject\";\nimport { toVariantKey } from \"../utils/variantKey\";\n\n/**\n * A dictionary as `Dictionary.create` produces it: a name and a\n * `{ key: { locale: string } }` map.\n *\n * Typed structurally rather than as `Dictionary<T>` for two reasons. It keeps\n * `gemi/testing` from importing `gemi/i18n` — a server entry, which reaches the\n * `Lang` facade and through it the container. And it means an object literal of\n * the same shape is accepted, so a test never *has* to import the app's\n * dictionaries at all.\n *\n * Only `name` and `dictionary` are read — both plain data. `Dictionary`'s\n * server-only methods (`render`, `reference`, which throw once `window` is\n * defined) are never called from here.\n */\nexport interface PageDictionary {\n  name: string;\n  dictionary: Record<string, Record<string, string>>;\n}\n\nexport interface PageProps {\n  /**\n   * The URL the view is mounted at. A template (`/app/:orgId/chat`) is resolved\n   * against `params`, so the same string can be pasted from the router.\n   */\n  pathname?: string;\n  /** Route params, as the router would have parsed them out of `pathname`. */\n  params?: Record<string, string>;\n  /** `\"?tab=recent\"`, `\"tab=recent\"`, or `{ tab: \"recent\" }`. */\n  searchParams?: string | Record<string, string | number | boolean>;\n  hash?: string;\n  /** The locale `useTranslator` and `useLocale` report. */\n  locale?: string;\n  /**\n   * The app's default locale. Links and `useNavigate` omit the locale segment\n   * for it, so leaving this equal to `locale` (the default) keeps hrefs\n   * unprefixed — set it to seed a page being viewed in a non-default locale.\n   */\n  defaultLocale?: string;\n  supportedLocales?: string[];\n  /**\n   * Dictionaries the components under test translate against — the app's own,\n   * or literals of the same shape.\n   *\n   * Note what importing the app's costs: `app/i18n/index.ts` imports\n   * `gemi/i18n`, a server entry, so the test file pulls the container and\n   * `node:async_hooks` into its module graph. Nothing there runs (and nothing\n   * here calls it), so it is fine under any runner that has Node builtins —\n   * vitest, `bun test` — and not under one that renders in a real browser. Use\n   * `translations` there, which is the shape the client actually receives.\n   */\n  dictionaries?: PageDictionary[];\n  /**\n   * Translations for the current locale, already resolved: dictionary name →\n   * key → string. This is the shape the server serializes onto the page, so it\n   * is what the client reads at runtime — and it imports nothing.\n   *\n   * ```tsx\n   * <Page translations={{ Chat: { greeting: \"Hello {{name}}\" } }}>\n   * ```\n   *\n   * Merged over `dictionaries`, so the two compose: seed from the app's real\n   * dictionary and override the one key a test is about.\n   */\n  translations?: Record<string, Record<string, string>>;\n  /**\n   * Data `useQuery` finds already cached, keyed by API path — the path passed\n   * to `useQuery`, without the `/api` prefix the client adds when it fetches.\n   * A key may carry a query string (`\"/lists?page=2\"`) to seed one search\n   * variant.\n   *\n   * The cache is keyed by the *resolved* path, so a key's `:params` are\n   * resolved against the page's `params` — and a key naming one the page does\n   * not carry is an error, naming the key. That case is common enough to be\n   * worth the loud failure: a query often takes its params from the call site\n   * rather than the route (`useQuery(\"/orgs/:orgId/lists\", { params: { orgId } })`\n   * with `orgId` in component state), and the right seed for it is the resolved\n   * path, `\"/orgs/abc/lists\"`.\n   *\n   * Seeded at mount only: a component that mutates or refetches its data owns\n   * the cache from then on.\n   */\n  queryData?: Record<string, unknown>;\n  /** App-wide `useQuery` defaults, as `createRoot` threads them. */\n  queryConfig?: QueryConfig;\n  /**\n   * What `useUser()` reports. Defaults to `null` — an anonymous visitor — and\n   * either way the hook resolves from here without issuing a request.\n   */\n  user?: Partial<User> | null;\n  /** What `useBreadcrumbs()` returns, in order. */\n  breadcrumbs?: Breadcrumb[];\n  /**\n   * What `useFeature()` reports, keyed by feature key. Anything left out reads\n   * as off, exactly as an undeclared key does in a real request.\n   *\n   * A test seeds the *outcome*, not the declaration: `app/features` owns the\n   * targeting and the rollout, and re-deriving those here would mean building a\n   * request context — a user, a `session_id`, a bot verdict — to assert a\n   * branch that only cares which way the feature came out. Cover the targeting\n   * where it lives, with a server test.\n   */\n  features?: Partial<Record<ClientFeatureKey, boolean>>;\n  /**\n   * The theme `useTheme()` starts on. The app reads a visitor's stored choice\n   * out of `localStorage`; a test has no session to have made one in, so this\n   * seeds it without writing to storage. `setTheme` works from either.\n   */\n  theme?: \"light\" | \"dark\" | \"system\";\n  /**\n   * Fallback for the `Suspense` boundary wrapped around the children — the\n   * stand-in for the view's own `Loading` export, which the real router\n   * supplies. Defaults to `null`.\n   */\n  fallback?: ReactNode;\n  /**\n   * Renders in place of the children when one throws, mirroring a view's\n   * `Error` export. Without it a thrown render (an errored suspense query,\n   * say) propagates out of `render()` and fails the test, which is usually\n   * what you want.\n   */\n  errorFallback?: ComponentType<FallbackProps>;\n  /**\n   * Called when something navigates — a `Link` click, `useNavigate().push`.\n   * The navigation is reported, not performed: `<Page>` renders one route and\n   * does not re-resolve the tree, so `useLocation()` keeps reporting the\n   * pathname it was given.\n   */\n  onNavigate?: (href: string, action: \"push\" | \"replace\") => void;\n}\n\n/** `\"?a=b\"` (or `\"\"`) from any of the shapes `searchParams` accepts. */\nfunction toSearchString(search: PageProps[\"searchParams\"]): string {\n  if (!search) return \"\";\n  const query =\n    typeof search === \"string\"\n      ? search.replace(/^\\?/, \"\")\n      : new URLSearchParams(\n          Object.entries(search).map(([key, value]) => [key, String(value)]),\n        ).toString();\n  return query ? `?${query}` : \"\";\n}\n\n/**\n * The `:params` a seed key needs supplied. Wildcards (`:rest*`) are excluded —\n * `applyParams` drops those when missing, which is a resolution rather than a\n * failure.\n *\n * Optional params (`:id?`) cannot reach here at all: a key is split at its\n * first `?` to separate the search string, so `\"/lists/:folderId?\"` arrives as\n * the path `/lists/:folderId`. Seed the resolved path for those.\n */\nfunction requiredParamsOf(path: string): string[] {\n  return Array.from(path.matchAll(/:([^/]+)/g), ([, name]) => name).filter(\n    (name) => !name.endsWith(\"*\"),\n  );\n}\n\n/**\n * Fails a `queryData` key whose `:params` the page does not carry, saying so\n * in terms of the key.\n *\n * Without this the two documented runners disagree, and neither is legible.\n * `applyParams` throws `Missing parameter: orgId` under `import.meta.env.DEV`\n * (vitest) — a router-utility stack trace out of `<Page>`'s render, before\n * anything mounts, naming nothing that appears in the test. Under `bun test`\n * that flag is falsy, so it logs and seeds the literal `/orgs/undefined/lists`\n * instead: the seed misses, the query goes to the network, and the assertion\n * runs against a loading state.\n *\n * The case is common because a query's params often come from the call site\n * rather than the route — `useQuery(\"/orgs/:orgId/lists\", { params: { orgId } })`\n * with `orgId` in component state. The cache is keyed by the *resolved* path,\n * so the way out is to seed that path directly.\n */\nfunction resolveSeedPath(\n  key: string,\n  rawPath: string,\n  params: Record<string, string>,\n): string {\n  const missing = requiredParamsOf(rawPath).filter(\n    (name) => params[name] === undefined,\n  );\n  if (missing.length > 0) {\n    throw new Error(\n      `[gemi] <Page> cannot resolve the queryData key \"${key}\": no value for ` +\n        `${missing.map((name) => `:${name}`).join(\", \")}. The query cache is ` +\n        `keyed by the resolved path, so either add ${missing\n          .map((name) => `\\`${name}\\``)\n          .join(\", \")} to the page's \\`params\\`, or seed the resolved path ` +\n        `(e.g. \"${applyParams(\n          rawPath,\n          Object.fromEntries(missing.map((name) => [name, \"123\"])),\n        )}\") — which is what a query taking its params from component state ` +\n        `reads under.`,\n    );\n  }\n  return applyParams(rawPath, params);\n}\n\n/**\n * `queryData` in the shape the query cache seeds from: `{ [path]: { [variant]:\n * data } }`, the same payload `Query.prefetch` puts on a server-rendered page.\n */\nfunction toPrefetchedData(\n  queryData: Record<string, unknown>,\n  params: Record<string, string>,\n  warned: Set<string>,\n) {\n  const prefetchedData: Record<string, Record<string, unknown>> = {};\n  for (const [key, data] of Object.entries(queryData)) {\n    const [rawPath, rawSearch = \"\"] = key.split(\"?\");\n    // Once per key per page, not once per render: this runs again on every\n    // re-render, and a duplicated warning reads as a second mistake.\n    if (rawPath.startsWith(\"/api/\") && !warned.has(key)) {\n      warned.add(key);\n      console.warn(\n        `[gemi] queryData key \"${key}\" starts with /api. useQuery is keyed by ` +\n          `the path you pass it — the /api prefix is added when it fetches — ` +\n          `so this entry seeds a path no query reads.`,\n      );\n    }\n    const path = resolveSeedPath(key, rawPath, params);\n    prefetchedData[path] = {\n      ...prefetchedData[path],\n      [toVariantKey(rawSearch)]: data,\n    };\n  }\n  return prefetchedData;\n}\n\n/**\n * `{ [locale]: { [dictionary]: { [key]: string } } }` — the payload\n * `Translator` serializes onto the page, which is the only form the client\n * ever sees. `dictionaries` are transposed into it (they are keyed the other\n * way round, by key then locale); `translations` is already in it and lands\n * under `locale`, last, so it wins.\n */\nfunction toClientDictionary(\n  dictionaries: PageDictionary[],\n  locales: string[],\n  locale: string,\n  translations: Record<string, Record<string, string>>,\n): Record<string, Record<string, Record<string, string>>> {\n  const clientDictionary: Record<\n    string,\n    Record<string, Record<string, string>>\n  > = {};\n  for (const supported of locales) {\n    clientDictionary[supported] ??= {};\n  }\n  for (const { name, dictionary } of dictionaries) {\n    for (const [key, byLocale] of Object.entries(dictionary ?? {})) {\n      for (const [dictLocale, translation] of Object.entries(byLocale ?? {})) {\n        clientDictionary[dictLocale] ??= {};\n        clientDictionary[dictLocale][name] ??= {};\n        clientDictionary[dictLocale][name][key] = translation;\n      }\n    }\n  }\n  for (const [name, keys] of Object.entries(translations)) {\n    clientDictionary[locale] ??= {};\n    clientDictionary[locale][name] = {\n      ...clientDictionary[locale][name],\n      ...keys,\n    };\n  }\n  return clientDictionary;\n}\n\n/**\n * Mounts a component with the inputs a view normally arrives with — route\n * params, the current locale and its dictionaries, prefetched query data, the\n * signed-in user — so a unit test can assert what it renders rather than only\n * its empty state.\n *\n * ```tsx\n * import { render, screen } from \"@testing-library/react\";\n * import { Page } from \"gemi/testing\";\n *\n * render(\n *   <Page\n *     pathname=\"/app/:orgId/chat\"\n *     params={{ orgId: \"abc\" }}\n *     queryData={{ \"/organizations/:orgId/messages\": [{ id: 1, body: \"hi\" }] }}\n *     dictionaries={[ChatDictionary]}\n *   >\n *     <OrgChat />\n *   </Page>,\n * );\n *\n * expect(screen.getByText(\"hi\")).toBeDefined();\n * ```\n *\n * It is a plain component, so it composes with any renderer — Testing\n * Library's `render`, `react-test-renderer`, or `renderToString`.\n *\n * Two things it does not do.\n *\n * It does not route: there is no view tree and no route manifest behind it, so\n * a navigation is reported through `onNavigate` rather than resolved. To\n * assert the page *after* one, render a second `<Page>`.\n *\n * And under `renderToString` it renders the server's own no-data branch for an\n * *unseeded* query rather than suspending — deliberately, because suspending\n * there is the streaming server's job: `createRoot` threads the request's\n * `ServerQueryStore` through `ServerQueryContext`, and that store is what runs\n * the route handler. A harness has no request and no handler to run, so there\n * is nothing to suspend on. Seeded queries render their data on the server\n * exactly as they do in the browser; unseeded ones behave as a route with no\n * `Query.prefetch` does, framework warning included.\n */\nexport const Page = (props: PropsWithChildren<PageProps>) => {\n  const {\n    children,\n    pathname: routePath = \"/\",\n    params = {},\n    searchParams,\n    hash = \"\",\n    locale = \"en-US\",\n    defaultLocale = locale,\n    dictionaries = [],\n    translations = {},\n    queryData = {},\n    queryConfig,\n    user = null,\n    breadcrumbs = [],\n    features = {},\n    theme,\n    fallback = null,\n    errorFallback,\n    onNavigate,\n  } = props;\n\n  // The caller's list, in the caller's order — a language switcher maps over\n  // it, so hoisting the page's own locale to the front would reorder the\n  // rendered options. The defaults are appended, only to guarantee presence.\n  const supportedLocales = useMemo(\n    () =>\n      Array.from(\n        new Set([...(props.supportedLocales ?? []), defaultLocale, locale]),\n      ),\n    [props.supportedLocales, defaultLocale, locale],\n  );\n  const pathname = applyParams(routePath, params) || \"/\";\n  const search = toSearchString(searchParams);\n  // The URL's locale segment, which the default locale does not get.\n  const urlLocaleSegment = locale === defaultLocale ? null : locale;\n\n  const dictionary = useMemo(\n    () =>\n      toClientDictionary(dictionaries, supportedLocales, locale, translations),\n    [dictionaries, supportedLocales, locale, translations],\n  );\n\n  // Keys that have already drawn a warning, so a re-render does not repeat it.\n  const warnedRef = useRef<Set<string>>(new Set());\n  const prefetchedData = useMemo(() => {\n    const seeded = toPrefetchedData(queryData, params, warnedRef.current);\n    // `useUser` reads `/auth/me` like any other query. Seeding it — with `null`\n    // for the anonymous default — is what keeps a component test off the\n    // network for a hook nothing in the test asked for.\n    seeded[\"/auth/me\"] ??= { \"\": user ?? null };\n    return seeded;\n  }, [queryData, params, user]);\n\n  // Keyed by `${view}:${pathname}` in the router's cache; the view names are\n  // ours to choose here, and only their order reaches `useBreadcrumbs`.\n  const { breadcrumbViews, breadcrumbsCache, breadcrumbsRecord } =\n    useMemo(() => {\n      const views = breadcrumbs.map((_, index) => `breadcrumb-${index}`);\n      const cache = new Map<string, Breadcrumb>(\n        breadcrumbs.map((breadcrumb, index) => [\n          `${views[index]}:${pathname}`,\n          breadcrumb,\n        ]),\n      );\n      return {\n        breadcrumbViews: views,\n        breadcrumbsCache: cache,\n        breadcrumbsRecord: Object.fromEntries(cache),\n      };\n    }, [breadcrumbs, pathname]);\n\n  const [isNavigatingSubject] = useState(() => new Subject<boolean>(false));\n  const [progressManager] = useState(\n    () => new ProgressManager(isNavigatingSubject),\n  );\n  const [history] = useState(() =>\n    createMemoryHistory({ initialEntries: [`${pathname}${search}${hash}`] }),\n  );\n\n  const routeState: RouteState & PageData = useMemo(\n    () => ({\n      views: [],\n      params,\n      search,\n      state: {},\n      pathname,\n      hash,\n      action: null,\n      routePath,\n      locale: urlLocaleSegment,\n      data: {},\n      i18n: { currentLocale: locale, dictionary, supportedLocales },\n      prefetchedData,\n      breadcrumbs: breadcrumbsRecord,\n      features: features as Record<string, boolean>,\n      appId: \"test\",\n    }),\n    [\n      params,\n      search,\n      pathname,\n      hash,\n      routePath,\n      urlLocaleSegment,\n      locale,\n      dictionary,\n      supportedLocales,\n      prefetchedData,\n      breadcrumbsRecord,\n      features,\n    ],\n  );\n\n  const [routerSubject] = useState(() => new Subject<RouteState>(routeState));\n\n  const onNavigateRef = useRef(onNavigate);\n  onNavigateRef.current = onNavigate;\n  // Subscribed during render, not in an effect, because React flushes child\n  // effects before parent ones — and mount-time navigation is a real pattern:\n  // `<Redirect>` pushes from its own mount effect, as does any auth guard. A\n  // listener registered in `<Page>`'s effect is not there yet when those fire,\n  // so `onNavigate` would silently miss exactly the redirects a test most\n  // wants to assert. Ref-guarded, so React's double-invoke registers one.\n  //\n  // Nothing unsubscribes: this history is created per `<Page>` and reachable\n  // from nowhere else, so it is collected with the page it belongs to.\n  const listeningRef = useRef(false);\n  if (!listeningRef.current) {\n    listeningRef.current = true;\n    history.listen(({ location, action }) => {\n      const href = `${location.pathname}${location.search}${location.hash}`;\n      onNavigateRef.current?.(\n        href,\n        action === Action.Replace ? \"replace\" : \"push\",\n      );\n    });\n  }\n\n  const serverData: ServerDataContextValue = useMemo(\n    () => ({\n      routeManifest: {},\n      pageData: {},\n      breadcrumbs: breadcrumbsRecord,\n      prefetchedData,\n      router: {\n        pathname,\n        params,\n        currentPath: routePath,\n        is404: false,\n        searchParams: search,\n        urlLocaleSegment,\n      },\n      i18n: {\n        dictionary,\n        currentLocale: locale,\n        supportedLocales,\n        defaultLocale,\n      },\n      componentTree: [],\n      auth: { user: user as User },\n      features: features as Record<string, boolean>,\n      __csrf: \"test-csrf-token\",\n      cssManifest: {},\n      modulePreloadManifest: {},\n      meta: {},\n      appId: \"test\",\n    }),\n    [\n      breadcrumbsRecord,\n      prefetchedData,\n      pathname,\n      params,\n      routePath,\n      search,\n      urlLocaleSegment,\n      dictionary,\n      locale,\n      supportedLocales,\n      defaultLocale,\n      user,\n      features,\n    ],\n  );\n\n  // Everything the router hooks read, inert: nothing here fetches, preloads or\n  // resolves a route, but every hook finds the shape it expects rather than an\n  // empty context to crash on.\n  const [viewEntriesSubject] = useState(() => new Subject<string[]>([]));\n  const routerContext = useMemo(\n    () => ({\n      viewEntriesSubject,\n      history,\n      updatePageData: () => {},\n      getPageData: () => ({}),\n      getScrollPosition: () => 0,\n      getViewPathsFromPathname: () => breadcrumbViews,\n      getRoutePathnameFromHref: (href: string) => href,\n      isNavigatingSubject,\n      setNavigationAbortController: () => {},\n      progressManager,\n      fetchRouteCSS: async () => {},\n      preloadRouteModules: () => {},\n      prefetchRoute: async () => {},\n      takePrefetched: () => null,\n      clearPrefetchCache: () => {},\n      breadcrumbsCache,\n      routerSubject,\n      urlLocaleSegment,\n    }),\n    [\n      viewEntriesSubject,\n      history,\n      breadcrumbViews,\n      isNavigatingSubject,\n      progressManager,\n      breadcrumbsCache,\n      routerSubject,\n      urlLocaleSegment,\n    ],\n  );\n\n  const [websocket] = useState(() => ({\n    subscribe: async () => {},\n    unsubscribe: async () => {},\n    broadcast: () => {},\n  }));\n\n  return (\n    <ThemeProvider theme={theme}>\n      <ServerDataContext.Provider value={serverData}>\n        <I18nProvider>\n          <WebSocketContext.Provider value={websocket}>\n            <QueryManagerProvider queryConfig={queryConfig}>\n              <ClientRouterContext.Provider value={routerContext}>\n                <RouteTransitionProvider\n                  isPending={false}\n                  isFetching={false}\n                  transitionPath={[\"\", pathname]}\n                >\n                  <RouteStateProvider state={routeState}>\n                    <Boundary\n                      errorFallback={errorFallback}\n                      fallback={fallback}\n                      resetKey={pathname}\n                    >\n                      {children}\n                    </Boundary>\n                  </RouteStateProvider>\n                </RouteTransitionProvider>\n              </ClientRouterContext.Provider>\n            </QueryManagerProvider>\n          </WebSocketContext.Provider>\n        </I18nProvider>\n      </ServerDataContext.Provider>\n    </ThemeProvider>\n  );\n};\n\n/**\n * The `Suspense` boundary every view renders inside, and — when the test\n * supplies a fallback for it — the error boundary too.\n *\n * `onReset={clearErrors}` is the part that has to be here rather than inline\n * above: it needs `QueryManagerContext`, and it is what makes a view's real\n * `Error` export testable. A fallback whose \"Try again\" calls\n * `resetErrorBoundary()` re-renders the child, and `useQuery` reads the\n * failure still stored on the `QueryResource` and throws it straight back —\n * so without this the fallback never goes away and the retry path that works\n * in the app cannot be exercised. `ClientRouter`'s own boundary wires exactly\n * this pair.\n */\nconst Boundary = (\n  props: PropsWithChildren<{\n    errorFallback?: ComponentType<FallbackProps>;\n    fallback: ReactNode;\n    resetKey: string;\n  }>,\n) => {\n  const { errorFallback: ErrorFallback, fallback, resetKey, children } = props;\n  const { clearErrors } = useContext(QueryManagerContext);\n  const content = <Suspense fallback={fallback}>{children}</Suspense>;\n\n  if (!ErrorFallback) {\n    return content;\n  }\n\n  return (\n    <ErrorBoundary\n      FallbackComponent={ErrorFallback}\n      resetKeys={[resetKey]}\n      onReset={clearErrors}\n    >\n      {content}\n    </ErrorBoundary>\n  );\n};\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../testing/Page.tsx"],"sourcesContent":["import {\n  Suspense,\n  useContext,\n  useMemo,\n  useRef,\n  useState,\n  type ComponentType,\n  type PropsWithChildren,\n  type ReactNode,\n} from \"react\";\nimport { ErrorBoundary, type FallbackProps } from \"react-error-boundary\";\nimport { Action, createMemoryHistory } from \"history\";\n\nimport type { User } from \"../auth/types\";\nimport { ClientRouterContext } from \"../client/ClientRouterContext\";\nimport { I18nProvider } from \"../client/I18nContext\";\nimport { ProgressManager } from \"../client/ProgressManager\";\nimport {\n  QueryManagerContext,\n  QueryManagerProvider,\n  type QueryConfig,\n} from \"../client/QueryManagerContext\";\nimport {\n  RouteStateProvider,\n  type PageData,\n  type RouteState,\n} from \"../client/RouteStateContext\";\nimport { RouteTransitionProvider } from \"../client/RouteTransitionProvider\";\nimport {\n  ServerDataContext,\n  type ServerDataContextValue,\n} from \"../client/ServerDataProvider\";\nimport { ThemeProvider } from \"../client/ThemeProvider\";\nimport type { ClientFeatureKey } from \"../client/rpc\";\nimport type { Breadcrumb } from \"../client/useBreadcrumbs\";\nimport { WebSocketContext } from \"../client/WebsocketContext\";\nimport { applyParams } from \"../utils/applyParams\";\nimport { Subject } from \"../utils/Subject\";\nimport { toVariantKey } from \"../utils/variantKey\";\n\n/**\n * A dictionary as `Dictionary.create` produces it: a name and a\n * `{ key: { locale: string } }` map.\n *\n * Typed structurally rather than as `Dictionary<T>` for two reasons. It keeps\n * `gemi/testing` from importing `gemi/i18n` — a server entry, which reaches the\n * `Lang` facade and through it the container. And it means an object literal of\n * the same shape is accepted, so a test never *has* to import the app's\n * dictionaries at all.\n *\n * Only `name` and `dictionary` are read — both plain data. `Dictionary`'s\n * server-only methods (`render`, `reference`, which throw once `window` is\n * defined) are never called from here.\n */\nexport interface PageDictionary {\n  name: string;\n  dictionary: Record<string, Record<string, string>>;\n}\n\nexport interface PageProps {\n  /**\n   * The URL the view is mounted at. A template (`/app/:orgId/chat`) is resolved\n   * against `params`, so the same string can be pasted from the router.\n   */\n  pathname?: string;\n  /** Route params, as the router would have parsed them out of `pathname`. */\n  params?: Record<string, string>;\n  /** `\"?tab=recent\"`, `\"tab=recent\"`, or `{ tab: \"recent\" }`. */\n  searchParams?: string | Record<string, string | number | boolean>;\n  hash?: string;\n  /** The locale `useTranslator` and `useLocale` report. */\n  locale?: string;\n  /**\n   * The app's default locale. Links and `useNavigate` omit the locale segment\n   * for it, so leaving this equal to `locale` (the default) keeps hrefs\n   * unprefixed — set it to seed a page being viewed in a non-default locale.\n   */\n  defaultLocale?: string;\n  supportedLocales?: string[];\n  /**\n   * Dictionaries the components under test translate against — the app's own,\n   * or literals of the same shape.\n   *\n   * Note what importing the app's costs: `app/i18n/index.ts` imports\n   * `gemi/i18n`, a server entry, so the test file pulls the container and\n   * `node:async_hooks` into its module graph. Nothing there runs (and nothing\n   * here calls it), so it is fine under any runner that has Node builtins —\n   * vitest, `bun test` — and not under one that renders in a real browser. Use\n   * `translations` there, which is the shape the client actually receives.\n   */\n  dictionaries?: PageDictionary[];\n  /**\n   * Translations for the current locale, already resolved: dictionary name →\n   * key → string. This is the shape the server serializes onto the page, so it\n   * is what the client reads at runtime — and it imports nothing.\n   *\n   * ```tsx\n   * <Page translations={{ Chat: { greeting: \"Hello {{name}}\" } }}>\n   * ```\n   *\n   * Merged over `dictionaries`, so the two compose: seed from the app's real\n   * dictionary and override the one key a test is about.\n   */\n  translations?: Record<string, Record<string, string>>;\n  /**\n   * Data `useQuery` finds already cached, keyed by API path — the path passed\n   * to `useQuery`, without the `/api` prefix the client adds when it fetches.\n   * A key may carry a query string (`\"/lists?page=2\"`) to seed one search\n   * variant.\n   *\n   * The cache is keyed by the *resolved* path, so a key's `:params` are\n   * resolved against the page's `params` — and a key naming one the page does\n   * not carry is an error, naming the key. That case is common enough to be\n   * worth the loud failure: a query often takes its params from the call site\n   * rather than the route (`useQuery(\"/orgs/:orgId/lists\", { params: { orgId } })`\n   * with `orgId` in component state), and the right seed for it is the resolved\n   * path, `\"/orgs/abc/lists\"`.\n   *\n   * Seeded at mount only: a component that mutates or refetches its data owns\n   * the cache from then on.\n   */\n  queryData?: Record<string, unknown>;\n  /** App-wide `useQuery` defaults, as `createRoot` threads them. */\n  queryConfig?: QueryConfig;\n  /**\n   * What `useUser()` reports. Defaults to `null` — an anonymous visitor — and\n   * either way the hook resolves from here without issuing a request.\n   */\n  user?: Partial<User> | null;\n  /** What `useBreadcrumbs()` returns, in order. */\n  breadcrumbs?: Breadcrumb[];\n  /**\n   * What `useFeature()` reports, keyed by feature key. Anything left out reads\n   * as off, exactly as an undeclared key does in a real request.\n   *\n   * A test seeds the *outcome*, not the declaration: `app/features` owns the\n   * targeting and the rollout, and re-deriving those here would mean building a\n   * request context — a user, a `session_id`, a bot verdict — to assert a\n   * branch that only cares which way the feature came out. Cover the targeting\n   * where it lives, with a server test.\n   */\n  features?: Partial<Record<ClientFeatureKey, boolean>>;\n  /**\n   * The theme `useTheme()` starts on. The app reads a visitor's stored choice\n   * out of `localStorage`; a test has no session to have made one in, so this\n   * seeds it without writing to storage. `setTheme` works from either.\n   */\n  theme?: \"light\" | \"dark\" | \"system\";\n  /**\n   * Fallback for the `Suspense` boundary wrapped around the children — the\n   * stand-in for the view's own `Loading` export, which the real router\n   * supplies. Defaults to `null`.\n   */\n  fallback?: ReactNode;\n  /**\n   * Renders in place of the children when one throws, mirroring a view's\n   * `Error` export. Without it a thrown render (an errored suspense query,\n   * say) propagates out of `render()` and fails the test, which is usually\n   * what you want.\n   */\n  errorFallback?: ComponentType<FallbackProps>;\n  /**\n   * Called when something navigates — a `Link` click, `useNavigate().push`.\n   * The navigation is reported, not performed: `<Page>` renders one route and\n   * does not re-resolve the tree, so `useLocation()` keeps reporting the\n   * pathname it was given.\n   */\n  onNavigate?: (href: string, action: \"push\" | \"replace\") => void;\n}\n\n/** `\"?a=b\"` (or `\"\"`) from any of the shapes `searchParams` accepts. */\nfunction toSearchString(search: PageProps[\"searchParams\"]): string {\n  if (!search) return \"\";\n  const query =\n    typeof search === \"string\"\n      ? search.replace(/^\\?/, \"\")\n      : new URLSearchParams(\n          Object.entries(search).map(([key, value]) => [key, String(value)]),\n        ).toString();\n  return query ? `?${query}` : \"\";\n}\n\n/**\n * The `:params` a seed key needs supplied. Wildcards (`:rest*`) are excluded —\n * `applyParams` drops those when missing, which is a resolution rather than a\n * failure.\n *\n * Optional params (`:id?`) cannot reach here at all: a key is split at its\n * first `?` to separate the search string, so `\"/lists/:folderId?\"` arrives as\n * the path `/lists/:folderId`. Seed the resolved path for those.\n */\nfunction requiredParamsOf(path: string): string[] {\n  return Array.from(path.matchAll(/:([^/]+)/g), ([, name]) => name).filter(\n    (name) => !name.endsWith(\"*\"),\n  );\n}\n\n/**\n * Fails a `queryData` key whose `:params` the page does not carry, saying so\n * in terms of the key.\n *\n * Without this the two documented runners disagree, and neither is legible.\n * `applyParams` throws `Missing parameter: orgId` under `import.meta.env.DEV`\n * (vitest) — a router-utility stack trace out of `<Page>`'s render, before\n * anything mounts, naming nothing that appears in the test. Under `bun test`\n * that flag is falsy, so it logs and seeds the literal `/orgs/undefined/lists`\n * instead: the seed misses, the query goes to the network, and the assertion\n * runs against a loading state.\n *\n * The case is common because a query's params often come from the call site\n * rather than the route — `useQuery(\"/orgs/:orgId/lists\", { params: { orgId } })`\n * with `orgId` in component state. The cache is keyed by the *resolved* path,\n * so the way out is to seed that path directly.\n */\nfunction resolveSeedPath(\n  key: string,\n  rawPath: string,\n  params: Record<string, string>,\n): string {\n  const missing = requiredParamsOf(rawPath).filter(\n    (name) => params[name] === undefined,\n  );\n  if (missing.length > 0) {\n    throw new Error(\n      `[gemi] <Page> cannot resolve the queryData key \"${key}\": no value for ` +\n        `${missing.map((name) => `:${name}`).join(\", \")}. The query cache is ` +\n        `keyed by the resolved path, so either add ${missing\n          .map((name) => `\\`${name}\\``)\n          .join(\", \")} to the page's \\`params\\`, or seed the resolved path ` +\n        `(e.g. \"${applyParams(\n          rawPath,\n          Object.fromEntries(missing.map((name) => [name, \"123\"])),\n        )}\") — which is what a query taking its params from component state ` +\n        `reads under.`,\n    );\n  }\n  return applyParams(rawPath, params);\n}\n\n/**\n * `queryData` in the shape the query cache seeds from: `{ [path]: { [variant]:\n * data } }`, the same payload `Query.prefetch` puts on a server-rendered page.\n */\nfunction toPrefetchedData(\n  queryData: Record<string, unknown>,\n  params: Record<string, string>,\n  warned: Set<string>,\n) {\n  const prefetchedData: Record<string, Record<string, unknown>> = {};\n  for (const [key, data] of Object.entries(queryData)) {\n    const [rawPath, rawSearch = \"\"] = key.split(\"?\");\n    // Once per key per page, not once per render: this runs again on every\n    // re-render, and a duplicated warning reads as a second mistake.\n    if (rawPath.startsWith(\"/api/\") && !warned.has(key)) {\n      warned.add(key);\n      console.warn(\n        `[gemi] queryData key \"${key}\" starts with /api. useQuery is keyed by ` +\n          `the path you pass it — the /api prefix is added when it fetches — ` +\n          `so this entry seeds a path no query reads.`,\n      );\n    }\n    const path = resolveSeedPath(key, rawPath, params);\n    prefetchedData[path] = {\n      ...prefetchedData[path],\n      [toVariantKey(rawSearch)]: data,\n    };\n  }\n  return prefetchedData;\n}\n\n/**\n * `{ [locale]: { [dictionary]: { [key]: string } } }` — the payload\n * `Translator` serializes onto the page, which is the only form the client\n * ever sees. `dictionaries` are transposed into it (they are keyed the other\n * way round, by key then locale); `translations` is already in it and lands\n * under `locale`, last, so it wins.\n */\nfunction toClientDictionary(\n  dictionaries: PageDictionary[],\n  locales: string[],\n  locale: string,\n  translations: Record<string, Record<string, string>>,\n): Record<string, Record<string, Record<string, string>>> {\n  const clientDictionary: Record<\n    string,\n    Record<string, Record<string, string>>\n  > = {};\n  for (const supported of locales) {\n    clientDictionary[supported] ??= {};\n  }\n  for (const { name, dictionary } of dictionaries) {\n    for (const [key, byLocale] of Object.entries(dictionary ?? {})) {\n      for (const [dictLocale, translation] of Object.entries(byLocale ?? {})) {\n        clientDictionary[dictLocale] ??= {};\n        clientDictionary[dictLocale][name] ??= {};\n        clientDictionary[dictLocale][name][key] = translation;\n      }\n    }\n  }\n  for (const [name, keys] of Object.entries(translations)) {\n    clientDictionary[locale] ??= {};\n    clientDictionary[locale][name] = {\n      ...clientDictionary[locale][name],\n      ...keys,\n    };\n  }\n  return clientDictionary;\n}\n\n/**\n * Mounts a component with the inputs a view normally arrives with — route\n * params, the current locale and its dictionaries, prefetched query data, the\n * signed-in user — so a unit test can assert what it renders rather than only\n * its empty state.\n *\n * ```tsx\n * import { render, screen } from \"@testing-library/react\";\n * import { Page } from \"gemi/testing\";\n *\n * render(\n *   <Page\n *     pathname=\"/app/:orgId/chat\"\n *     params={{ orgId: \"abc\" }}\n *     queryData={{ \"/organizations/:orgId/messages\": [{ id: 1, body: \"hi\" }] }}\n *     dictionaries={[ChatDictionary]}\n *   >\n *     <OrgChat />\n *   </Page>,\n * );\n *\n * expect(screen.getByText(\"hi\")).toBeDefined();\n * ```\n *\n * It is a plain component, so it composes with any renderer — Testing\n * Library's `render`, `react-test-renderer`, or `renderToString`.\n *\n * Two things it does not do.\n *\n * It does not route: there is no view tree and no route manifest behind it, so\n * a navigation is reported through `onNavigate` rather than resolved. To\n * assert the page *after* one, render a second `<Page>`.\n *\n * And under `renderToString` it renders the server's own no-data branch for an\n * *unseeded* query rather than suspending — deliberately, because suspending\n * there is the streaming server's job: `createRoot` threads the request's\n * `ServerQueryStore` through `ServerQueryContext`, and that store is what runs\n * the route handler. A harness has no request and no handler to run, so there\n * is nothing to suspend on. Seeded queries render their data on the server\n * exactly as they do in the browser; unseeded ones behave as a route with no\n * `Query.prefetch` does, framework warning included.\n */\nexport const Page = (props: PropsWithChildren<PageProps>) => {\n  const {\n    children,\n    pathname: routePath = \"/\",\n    params = {},\n    searchParams,\n    hash = \"\",\n    locale = \"en-US\",\n    defaultLocale = locale,\n    dictionaries = [],\n    translations = {},\n    queryData = {},\n    queryConfig,\n    user = null,\n    breadcrumbs = [],\n    features = {},\n    theme,\n    fallback = null,\n    errorFallback,\n    onNavigate,\n  } = props;\n\n  // The caller's list, in the caller's order — a language switcher maps over\n  // it, so hoisting the page's own locale to the front would reorder the\n  // rendered options. The defaults are appended, only to guarantee presence.\n  const supportedLocales = useMemo(\n    () =>\n      Array.from(\n        new Set([...(props.supportedLocales ?? []), defaultLocale, locale]),\n      ),\n    [props.supportedLocales, defaultLocale, locale],\n  );\n  const pathname = applyParams(routePath, params) || \"/\";\n  const search = toSearchString(searchParams);\n  // The URL's locale segment, which the default locale does not get.\n  const urlLocaleSegment = locale === defaultLocale ? null : locale;\n\n  const dictionary = useMemo(\n    () =>\n      toClientDictionary(dictionaries, supportedLocales, locale, translations),\n    [dictionaries, supportedLocales, locale, translations],\n  );\n\n  // Keys that have already drawn a warning, so a re-render does not repeat it.\n  const warnedRef = useRef<Set<string>>(new Set());\n  const prefetchedData = useMemo(() => {\n    const seeded = toPrefetchedData(queryData, params, warnedRef.current);\n    // `useUser` reads `/auth/me` like any other query. Seeding it — with `null`\n    // for the anonymous default — is what keeps a component test off the\n    // network for a hook nothing in the test asked for.\n    seeded[\"/auth/me\"] ??= { \"\": user ?? null };\n    return seeded;\n  }, [queryData, params, user]);\n\n  // Keyed by `${view}:${pathname}` in the router's cache; the view names are\n  // ours to choose here, and only their order reaches `useBreadcrumbs`.\n  const { breadcrumbViews, breadcrumbsCache, breadcrumbsRecord } =\n    useMemo(() => {\n      const views = breadcrumbs.map((_, index) => `breadcrumb-${index}`);\n      const cache = new Map<string, Breadcrumb>(\n        breadcrumbs.map((breadcrumb, index) => [\n          `${views[index]}:${pathname}`,\n          breadcrumb,\n        ]),\n      );\n      return {\n        breadcrumbViews: views,\n        breadcrumbsCache: cache,\n        breadcrumbsRecord: Object.fromEntries(cache),\n      };\n    }, [breadcrumbs, pathname]);\n\n  const [isNavigatingSubject] = useState(() => new Subject<boolean>(false));\n  const [progressManager] = useState(\n    () => new ProgressManager(isNavigatingSubject),\n  );\n  const [history] = useState(() =>\n    createMemoryHistory({ initialEntries: [`${pathname}${search}${hash}`] }),\n  );\n\n  const routeState: RouteState & PageData = useMemo(\n    () => ({\n      views: [],\n      params,\n      search,\n      state: {},\n      pathname,\n      hash,\n      action: null,\n      routePath,\n      locale: urlLocaleSegment,\n      data: {},\n      i18n: { currentLocale: locale, dictionary, supportedLocales },\n      prefetchedData,\n      breadcrumbs: breadcrumbsRecord,\n      features: features as Record<string, boolean>,\n      appId: \"test\",\n    }),\n    [\n      params,\n      search,\n      pathname,\n      hash,\n      routePath,\n      urlLocaleSegment,\n      locale,\n      dictionary,\n      supportedLocales,\n      prefetchedData,\n      breadcrumbsRecord,\n      features,\n    ],\n  );\n\n  const [routerSubject] = useState(() => new Subject<RouteState>(routeState));\n\n  const onNavigateRef = useRef(onNavigate);\n  onNavigateRef.current = onNavigate;\n  // Subscribed during render, not in an effect, because React flushes child\n  // effects before parent ones — and mount-time navigation is a real pattern:\n  // `<Redirect>` pushes from its own mount effect, as does any auth guard. A\n  // listener registered in `<Page>`'s effect is not there yet when those fire,\n  // so `onNavigate` would silently miss exactly the redirects a test most\n  // wants to assert. Ref-guarded, so React's double-invoke registers one.\n  //\n  // Nothing unsubscribes: this history is created per `<Page>` and reachable\n  // from nowhere else, so it is collected with the page it belongs to.\n  const listeningRef = useRef(false);\n  if (!listeningRef.current) {\n    listeningRef.current = true;\n    history.listen(({ location, action }) => {\n      const href = `${location.pathname}${location.search}${location.hash}`;\n      onNavigateRef.current?.(\n        href,\n        action === Action.Replace ? \"replace\" : \"push\",\n      );\n    });\n  }\n\n  const serverData: ServerDataContextValue = useMemo(\n    () => ({\n      routeManifest: {},\n      pageData: {},\n      breadcrumbs: breadcrumbsRecord,\n      prefetchedData,\n      router: {\n        pathname,\n        params,\n        currentPath: routePath,\n        is404: false,\n        searchParams: search,\n        urlLocaleSegment,\n      },\n      i18n: {\n        dictionary,\n        currentLocale: locale,\n        supportedLocales,\n        defaultLocale,\n      },\n      componentTree: [],\n      auth: { user: user as User },\n      features: features as Record<string, boolean>,\n      __csrf: \"test-csrf-token\",\n      cssManifest: {},\n      modulePreloadManifest: {},\n      meta: {},\n      appId: \"test\",\n    }),\n    [\n      breadcrumbsRecord,\n      prefetchedData,\n      pathname,\n      params,\n      routePath,\n      search,\n      urlLocaleSegment,\n      dictionary,\n      locale,\n      supportedLocales,\n      defaultLocale,\n      user,\n      features,\n    ],\n  );\n\n  // Everything the router hooks read, inert: nothing here fetches, preloads or\n  // resolves a route, but every hook finds the shape it expects rather than an\n  // empty context to crash on.\n  const [viewEntriesSubject] = useState(() => new Subject<string[]>([]));\n  const routerContext = useMemo(\n    () => ({\n      viewEntriesSubject,\n      history,\n      updatePageData: () => {},\n      getPageData: () => ({}),\n      getScrollPosition: () => 0,\n      getViewPathsFromPathname: () => breadcrumbViews,\n      getRoutePathnameFromHref: (href: string) => href,\n      isNavigatingSubject,\n      setNavigationAbortController: () => {},\n      progressManager,\n      fetchRouteCSS: async () => {},\n      preloadRouteModules: () => {},\n      prefetchRoute: async () => {},\n      takePrefetched: () => null,\n      clearPrefetchCache: () => {},\n      breadcrumbsCache,\n      routerSubject,\n      urlLocaleSegment,\n    }),\n    [\n      viewEntriesSubject,\n      history,\n      breadcrumbViews,\n      isNavigatingSubject,\n      progressManager,\n      breadcrumbsCache,\n      routerSubject,\n      urlLocaleSegment,\n    ],\n  );\n\n  const [websocket] = useState(() => ({\n    subscribe: async () => {},\n    unsubscribe: async () => {},\n    broadcast: () => {},\n  }));\n\n  return (\n    <ThemeProvider theme={theme}>\n      <ServerDataContext.Provider value={serverData}>\n        <I18nProvider>\n          <WebSocketContext.Provider value={websocket}>\n            <QueryManagerProvider queryConfig={queryConfig}>\n              <ClientRouterContext.Provider value={routerContext}>\n                <RouteTransitionProvider\n                  isPending={false}\n                  isFetching={false}\n                  transitionPath={[\"\", pathname]}\n                >\n                  <RouteStateProvider state={routeState}>\n                    <Boundary\n                      errorFallback={errorFallback}\n                      fallback={fallback}\n                      resetKey={pathname}\n                    >\n                      {children}\n                    </Boundary>\n                  </RouteStateProvider>\n                </RouteTransitionProvider>\n              </ClientRouterContext.Provider>\n            </QueryManagerProvider>\n          </WebSocketContext.Provider>\n        </I18nProvider>\n      </ServerDataContext.Provider>\n    </ThemeProvider>\n  );\n};\n\n/**\n * The `Suspense` boundary every view renders inside, and — when the test\n * supplies a fallback for it — the error boundary too.\n *\n * `onReset={clearErrors}` is the part that has to be here rather than inline\n * above: it needs `QueryManagerContext`, and it is what makes a view's real\n * `Error` export testable. A fallback whose \"Try again\" calls\n * `resetErrorBoundary()` re-renders the child, and `useQuery` reads the\n * failure still stored on the `QueryResource` and throws it straight back —\n * so without this the fallback never goes away and the retry path that works\n * in the app cannot be exercised. `ClientRouter`'s own boundary wires exactly\n * this pair.\n */\nconst Boundary = (\n  props: PropsWithChildren<{\n    errorFallback?: ComponentType<FallbackProps>;\n    fallback: ReactNode;\n    resetKey: string;\n  }>,\n) => {\n  const { errorFallback: ErrorFallback, fallback, resetKey, children } = props;\n  const { clearErrors } = useContext(QueryManagerContext);\n  const content = <Suspense fallback={fallback}>{children}</Suspense>;\n\n  if (!ErrorFallback) {\n    return content;\n  }\n\n  return (\n    <ErrorBoundary\n      FallbackComponent={ErrorFallback}\n      resetKeys={[resetKey]}\n      onReset={clearErrors}\n    >\n      {content}\n    </ErrorBoundary>\n  );\n};\n"],"mappings":";;;;;;AA2KA,SAAS,eAAe,QAA2C;CACjE,IAAI,CAAC,QAAQ,OAAO;CACpB,MAAM,QACJ,OAAO,WAAW,WACd,OAAO,QAAQ,OAAO,EAAE,IACxB,IAAI,gBACF,OAAO,QAAQ,MAAM,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,CAAC,KAAK,OAAO,KAAK,CAAC,CAAC,CACnE,CAAC,CAAC,SAAS;CACjB,OAAO,QAAQ,IAAI,UAAU;AAC/B;;;;;;;;;;AAWA,SAAS,iBAAiB,MAAwB;CAChD,OAAO,MAAM,KAAK,KAAK,SAAS,WAAW,IAAI,GAAG,UAAU,IAAI,CAAC,CAAC,QAC/D,SAAS,CAAC,KAAK,SAAS,GAAG,CAC9B;AACF;;;;;;;;;;;;;;;;;;AAmBA,SAAS,gBACP,KACA,SACA,QACQ;CACR,MAAM,UAAU,iBAAiB,OAAO,CAAC,CAAC,QACvC,SAAS,OAAO,UAAU,KAAA,CAC7B;CACA,IAAI,QAAQ,SAAS,GACnB,MAAM,IAAI,MACR,mDAAmD,IAAI,kBAClD,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,iEACH,QAC1C,KAAK,SAAS,KAAK,KAAK,GAAG,CAAC,CAC5B,KAAK,IAAI,EAAE,8DACJ,YACR,SACA,OAAO,YAAY,QAAQ,KAAK,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CACzD,EAAE,+EAEN;CAEF,OAAO,YAAY,SAAS,MAAM;AACpC;;;;;AAMA,SAAS,iBACP,WACA,QACA,QACA;CACA,MAAM,iBAA0D,CAAC;CACjE,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,SAAS,GAAG;EACnD,MAAM,CAAC,SAAS,YAAY,MAAM,IAAI,MAAM,GAAG;EAG/C,IAAI,QAAQ,WAAW,OAAO,KAAK,CAAC,OAAO,IAAI,GAAG,GAAG;GACnD,OAAO,IAAI,GAAG;GACd,QAAQ,KACN,yBAAyB,IAAI,sJAG/B;EACF;EACA,MAAM,OAAO,gBAAgB,KAAK,SAAS,MAAM;EACjD,eAAe,QAAQ;GACrB,GAAG,eAAe;IACjB,aAAa,SAAS,IAAI;EAC7B;CACF;CACA,OAAO;AACT;;;;;;;;AASA,SAAS,mBACP,cACA,SACA,QACA,cACwD;CACxD,MAAM,mBAGF,CAAC;CACL,KAAK,MAAM,aAAa,SACtB,iBAAiB,eAAe,CAAC;CAEnC,KAAK,MAAM,EAAE,MAAM,gBAAgB,cACjC,KAAK,MAAM,CAAC,KAAK,aAAa,OAAO,QAAQ,cAAc,CAAC,CAAC,GAC3D,KAAK,MAAM,CAAC,YAAY,gBAAgB,OAAO,QAAQ,YAAY,CAAC,CAAC,GAAG;EACtE,iBAAiB,gBAAgB,CAAC;EAClC,iBAAiB,WAAW,CAAC,UAAU,CAAC;EACxC,iBAAiB,WAAW,CAAC,KAAK,CAAC,OAAO;CAC5C;CAGJ,KAAK,MAAM,CAAC,MAAM,SAAS,OAAO,QAAQ,YAAY,GAAG;EACvD,iBAAiB,YAAY,CAAC;EAC9B,iBAAiB,OAAO,CAAC,QAAQ;GAC/B,GAAG,iBAAiB,OAAO,CAAC;GAC5B,GAAG;EACL;CACF;CACA,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,IAAa,QAAQ,UAAwC;CAC3D,MAAM,EACJ,UACA,UAAU,YAAY,KACtB,SAAS,CAAC,GACV,cACA,OAAO,IACP,SAAS,SACT,gBAAgB,QAChB,eAAe,CAAC,GAChB,eAAe,CAAC,GAChB,YAAY,CAAC,GACb,aACA,OAAO,MACP,cAAc,CAAC,GACf,WAAW,CAAC,GACZ,OACA,WAAW,MACX,eACA,eACE;CAKJ,MAAM,mBAAmB,cAErB,MAAM,qBACJ,IAAI,IAAI;EAAC,GAAI,MAAM,oBAAoB,CAAC;EAAI;EAAe;CAAM,CAAC,CACpE,GACF;EAAC,MAAM;EAAkB;EAAe;CAAM,CAChD;CACA,MAAM,WAAW,YAAY,WAAW,MAAM,KAAK;CACnD,MAAM,SAAS,eAAe,YAAY;CAE1C,MAAM,mBAAmB,WAAW,gBAAgB,OAAO;CAE3D,MAAM,aAAa,cAEf,mBAAmB,cAAc,kBAAkB,QAAQ,YAAY,GACzE;EAAC;EAAc;EAAkB;EAAQ;CAAY,CACvD;CAGA,MAAM,YAAY,uBAAoB,IAAI,IAAI,CAAC;CAC/C,MAAM,iBAAiB,cAAc;EACnC,MAAM,SAAS,iBAAiB,WAAW,QAAQ,UAAU,OAAO;EAIpE,OAAO,gBAAgB,EAAE,IAAI,QAAQ,KAAK;EAC1C,OAAO;CACT,GAAG;EAAC;EAAW;EAAQ;CAAI,CAAC;CAI5B,MAAM,EAAE,iBAAiB,kBAAkB,sBACzC,cAAc;EACZ,MAAM,QAAQ,YAAY,KAAK,GAAG,UAAU,cAAc,OAAO;EACjE,MAAM,QAAQ,IAAI,IAChB,YAAY,KAAK,YAAY,UAAU,CACrC,GAAG,MAAM,OAAO,GAAG,YACnB,UACF,CAAC,CACH;EACA,OAAO;GACL,iBAAiB;GACjB,kBAAkB;GAClB,mBAAmB,OAAO,YAAY,KAAK;EAC7C;CACF,GAAG,CAAC,aAAa,QAAQ,CAAC;CAE5B,MAAM,CAAC,uBAAuB,eAAe,IAAI,QAAiB,KAAK,CAAC;CACxE,MAAM,CAAC,mBAAmB,eAClB,IAAI,gBAAgB,mBAAmB,CAC/C;CACA,MAAM,CAAC,WAAW,eAChB,oBAAoB,EAAE,gBAAgB,CAAC,GAAG,WAAW,SAAS,MAAM,EAAE,CAAC,CACzE;CAEA,MAAM,aAAoC,eACjC;EACL,OAAO,CAAC;EACR;EACA;EACA,OAAO,CAAC;EACR;EACA;EACA,QAAQ;EACR;EACA,QAAQ;EACR,MAAM,CAAC;EACP,MAAM;GAAE,eAAe;GAAQ;GAAY;EAAiB;EAC5D;EACA,aAAa;EACH;EACV,OAAO;CACT,IACA;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CACF,CACF;CAEA,MAAM,CAAC,iBAAiB,eAAe,IAAI,QAAoB,UAAU,CAAC;CAE1E,MAAM,gBAAgB,OAAO,UAAU;CACvC,cAAc,UAAU;CAUxB,MAAM,eAAe,OAAO,KAAK;CACjC,IAAI,CAAC,aAAa,SAAS;EACzB,aAAa,UAAU;EACvB,QAAQ,QAAQ,EAAE,UAAU,aAAa;GACvC,MAAM,OAAO,GAAG,SAAS,WAAW,SAAS,SAAS,SAAS;GAC/D,cAAc,UACZ,MACA,WAAW,OAAO,UAAU,YAAY,MAC1C;EACF,CAAC;CACH;CAEA,MAAM,aAAqC,eAClC;EACL,eAAe,CAAC;EAChB,UAAU,CAAC;EACX,aAAa;EACb;EACA,QAAQ;GACN;GACA;GACA,aAAa;GACb,OAAO;GACP,cAAc;GACd;EACF;EACA,MAAM;GACJ;GACA,eAAe;GACf;GACA;EACF;EACA,eAAe,CAAC;EAChB,MAAM,EAAQ,KAAa;EACjB;EACV,QAAQ;EACR,aAAa,CAAC;EACd,uBAAuB,CAAC;EACxB,MAAM,CAAC;EACP,OAAO;CACT,IACA;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CACF,CACF;CAKA,MAAM,CAAC,sBAAsB,eAAe,IAAI,QAAkB,CAAC,CAAC,CAAC;CACrE,MAAM,gBAAgB,eACb;EACL;EACA;EACA,sBAAsB,CAAC;EACvB,oBAAoB,CAAC;EACrB,yBAAyB;EACzB,gCAAgC;EAChC,2BAA2B,SAAiB;EAC5C;EACA,oCAAoC,CAAC;EACrC;EACA,eAAe,YAAY,CAAC;EAC5B,2BAA2B,CAAC;EAC5B,eAAe,YAAY,CAAC;EAC5B,sBAAsB;EACtB,0BAA0B,CAAC;EAC3B;EACA;EACA;CACF,IACA;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CACF,CACF;CAEA,MAAM,CAAC,aAAa,gBAAgB;EAClC,WAAW,YAAY,CAAC;EACxB,aAAa,YAAY,CAAC;EAC1B,iBAAiB,CAAC;CACpB,EAAE;CAEF,OACE,oBAAC,eAAD;EAAsB;YACpB,oBAAC,kBAAkB,UAAnB;GAA4B,OAAO;aACjC,oBAAC,cAAD,EAAA,UACE,oBAAC,iBAAiB,UAAlB;IAA2B,OAAO;cAChC,oBAAC,sBAAD;KAAmC;eACjC,oBAAC,oBAAoB,UAArB;MAA8B,OAAO;gBACnC,oBAAC,yBAAD;OACE,WAAW;OACX,YAAY;OACZ,gBAAgB,CAAC,IAAI,QAAQ;iBAE7B,oBAAC,oBAAD;QAAoB,OAAO;kBACzB,oBAAC,UAAD;SACiB;SACL;SACV,UAAU;SAET;QACO,CAAA;OACQ,CAAA;MACG,CAAA;KACG,CAAA;IACV,CAAA;GACG,CAAA,EACf,CAAA;EACY,CAAA;CACf,CAAA;AAEnB;;;;;;;;;;;;;;AAeA,IAAM,YACJ,UAKG;CACH,MAAM,EAAE,eAAe,eAAe,UAAU,UAAU,aAAa;CACvE,MAAM,EAAE,gBAAgB,WAAW,mBAAmB;CACtD,MAAM,UAAU,oBAAC,UAAD;EAAoB;EAAW;CAAmB,CAAA;CAElE,IAAI,CAAC,eACH,OAAO;CAGT,OACE,oBAAC,GAAD;EACE,mBAAmB;EACnB,WAAW,CAAC,QAAQ;EACpB,SAAS;YAER;CACY,CAAA;AAEnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gemi",
-  "version": "0.59.0",
+  "version": "0.61.0",
   "private": false,
   "license": "MIT",
   "author": "Enes Tufekci <enes@gemijs.dev>",
@@ -15,12 +15,15 @@
   },
   "files": [
     "dist/**/*",
-    "ide/typescript-plugin/package.json"
+    "ide/typescript-plugin/package.json",
+    "skills/**/*"
   ],
   "module": true,
   "exports": {
     "./http": "./dist/http/index.js",
     "./client": "./dist/client/index.js",
+    "./ai": "./dist/ai/index.js",
+    "./ai/client": "./dist/ai/client/index.js",
     "./testing": "./dist/testing/index.js",
     "./app": "./dist/app/index.js",
     "./facades": "./dist/facades/index.js",

package/skills/gemi-react-best-practices/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: gemi-react-best-practices
+description: Best practices for the gemi framework (Bun + Vite + React 19 SSR full-stack TypeScript framework) — routing, controllers, the ORM, the SSR data payload, useQuery, i18n, jobs/services, and testing. Use when writing, reviewing, or refactoring anything under app/ — views, routers, controllers, models, dictionaries — or when a task mentions slow pages, extra round-trips, N+1 queries, bundle size, or re-renders.
+---
+
+# gemi Best Practices
+
+Rules for building on **gemi**, the full-stack TypeScript framework this app runs on
+(Bun + Vite, React 19 SSR). 45 rules across 11 categories, ordered by impact.
+
+Every rule is derived from the gemi documentation and from patterns that recur across
+gemi codebases. This skill ships with the `gemi` package, so it describes the
+framework; where it and your app disagree, your app wins (ground rule 2).
+
+## When to Apply
+
+- Adding or changing a route, view, layout, controller, or middleware
+- Writing a `useQuery` read, a mutation, or a `Query.prefetch`
+- Writing ORM queries — especially list reads, aggregations, and transactions
+- Adding a Job, Service, or one-off Command
+- Writing dictionaries or tests
+- Diagnosing extra round-trips, slow first paint, blank flashes, or bundle growth
+
+## Ground Rules That Precede Everything Below
+
+1. **Fetch the docs; do not guess an API.** Index (page list + one-line summaries):
+   <https://nstfkc.github.io/gemi/llms.txt> — fetch only the pages you need.
+   Everything in one file: <https://nstfkc.github.io/gemi/llms-full.txt> (~170 KB).
+2. **`CLAUDE.md` in this app wins** where it and either the docs or this skill
+   disagree — it describes *our* app, not the framework in general.
+3. **Mirror existing code.** Don't invent gemi patterns. When a rule here and an
+   existing pattern disagree, check git history before "fixing" it.
+4. **Routing is class-based and data is loaded in controllers.** File location
+   registers nothing; a view's file name has no relation to its URL.
+5. **Check whether the React Compiler is on before hand-memoizing.** It is enabled
+   per app in `gemi.config.ts` via the React plugin's `compiler` option, which the
+   gemi template turns on by default — and `GEMI_REACT_COMPILER=off` in the
+   environment disables it, so the config is not the last word. With it on, the client build is
+   auto-memoized and a hand-written `useMemo` is usually redundant; with it off,
+   memoization is manual and load-bearing. The compiler never runs on the SSR view
+   build — server rendering is a single pass — so it changes nothing about what a
+   controller does.
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 0 | Project Structure | HIGH | `structure-` |
+| 1 | Server Payload & Waterfalls | CRITICAL | `payload-` |
+| 2 | Client Data Fetching | CRITICAL | `query-` |
+| 3 | Data Access (ORM) | HIGH | `orm-` |
+| 4 | Routing & Middleware | HIGH | `routing-` |
+| 5 | Controllers & Request Handling | HIGH | `controller-` |
+| 6 | Services, Jobs & Commands | HIGH | `service-` |
+| 7 | Client Components & Navigation | MEDIUM | `client-` |
+| 8 | Bundle Size | MEDIUM | `bundle-` |
+| 9 | Internationalization | MEDIUM | `i18n-` |
+| 10 | Testing | MEDIUM | `testing-` |
+
+## Project Structure
+
+Everything the framework guarantees lives under `app/`. This is the layout a
+scaffolded project has; the parts marked *discovered* are read by walking the
+directory, so writing the file is the registration.
+
+```
+app/
+  server.ts            server entry - boots the kernel, starts the HTTP server
+  client.tsx           browser entry - hydrates the React app
+  preload.ts           optional Bun preload, runs before the server starts
+  kernel/Kernel.ts     declares `config`, `providers`, and `models`
+  config/              runtime config, one file per framework service
+  providers/           your own container bindings
+  http/
+    routes/            api.ts and view.ts - the root routers
+    controllers/       controller classes
+    requests/          HttpRequest subclasses used for validation
+  models/              ORM models  (declared on the Kernel)
+    generated/         OUTPUT - never hand-edit
+  views/               React views, layouts, RootLayout  (path is NOT the URL)
+  email/               jsx-email templates
+  i18n/                dictionaries
+  cron/                CronJob classes        <- discovered at boot
+  jobs/                Job classes            <- discovered at boot
+  listeners/           Listener classes       <- discovered at boot
+  commands/            defineCommand chains   <- discovered by `gemi run`
+  database/prisma.ts   the Prisma client instance
+```
+
+`app/listeners/` is absent from a fresh scaffold; that is not an error, it means
+the app has no listeners yet.
+
+### Where a new file goes
+
+| Adding a… | Goes in | Reached by |
+|---|---|---|
+| page / layout | `app/views/` | a **router**, never its file path |
+| URL, or middleware on one | `app/http/routes/` | mounted from `view.ts` / `api.ts` |
+| handler logic for a route | `app/http/controllers/` | named by a router |
+| request validation | `app/http/requests/` | named by a controller method |
+| ORM model | `app/models/` | the Kernel's `models` |
+| background work | `app/jobs/` | discovery |
+| scheduled work | `app/cron/` | discovery |
+| event handler | `app/listeners/` | discovery |
+| one-off ops task | `app/commands/` | discovery, via `gemi run` |
+| anything with I/O, a client, or state | `app/services/` | the container, by `static token` |
+| container bindings | `app/providers/` | the Kernel's `providers` |
+| settings for a framework service | `app/config/` | the Kernel's `config` |
+| translations | `app/i18n/` | `defineDictionary` |
+| build config (Vite/Bun plugins) | `gemi.config.ts` **at the root** | the CLI — *not* `app/config/` |
+
+Two mistakes this table exists to prevent, both of which typecheck and then do
+nothing: putting a view at a path that looks like its URL and expecting it to
+route, and writing a model without declaring it on the Kernel. See
+`structure-discovered-vs-registered` and `structure-do-not-reinvent-the-framework`.
+
+## Quick Reference
+
+### 0. Project Structure (HIGH)
+
+- `structure-discovered-vs-registered` - Four directories register by being walked; models, routers, config and providers are declared
+- `structure-do-not-reinvent-the-framework` - `lib/`, a singleton, a hand-rolled registry: gemi already has each of these with a name
+
+### 1. Server Payload & Waterfalls (CRITICAL)
+
+The biggest lever in the app. gemi ships a data payload with the SSR HTML; every read
+the client discovers only after hydration costs a round-trip the payload could have
+carried for free.
+
+- `payload-prefetch-mirrors-usequery` - A prefetch lands only if path + params + search match the cache key exactly
+- `payload-prefetch-late-queries` - Prefetch reads render discovers late (nested under suspense, conditionally rendered)
+- `payload-instant-vs-prefetch` - `Query.instant` blocks the response; `Query.prefetch` runs in parallel
+- `payload-parallel-controller-work` - `Promise.all` independent work in a controller method
+- `payload-dont-overprefetch` - Popover and heavy-collection reads belong behind a mount gate
+- `payload-minimal-view-props` - Ship the shape the view renders, not the row you loaded
+
+### 2. Client Data Fetching (CRITICAL)
+
+- `query-no-hand-rolled-fetch` - `useQuery` / mutation hooks, never a raw `fetch`
+- `query-suspense-default` - `suspense: true` is the DEFAULT and throws to the nearest boundary
+- `query-lazy-vs-mount-gate` - A lazy query does not refetch when its variant changes
+- `query-share-cache-key` - Identical path + params + search dedupes across components for free
+- `query-keep-previous-data` - Keep the previous page rendered while the next variant loads
+- `query-mutate-over-refetch` - Write the cache with `mutate` / `useMutate` instead of refetching
+- `query-debounce-search-variant` - Debounce a value before it becomes a query variant
+- `query-revalidate-on-focus` - Opt in only for cross-tab-mutable data; let `staleTime` gate it
+
+### 3. Data Access — ORM (HIGH)
+
+- `orm-include-not-n-plus-one` - One `include` tree beats a loop of queries (lateral strategy = one round trip)
+- `orm-transaction-sequential` - `Promise.all` inside `Model.transaction` is unsafe — one reserved connection
+- `orm-transaction-no-io` - Keep network calls, uploads and queue pushes out of a transaction callback
+- `orm-analytics-connection` - Heavy admin/cron aggregations run on the analytics pool
+- `orm-paginate-helper` - Use `paginate()` from `gemi/orm`; know its 100-row ceiling
+- `orm-select-narrow` - `select` the columns the response actually serializes
+- `orm-plain-rows-by-default` - Plain rows are free; `track` costs ~100% on a large read
+
+### 4. Routing & Middleware (HIGH)
+
+- `routing-routers-are-classes` - Routes are declared on router classes, not by file location
+- `routing-middleware-dsl` - Middleware is a string DSL at router or route level; `-name` cancels
+- `routing-cache-policy-constants` - Name cache policies once and reuse the constant
+- `routing-resource-routes` - `resource()` for standard REST, with per-method middleware
+
+### 5. Controllers & Request Handling (HIGH)
+
+- `controller-request-schema` - Validate with a request schema, not inline checks
+- `controller-throw-framework-errors` - Throw `ValidationError` / auth errors; never invent a response shape
+- `controller-redirect-facade-throws` - Never wrap the `Redirect` facade in try/catch — it works by throwing
+- `controller-authorize-every-tenant-read` - Scope every tenant read, in middleware or an ORM policy
+- `controller-parse-request-at-the-boundary` - Parse the request in the controller; keep utils framework-free
+
+### 6. Services, Jobs & Commands (HIGH)
+
+- `service-static-token-and-name` - `static token` / `static name` survive minification; class names do not
+- `service-queue-is-in-memory` - The queue is in-process; enqueued work is lost on restart
+- `service-lazy-not-module-scope` - Construct clients lazily — discovery imports every module
+
+### 7. Client Components & Navigation (MEDIUM)
+
+- `client-typed-links` - Navigate with a typed `Link` / `useNavigate`, not an interpolated path
+- `client-form-vs-mutation-hooks` - `<Form>` first; mutation hooks when you need control
+- `client-loading-error-exports` - A route module's `Loading` / `Error` exports ARE its suspense boundary
+- `client-no-effect-data-flow` - Derive in `useMemo`, reset in the handler, debounce before use
+
+### 8. Bundle Size (MEDIUM)
+
+- `bundle-deep-imports` - Import UI primitives by deep path; a barrel drags the whole library in
+- `bundle-mount-gate-heavy-panels` - Put heavy subtrees inside the thing that unmounts them
+
+### 9. Internationalization (MEDIUM)
+
+- `i18n-define-dictionary-inline` - The `defineDictionary` literal must be inline — a helper fails the BUILD
+
+### 10. Testing (MEDIUM)
+
+- `testing-page-seeds-real-inputs` - Mount with `<Page>` from `gemi/testing`; never mock `gemi/client`
+- `testing-assert-behaviour-over-markup` - Query the DOM; don't scrape `renderToStaticMarkup` output
+- `testing-match-the-suite` - Copy the runner and naming already in the directory; component tests need a DOM
+
+## The Gotchas Most Likely to Bite
+
+Counter-intuitive behaviours that produce silent failures rather than errors:
+
+| Gotcha | Rule |
+|---|---|
+| `Redirect` works by **throwing** — a `try/catch` swallows it | `controller-redirect-facade-throws` |
+| A `defineDictionary` behind a helper passes tests and fails the **build** | `i18n-define-dictionary-inline` |
+| `Promise.all` inside a transaction shares one reserved connection | `orm-transaction-sequential` |
+| A lazy query never refetches when its variant changes | `query-lazy-vs-mount-gate` |
+| A prefetch whose `search` differs primes a slot nothing reads | `payload-prefetch-mirrors-usequery` |
+| A class name is minified in prod — jobs and services need a static string | `service-static-token-and-name` |
+| `paginate()` silently caps `perPage` at 100 | `orm-paginate-helper` |
+| Command discovery **imports** every file under `app/commands` | `service-lazy-not-module-scope` |
+| A suspending query blanks everything up to the nearest boundary | `query-suspense-default` |
+| Returning `{ error }` from a controller is a **200** the client reads as success | `controller-throw-framework-errors` |
+
+## How to Use
+
+Read a rule file for the full explanation and examples:
+
+```
+rules/payload-prefetch-mirrors-usequery.md
+rules/orm-transaction-sequential.md
+```
+
+Each contains a short why, an incorrect example, a correct example, and — where one
+exists — a link to the gemi documentation page that covers it.
+
+`rules/_sections.md` holds the category metadata; `rules/_template.md` is the shape a
+new rule follows.

package/skills/gemi-react-best-practices/rules/_sections.md

@@ -0,0 +1,56 @@
+# Sections
+
+The section ID (in parentheses) is the filename prefix used to group rules.
+Rules are sorted by title within a section. Files starting with `_` are not rules.
+
+---
+
+## 1. Server Payload & Waterfalls (payload)
+
+**Impact:** CRITICAL
+**Description:** gemi renders on the server and ships a data payload with the HTML. Every read the client discovers only after hydration costs a full round-trip the payload could have carried. This is the largest lever in the app.
+
+## 2. Client Data Fetching (query)
+
+**Impact:** CRITICAL
+**Description:** `useQuery` defaults (suspense on, keepPreviousData on, 5s staleTime, focus revalidation off) are opinionated. Fighting them — or not knowing them — produces blank flashes, dead pagination, and duplicate requests.
+
+## 3. Data Access — ORM (orm)
+
+**Impact:** HIGH
+**Description:** The ORM is Prisma-typed but gemi-executed, with its own relation-loading strategies, transaction semantics, connection selection, and row-provenance model. Its constraints are not Prisma's.
+
+## 4. Routing & Middleware (routing)
+
+**Impact:** HIGH
+**Description:** Routing is class-based: routers declare a routes object, and middleware attaches as a string DSL. This is where a URL, its cache policy, and its auth boundary are all defined.
+
+## 5. Controllers & Request Handling (controller)
+
+**Impact:** HIGH
+**Description:** Controllers hold server logic and own the request boundary — validation, authorization, error shape. The client's error handling is a contract with what a controller throws.
+
+## 6. Services, Jobs & Commands (service)
+
+**Impact:** HIGH
+**Description:** Long-lived singletons, background work, and one-off ops. Most failures here are invisible in development and appear only in the production build or on a restart.
+
+## 7. Client Components & Navigation (client)
+
+**Impact:** MEDIUM
+**Description:** React 19 SSR with hydration. Typed navigation, forms, suspense boundaries declared by route module exports, and data flow that does not go through effects.
+
+## 8. Bundle Size (bundle)
+
+**Impact:** MEDIUM
+**Description:** Vite code-splits per route chunk. Client cost is determined by which module graph a route pulls in and where a heavy subtree is mounted.
+
+## 9. Internationalization (i18n)
+
+**Impact:** MEDIUM
+**Description:** Two dictionary systems coexist. The newer one is rewritten at build time by a Vite plugin, which constrains how it may be written.
+
+## 10. Testing (testing)
+
+**Impact:** MEDIUM
+**Description:** Views mount for real with seeded framework inputs, through `<Page>` from `gemi/testing`. Match whichever runner and naming convention the directory already uses — a test the runner never selects is a test that does not exist.

package/skills/gemi-react-best-practices/rules/_template.md

@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)

package/skills/gemi-react-best-practices/rules/bundle-deep-imports.md

@@ -0,0 +1,48 @@
+---
+title: Import UI Primitives By Deep Path
+impact: HIGH
+impactDescription: keeps a component library's dependencies out of routes that do not use it
+tags: bundle, imports, barrel, ui
+---
+
+## Import UI Primitives By Deep Path
+
+A component library where every primitive is its own module — the shadcn/ui shape,
+and the shape most in-repo `packages/ui` workspaces take — should be imported by deep
+path. A route then pulls in exactly the primitives it uses.
+
+A barrel import, or adding a barrel that re-exports everything, pulls the whole
+library and its transitive dependencies (for a Radix-based kit, ~25 packages) into
+every route that touches one button. Tree-shaking does not reliably save you here:
+the library is often source-only with no build step, and a single side-effecting
+module in the barrel's graph defeats it.
+
+**Incorrect (drags the library in):**
+
+```tsx
+import { Button, Input, Badge } from "@acme/ui";
+```
+
+**Correct (one module each):**
+
+```tsx
+import { Button } from "@acme/ui/components/ui/button";
+import { Input } from "@acme/ui/components/ui/input";
+import { Badge } from "@acme/ui/components/ui/badge";
+import { cn } from "@acme/ui/lib/utils";
+```
+
+**Do not add a barrel** to make the imports shorter. The deep paths are the
+mechanism, not a style preference.
+
+Two related notes:
+
+- **Check whether your repo has a legacy copy.** A local `app/views/components/ui`
+  alongside a shared `packages/ui` means two divergent sets of the same primitives;
+  pick the shared one and say so in `CLAUDE.md`.
+- **Keep import paths statically analyzable.** A computed specifier defeats
+  tree-shaking and widens what the build has to trace.
+
+This matters more under gemi than under a bundler that ships one chunk: each view is
+its own build entry (`preserveEntrySignatures: "strict"`), so a barrel import in one
+view inflates that view's chunk and every chunk that shares its graph.

package/skills/gemi-react-best-practices/rules/bundle-mount-gate-heavy-panels.md

@@ -0,0 +1,63 @@
+---
+title: Put Heavy Subtrees Inside the Thing That Unmounts Them
+impact: HIGH
+impactDescription: ~47 kB and two queries off the initial load, measured
+tags: bundle, mounting, radix, queries
+---
+
+## Put Heavy Subtrees Inside the Thing That Unmounts Them
+
+The cheapest work is work that never mounts. **Let an unmounted subtree be the
+gate**: Radix `PopoverContent`, `DialogContent`,
+`DropdownMenuContent` and the tab primitives do not render their children while
+closed. A component placed inside them costs nothing until the user opens the thing.
+
+Hoisting a query or a heavy component *above* that boundary "to keep the parent
+tidy" is how it starts running on every page load for a panel nobody opened. In this
+app that cost ~47 kB resolved across two reads, on every load of the customer app.
+
+**Incorrect (reads run on every page load to fill a closed popover):**
+
+```tsx
+function ProductPicker() {
+  const { data: products } = useQuery("/app/:orgId/products/search", { params });
+  const { data: lists } = useQuery("/app/:orgId/lists", { params });
+
+  return (
+    <Popover>
+      <PopoverTrigger>Add product</PopoverTrigger>
+      <PopoverContent>
+        <CatalogSearchPanel products={products} lists={lists} />
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+**Correct (the reads move down, inside the content Radix unmounts):**
+
+```tsx
+function ProductPicker() {
+  return (
+    <Popover>
+      <PopoverTrigger>Add product</PopoverTrigger>
+      <PopoverContent>
+        <CatalogSearchPanel orgId={orgId} />
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+function CatalogSearchPanel({ orgId }: { orgId: string }) {
+  const { data: products = [] } = useQuery(/* … */, { suspense: false });
+  const { data: lists = [] } = useQuery(/* … */, { suspense: false });
+}
+```
+
+**Why mounting rather than `{ lazy: true }`:** a lazy query does not refetch when
+its variant changes, so a searchable or paginated read breaks under it — see
+`query-lazy-vs-mount-gate`.
+
+**For a genuinely heavy module** (a chart library, an editor, a PDF renderer) plain
+`React.lazy` + `Suspense` is the right tool; gemi ships no wrapper of its own for
+it, and none is needed.