tempest-react-sdk 0.75.0 → 0.77.0

package/README.md

@@ -284,9 +284,10 @@ 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`), `registerPeriodicSync` (main-thread periodic sync), `inspectCaches`/`clearCaches` (cache observability) — 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), `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)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `audio`                                                                                           | `createAudioPlayer`, `playAudio`, `stopAudio`, `useAudio`, `createAudioBus` / `useAudioBus` (gain above 100%, post-mix limiter, `setSinkId` routing), `DEFAULT_MAX_GAIN`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `capture`                                                                                         | `BarcodeScanner`, `useBarcodeScanner`, `useTorch`, `isBarcodeDetectionSupported`, `getSupportedBarcodeFormats`, `createBarcodeDetector`, `normalizeBarcode`, `useVideoRecorder`, `createVideoRecorder`, `pickVideoMimeType`, `isVideoRecordingSupported`, `useScreenCapture`, `isScreenCaptureSupported`, `useSpeechRecognition`, `isSpeechRecognitionSupported`, `createMediaRecorder` — barcode/QR reading over the native `BarcodeDetector` (Chromium-only, so inject a polyfill through `detector` or render the `unsupported` fallback), video + screen recording on the same engine as the audio recorder, and Web Speech dictation (**Chromium streams the audio to a Google server**)                                                                                                                                                                                                                                                           |
 | `offline` _(peer: `dexie`)_                                                                       | `createOfflineStore`, `createOfflineSync` (outbox + delta-pull + watermark engine, now with `subscribe`/`getState`/`dispose` + cross-tab `crossTab`), `useOfflineSync`/`useSyncStatus` (reactive hooks), `lastWriteWins`/`higherVersionWins` (conflict resolvers), types: `OfflineStore`, `OfflineStoreConfig`, `ListOptions`, `OfflineSync`, `OfflineSyncConfig`, `OutboxEntry`, `PullPage`, `SyncPhase`, `SyncState`, `SyncRunSummary`, `SyncTrigger`, `SyncStatus`, `SyncTone`, `WatermarkStore`                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -320,11 +321,12 @@ 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`), `registerPeriodicSync` (main-thread periodic sync), `inspectCaches`/`clearCaches` (cache observability) — 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), `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                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `imaging` _(subpath `tempest-react-sdk/imaging`, no deps)_                                        | `resizeImage`, `cropImage`, `rotateImage`, `flipImage`, `compressToTarget` (binary-searches quality into a byte budget), `createThumbnails` (several sizes from one decode), `captureFrame` (one frame out of a `<video>`, at the instant you ask for), `decodeImage`/`readImageInfo`, `encodeImage`, `supportsImageType`/`bestSupportedType`, plus `useImagePreview`/`useImageProcessing`. Canvas only — decodes with EXIF orientation applied (phone photos arrive upright), reports the format actually produced (asking for AVIF where there is no encoder silently returns PNG), and re-encoding drops EXIF, which is the privacy step as much as the bandwidth one. `captureFrame` is the one with teeth: `seeked` does not mean the new frame is readable, so the naive seek-then-draw returns the neighbouring frame with no error — and a `MediaRecorder` blob reports no duration until it is probed for one, which it does for you           |
