;\n\ninterface NextAppAvsbServer {\n forUser(ctx: EvalContext): RequestBoundClient;\n}\n\ninterface NextAppMiddlewareOptions {\n contextFrom(req: Request): EvalContext | undefined;\n withDecisionLog?: boolean;\n}\n```\n\n### `@avsbhq/next/pages`\n\n```ts\nfunction getServerSideAvsb = Record>(\n options: GetServerSideAvsbOptions,\n handler?: (avsbCtx: AvsbGsspContext) => Promise<{ props: P }>,\n): (gsspCtx: GsspContext) => Promise>;\n\ninterface GetServerSideAvsbOptions {\n sdkKey: string;\n cdnHost?: string;\n contextFrom?: (ctx: GsspContext) => EvalContext;\n cookie?: AnonCookieOptions;\n}\n\n/** The slice of Next's `GetServerSidePropsContext` this helper needs. */\ninterface GsspContext {\n req: {\n headers: Record;\n cookies?: Record;\n url?: string;\n };\n res?: {\n setHeader(name: string, value: string | string[]): void;\n getHeader?(name: string): string | string[] | number | undefined;\n };\n params?: Record;\n query?: Record;\n [key: string]: unknown;\n}\n\n/** What the optional inner handler receives. */\ninterface AvsbGsspContext {\n datafile: FlagDatafile;\n /** Evaluated flags as `Flag` objects, methods included, for server logic. */\n flags: Record;\n context: EvalContext;\n gsspCtx: GsspContext;\n}\n\ninterface GsspResult> {\n props: P & { avsbBootstrap: AvsbPagesBootstrap };\n}\n\n/** The prop to spread into `` in `_app.tsx`. */\ninterface AvsbPagesBootstrap {\n sdkKey: string;\n context: EvalContext;\n bootstrap: FlagDatafile;\n serverFlags: SerializedFlagMap;\n}\n```\n\n### `@avsbhq/next` (client)\n\n```ts\nfunction AvsbProvider(props: AvsbNextProviderProps): ReactElement;\n\ninterface AvsbNextProviderProps extends Omit<\n AvsbClientOptions,\n 'sdkKey' | 'context' | 'bootstrap'\n> {\n sdkKey: string;\n context?: EvalContext;\n bootstrap?: FlagDatafile;\n serverFlags?: SerializedFlagMap;\n children: ReactNode;\n}\n\nfunction readBootstrapBlob(): AvsbBootstrapBlob | null;\nfunction contextFromBlob(blob: AvsbBootstrapBlob | null): EvalContext | undefined;\n```\n\nPlus every hook from `@avsbhq/react`: `useFlag`, `useFlagValue`, `useBoolFlag`, `useStringFlag`, `useNumberFlag`, `useJsonFlag`, `useAllFlags`, `useFlagSuspense`, `useFlagChange`, `useFlagSubscription`, `useExposure`, `useAvsbStatus`, `useFlagReady`, `useAvsbClient`, `useAvsbClientSuspense`, `useIdentify`, `useAlias`, `useReset`, `useTrack`. Their signatures and the `Flag` shape are documented in the `@avsbhq/react` README.\n\n### Typed flag keys\n\nEvery `flagKey` above is `string` until you generate your keys. Generate them\nand it becomes the union of this project's real flag keys, so a typo is a\ncompile error and your editor completes the list:\n\n```bash\nnpx avsb codegen --output src/generated/flags.ts\n```\n\nThe generated file declares your flags twice on purpose: an importable\n`FlagValues` interface for payload types, and a `declare global` block that\nteaches every hook, and `evaluateFlagServer`, which keys exist. Its important\nparts:\n\n```text\n// AUTO-GENERATED by @avsbhq/cli codegen. Do not edit by hand.\n\nexport interface FlagValues {\n 'checkout-v2': boolean\n 'hero-copy': 'control' | 'variant-a'\n 'theme': { primary: string }\n}\n\ndeclare global {\n interface AvsbFlags {\n 'checkout-v2': boolean\n 'hero-copy': 'control' | 'variant-a'\n 'theme': { primary: string }\n }\n}\n```\n\n```ts\nimport { useBoolFlag, useJsonFlag } from '@avsbhq/next';\nimport type { FlagValues } from './generated/flags';\n\nfunction useCheckoutFlags() {\n const checkout = useBoolFlag('checkout-v2', false);\n\n // A JSON flag types its payload from the generated table:\n const theme = useJsonFlag('theme', { primary: '#111' });\n\n // Once the generated file exists, this line stops compiling:\n // 'chekcout-v2' is not a flag key.\n const typo = useBoolFlag('chekcout-v2', false);\n\n return { checkout, theme };\n}\n```\n\nThe server side narrows the same way: the third argument of\n`evaluateFlagServer(datafile, ctx, flagKey, defaultValue)` is the same key type.\n\nNothing changes for a project that never runs `codegen`: with no generated file\nthe table is empty, every `flagKey` is exactly `string`, and every call you have\nalready written compiles unchanged. For a key computed at runtime, such as one\nread from a loop over the datafile, widen deliberately with\n`key as AvsbFlagKey` (that type is exported from `@avsbhq/core`).\n\n---\n\n## 5. Server Components\n\n`evaluateFlagServer` is a pure function: no network, no state, no side effects. Call it as often as you like inside one render.\n\n```tsx\n// app/pricing/page.tsx\nimport { getDatafile, evaluateFlagServer } from '@avsbhq/next/server';\nimport type { Flag } from '@avsbhq/next/server';\n\nexport default async function PricingPage() {\n const datafile = await getDatafile(process.env.AVSB_SDK_KEY ?? '');\n const context = { kind: 'user' as const, key: 'u_123', plan: 'pro' };\n const flag: Flag = evaluateFlagServer(datafile, context, 'pricing-experiment', 'control');\n\n if (flag.variationKey === 'usage-based') return ;\n return ;\n}\n```\n\n`getDatafile` is deduplicated within a request and cached across requests for `revalidate` seconds (60 by default), so ten server components asking for the same key cost one fetch.\n\n### Server evaluation and exposures\n\nServer evaluation fires no exposures, on purpose: an RSC render is not proof a person saw anything. Pair it with `useExposure` in the client component that renders the variation.\n\n```tsx\n// app/pricing/page.tsx (server)\nexport default async function PricingPage() {\n const datafile = await getDatafile(process.env.AVSB_SDK_KEY ?? '');\n const context = { kind: 'user' as const, key: 'u_123' };\n const flag = evaluateFlagServer(datafile, context, 'pricing-experiment', 'control');\n\n return ;\n}\n```\n\n```tsx\n// app/PricingPanel.tsx (client)\n'use client';\nimport { useExposure } from '@avsbhq/next';\n\nexport function PricingPanel({ variation }: { variation: string }) {\n useExposure('pricing-experiment');\n return variation === 'usage-based' ? : ;\n}\n```\n\nWithout that pairing, a server-rendered variant is invisible in your results.\n\n---\n\n## 6. Identity\n\n`` uses the `avsb_anon_id` cookie for anonymous visitors, so the server render and the browser bucket the same person. Pass `context` once you know who they are:\n\n```tsx\nimport { AvsbRoot } from '@avsbhq/next/server';\nimport { auth } from './lib/auth';\n\nexport default async function RootLayout({ children }: { children: React.ReactNode }) {\n const session = await auth();\n const context = session\n ? { kind: 'user' as const, key: session.userId, plan: session.plan }\n : undefined;\n\n return (\n \n \n {children}\n \n \n );\n}\n```\n\nOmitting `context` keeps the anonymous cookie. Passing it makes the server and the client evaluate the same identified user.\n\n---\n\n## 7. Middleware\n\n```ts\n// middleware.ts\nimport { NextResponse } from 'next/server';\nimport type { NextRequest } from 'next/server';\nimport { withAvsb } from '@avsbhq/next/middleware';\nimport { server } from './lib/avsbServer';\n\nexport const middleware = withAvsb(\n (request: NextRequest) => {\n if (request.nextUrl.pathname === '/old') {\n return NextResponse.redirect(new URL('/new', request.url));\n }\n return undefined;\n },\n {\n server,\n contextFrom: (request: NextRequest) => ({\n kind: 'user',\n key: request.cookies.get('uid')?.value ?? 'anon',\n }),\n },\n);\n\nexport const config = { matcher: ['/((?!_next|.*\\\\..*).*)'] };\n```\n\nWhat it guarantees:\n\n- Your middleware's return value passes through untouched. Return nothing and the request continues, exactly like `NextResponse.next()`.\n- The anonymous visitor cookie is maintained on whatever response goes out, redirects included.\n- With `server` and `contextFrom`, the request runs inside an evaluation scope, so `getRequestClient()` from `@avsbhq/utils` works downstream.\n\nOne honest limit: that scope covers the middleware chain, route handlers, and server actions. It does **not** reach React Server Component renders, which Next.js runs separately. For RSCs, evaluate with `evaluateFlagServer` or let `` do it.\n\nFor route handlers there is also `nextAppHandler(server, options, handler)`, which opens the same scope per request.\n\n---\n\n## 8. Pages Router\n\n```tsx\n// pages/checkout.tsx\nimport { getServerSideAvsb } from '@avsbhq/next/pages';\n\nexport const getServerSideProps = getServerSideAvsb({\n sdkKey: process.env.AVSB_SDK_KEY ?? '',\n});\n\nexport default function CheckoutPage() {\n return ;\n}\n```\n\n```tsx\n// pages/_app.tsx\nimport { AvsbProvider } from '@avsbhq/next';\nimport type { AppProps } from 'next/app';\n\nexport default function App({ Component, pageProps }: AppProps) {\n const { avsbBootstrap, ...rest } = pageProps;\n return (\n \n \n \n );\n}\n```\n\n`props.avsbBootstrap` is exactly the provider's props: the key, the context that was evaluated, the datafile, and the evaluated values. An inner handler still gets `Flag` objects for server-side branching:\n\n```ts\nexport const getServerSideProps = getServerSideAvsb(\n { sdkKey: process.env.AVSB_SDK_KEY ?? '' },\n async ({ flags }) => ({\n props: { showBanner: flags['show-banner']?.isEnabled() ?? false },\n }),\n);\n```\n\n---\n\n## 9. The bootstrap blob\n\n`` writes one, and you rarely need to think about it. Render `` yourself only when your provider lives outside the `AvsbRoot` subtree:\n\n```tsx\nimport { AvsbHydrator } from '@avsbhq/next/server';\n\ndeclare const context: EvalContext;\n\n;\n```\n\nIt emits a `