tempest-react-sdk 0.80.0 → 0.82.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)
@@ -159,7 +159,7 @@ Via `package.json`:
 
 Requires React `>=18` and Node `>=22.12` to build.
 
-**A bundler is assumed — outside one, load the shipped `.css` loader.** Every component module imports its own stylesheet (see [CSS import](#css-import)), and `.css` is not a format Node can load — `node -e "import('tempest-react-sdk')"` fails with `ERR_UNKNOWN_FILE_EXTENSION`. Vite, webpack, Rspack, Parcel and esbuild all resolve that import, and the SDK is client-side only, so no real app consumer is affected. For everything that is not a bundler — a script, a Jest suite, reading the surface by introspection — the package ships the loader: `node --import tempest-react-sdk/node-css-loader your-script.mjs` resolves every stylesheet to an empty module, for `import` and `require` both. A **Jest** suite can use it or the usual `moduleNameMapper: { "\\.css$": "<rootDir>/test/css-stub.js" }`. Vitest needs nothing.
+**A bundler is assumed — outside one, load the shipped `.css` loader.** Every component module imports its own stylesheet (see [CSS import](#css-import)), and `.css` is not a format Node can load — `node -e "import('tempest-react-sdk')"` fails with `ERR_UNKNOWN_FILE_EXTENSION`. Vite, webpack, Rspack, Parcel and esbuild all resolve that import, and the SDK is client-side only, so no real app consumer is affected. For everything that is not a bundler — a script, a Jest suite, reading the surface by introspection — the package ships the loader: `node --import tempest-react-sdk/node-css-loader your-script.mjs` resolves every stylesheet to an empty module, for `import` and `require` both. A **Jest** suite can use it or the usual `moduleNameMapper: { "\\.css$": "<rootDir>/test/css-stub.js" }`. **Vitest** needs `tempestVitest()` from `tempest-react-sdk/vite`, because it hands every ESM package from `node_modules` to Node: `createViteConfig` already wires it, but a separate `vitest.config.ts` (or a plain `vite.config.ts`) must add it to `plugins`, or the first import of the SDK fails with `Unknown file extension ".css"` — see [Testing with Vitest](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/vite-config/#testing-with-vitest).
 
 ### Peer & bundled dependencies
 
@@ -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
@@ -1964,15 +1995,14 @@ Every gallery section maps 1-to-1 with a docs page — see [`docs/gallery.md`](.
 
 ## Release
 
-Versioning is managed with [Changesets](https://github.com/changesets/changesets):
+Two commands, with the release PR's review in between:
 
 ```bash
-npx changeset          # describe the change (patch / minor / major)
-npx changeset version  # bump versions + update CHANGELOG.md
-npm run release        # build + changeset publish
+make release TAG=X.Y.Z       # opens the release PR (no tag, no publish)
+make release-tag TAG=X.Y.Z   # after the merge: tags the merge commit and pushes it
 ```
 
-CI workflow `.github/workflows/release.yml` publishes to npm whenever a "Version Packages" PR merges into `main`. The first publish is manual — set the `NPM_TOKEN` secret in _Settings → Secrets and variables → Actions_ and run `npm publish` once.
+The tag push runs `.github/workflows/release-npm.yml`, which publishes through npm Trusted Publishing (OIDC, with provenance) — no npm token anywhere, and no local publish (`make publish` refuses). Pipeline and the repository owner's settings checklist: [Release pipeline](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/release/).
 
 Tags follow `vMAJOR.MINOR.PATCH`. CSS tokens (`--tempest-*`) are treated as public API — renames bump the minor (or major, on removal).
 

package/bin/create-tempest-app.e2e.test.mjs

@@ -49,6 +49,37 @@ function scaffoldHere() {
     return { status: result.status, stdout: result.stdout + result.stderr };
 }
 
+describe("create-tempest-app new-folder mode refuses a destination that is a symlink (#533)", () => {
+    it("my-app -> ../outside is refused and nothing lands at the link target", () => {
+        symlinkSync("../outside", join(proj, "my-app"));
+
+        const result = spawnSync(process.execPath, [CLI, "my-app"], {
+            cwd: proj,
+            encoding: "utf8",
+            env: { ...process.env, NO_COLOR: "1" },
+        });
+
+        expect(result.status).toBe(1);
+        expect(result.stderr).toMatch(/"my-app" is a symbolic link/);
+        expect(readdirSync(outside)).toEqual([]);
+        expect(lstatSync(join(proj, "my-app")).isSymbolicLink()).toBe(true);
+    });
+
+    it("a plain new folder name is still scaffolded", () => {
+        const result = spawnSync(process.execPath, [CLI, "my-app"], {
+            cwd: proj,
+            encoding: "utf8",
+            env: { ...process.env, NO_COLOR: "1" },
+        });
+
+        expect(result.status).toBe(0);
+        expect(existsSync(join(proj, "my-app", "src", "main.tsx"))).toBe(true);
+        expect(JSON.parse(readFileSync(join(proj, "my-app", "package.json"), "utf8")).name).toBe(
+            "my-app",
+        );
+    });
+});
+
 describe("create-tempest-app merge mode never writes through a symlink (#436)", () => {
     it("a symlinked src/ pointing outside the project is skipped, not written into", () => {
         writeFileSync(join(outside, "main.tsx"), "OUTSIDE-USER-FILE");

package/bin/create-tempest-app.mjs

@@ -10,7 +10,8 @@
 // package.json has the Tempest scripts/deps merged in (your name/version are
 // preserved). A symlink already in the destination is never written through:
 // it is skipped and reported, so a link to a folder outside the project cannot
-// redirect the template there. The `--pwa` flag overlays the PWA template
+// redirect the template there. A named destination that is itself a symlink is
+// refused for the same reason. The `--pwa` flag overlays the PWA template
 // (manifest, service worker, push-subscribe wiring) on top of the base.
 import { cp, lstat, mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -239,6 +240,15 @@ async function main() {
             process.exit(1);
         }
         destDir = resolve(process.cwd(), arg);
+        if (await isSymlink(destDir)) {
+            console.error(
+                `${c.red}✗ "${arg}" is a symbolic link; the project would be created where it points.${c.reset}`,
+            );
+            console.error(
+                `${c.dim}  Create the project at the real path, or remove the link.${c.reset}`,
+            );
+            process.exit(1);
+        }
         if (!(await isEmptyDir(destDir))) {
             console.error(`${c.red}✗ Directory "${arg}" exists and is not empty.${c.reset}`);
             console.error(

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/doctor/doctor.e2e.test.mjs

@@ -98,6 +98,11 @@ describe("tempest doctor — a third-party project that does not use the SDK", (
         expect(out).not.toContain('add import "tempest-react-sdk/styles.css"');
     });
 
+    it("does not judge the Vitest config of a project without the SDK", () => {
+        installed("vitest", "4.1.12");
+        expect(doctor().out).not.toContain("inline the SDK");
+    });
+
     it("does not demand a src/main.tsx it has no reason to expect", () => {
         const { out } = doctor();
         expect(out).not.toContain("app entry");
@@ -336,6 +341,30 @@ describe("tempest doctor — a project that does use the SDK", () => {
         expect(doctor().out).toContain("leaflet missing");
     });
 
+    it("warns when Vitest would load the SDK without the plugin", () => {
+        installed("vitest", "4.1.12");
+        const { out, code } = doctor();
+        expect(out).toContain("vite.config.ts does not inline the SDK for Vitest");
+        expect(out).toContain("tempestVitest()");
+        expect(code).toBe(0);
+    });
+
+    it("accepts a vitest.config that adds tempestVitest", () => {
+        installed("vitest", "4.1.12");
+        write(
+            "vitest.config.ts",
+            'import { tempestVitest } from "tempest-react-sdk/vite";\n' +
+                "export default defineConfig({ plugins: [tempestVitest()] });",
+        );
+        const { out } = doctor();
+        expect(out).toContain("vitest.config.ts lets Vitest load the SDK");
+        expect(out).not.toContain("does not inline the SDK");
+    });
+
+    it("says nothing about Vitest in a project that does not install it", () => {
+        expect(doctor().out).not.toContain("Vitest");
+    });
+
     it("warns when the SDK is installed but undeclared", () => {
         write("package.json", {
             name: "sdk-app",

package/bin/lib/doctor/vitest.mjs

@@ -0,0 +1,120 @@
+/**
+ * The Vitest config check for `tempest doctor`.
+ *
+ * Every SDK component module imports its own stylesheet, and Vitest hands an ESM
+ * package from `node_modules` to plain Node, which has no loader for `.css`. A
+ * consumer suite that imports the SDK therefore dies before running with
+ * `Unknown file extension ".css"` unless the config inlines the SDK — which is what
+ * `tempestVitest()` does, and what `createViteConfig` includes. Measured in #548
+ * with the 0.81.0 tarball on Vitest 4.1.12: an own `vitest.config.ts`, a plain
+ * `vite.config.ts` and no config at all fail; only the plugin passes.
+ *
+ * The check is a text heuristic over the config file Vitest would load, not an
+ * evaluation of it: running the user's config would execute their code and pull
+ * their plugins in, which a health check has no business doing. The markers are the
+ * plugin and helper names, an explicit `inline: true` (which inlines everything,
+ * the SDK included), and an inline list naming the package — the three shapes that
+ * make the suite pass.
+ */
+
+/**
+ * Config file names Vitest looks for, in the order it prefers them.
+ *
+ * Ported from Vitest 4.1.12's `configFiles` (`CONFIG_NAMES` × `CONFIG_EXTENSIONS`
+ * in `dist/chunks/constants.*.js`, not exported): a `vitest.config.*` wins over a
+ * `vite.config.*`, and within each the extensions are tried in this order. The
+ * test reads the installed Vitest and fails when the list drifts.
+ */
+export const VITEST_CONFIG_FILES = [
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "vitest.config.cts",
+    "vitest.config.js",
+    "vitest.config.mjs",
+    "vitest.config.cjs",
+    "vite.config.ts",
+    "vite.config.mts",
+    "vite.config.cts",
+    "vite.config.js",
+    "vite.config.mjs",
+    "vite.config.cjs",
+];
+
+/** Text that, once comments are gone, means the config already inlines the SDK. */
+const INLINES_SDK = [
+    /\btempestVitest\b/,
+    /\bcreateViteConfig\b/,
+    /\binline\s*:\s*true\b/,
+    /\binline\s*:\s*\[[^\]]*["'`]tempest-react-sdk["'`]/,
+];
+
+/** An import of the project's own `vite.config`, as `mergeConfig` setups do. */
+const IMPORTS_VITE_CONFIG = /from\s*["']\.\/vite\.config(?:\.[cm]?[jt]s)?["']/;
+
+/**
+ * Drop JavaScript comments so a marker that only appears in prose does not count.
+ *
+ * A line comment is only removed when `//` is not preceded by `:`, which keeps
+ * `https://` inside a string intact; a missed edge case here costs one false "ok",
+ * never a crash.
+ *
+ * @param {string} text - Source text of a config file.
+ * @returns {string} The text without block and line comments.
+ */
+function stripComments(text) {
+    return text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+
+/**
+ * Whether a config file's text makes Vitest inline the SDK.
+ *
+ * @param {string} text - Source text of the config.
+ * @returns {boolean} Whether one of the passing shapes is present.
+ */
+function inlinesSdk(text) {
+    const code = stripComments(text);
+    return INLINES_SDK.some((marker) => marker.test(code));
+}
+
+/**
+ * Audit whether the project's Vitest setup can import the SDK.
+ *
+ * Vitest loads the first `vitest.config.*`, else the first `vite.config.*`, else
+ * runs with defaults; this mirrors that choice and judges only the file it would
+ * load. A `vitest.config.*` that imports `./vite.config` (the `mergeConfig`
+ * pattern) passes when that `vite.config.*` does, so a project using
+ * `createViteConfig` there is not flagged.
+ *
+ * @param {object} params
+ * @param {boolean} params.vitestInstalled - Whether `vitest` resolves in the project.
+ * @param {Record<string, string>} params.configs - Text of each config file present,
+ *   keyed by its name from {@link VITEST_CONFIG_FILES}.
+ * @returns {Array<[status: string, label: string, detail?: string]>} Check rows;
+ *   empty when the project does not use Vitest.
+ */
+export function checkVitest({ vitestInstalled, configs }) {
+    if (!vitestInstalled) return [];
+
+    const loaded = VITEST_CONFIG_FILES.find((name) => name in configs);
+    const fix =
+        "add `plugins: [tempestVitest()]` from tempest-react-sdk/vite, or build the config " +
+        "with createViteConfig — otherwise any test importing the SDK fails with " +
+        '`Unknown file extension ".css"`';
+
+    if (!loaded) {
+        return [["warn", "Vitest runs with no config", fix]];
+    }
+
+    const text = configs[loaded];
+    const viaViteConfig =
+        loaded.startsWith("vitest.") &&
+        IMPORTS_VITE_CONFIG.test(stripComments(text)) &&
+        VITEST_CONFIG_FILES.some(
+            (name) => name.startsWith("vite.") && name in configs && inlinesSdk(configs[name]),
+        );
+
+    if (inlinesSdk(text) || viaViteConfig) {
+        return [["ok", `${loaded} lets Vitest load the SDK`]];
+    }
+    return [["warn", `${loaded} does not inline the SDK for Vitest`, fix]];
+}

package/bin/lib/doctor/vitest.test.mjs

@@ -0,0 +1,139 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import { VITEST_CONFIG_FILES, checkVitest } from "./vitest.mjs";
+
+const VITEST_CHUNKS = join(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "..",
+    "node_modules",
+    "vitest",
+    "dist",
+    "chunks",
+);
+
+/** Statuses of the returned rows, in order. */
+const statuses = (rows) => rows.map(([status]) => status);
+
+/** Run the check for a project with Vitest and the given config files. */
+const check = (configs) => checkVitest({ vitestInstalled: true, configs });
+
+/**
+ * The config file list the installed Vitest really searches, read from its source.
+ *
+ * @returns {string[]} `CONFIG_NAMES` × `CONFIG_EXTENSIONS`, in Vitest's order.
+ */
+function installedVitestConfigFiles() {
+    const file = readdirSync(VITEST_CHUNKS).find((name) => /^constants\..*\.js$/.test(name));
+    const text = readFileSync(join(VITEST_CHUNKS, file), "utf8");
+    const array = (name) =>
+        JSON.parse(
+            new RegExp(`const ${name} = (\\[[^\\]]*\\])`)
+                .exec(text)[1]
+                .replace(/\s+/g, "")
+                .replace(/,]/, "]"),
+        );
+    return array("CONFIG_NAMES").flatMap((name) =>
+        array("CONFIG_EXTENSIONS").map((ext) => name + ext),
+    );
+}
+
+describe("checkVitest — which file it judges", () => {
+    it("searches the same files, in the same order, as the installed Vitest", () => {
+        expect(VITEST_CONFIG_FILES).toEqual(installedVitestConfigFiles());
+    });
+
+    it("judges vitest.config over vite.config, the one Vitest loads", () => {
+        const rows = check({
+            "vite.config.ts": "export default createViteConfig();",
+            "vitest.config.ts": "export default defineConfig({ test: {} });",
+        });
+        expect(statuses(rows)).toEqual(["warn"]);
+        expect(rows[0][1]).toContain("vitest.config.ts");
+    });
+
+    it("falls back to vite.config when there is no vitest.config", () => {
+        const rows = check({ "vite.config.mjs": "export default defineConfig({});" });
+        expect(rows[0][1]).toContain("vite.config.mjs");
+    });
+});
+
+describe("checkVitest — setups that fail the suite", () => {
+    it("says nothing when the project does not use Vitest", () => {
+        expect(checkVitest({ vitestInstalled: false, configs: {} })).toEqual([]);
+    });
+
+    it("warns when Vitest would run with no config at all", () => {
+        const rows = check({});
+        expect(statuses(rows)).toEqual(["warn"]);
+        expect(rows[0][2]).toContain("tempestVitest()");
+        expect(rows[0][2]).toContain('Unknown file extension ".css"');
+    });
+
+    it("warns on a plain vitest.config without the plugin", () => {
+        const rows = check({
+            "vitest.config.ts":
+                'import { defineConfig } from "vitest/config";\n' +
+                'export default defineConfig({ test: { environment: "jsdom" } });',
+        });
+        expect(statuses(rows)).toEqual(["warn"]);
+    });
+
+    it("does not count the plugin named only in a comment", () => {
+        const rows = check({
+            "vitest.config.ts":
+                "// TODO: add tempestVitest()\n/* createViteConfig later */\n" +
+                "export default defineConfig({});",
+        });
+        expect(statuses(rows)).toEqual(["warn"]);
+    });
+
+    it("does not trust an import of a vite.config that lacks the plugin too", () => {
+        const rows = check({
+            "vite.config.ts": "export default defineConfig({});",
+            "vitest.config.ts":
+                'import viteConfig from "./vite.config";\n' +
+                "export default mergeConfig(viteConfig, defineConfig({ test: {} }));",
+        });
+        expect(statuses(rows)).toEqual(["warn"]);
+    });
+});
+
+describe("checkVitest — setups that pass", () => {
+    it.each([
+        ["tempestVitest()", "export default defineConfig({ plugins: [tempestVitest()] });"],
+        ["createViteConfig", "export default createViteConfig({ overrides: {} });"],
+        [
+            "inline: true",
+            "export default defineConfig({ test: { server: { deps: { inline: true } } } });",
+        ],
+        [
+            "an inline list naming the SDK",
+            'export default defineConfig({ test: { server: { deps: { inline: ["x", "tempest-react-sdk"] } } } });',
+        ],
+    ])("accepts %s", (_, text) => {
+        expect(statuses(check({ "vitest.config.ts": text }))).toEqual(["ok"]);
+    });
+
+    it("accepts a vitest.config merged over a vite.config that uses createViteConfig", () => {
+        const rows = check({
+            "vite.config.ts": "export default createViteConfig();",
+            "vitest.config.ts":
+                'import viteConfig from "./vite.config.ts";\n' +
+                "export default mergeConfig(viteConfig, defineConfig({ test: {} }));",
+        });
+        expect(statuses(rows)).toEqual(["ok"]);
+    });
+
+    it("keeps a URL inside a string from hiding a marker after it", () => {
+        const rows = check({
+            "vitest.config.ts":
+                'const docs = "https://example.com"; export default defineConfig({ plugins: [tempestVitest()] });',
+        });
+        expect(statuses(rows)).toEqual(["ok"]);
+    });
+});

package/bin/lib/fs/contain.mjs

@@ -28,6 +28,13 @@ export function lstatOrNull(path) {
  * not skipped over: its `realpath` throws and the path counts as outside, since
  * `mkdir` or `writeFile` would create whatever the link names.
  *
+ * The answer is about the tree as it is now; nothing makes it and the write that
+ * follows one atomic step. A process swapping a folder for a symlink between the
+ * two can still redirect the write, and Node has no `openat`/`O_NOFOLLOW` walk
+ * to close that. Such a process is already writing inside the user's project, so
+ * it could edit the generated files or `package.json` directly: the window is an
+ * accepted risk, the same one `create-tempest-app` documents (#533).
+ *
  * @param {string} root - Project root.
  * @param {string} path - Absolute path, existing or about to be created.
  * @returns {boolean}