tempest-react-sdk 0.79.0 → 0.81.0

package/README.md

@@ -1,7 +1,6 @@
 # tempest-react-sdk
 
 [![npm version](https://img.shields.io/npm/v/tempest-react-sdk.svg)](https://www.npmjs.com/package/tempest-react-sdk)
-[![CI](https://github.com/mauriciobenjamin700/tempest-react-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/mauriciobenjamin700/tempest-react-sdk/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![React 18 / 19](https://img.shields.io/badge/react-18%20%7C%2019-61dafb.svg?logo=react)](https://react.dev)
 [![TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6.svg?logo=typescript)](https://www.typescriptlang.org/)
@@ -43,6 +42,7 @@ The goal is to start every new React frontend with the same opinionated foundati
   - [Polling](#polling-recipe)
   - [Retry & idempotency](#retry--idempotency-recipe)
   - [Auth store (Zustand)](#auth-store-recipe)
+  - [Auth screens (login, sign-up, password reset)](#auth-screens-recipe)
   - [Route guard](#route-guard-recipe)
   - [JWT helpers & refresh queue](#jwt-helpers--refresh-queue-recipe)
   - [Code-splitting with retry](#code-splitting-with-retry-recipe)
@@ -267,7 +267,7 @@ Every module is re-exported from the package root — `import { Button, useDebou
 
 | Module                                                                                            | Exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `components`                                                                                      | `Avatar`, `Badge`, `Breadcrumbs`, `Button`, `Card`, `Checkbox`, `ChipInput`, `ConfirmDialog`, `Container`, `DatePicker`, `Drawer`, `EmptyState`, `ErrorState`, `FileUpload`, `Form` (`FormSection`, `FormRow`, `FormActions`), `Grid`, `Input`, `InstallBanner`, `InstallButton`, `Modal`, `Pagination`, `Progress`, `Radio`, `RadioGroup`, `SearchBar`, `Select`, `Skeleton`, `Spinner`, `Stack`, `Stepper`, `Switch`, `Table`, `Tabs`, `Textarea`, `Toast` (`ToastProvider`, `useToast`), `Tooltip`, `VirtualList`                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `components`                                                                                      | `AuthPage` + `AuthForm` with the presets `LoginForm`, `SignUpForm`, `ForgotPasswordForm`, `ResetPasswordForm` (auth screens from a list of fields), `Avatar`, `Badge`, `Breadcrumbs`, `Button`, `Card`, `Checkbox`, `ChipInput`, `ConfirmDialog`, `Container`, `DatePicker`, `Drawer`, `EmptyState`, `ErrorState`, `FileUpload`, `Form` (`FormSection`, `FormRow`, `FormActions`), `Grid`, `Input`, `InstallBanner`, `InstallButton`, `Modal`, `Pagination`, `Progress`, `Radio`, `RadioGroup`, `SearchBar`, `Select`, `Skeleton`, `Spinner`, `Stack`, `Stepper`, `Switch`, `Table`, `Tabs`, `Textarea`, `Toast` (`ToastProvider`, `useToast`), `Tooltip`, `VirtualList`                                                                                                                                                                                                                                                                                |
 | `hooks`                                                                                           | `useDebounce`, `usePagination`, `useClientFilter`, `useDraftFilters` (draft vs applied server-side filter), `useMediaQuery`, `useOnline`, `useDocumentVisibility`, `useIntersectionObserver`, `useResizeObserver`, `useClipboard`, `useKeyboardShortcut`, `useBeforeInstallPrompt`, `useIdle`, `useGeolocation`, `useScrollLock`, `useFocusTrap`, `useStableCallback`, `useAnnounce` (+ pure `announce`/`clearAnnouncer` — one shared live-region pair), `useDeepMemo`, `useObjectUrl`, `useLongPressHandlers` (spreadable long-press handlers + `wasLongPress()` guard), `useInstallPrompt` (install-method resolver with decline cooldown), `useServiceWorkerUpdate` (consent-based SW update flow), `useStorageEstimate` + `estimateStorage`/`requestPersistentStorage` (Storage API quota & persistence), PWA env helpers `isIOS`/`isAndroid`/`isAndroidWithoutPromptApi`/`isStandalone`/`buildOpenInChromeIntent`, type `BeforeInstallPromptEvent` |
 | `http`                                                                                            | `createApiClient`, `buildApiUrl`, `csrfHeaders`, `parseResponse`, `uploadWithProgress`, `createResumableUpload` (tus 1.0.0: chunked + resumable, `pause`/`resume`/`abort`), `createLocalUploadStorage`, `uploadFingerprint`, `retry`, `generateIdempotencyKey`, `usePoll`, types: `ApiClient`, `ApiClientConfig`, `ApiError`, `BuildApiUrlOptions`, `CsrfOptions`, `RequestOptions`, `RetryOptions`, `UploadProgressEvent`, `UploadWithProgressOptions`, `UsePollOptions`, `UsePollResult`                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `auth` _(peer: `zustand`)_                                                                        | `createAuthStore`, `AuthGuard`, `decodeJWT`, `isJWTExpired`, `lazyWithRetry`, `createRefreshQueue`, **passkeys/WebAuthn**: `createPasskeyClient`, `usePasskeyRegistration`, `usePasskeySignIn`, `usePasskeyCapabilities`, `isPasskeySupported`, `isPlatformAuthenticatorAvailable`, `isConditionalMediationAvailable`, `classifyPasskeyError`, `PasskeyError`, `base64UrlToBytes`, `bytesToBase64Url`, types: `AuthState`, `CreateAuthStoreOptions`, `AuthGuardProps`, `DecodedJWT`, `LazyWithRetryOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                             |
@@ -284,7 +284,7 @@ Every module is re-exported from the package root — `import { Button, useDebou
 | `geo` _(opt. peer `leaflet`)_                                                                     | `haversineKm`, `pathLengthKm`, `bearingDeg`, `estimateTravel`, `createOSRMBackend`, `boundingBox`, `projectMercator`, `fitProjection`, `createPositionTracker`, `usePositionTracker`, `TrajectoryMap` — tile-free SVG map + trajectory tracking (no external/paid API; Leaflet is an opt-in, lazy-loaded tile layer for self-hosted tiles), types: `Coordinate`, `TrackPoint`, `TravelEstimate`, `TravelMode`, `GeoBounds`, `RoutingBackend`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `br` _(subpath `tempest-react-sdk/br`)_                                                           | `BrazilMap`, `BrazilStateMap`, `BrazilStateCitySelect`, `listStates`, `getState`, `citiesByUf`, `statesByRegion`, `ufChoices`, `cityChoices`, `isValidUf`, `normalizeUf`, `isValidCity`, `loadBrUfGeoJson`, `loadStateMunicipalities`, types `UF`, `BrRegion`, `BrazilState` — clickable 27-UF SVG map + per-state municipality submaps (bundled simplified IBGE GeoJSON, lazy per UF) + states/cities dataset, no external API; mirrors the FastAPI SDK `utils/locations`                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `push`                                                                                            | `WebPushClient`, `WebPushUnsupportedError`, `WebPushPermissionDeniedError`, `usePushSubscription`, `urlBase64ToUint8Array`, `isPushSupported`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `sw` _(also subpath `tempest-react-sdk/sw`)_                                                      | `registerServiceWorker` (opt-in `autoUpdate` poll + reload, no `vite-plugin-pwa`), `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline + Navigation Preload), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue + `periodicsync`, credentials never stored), `provideBackgroundSyncCredentials`, `registerPeriodicSync` (main-thread periodic sync), `inspectCaches`/`clearCaches` (cache observability), `clearSessionData`/`clearBackgroundSyncQueue` (logout cleanup) — the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts`                                                                                                                                                 |
+| `sw` _(also subpath `tempest-react-sdk/sw`)_                                                      | `registerServiceWorker` (opt-in `autoUpdate` poll + reload, no `vite-plugin-pwa`), `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline + Navigation Preload), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue + `periodicsync`, credentials never stored and re-applied only to the worker's origin or `trustedOrigins`), `provideBackgroundSyncCredentials`, `registerPeriodicSync` (main-thread periodic sync), `inspectCaches`/`clearCaches` (cache observability), `clearSessionData`/`clearBackgroundSyncQueue` (logout cleanup) — the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts`                                                                                  |
 | `charts` _(subpath `tempest-react-sdk/charts`, opt. peer `recharts`)_                             | `AreaChart`, `BarChart`, `LineChart`, `PieChart`, `RadarChart`, `DEFAULT_CHART_COLORS` — themed recharts wrappers (recharts externalized; install it only if you use charts)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `icons` _(subpath `tempest-react-sdk/icons`)_                                                     | `Icon`, `IconProvider`, `createIconRegistry`, `useIcon`, `preloadIcons`, `iconStatus`, `peekIcon`, `loadIcon`, `resolveIconAlias`, `isIconName`, `iconNames`, `iconAliases`, type `IconName` — render any of lucide's **2065 icons by kebab-case slug**. A literal slug becomes a static import via the `tempestIcons()` Vite plugin (zero extra requests); a runtime slug loads **one of 46 balanced shards** (40 slugs each) instead of the ~2000 chunk boundaries `lucide-react`'s own `DynamicIcon` forces — sharding by range rather than by initial letter took the worst fetch from 19.10 KB to 4.78 KB brotli. Unknown slug renders `fallback` and never throws; lucide's 258 deprecated aliases keep resolving                                                                                                                                                                                                                                 |
 | `neural` _(subpath `tempest-react-sdk/neural`, opt. peer `@sapphi-red/web-noise-suppressor`)_     | `isNeuralSuppressionSupported`, `prepareNeuralSuppressor`, `createNeuralSuppressor`, types `NeuralSuppressorAssets`, `NeuralSuppressor` — RNNoise noise suppression: a recurrent model in an `AudioWorklet` separates speech from non-speech on a 48 kHz context and hands back a denoised `MediaStreamTrack` to publish in place of the capture (peer externalized; install it only if you use neural)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
@@ -321,7 +321,7 @@ Every module is re-exported from the package root — `import { Button, useDebou
 | `br` _(subpath `tempest-react-sdk/br`)_                                                           | `BrazilMap`, `BrazilStateMap`, `BrazilStateCitySelect`, `listStates`, `getState`, `citiesByUf`, `statesByRegion`, `ufChoices`, `cityChoices`, `isValidUf`, `normalizeUf`, `isValidCity`, `loadBrUfGeoJson`, `loadStateMunicipalities`, types `UF`, `BrRegion`, `BrazilState` — clickable 27-UF SVG map + per-state municipality submaps (bundled simplified IBGE GeoJSON, lazy per UF) + states/cities dataset, no external API; mirrors the FastAPI SDK `utils/locations`                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `icons` _(subpath `tempest-react-sdk/icons`)_                                                     | `Icon`, `IconProvider`, `createIconRegistry`, `useIcon`, `preloadIcons`, `iconStatus`, `peekIcon`, `loadIcon`, `resolveIconAlias`, `isIconName`, `iconNames`, `iconAliases`, type `IconName` — render any of lucide's **2065 icons by kebab-case slug**. A literal slug becomes a static import via the `tempestIcons()` Vite plugin (zero extra requests); a runtime slug loads **one of 46 balanced shards** (40 slugs each) instead of the ~2000 chunk boundaries `lucide-react`'s own `DynamicIcon` forces — sharding by range rather than by initial letter took the worst fetch from 19.10 KB to 4.78 KB brotli. Unknown slug renders `fallback` and never throws; lucide's 258 deprecated aliases keep resolving                                                                                                                                                                                                                                 |
 | `push`                                                                                            | `WebPushClient`, `WebPushUnsupportedError`, `WebPushPermissionDeniedError`, `usePushSubscription`, `urlBase64ToUint8Array`, `isPushSupported`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `sw` _(also subpath `tempest-react-sdk/sw`)_                                                      | `registerServiceWorker` (opt-in `autoUpdate` poll + reload, no `vite-plugin-pwa`), `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline + Navigation Preload), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue + `periodicsync`, credentials never stored), `provideBackgroundSyncCredentials`, `registerPeriodicSync` (main-thread periodic sync), `inspectCaches`/`clearCaches` (cache observability), `clearSessionData`/`clearBackgroundSyncQueue` (logout cleanup) — the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts`                                                                                                                                                 |
+| `sw` _(also subpath `tempest-react-sdk/sw`)_                                                      | `registerServiceWorker` (opt-in `autoUpdate` poll + reload, no `vite-plugin-pwa`), `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline + Navigation Preload), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue + `periodicsync`, credentials never stored and re-applied only to the worker's origin or `trustedOrigins`), `provideBackgroundSyncCredentials`, `registerPeriodicSync` (main-thread periodic sync), `inspectCaches`/`clearCaches` (cache observability), `clearSessionData`/`clearBackgroundSyncQueue` (logout cleanup) — the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts`                                                                                  |
 | `editor` _(subpath `tempest-react-sdk/editor`, opt. peers `@tiptap/react`+`@tiptap/starter-kit`)_ | `RichTextEditor` — themed tiptap v3 rich-text editor with toolbar (tiptap externalized; install it only if you use the editor)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `vision` _(subpath `tempest-react-sdk/vision`, opt. peer `onnxruntime-web`)_                      | `Classifier`, `Detector`, `Segmenter`, `DetectClassify` (fused detect→classify pipeline, optionally with a segmentation stage) + `warmup()`, FP16 models, `cache` (Cache Storage), video/`VideoFrame` inputs, `raiseOnEmpty`/`NoDetectionsError`, `LetterboxPipeline`, `readFusionSpec` and results/labels/preprocess — on-device ONNX vision inference, vendored from `@mauriciobenjamin700/ort-vision-sdk-web` (onnxruntime-web externalized; install it only if you use vision). Plus browser capture primitives: `useCameraStream` (rear-camera `getUserMedia` + classified errors + `retry()`), `computeImageLuminance`/`isLuminanceAcceptable`/`LowLuminanceError`/`LUMINANCE_SAMPLE_MAX_EDGE` (BT.709 brightness), `useLiveLuminance` (live rAF sampling)                                                                                                                                                                                        |
 | `tabular` _(subpath `tempest-react-sdk/tabular`, opt. peer `onnxruntime-web`)_                    | `TabularPredictor`, `useTabularPredictor` — scikit-learn models exported by `tempest-fastapi-sdk`'s `export_sklearn_to_onnx`, running in the browser with no inference server. Offline by design: `fetchModelBytes`/`isModelCached`/`cacheModelBytes`/`clearModelCache` (Cache Storage, cache-first) plus `configureOrtAssets`/`ortAssetUrls`/`ORT_WASM_ASSETS` for the runtime's WebAssembly binaries, which ONNX Runtime Web fetches at session creation. Import the default `onnxruntime-web` entry — the WebGPU build has no `ai.onnx.ml` kernels                                                                                                                                                                                                                                                                                                                                                                                                   |
@@ -778,6 +778,37 @@ useAuthStore.getState().logout();
 
 The store exposes `user`, `token`, `isAuthenticated`, `setSession`, `setUser`, `setToken`, and `logout`. `isAuthenticated` is derived from `token` and rehydrates correctly after page reload.
 
+### Auth screens recipe
+
+The sign-in screen without hand-building the layout or the form: `AuthPage` is the shell (colored top + rounded sheet below 768 px, 50/50 brand panel and form above it, or a centered `card`), and `LoginForm` / `SignUpForm` / `ForgotPasswordForm` / `ResetPasswordForm` are generated from a list of fields and a zod schema. A 422 with `fields` lands on the matching inputs; any other error shows an `Alert`.
+
+```tsx
+import { AuthPage, LoginForm, createApiClient, useNavigate } from "tempest-react-sdk";
+
+const api = createApiClient({ baseURL: "/api" });
+
+export function LoginScreen() {
+  const navigate = useNavigate();
+  return (
+    <AuthPage
+      brand={<img src="/logo.svg" alt="Acme" width={96} height={96} />}
+      back="/"
+      title="Bem-vindo!"
+    >
+      <LoginForm
+        onSubmit={async (values) => {
+          await api.post("/auth/login", { body: values });
+          navigate("/", { replace: true });
+        }}
+        links={{ forgotPassword: "/recuperar-senha", signUp: "/cadastro" }}
+      />
+    </AuthPage>
+  );
+}
+```
+
+Full guide: [Auth screens](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/components/auth-screens/) · [Telas de autenticação](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/auth-screens/).
+
 ### Route guard recipe
 
 ```tsx

package/bin/lib/component/generate.test.mjs

@@ -15,10 +15,22 @@ import { fileURLToPath } from "node:url";
 
 import { ESLint } from "eslint";
 import ts from "typescript";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { componentFiles, normalizeComponentName } from "./generate.mjs";
 
+/**
+ * Gives the tests in this file 60 s instead of Vitest's 5 s default.
+ *
+ * Several of them build a TypeScript program (and, some, an ESLint instance)
+ * in-process over the generated files. That takes 3-5 s on an idle machine,
+ * right at the default, so a busy one — another suite, a model training — failed
+ * them by timeout while the code was correct: 5.1-5.7 s measured in three
+ * `make check` runs on 2026-11-01, load average between 21 and 48.
+ * `test/docs-guard.test.ts` gives its compile 120 s for the same reason.
+ */
+vi.setConfig({ testTimeout: 60_000 });
+
 const HERE = dirname(fileURLToPath(import.meta.url));
 const REPO = resolve(HERE, "..", "..", "..");
 const CLI = join(REPO, "bin", "tempest.mjs");

package/bin/lib/openapi/generate.hostile.test.mjs

@@ -4,11 +4,23 @@ import { fileURLToPath } from "node:url";
 import vm from "node:vm";
 
 import ts from "typescript";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 
 import { encodeIdSegment } from "../../../src/data";
 import { generate } from "./generate.mjs";
 
+/**
+ * Gives the tests in this file 60 s instead of Vitest's 5 s default.
+ *
+ * Several of them build a TypeScript program (and, some, an ESLint instance)
+ * in-process over the generated files. That takes 3-5 s on an idle machine,
+ * right at the default, so a busy one — another suite, a model training — failed
+ * them by timeout while the code was correct: 5.1-5.7 s measured in three
+ * `make check` runs on 2026-11-01, load average between 21 and 48.
+ * `test/docs-guard.test.ts` gives its compile 120 s for the same reason.
+ */
+vi.setConfig({ testTimeout: 60_000 });
+
 const require = createRequire(import.meta.url);
 /**
  * Transpile one generated TypeScript file and run it in a fresh VM context.
@@ -84,6 +96,8 @@ function spec(paths, schemas = {}) {
 }
 
 const OK = { 200: { description: "ok" } };
+const schemaRef = (name) => ({ $ref: `#/components/schemas/${name}` });
+const json = (schema) => ({ content: { "application/json": { schema } } });
 
 describe("generate — hostile spec text never becomes code (#434)", () => {
     it("a tag that closes the class doc comment stays inside it", async () => {
@@ -233,12 +247,45 @@ describe("generate — hostile spec text never becomes code (#434)", () => {
         await runGroup(files, "t");
     });
 
+    /**
+     * Rewritten for #516: this used to pass with `spec({}, …)`, two schemas no
+     * route reaches. The check now runs over the schemas a group emits, so the
+     * pair has to be referenced to collide — and still is refused, naming both.
+     */
     it("two schema names that map to the same identifier are refused, naming both", () => {
+        const both = {
+            200: json({ anyOf: [schemaRef("User-Out"), schemaRef("user.Out")] }),
+        };
         expect(() =>
-            generate(spec({}, { "User-Out": { type: "object" }, "user.Out": { type: "object" } })),
+            generate(
+                spec(
+                    { "/a": { get: { tags: ["t"], responses: both } } },
+                    { "User-Out": { type: "object" }, "user.Out": { type: "object" } },
+                ),
+            ),
         ).toThrow(/"User-Out" and "user\.Out" both map to the TypeScript identifier "UserOut"/);
     });
 
+    it("schema names no route reaches are neither emitted nor checked, so an orphan cannot abort the run (#516)", () => {
+        const { files } = generate(
+            spec(
+                {
+                    "/a": {
+                        get: { tags: ["t"], responses: { 200: json(schemaRef("MediaType")) } },
+                    },
+                },
+                {
+                    MediaType: { type: "string", enum: ["image/png"] },
+                    "Media-Type": { type: "string", enum: ["image/png", "image/webp"] },
+                    "***": { type: "object" },
+                },
+            ),
+        );
+        expect(files["t/types.ts"]).toContain("export type MediaType = ");
+        expect(files["t/schemas.ts"]).not.toContain("image/webp");
+        expect(files["t/types.ts"].match(/export type/g)).toHaveLength(1);
+    });
+
     it("a path parameter that maps onto another method argument is refused", () => {
         expect(() =>
             generate(
@@ -258,10 +305,16 @@ describe("generate — hostile spec text never becomes code (#434)", () => {
         ).toThrow(/"user-id" and "userId" both map to the TypeScript identifier "userId"/);
     });
 
+    /** Rewritten for #516 like the collision above: the schema is now referenced. */
     it("a name with nothing to build an identifier from is refused", () => {
-        expect(() => generate(spec({}, { "***": { type: "object" } }))).toThrow(
-            /schema name "\*\*\*" has no letter or digit/,
-        );
+        expect(() =>
+            generate(
+                spec(
+                    { "/a": { get: { tags: ["t"], responses: { 200: json(schemaRef("***")) } } } },
+                    { "***": { type: "object" } },
+                ),
+            ),
+        ).toThrow(/schema name "\*\*\*" has no letter or digit/);
     });
 
     it("a regex pattern with an escaped slash or a line break compiles to the same regex", () => {

package/bin/lib/openapi/generate.mjs

@@ -50,12 +50,88 @@ function methodName(op, method, path) {
 const CLASS_MEMBERS = ["constructor", "api"];
 
 /**
- * Names a generated method body uses besides its path parameters: the `body` and
- * `params` arguments, the `S` schemas import and the `encodeIdSegment` import. A
- * path parameter that maps to one of them becomes `<name>Param` (`{body}` →
- * `bodyParam`), so it neither duplicates an argument nor shadows the import.
+ * Names a generated method body uses besides its path parameters: the `body`,
+ * `params` and `headers` arguments, the `S` schemas import, the `encodeIdSegment`
+ * import and the module-level `headerRecord` helper. A path parameter that maps to
+ * one of them becomes `<name>Param` (`{body}` → `bodyParam`), so it neither
+ * duplicates an argument nor shadows the import.
  */
-const METHOD_LOCALS = new Set(["body", "params", "S", "encodeIdSegment"]);
+const METHOD_LOCALS = new Set([
+    "body",
+    "params",
+    "headers",
+    "S",
+    "encodeIdSegment",
+    "headerRecord",
+]);
+
+/**
+ * Header parameter names OpenAPI 3 says a generator SHALL ignore: the client sets
+ * `Accept` and `Content-Type` from the request it builds and `Authorization` from
+ * its `getToken`, so a spec that also declares them must not open a second way to
+ * send them. Compared case-insensitively, as HTTP header names are.
+ */
+const IGNORED_HEADERS = new Set(["accept", "content-type", "authorization"]);
+
+/**
+ * Module-level helper a `service.ts` declares when one of its methods sends header
+ * parameters. `fetch` turns a header value of `undefined` into the literal text
+ * `"undefined"`, and `RequestOptions.headers` only takes strings, so an optional
+ * header left out is dropped and every other value goes through `String()`.
+ */
+const HEADER_RECORD_HELPER = [
+    "/** Header parameters as strings, without the ones left out (`fetch` would send `undefined` as text). */",
+    "function headerRecord(",
+    "    values: Record<string, string | number | boolean | null | undefined>,",
+    "): Record<string, string> {",
+    "    const out: Record<string, string> = {};",
+    "    for (const [name, value] of Object.entries(values)) {",
+    "        if (value !== undefined && value !== null) out[name] = String(value);",
+    "    }",
+    "    return out;",
+    "}",
+].join("\n");
+
+/**
+ * Follow a `#/components/parameters/...` `$ref` chain to the parameter object.
+ *
+ * @param {object | undefined} param - A parameter object or a reference to one.
+ * @param {Record<string, object>} components - `components.parameters`.
+ * @returns {object | undefined} The parameter object, or `undefined` when the
+ *   chain does not resolve.
+ */
+function resolveParameter(param, components) {
+    let node = param;
+    let guard = 0;
+    while (node && node.$ref && guard++ < 16) node = components[refName(node.$ref)];
+    return node && !node.$ref ? node : undefined;
+}
+
+/**
+ * The parameters that apply to one operation: the path item's `parameters`
+ * merged with the operation's, the operation winning on the same `(name, in)` —
+ * the rule OpenAPI 3 sets for the two levels.
+ *
+ * Before #509 only `operation.parameters` was read, so a `{id}` declared on the
+ * path item reached the URL literally (`"/items/{id}"`, measured), and a path item
+ * declaring one placeholder while the operation declared the other refused to
+ * generate. `$ref`s into `components.parameters` are resolved here too: they were
+ * dropped the same way, because a reference object has no `in`.
+ *
+ * @param {object} item - The path item.
+ * @param {object} op - The operation.
+ * @param {Record<string, object>} components - `components.parameters`.
+ * @returns {object[]} The effective parameter objects, path-item order first.
+ */
+function operationParameters(item, op, components) {
+    const merged = new Map();
+    for (const raw of [...(item.parameters ?? []), ...(op.parameters ?? [])]) {
+        const param = resolveParameter(raw, components);
+        if (!param || typeof param.name !== "string" || typeof param.in !== "string") continue;
+        merged.set(`${param.in}\u0000${param.name}`, param);
+    }
+    return [...merged.values()];
+}
 
 /**
  * Whether a path parameter's schema only ever produces a `string` or a `number` —
@@ -208,16 +284,17 @@ function isQueryScalar(schema, schemas, depth = 0) {
 }
 
 /**
- * TS type for a query-param value. Query params serialize to strings, so the
- * client only accepts `string | number | boolean | null`. Anything richer
- * (objects, arrays) is narrowed to `string` to stay assignable.
+ * TS type for a query- or header-param value. Both serialize to strings, so the
+ * client's `params` and the generated `headerRecord` only accept
+ * `string | number | boolean | null`. Anything richer (objects, arrays) is
+ * narrowed to `string` to stay assignable.
  *
  * @param {object | undefined} schema - The parameter's schema.
  * @param {Record<string, object>} schemas - `components.schemas`.
  * @param {Set<string>} refs - Collects the schemas the type names.
  * @returns {string} The TypeScript type expression.
  */
-function queryParamType(schema, schemas, refs) {
+function scalarParamType(schema, schemas, refs) {
     const node = schema ?? { type: "string" };
     return isQueryScalar(node, schemas) ? tsType(node, refs) : "string";
 }
@@ -343,16 +420,25 @@ function compareNames(a, b) {
  * template's ESLint enforces, so the output passes its lint and `tsc` with
  * `noUnusedLocals` as generated (#504, #505).
  *
+ * A component schema no route reaches is never emitted — FastAPI publishes an
+ * unreferenced enum for every `Enum`-annotated field (`ImageMediaType`, #516),
+ * and it lands in no group. Its name is not checked either: the identifier
+ * collision check runs per group over the schemas that group emits, so an orphan
+ * named `Media-Type` next to a referenced `MediaType` no longer aborts the whole
+ * run for a type nobody would see.
+ *
+ * Parameters are read from the path item and the operation, merged by
+ * `(name, in)` (see {@link operationParameters}); `in: "cookie"` is skipped,
+ * because a browser `fetch` cannot set `Cookie` — the browser sends its own
+ * cookies with `credentials`, which is how a cookie parameter reaches the server.
+ *
  * @param {object} doc - The parsed OpenAPI 3.x spec.
  * @returns {{ files: Record<string, string>, tags: string[] }}
  */
 export function generate(doc) {
     const schemas = doc.components?.schemas ?? {};
-    assertNoCollision(
-        Object.keys(schemas).map((n) => [n, typeName(n)]),
-        "schema names",
-    );
-    const groups = new Map(); // slug → { tag, ops: [...] }
+    const parameterComponents = doc.components?.parameters ?? {};
+    const groups = new Map();
 
     for (const [path, item] of Object.entries(doc.paths ?? {})) {
         for (const method of HTTP_METHODS) {
@@ -361,7 +447,8 @@ export function generate(doc) {
             const tag = op.tags?.[0] ?? "default";
             const slug = tagSlug(tag);
             if (!groups.has(slug)) groups.set(slug, { tag, slug, ops: [] });
-            groups.get(slug).ops.push({ method, path, op });
+            const params = operationParameters(item, op, parameterComponents);
+            groups.get(slug).ops.push({ method, path, op, params });
         }
     }
 
@@ -378,9 +465,9 @@ export function generate(doc) {
         const Class = `${slugIdent(pascal(slug))}Service`;
 
         const usedNames = new Set(CLASS_MEMBERS);
-        const signature = { refs: new Set(), validates: false };
-        const methods = ops.map(({ method, path, op }) =>
-            emitMethod(method, path, op, schemas, usedNames, signature),
+        const signature = { refs: new Set(), validates: false, sendsHeaders: false };
+        const methods = ops.map(({ method, path, op, params }) =>
+            emitMethod(method, path, op, params, schemas, usedNames, signature),
         );
 
         const used = new Set();
@@ -392,6 +479,10 @@ export function generate(doc) {
         }
         for (const name of signature.refs) collectRefs({ $ref: name }, schemas, used);
         const { sorted, cyclic } = topoSort(used, schemas);
+        assertNoCollision(
+            sorted.map((n) => [n, typeName(n)]),
+            "schema names",
+        );
         for (const name of sorted) assertPatterns(schemas[name], name);
 
         const schemaLines = sorted.map((name) => {
@@ -433,6 +524,7 @@ export function generate(doc) {
                 .filter((group) => group.length)
                 .map((group) => group.join("\n"))
                 .join("\n\n") +
+            (signature.sendsHeaders ? `\n\n${HEADER_RECORD_HELPER}` : "") +
             `\n\n/** Generated service for the "${commentText(tag)}" routes. Inject an ApiClient (createApiClient). */\n` +
             `export class ${Class} {\n` +
             `    constructor(private readonly api: ApiClient) {}\n\n` +
@@ -461,16 +553,27 @@ export function generate(doc) {
  * pagination envelope maps to `OffsetPage<T>` / `CursorPage<T>`, and a body typed
  * by a `$ref` is validated with its Zod schema before the call.
  *
+ * Arguments come in a fixed order: path parameters, `body`, `params` (query),
+ * `headers`. Header parameters are typed like query parameters and sent through
+ * the request's `headers`, via `headerRecord`; the `headers` argument defaults to
+ * `{}` when none of them is required, so a spec gaining an optional header does
+ * not break the call sites. `Accept`, `Content-Type` and `Authorization` are left
+ * out ({@link IGNORED_HEADERS}), and so is every `in: "cookie"` parameter: a
+ * browser `fetch` cannot set `Cookie` (forbidden header name), the cookie jar
+ * sends it with `credentials`.
+ *
  * @param {string} method - The HTTP method, lower case.
  * @param {string} path - The OpenAPI path template.
  * @param {object} op - The operation object.
+ * @param {object[]} parameters - The effective parameters, from {@link operationParameters}.
  * @param {Record<string, object>} schemas - `components.schemas`.
  * @param {Set<string>} usedNames - Member names already taken in the class.
- * @param {{ refs: Set<string>, validates: boolean }} signature - Collects the
- *   component schemas the emitted types name, and whether `S` was used.
+ * @param {{ refs: Set<string>, validates: boolean, sendsHeaders: boolean }} signature -
+ *   Collects the component schemas the emitted types name, whether `S` was used
+ *   and whether `headerRecord` was.
  * @returns {string} The method source.
  */
-function emitMethod(method, path, op, schemas, usedNames, signature) {
+function emitMethod(method, path, op, parameters, schemas, usedNames, signature) {
     let name = methodName(op, method, path);
     if (usedNames.has(name)) {
         let n = 2;
@@ -478,7 +581,11 @@ function emitMethod(method, path, op, schemas, usedNames, signature) {
         name = `${name}${n}`;
     }
     usedNames.add(name);
-    const pathParams = (op.parameters ?? []).filter((p) => p.in === "path");
+    const pathParams = parameters.filter((p) => p.in === "path");
+    const queryParams = parameters.filter((p) => p.in === "query");
+    const headerParams = parameters.filter(
+        (p) => p.in === "header" && !IGNORED_HEADERS.has(p.name.toLowerCase()),
+    );
     const where = `${method.toUpperCase()} ${path}`;
     const paramId = (name) => {
         const id = toIdentifier(name, "camel", `path parameter in ${where}`);
@@ -496,13 +603,11 @@ function emitMethod(method, path, op, schemas, usedNames, signature) {
         [
             ...[...paramIds],
             ...(bodySchema(op) ? [["the request body argument", "body"]] : []),
-            ...((op.parameters ?? []).some((p) => p.in === "query")
-                ? [["the query argument", "params"]]
-                : []),
+            ...(queryParams.length ? [["the query argument", "params"]] : []),
+            ...(headerParams.length ? [["the headers argument", "headers"]] : []),
         ],
         `method arguments of ${where}`,
     );
-    const queryParams = (op.parameters ?? []).filter((p) => p.in === "query");
     const body = bodySchema(op);
     const resp = successSchema(op);
     const page = resp ? detectPage(resp, schemas, signature.refs) : null;
@@ -512,6 +617,14 @@ function emitMethod(method, path, op, schemas, usedNames, signature) {
           ? tsType(resp, signature.refs)
           : "void";
 
+    const fields = (list) =>
+        list
+            .map(
+                (p) =>
+                    `${JSON.stringify(p.name)}${p.required ? "" : "?"}: ${scalarParamType(p.schema, schemas, signature.refs)}`,
+            )
+            .join("; ");
+
     const args = [];
     for (const p of pathParams) {
         args.push(
@@ -519,14 +632,11 @@ function emitMethod(method, path, op, schemas, usedNames, signature) {
         );
     }
     if (body) args.push(`body: ${tsType(body, signature.refs)}`);
-    if (queryParams.length) {
-        const q = queryParams
-            .map(
-                (p) =>
-                    `${JSON.stringify(p.name)}${p.required ? "" : "?"}: ${queryParamType(p.schema, schemas, signature.refs)}`,
-            )
-            .join("; ");
-        args.push(`params: { ${q} }`);
+    if (queryParams.length) args.push(`params: { ${fields(queryParams)} }`);
+    if (headerParams.length) {
+        const optional = headerParams.every((p) => !p.required);
+        args.push(`headers: { ${fields(headerParams)} }${optional ? " = {}" : ""}`);
+        signature.sendsHeaders = true;
     }
 
     const url = urlTemplate(path, segmentArgs);
@@ -534,6 +644,7 @@ function emitMethod(method, path, op, schemas, usedNames, signature) {
     const callOpts = [];
     if (body) callOpts.push("body");
     if (queryParams.length) callOpts.push("params");
+    if (headerParams.length) callOpts.push("headers: headerRecord(headers)");
     const optsArg = callOpts.length ? `, { ${callOpts.join(", ")} }` : "";
 
     let validation = "";