+| `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)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `audio`                                                                                           | `createAudioPlayer`, `playAudio`, `stopAudio`, `useAudio`, `createAudioBus` / `useAudioBus` (gain above 100%, post-mix limiter, `setSinkId` routing), `DEFAULT_MAX_GAIN`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `capture`                                                                                         | `BarcodeScanner`, `useBarcodeScanner`, `useTorch`, `isBarcodeDetectionSupported`, `getSupportedBarcodeFormats`, `createBarcodeDetector`, `normalizeBarcode`, `useVideoRecorder`, `createVideoRecorder`, `pickVideoMimeType`, `isVideoRecordingSupported`, `useScreenCapture`, `isScreenCaptureSupported`, `useSpeechRecognition`, `isSpeechRecognitionSupported`, `createMediaRecorder` — barcode/QR reading over the native `BarcodeDetector` (Chromium-only, so inject a polyfill through `detector` or render the `unsupported` fallback), video + screen recording on the same engine as the audio recorder, and Web Speech dictation (**Chromium streams the audio to a Google server**)                                                                                                                                                                                                                                                           |
 | `offline` _(peer: `dexie`)_                                                                       | `createOfflineStore`, `createOfflineSync` (outbox + delta-pull + watermark engine, now with `subscribe`/`getState`/`dispose` + cross-tab `crossTab`), `useOfflineSync`/`useSyncStatus` (reactive hooks), `lastWriteWins`/`higherVersionWins` (conflict resolvers), types: `OfflineStore`, `OfflineStoreConfig`, `ListOptions`, `OfflineSync`, `OfflineSyncConfig`, `OutboxEntry`, `PullPage`, `SyncPhase`, `SyncState`, `SyncRunSummary`, `SyncTrigger`, `SyncStatus`, `SyncTone`, `WatermarkStore`                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

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

@@ -0,0 +1,112 @@
+import { spawnSync } from "node:child_process";
+import {
+    existsSync,
+    lstatSync,
+    mkdirSync,
+    mkdtempSync,
+    readdirSync,
+    readFileSync,
+    rmSync,
+    symlinkSync,
+    writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const CLI = join(dirname(fileURLToPath(import.meta.url)), "create-tempest-app.mjs");
+
+let root;
+let proj;
+let outside;
+
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "cta-"));
+    proj = join(root, "proj");
+    outside = join(root, "outside");
+    mkdirSync(proj);
+    mkdirSync(outside);
+    writeFileSync(join(proj, "package.json"), JSON.stringify({ name: "mine" }));
+});
+
+afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+});
+
+/**
+ * Run `create-tempest-app .` in `proj` (merge mode) and return its output.
+ *
+ * @returns {{ status: number | null, stdout: string }}
+ */
+function scaffoldHere() {
+    const result = spawnSync(process.execPath, [CLI, "."], {
+        cwd: proj,
+        encoding: "utf8",
+        env: { ...process.env, NO_COLOR: "1" },
+    });
+    return { status: result.status, stdout: result.stdout + result.stderr };
+}
+
+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");
+        symlinkSync("../outside", join(proj, "src"));
+
+        const { status, stdout } = scaffoldHere();
+
+        expect(status).toBe(0);
+        expect(readFileSync(join(outside, "main.tsx"), "utf8")).toBe("OUTSIDE-USER-FILE");
+        expect(readdirSync(outside)).toEqual(["main.tsx"]);
+        expect(stdout).toMatch(/· src\b/);
+        expect(lstatSync(join(proj, "src")).isSymbolicLink()).toBe(true);
+    });
+
+    it("a symlinked nested directory is skipped while its siblings are still written", () => {
+        mkdirSync(join(proj, "src"));
+        symlinkSync("../../outside", join(proj, "src", "pages"));
+
+        const { status, stdout } = scaffoldHere();
+
+        expect(status).toBe(0);
+        expect(readdirSync(outside)).toEqual([]);
+        expect(stdout).toMatch(/· src[/\\]pages\b/);
+        expect(existsSync(join(proj, "src", "main.tsx"))).toBe(true);
+    });
+
+    it("a symlinked package.json is not merged through", () => {
+        rmSync(join(proj, "package.json"));
+        writeFileSync(join(outside, "package.json"), '{"name":"outside"}');
+        symlinkSync("../outside/package.json", join(proj, "package.json"));
+
+        const { status, stdout } = scaffoldHere();
+
+        expect(status).toBe(0);
+        expect(readFileSync(join(outside, "package.json"), "utf8")).toBe('{"name":"outside"}');
+        expect(stdout).toMatch(/· package\.json\b/);
+    });
+
+    it("leaves the user's own _gitignore alone instead of renaming it over .gitignore", () => {
+        mkdirSync(join(proj, "notes"));
+        writeFileSync(join(proj, "notes", "_gitignore"), "user-underscore");
+        writeFileSync(join(proj, "notes", ".gitignore"), "user-dot");
+
+        const { status } = scaffoldHere();
+
+        expect(status).toBe(0);
+        expect(readFileSync(join(proj, "notes", "_gitignore"), "utf8")).toBe("user-underscore");
+        expect(readFileSync(join(proj, "notes", ".gitignore"), "utf8")).toBe("user-dot");
+        expect(existsSync(join(proj, ".gitignore"))).toBe(true);
+        expect(existsSync(join(proj, "_gitignore"))).toBe(false);
+    });
+
+    it("still scaffolds the full template into a plain directory", () => {
+        const { status } = scaffoldHere();
+
+        expect(status).toBe(0);
+        expect(existsSync(join(proj, "src", "main.tsx"))).toBe(true);
+        expect(existsSync(join(proj, ".env.example"))).toBe(true);
+        expect(JSON.parse(readFileSync(join(proj, "package.json"), "utf8")).name).toBe("mine");
+    });
+});

package/bin/create-tempest-app.mjs

@@ -8,11 +8,13 @@
 //
 // In merge mode, files the user already has are left untouched and an existing
 // package.json has the Tempest scripts/deps merged in (your name/version are
-// preserved). The `--pwa` flag overlays the PWA template (manifest, service
-// worker, push-subscribe wiring) on top of the base.
-import { cp, mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
+// 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
+// (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";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -86,23 +88,73 @@ async function readSdkVersion() {
     }
 }
 
+/**
+ * Whether `path` exists in the destination as a symbolic link.
+ *
+ * Checked with `lstat`, which does not follow the link: `mkdir(recursive)` and
+ * `cp` both would, and that is how a `src -> ../elsewhere` link turned a merge
+ * into writes outside the project (#436).
+ *
+ * @param {string} path - Absolute destination path.
+ * @returns {Promise<boolean>}
+ */
+async function isSymlink(path) {
+    try {
+        return (await lstat(path)).isSymbolicLink();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Whether the real location of `path`'s parent directory sits inside `root`.
+ *
+ * Second line behind {@link isSymlink}: it catches a link that appears in an
+ * ancestor the copy did not create itself. A folder whose name merely starts
+ * with two dots (`..cache`) is inside; only `..` itself or a `../` prefix is not.
+ *
+ * Both checks run immediately before each `mkdir`/`cp`, but nothing makes the
+ * check and the write one atomic step: a process that swaps a folder for a
+ * symlink in that window can still redirect the write. Node offers no
+ * `openat`/`O_NOFOLLOW` walk to close it, and the attacker would need to be
+ * racing the scaffold inside the user's own project folder, so this residual
+ * TOCTOU window is an accepted risk.
+ *
+ * @param {string} realRoot - `realpath` of the destination root.
+ * @param {string} path - Absolute destination path about to be written.
+ * @returns {Promise<boolean>}
+ */
+async function parentInside(realRoot, path) {
+    const parent = await realpath(dirname(path));
+    const rel = relative(realRoot, parent);
+    return !(rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel));
+}
+
 /**
  * Copy a template tree into `destDir`. `package.json` is handled separately;
  * any path already present in `protect` (the user's own files) is skipped and
- * recorded. Everything else is overwritten, so a later overlay wins over the
+ * recorded, and so is any symlink in the destination, which is never written
+ * through. Everything else is overwritten, so a later overlay wins over the
  * base it sits on.
+ *
+ * Template entries are written straight under their final name
+ * (`_gitignore` → `.gitignore`), so no rename pass over the destination is
+ * needed; the one that existed renamed the user's own `_gitignore` files too.
  */
-async function copyTree(srcDir, destDir, protect, skipped, relBase = "") {
+async function copyTree(srcDir, destDir, protect, skipped, realRoot, relBase = "") {
     const entries = await readdir(srcDir, { withFileTypes: true });
     for (const entry of entries) {
         const rel = join(relBase, finalName(entry.name));
         const from = join(srcDir, entry.name);
         const to = join(destDir, finalName(entry.name));
+        if (entry.name === "package.json" && !entry.isDirectory()) continue;
+        if ((await isSymlink(to)) || !(await parentInside(realRoot, to))) {
+            skipped.add(rel);
+            continue;
+        }
         if (entry.isDirectory()) {
             await mkdir(to, { recursive: true });
-            await copyTree(from, to, protect, skipped, rel);
-        } else if (entry.name === "package.json") {
-            // handled separately by writeFreshPackageJson / mergePackageJson
+            await copyTree(from, to, protect, skipped, realRoot, rel);
         } else if (protect.has(rel)) {
             skipped.add(rel);
         } else {
@@ -111,19 +163,6 @@ async function copyTree(srcDir, destDir, protect, skipped, relBase = "") {
     }
 }
 
-/** Recursively rename underscore-prefixed dotfiles after a directory copy. */
-async function fixDotfiles(dir) {
-    const entries = await readdir(dir, { withFileTypes: true });
-    for (const entry of entries) {
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) {
-            await fixDotfiles(full);
-        } else if (RENAME_ON_COPY[entry.name]) {
-            await rename(full, join(dir, RENAME_ON_COPY[entry.name]));
-        }
-    }
-}
-
 /** Stamp the SDK version into a fresh package.json. */
 async function writeFreshPackageJson(destDir, name, sdkVersion) {
     const pkg = JSON.parse(await readFile(join(TEMPLATE_DIR, "package.json"), "utf8"));
@@ -216,20 +255,22 @@ async function main() {
     const protect = await listFiles(destDir);
     const hadPkg = protect.has("package.json");
     const skipped = new Set();
+    const realRoot = await realpath(destDir);
 
-    await copyTree(TEMPLATE_DIR, destDir, protect, skipped);
-    if (pwa) await copyTree(TEMPLATE_PWA_DIR, destDir, protect, skipped);
-    await fixDotfiles(destDir);
+    await copyTree(TEMPLATE_DIR, destDir, protect, skipped, realRoot);
+    if (pwa) await copyTree(TEMPLATE_PWA_DIR, destDir, protect, skipped, realRoot);
 
-    // package.json: merge into the user's if present, otherwise write fresh.
-    if (hadPkg) {
+    const pkgIsLink = await isSymlink(join(destDir, "package.json"));
+    if (pkgIsLink) {
+        skipped.add("package.json");
+    } else if (hadPkg) {
         await mergePackageJson(destDir, sdkVersion);
         console.log(`${c.dim}Merged scripts + deps into existing package.json.${c.reset}`);
     } else {
         const name = mergeMode ? (destDir.split("/").pop() || "tempest-app").toLowerCase() : arg;
         await writeFreshPackageJson(destDir, name, sdkVersion);
     }
-    if (pwa) await applyPwaPackageJson(destDir);
+    if (pwa && !pkgIsLink) await applyPwaPackageJson(destDir);
 
     if (skipped.size) {
         console.log(`\n${c.yellow}Skipped ${skipped.size} existing file(s):${c.reset}`);

package/bin/lib/component/generate.mjs

@@ -0,0 +1,191 @@
+/**
+ * Scaffold for `tempest gen component <Name>`: one folder per component with
+ * `index.tsx`, `styles.module.css`, `constants.ts`, `utils.ts` and `hooks.ts`.
+ *
+ * Pure: takes a name, returns `{ name, files }`. The CLI does the I/O. The output
+ * is written to pass the app template's own gates as generated — `tsc` under its
+ * `strict` + `noUnusedLocals` tsconfig and ESLint under its `eslint.config.js`
+ * (sorted imports, type-only imports, no unused code) — and follows the
+ * template's Prettier config (double quotes, two-space indent, trailing commas).
+ * Every file is wired into `index.tsx`, so none starts out as dead code.
+ *
+ * `hooks.ts` reaches React through `import * as React` rather than a named
+ * import, so no generated name can ever redeclare what the file imports. The
+ * hook is `use<Name>`, or `use<Name>Component` when that would be a React
+ * built-in (see {@link REACT_BUILTIN_HOOKS}).
+ */
+
+const WORD = /[A-Za-z0-9]+/g;
+
+/**
+ * Folder names Windows reserves for devices, matched case-insensitively. A
+ * folder called `Con` or `Lpt1` cannot be created or cloned there, so a project
+ * with one breaks for every Windows teammate.
+ */
+/**
+ * React's built-in hook names. Ported from the `react` and `react-dom` hook
+ * exports (React 19). A component whose `use<Name>` lands on one of them gets
+ * `use<Name>Component` instead: the `react-hooks` lint rules match hooks by name,
+ * so a custom `useMemo(title)` would be linted as React's and warned about.
+ */
+export const REACT_BUILTIN_HOOKS = new Set([
+    "use",
+    "useActionState",
+    "useCallback",
+    "useContext",
+    "useDebugValue",
+    "useDeferredValue",
+    "useEffect",
+    "useEffectEvent",
+    "useFormStatus",
+    "useId",
+    "useImperativeHandle",
+    "useInsertionEffect",
+    "useLayoutEffect",
+    "useMemo",
+    "useOptimistic",
+    "useReducer",
+    "useRef",
+    "useState",
+    "useSyncExternalStore",
+    "useTransition",
+]);
+
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+
+/**
+ * Normalize a component name to PascalCase.
+ *
+ * Words are split on any non-alphanumeric character and on lower→upper case
+ * boundaries, so `"user card"`, `"user-card"`, `"user_card"`, `"userCard"` and
+ * `"UserCard"` all become `UserCard`. A word already in capitals (`"API"`) keeps
+ * them after its first letter: `"api client"` → `ApiClient`, `"APIClient"` →
+ * `APIClient`.
+ *
+ * @param {unknown} raw - The name as typed on the command line.
+ * @returns {string} The PascalCase component name.
+ * @throws {Error} When the name is empty, has characters other than ASCII
+ *   letters, digits, spaces, `-` and `_`, does not start with a letter, or is a
+ *   device name Windows reserves (`Con`, `Nul`, `Com1`…).
+ */
+export function normalizeComponentName(raw) {
+    const input = typeof raw === "string" ? raw.trim() : "";
+    if (!input) {
+        throw new Error("Missing component name. Usage: tempest gen component <Name>");
+    }
+    if (!/^[A-Za-z0-9 _-]+$/.test(input)) {
+        throw new Error(
+            `Invalid component name ${JSON.stringify(input)}: use ASCII letters, digits, spaces, "-" or "_".`,
+        );
+    }
+    if (!/^[A-Za-z]/.test(input)) {
+        throw new Error(
+            `Invalid component name ${JSON.stringify(input)}: it must start with a letter.`,
+        );
+    }
+    const words = input.replace(/([a-z0-9])([A-Z])/g, "$1 $2").match(WORD) ?? [];
+    const name = words.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("");
+    if (WINDOWS_RESERVED.test(name)) {
+        throw new Error(
+            `Invalid component name ${JSON.stringify(input)}: "${name}" is a reserved device name on Windows and cannot be a folder there.`,
+        );
+    }
+    return name;
+}
+
+/**
+ * Turn a PascalCase name into `UPPER_SNAKE_CASE` (`UserCard` → `USER_CARD`).
+ *
+ * @param {string} name - A PascalCase name.
+ * @returns {string}
+ */
+function upperSnake(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+        .toUpperCase();
+}
+
+/**
+ * Build the five files of a component folder.
+ *
+ * @param {string} rawName - The name as typed; normalized with
+ *   {@link normalizeComponentName}.
+ * @returns {{ name: string, files: Record<string, string> }} The PascalCase name
+ *   (also the folder name) and a `{ fileName: contents }` map.
+ * @throws {Error} When the name is invalid.
+ */
+export function componentFiles(rawName) {
+    const name = normalizeComponentName(rawName);
+    const constant = `${upperSnake(name)}_DEFAULT_TITLE`;
+    const hook = REACT_BUILTIN_HOOKS.has(`use${name}`) ? `use${name}Component` : `use${name}`;
+    const props = `${name}Props`;
+
+    const index = [
+        `import { ${hook} } from "./hooks";`,
+        `import styles from "./styles.module.css";`,
+        `import { joinClassNames } from "./utils";`,
+        ``,
+        `export interface ${props} {`,
+        `  title?: string;`,
+        `  className?: string;`,
+        `}`,
+        ``,
+        `export function ${name}({ title, className }: ${props}) {`,
+        `  const { heading } = ${hook}(title);`,
+        ``,
+        `  return (`,
+        `    <section className={joinClassNames(styles.root, className)}>`,
+        `      <h2 className={styles.title}>{heading}</h2>`,
+        `    </section>`,
+        `  );`,
+        `}`,
+        ``,
+    ].join("\n");
+
+    const css = [
+        `.root {`,
+        `  display: flex;`,
+        `  flex-direction: column;`,
+        `  gap: var(--tempest-space-2);`,
+        `}`,
+        ``,
+        `.title {`,
+        `  margin: 0;`,
+        `}`,
+        ``,
+    ].join("\n");
+
+    const constants = [`export const ${constant} = ${JSON.stringify(name)};`, ``].join("\n");
+
+    const utils = [
+        `export function joinClassNames(...names: Array<string | false | null | undefined>): string {`,
+        `  return names.filter(Boolean).join(" ");`,
+        `}`,
+        ``,
+    ].join("\n");
+
+    const hooks = [
+        `import * as React from "react";`,
+        ``,
+        `import { ${constant} } from "./constants";`,
+        ``,
+        `export function ${hook}(title?: string): { heading: string } {`,
+        `  const heading = React.useMemo(() => title?.trim() || ${constant}, [title]);`,
+        ``,
+        `  return { heading };`,
+        `}`,
+        ``,
+    ].join("\n");
+
+    return {
+        name,
+        files: {
+            "index.tsx": index,
+            "styles.module.css": css,
+            "constants.ts": constants,
+            "utils.ts": utils,
+            "hooks.ts": hooks,
+        },
+    };
+}