bsmnt 0.0.0

package/tasks/prd.json

@@ -0,0 +1,153 @@
+{
+  "project": "basement-cli",
+  "branchName": "ralph/next-starter-dynamic-layers",
+  "description": "Replace 4 static templates with next-starter clone + dynamic technology layers to eliminate maintenance burden",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Create layer configuration system",
+      "description": "As a CLI maintainer, I want technology layers defined in a config file so that adding or modifying layers only requires changing one file.",
+      "acceptanceCriteria": [
+        "Add LAYER_CONFIG export to src/mergers/config.js alongside existing CMS_CONFIG",
+        "Each layer config defines: replaceFiles, additivePaths, dependencies, devDependencies",
+        "Add getLayerConfig(layer) helper function export",
+        "Config contains entries for webgl, webgpu, and experiment",
+        "webgpu is a deps-only layer (empty replaceFiles and additivePaths arrays)",
+        "webgl dependencies: @react-three/fiber ^9.5.0, @react-three/drei ^10.7.7, three ^0.182.0, @gsap/react ^2.0.0, @radix-ui/react-navigation-menu ^1.2.5, leva ^0.9.35, devDeps: @types/three ^0.182.0",
+        "webgpu dependencies: @react-three/fiber 10.0.0-alpha.2, @react-three/drei ^11.0.0-alpha.4, three ^0.182.0, leva ^0.9.35, lucide-react ^0.474.0, @radix-ui/react-navigation-menu ^1.2.5, devDeps: @types/three ^0.182.0",
+        "experiment dependencies: @react-three/fiber ^9.5.0, @react-three/drei ^10.7.7, three ^0.172.0, leva ^0.9.35, lucide-react ^0.474.0, @radix-ui/react-navigation-menu ^1.2.5, devDeps: @types/three ^0.182.0",
+        "Typecheck passes"
+      ],
+      "priority": 1,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-002",
+      "title": "Extract layer files from templates",
+      "description": "As a CLI maintainer, I need the unique files from each template extracted into a layers/ directory so they can be overlaid on next-starter.",
+      "acceptanceCriteria": [
+        "Create layers/webgl/app/page.tsx copied from template/webgl/app/page.tsx (the one that imports DynamicCanvas)",
+        "Create layers/webgl/components/webgl/canvas/dynamic.tsx from template/webgl/components/webgl/canvas/dynamic.tsx",
+        "Create layers/webgl/components/webgl/canvas/index.tsx from template/webgl/components/webgl/canvas/index.tsx",
+        "Create layers/webgl/components/webgl/components/scene/index.tsx from template/webgl/components/webgl/components/scene/index.tsx",
+        "Create layers/experiment/components/layout/header/index.tsx from template/experiment/components/layout/header/index.tsx",
+        "Create layers/experiment/components/layout/navigation-menu.tsx from template/experiment/components/layout/navigation-menu.tsx",
+        "Create layers/experiment/lib/constats.ts from template/experiment/lib/constats.ts",
+        "Create layers/experiment/lib/utils/cn.ts from template/experiment/lib/utils/cn.ts",
+        "Create empty layers/webgpu/ directory with a .gitkeep file",
+        "All copied files are byte-for-byte identical to their template source files",
+        "Typecheck passes"
+      ],
+      "priority": 2,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-003",
+      "title": "Implement layer injection function",
+      "description": "As the CLI system, I need to overlay layer-specific files on top of the next-starter base so that WebGL/WebGPU/Experiment projects get their unique components.",
+      "acceptanceCriteria": [
+        "Add injectLayer(targetDir, layer, spinner) function to src/mergers/index.js",
+        "Function resolves layer directory from CLI repo's layers/{type}/ path using __dirname",
+        "Function calls existing detectPathPrefix() to handle src/ directory structure",
+        "Function copies additive files from local layers/ directory (no tiged clone needed)",
+        "Function replaces files listed in replaceFiles config (overwrites base version with overwrite: true)",
+        "Function uses existing transformPath() for path prefix support",
+        "Function returns results object with replaced, copied, skipped, and failed arrays",
+        "When layer is 'default' or not found in config, function returns early with skipped result (no error)",
+        "Extend formatMergeResults() to display replaced entries with checkmark prefix",
+        "Typecheck passes"
+      ],
+      "priority": 3,
+      "passes": true,
+      "notes": "Reuses existing detectPathPrefix() and transformPath() from src/mergers/index.js. Layer files are local (no network request)."
+    },
+    {
+      "id": "US-004",
+      "title": "Change create.js to clone next-starter instead of template",
+      "description": "As a developer using the CLI, I want my project scaffolded from the latest next-starter repo so I always get the most up-to-date base.",
+      "acceptanceCriteria": [
+        "Change tiged source on line 124 of src/commands/create.js from 'github:basementstudio/basement-cli/template/${type}#${branch}' to 'github:basementstudio/next-starter#main'",
+        "Remove the BASEMENT_CLI_BRANCH env var usage for template (keep if used elsewhere)",
+        "Delete bun.lock file after clone if it exists (since dependencies will be modified)",
+        "Update download spinner text to say 'Downloading next-starter from GitHub...' instead of mentioning template type",
+        "Update error/troubleshooting message in catch block to reference basementstudio/next-starter instead of basementstudio/basement-cli/template/{type}",
+        "Typecheck passes"
+      ],
+      "priority": 4,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-005",
+      "title": "Wire layer injection into create flow",
+      "description": "As the CLI system, I need the layer injection step between template download and CMS integration so layers are applied at the right time.",
+      "acceptanceCriteria": [
+        "Add new step between template download (step 3) and CMS integration (step 3.5) in src/commands/create.js",
+        "Layer injection only runs when type !== 'default'",
+        "Import injectLayer and formatMergeResults from src/mergers/index.js",
+        "Show ora spinner with layer name during injection (e.g. 'Applying webgl layer...')",
+        "Display injection results to user using formatMergeResults",
+        "On failure, show warning (not hard error) and continue with project creation",
+        "Typecheck passes"
+      ],
+      "priority": 5,
+      "passes": true,
+      "notes": "Must run BEFORE CMS integration because layers don't modify layout.tsx, and CMS mergers need the base layout intact."
+    },
+    {
+      "id": "US-006",
+      "title": "Config-driven dependency injection in package.json hydration",
+      "description": "As the CLI system, I need package.json hydration to read layer dependencies from LAYER_CONFIG instead of being hardcoded.",
+      "acceptanceCriteria": [
+        "Import getLayerConfig from src/mergers/config.js in create.js",
+        "Read layer dependencies from LAYER_CONFIG and merge into package.json: pkg.dependencies = { ...pkg.dependencies, ...layerConfig.dependencies }",
+        "Also merge devDependencies from layer config",
+        "CMS dependency injection (Sanity/BaseHub) still works unchanged",
+        "Animation library injection (GSAP/Framer Motion) still works unchanged",
+        "Simplify package.json handling: next-starter uses package.json directly (not package.template.json), remove the rename logic",
+        "Project name still set to user-provided name, version still set to 0.1.0",
+        "Typecheck passes"
+      ],
+      "priority": 6,
+      "passes": true,
+      "notes": "next-starter uses package.json not package.template.json, so the existsSync check for package.template.json can be simplified."
+    },
+    {
+      "id": "US-007",
+      "title": "Delete template directory",
+      "description": "As a CLI maintainer, I want the template/ directory removed so there's no duplicated code to maintain.",
+      "acceptanceCriteria": [
+        "Delete template/default/ directory and all contents",
+        "Delete template/webgl/ directory and all contents",
+        "Delete template/webgpu/ directory and all contents",
+        "Delete template/experiment/ directory and all contents",
+        "Grep source code for any remaining references to 'template/' paths and remove them",
+        "Grep source code for any remaining references to 'basementstudio/basement-cli/template/' and remove them",
+        "Typecheck passes"
+      ],
+      "priority": 7,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-008",
+      "title": "End-to-end verification of all template types",
+      "description": "As a CLI maintainer, I need to verify all template + CMS + animation combinations produce working projects.",
+      "acceptanceCriteria": [
+        "Run npm link to install CLI locally",
+        "Run: basement -c test-default -d -no-cms -no-animation -claude -no-hooks — project creates successfully",
+        "Run: basement -c test-webgl -webgl -no-cms -no-animation -claude -no-hooks — project has R3F components in components/webgl/",
+        "Run: basement -c test-webgpu -webgpu -no-cms -no-animation -claude -no-hooks — project has WebGPU deps in package.json",
+        "Run: basement -c test-experiment -exp -no-cms -no-animation -claude -no-hooks — project has custom header with NavigationMenu",
+        "Run: basement -c test-sanity -webgl -sanity -gsap -claude -no-hooks — project has CMS + animation + layer deps",
+        "All generated projects pass bun install without errors",
+        "Typecheck passes"
+      ],
+      "priority": 8,
+      "passes": true,
+      "notes": "This is the final validation step. Each test project should be cleaned up after verification."
+    }
+  ]
+}

package/tasks/progress.txt

@@ -0,0 +1,115 @@
+## Codebase Patterns
+- This is a plain JS (ESM) CLI project - no TypeScript, no typecheck command. "Typecheck passes" = no syntax errors.
+- Config pattern: export const CONFIG object + getXConfig(name) helper that returns config or null
+- src/mergers/config.js holds all configuration (CMS_CONFIG, LAYER_CONFIG)
+- src/mergers/index.js holds injection/merge logic (injectIntegration for CMS, injectLayer for layers)
+- src/commands/create.js is the main CLI flow
+- next-starter uses package.json directly (no template rename needed)
+- Layer files are local (in layers/ directory), CMS integration files are remote (fetched via tiged)
+- ESM requires __dirname workaround: `path.dirname(fileURLToPath(import.meta.url))`
+- CLI binary is basement (defined in package.json bin field)
+- Dependency injection order in create.js: layer deps → CMS deps → animation deps
+
+---
+
+## 2026-02-09 - US-001
+- Implemented LAYER_CONFIG export with webgl, webgpu, experiment entries
+- Added getLayerConfig() helper function
+- Each layer config has: replaceFiles, additivePaths, dependencies, devDependencies
+- webgpu is deps-only (empty replaceFiles and additivePaths)
+- Files changed: src/mergers/config.js
+- **Learnings for future iterations:**
+  - The CLI project is plain JS ESM, verified by running `node --input-type=module -e "import {...}"`
+  - Config pattern follows existing CMS_CONFIG style - object + getter helper
+  - experiment uses three ^0.172.0 (not ^0.182.0 like webgl/webgpu) per PRD
+---
+
+## 2026-02-09 - US-002
+- Created layers/webgl/ with app/page.tsx and 3 webgl component files from template/webgl/
+- Created layers/experiment/ with header, navigation-menu, constats.ts, cn.ts from template/experiment/
+- Created layers/webgpu/.gitkeep (empty layer, deps-only)
+- Verified all files are byte-for-byte identical using diff
+- Files changed: 9 new files in layers/
+- **Learnings for future iterations:**
+  - Layer files are local to CLI repo (no network clone needed, unlike CMS integrations)
+  - webgl is the only layer with a different app/page.tsx (imports DynamicCanvas)
+  - experiment has its own header and navigation-menu components
+---
+
+## 2026-02-09 - US-003
+- Added injectLayer(targetDir, layer, spinner) function to src/mergers/index.js
+- Uses __dirname (via import.meta.url + fileURLToPath) to resolve layers/ directory
+- Reuses detectPathPrefix() and transformPath() for src/ directory support
+- Handles replaceFiles (overwrite: true) and additivePaths (overwrite: false) separately
+- Returns results with replaced, copied, skipped, failed arrays
+- Extended formatMergeResults() with defensive optional chaining for replaced/merged/copied/etc
+- Files changed: src/mergers/index.js
+- **Learnings for future iterations:**
+  - ESM doesn't have __dirname, must use: `const __dirname = path.dirname(fileURLToPath(import.meta.url))`
+  - Layer injection is purely local file copy (no network), unlike CMS integration which uses tiged
+  - formatMergeResults now handles both CMS results (merged) and layer results (replaced) gracefully
+---
+
+## 2026-02-09 - US-004
+- Changed tiged source from basement/template/${type} to basementstudio/next-starter#main
+- Removed BASEMENT_CLI_BRANCH env var usage (was only used for template, not used elsewhere)
+- Added bun.lock deletion after clone (since deps will be modified by layers/CMS/animation)
+- Updated spinner text to "Downloading next-starter from GitHub..."
+- Updated troubleshooting message to reference basementstudio/next-starter
+- Kept dotenv import as it may be used by merger modules
+- Files changed: src/commands/create.js
+- **Learnings for future iterations:**
+  - dotenv is loaded in create.js but env vars are only used in merger modules (check-integration-merger.js)
+  - bun.lock must be deleted before modifying package.json deps, otherwise bun install may conflict
+---
+
+## 2026-02-09 - US-005
+- Added layer injection step (3.2) between template download and CMS integration (3.5)
+- Layer injection only runs when type !== 'default'
+- Uses dynamic import for injectLayer and formatMergeResults from mergers/index.js
+- Shows ora spinner with layer name during injection
+- On failure, shows warning and continues (not a hard error)
+- Files changed: src/commands/create.js
+- **Learnings for future iterations:**
+  - Layer injection MUST happen before CMS integration to keep layout.tsx intact for CMS mergers
+  - Uses dynamic import (await import) consistent with existing CMS integration pattern
+---
+
+## 2026-02-09 - US-006
+- Imported getLayerConfig from src/mergers/config.js at top of create.js
+- Layer deps injected from LAYER_CONFIG before CMS and animation deps
+- Simplified package.json handling: removed package.template.json logic (next-starter uses package.json directly)
+- CMS and animation dependency injection unchanged
+- Project name and version still set correctly
+- Files changed: src/commands/create.js
+- **Learnings for future iterations:**
+  - Dependency injection order matters: layer deps first, then CMS, then animation (later ones override earlier)
+  - next-starter uses package.json directly, no need for package.template.json rename logic
+---
+
+## 2026-02-09 - US-007
+- Deleted template/default/, template/webgl/, template/webgpu/, template/experiment/ directories
+- Removed entire template/ directory (281 files, -27,778 lines)
+- Verified no remaining references to template/ paths in source code (src/)
+- Updated CLAUDE.md to reflect new architecture (layers/ instead of template/)
+- Files changed: template/ deleted, CLAUDE.md updated
+- **Learnings for future iterations:**
+  - CLAUDE.md should be kept in sync with architecture changes
+  - Only documentation files (CLAUDE.md, PRD) had remaining references to template/ paths, not source code
+---
+
+## 2026-02-09 - US-008
+- Installed CLI locally via npm link
+- E2E test results (all passed):
+  - test-default: Created successfully, name=test-default, version=0.1.0, has next dep, no R3F deps
+  - test-webgl: Created with layer applied (replaced page.tsx, added 3 webgl components), R3F ^9.5.0, three ^0.182.0, @types/three ^0.182.0
+  - test-webgpu: Created with deps-only layer, R3F 10.0.0-alpha.2, drei ^11.0.0-alpha.4, lucide-react ^0.474.0
+  - test-experiment: Created with layer (header, navigation-menu, constats.ts, cn.ts), three ^0.172.0
+  - test-sanity: Combined webgl + sanity + gsap - all deps present (R3F, next-sanity, sanity, gsap, @gsap/react, sanity:extract script)
+- All 4 projects pass bun install without errors
+- CLI command is basement (not basement-starter as PRD mentions)
+- **Learnings for future iterations:**
+  - Skills installation may fail without network (bunx skills add), but it's non-blocking
+  - The sanity integration triggers an interactive Sanity setup prompt after project creation
+  - bun install correctly resolves all dependency versions including alpha packages
+---

package/template-hooks/use-battery.ts

@@ -0,0 +1,126 @@
+"use client";
+
+import isEqual from "lodash-es/isEqual";
+import { useEffect, useState } from "react";
+
+// misc
+
+function on<T extends Window | Document | HTMLElement | EventTarget>(
+	obj: T | null,
+
+	...args:
+		| Parameters<T["addEventListener"]>
+		| [string, EventListenerOrEventListenerObject | null, ...unknown[]]
+): void {
+	if (obj?.addEventListener) {
+		obj.addEventListener(
+			...(args as Parameters<HTMLElement["addEventListener"]>),
+		);
+	}
+}
+
+function off<T extends Window | Document | HTMLElement | EventTarget>(
+	obj: T | null,
+	...args:
+		| Parameters<T["removeEventListener"]>
+		| [string, EventListenerOrEventListenerObject | null, ...unknown[]]
+): void {
+	if (obj?.removeEventListener) {
+		obj.removeEventListener(
+			...(args as Parameters<HTMLElement["removeEventListener"]>),
+		);
+	}
+}
+
+const isNavigator = typeof navigator !== "undefined";
+
+// hook
+
+export interface BatteryState {
+	charging: boolean;
+	chargingTime: number;
+	dischargingTime: number;
+	level: number;
+}
+
+interface BatteryManager extends Readonly<BatteryState>, EventTarget {
+	onchargingchange: () => void;
+	onchargingtimechange: () => void;
+	ondischargingtimechange: () => void;
+	onlevelchange: () => void;
+}
+
+interface NavigatorWithPossibleBattery extends Navigator {
+	getBattery?: () => Promise<BatteryManager>;
+}
+
+type UseBatteryState =
+	| { isSupported: false } // Battery API is not supported
+	| { isSupported: true; fetched: false } // battery API supported but not fetched yet
+	| (BatteryState & { isSupported: true; fetched: true }); // battery API supported and fetched
+
+const nav: NavigatorWithPossibleBattery | undefined = isNavigator
+	? navigator
+	: undefined;
+const isBatteryApiSupported = nav && typeof nav.getBattery === "function";
+
+function useBatteryMock(): UseBatteryState {
+	return { isSupported: false };
+}
+
+function useBatteryReal(): UseBatteryState {
+	const [state, setState] = useState<UseBatteryState>({
+		isSupported: true,
+		fetched: false,
+	});
+
+	useEffect(() => {
+		let isMounted = true;
+		let battery: BatteryManager | null = null;
+
+		const handleChange = (): void => {
+			if (!isMounted || !battery) {
+				return;
+			}
+			const newState: UseBatteryState = {
+				isSupported: true,
+				fetched: true,
+				level: battery.level,
+				charging: battery.charging,
+				dischargingTime: battery.dischargingTime,
+				chargingTime: battery.chargingTime,
+			};
+			// eslint-disable-next-line @typescript-eslint/no-unused-expressions
+			!isEqual(state, newState) && setState(newState);
+		};
+
+		nav?.getBattery?.().then((bat: BatteryManager) => {
+			if (!isMounted) {
+				return;
+			}
+			battery = bat;
+			on(battery, "chargingchange", handleChange);
+			on(battery, "chargingtimechange", handleChange);
+			on(battery, "dischargingtimechange", handleChange);
+			on(battery, "levelchange", handleChange);
+			handleChange();
+		});
+
+		return () => {
+			isMounted = false;
+			if (battery) {
+				off(battery, "chargingchange", handleChange);
+				off(battery, "chargingtimechange", handleChange);
+				off(battery, "dischargingtimechange", handleChange);
+				off(battery, "levelchange", handleChange);
+			}
+		};
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, []);
+
+	return state;
+}
+
+export const useBattery = isBatteryApiSupported
+	? useBatteryReal
+	: useBatteryMock;

package/template-hooks/use-device-perf.ts

@@ -0,0 +1,184 @@
+"use client";
+
+import type { TierResult } from "detect-gpu";
+import { memo, useEffect } from "react";
+import { create } from "zustand";
+import { useShallow } from "zustand/react/shallow";
+
+import { Quality, useAppStore } from "@/stores/use-app-store";
+
+import { useBattery } from "./use-battery";
+
+export interface DeviceType {
+	browserName: string;
+	browserVersion: string;
+	deviceType: string;
+	engineName: string;
+	engineVersion: string;
+	fullBrowserVersion: string;
+	getUA: string;
+	isAndroid: boolean;
+	isBrowser: boolean;
+	isChrome: boolean;
+	isChromium: boolean;
+	isConsole: boolean;
+	isDesktop: boolean;
+	isEdge: boolean;
+	isEdgeChromium: boolean;
+	isElectron: boolean;
+	isEmbedded: boolean;
+	isFirefox: boolean;
+	isIE: boolean;
+	isIOS: boolean;
+	isIOS13: boolean;
+	isIPad13: boolean;
+	isIPhone13: boolean;
+	isIPod13: boolean;
+	isLegacyEdge: boolean;
+	isMIUI: boolean;
+	isMacOs: boolean;
+	isMobile: boolean;
+	isMobileOnly: boolean;
+	isMobileSafari: boolean;
+	isOpera: boolean;
+	isSafari: boolean;
+	isSamsungBrowser: boolean;
+	isSmartTV: boolean;
+	isTablet: boolean;
+	isWearable: boolean;
+	isWinPhone: boolean;
+	isWindows: boolean;
+	isYandex: boolean;
+	mobileModel: string;
+	mobileVendor: string;
+	osName: string;
+	osVersion: string;
+}
+
+interface Battery {
+	charging: boolean;
+	level: number;
+}
+
+interface UseDeviceStore {
+	device: DeviceType | null;
+	gpu: TierResult | null;
+	battery: Battery | null;
+}
+
+export const useDevice = create<UseDeviceStore>(() => ({
+	device: null,
+	gpu: null,
+	battery: null,
+}));
+
+function useSyncDeviceScore(): void {
+	const deviceData = useDevice(useShallow((state) => state.device));
+	const gpuData = useDevice(useShallow((state) => state.gpu));
+	const batteryData = useDevice(useShallow((state) => state.battery));
+
+	useEffect(() => {
+		let score = Quality.HIGH;
+
+		if (deviceData) {
+			if (deviceData.isMobile) {
+				score = Math.min(score, Quality.LOW);
+			} else if (deviceData.isTablet) {
+				score = Math.min(score, Quality.MEDIUM);
+			} else if (deviceData.isDesktop) {
+				score = Math.min(score, Quality.HIGH);
+			}
+		}
+
+		if (!batteryData) {
+			// not battery
+			score = Math.min(score, Quality.HIGH);
+		} else {
+			// has battery
+			if (batteryData.charging) {
+				if (batteryData.level > 0.3) {
+					// charging and high
+					score = Math.min(score, Quality.HIGH);
+				} else {
+					// charging but low
+					score = Math.min(score, Quality.LOW);
+				}
+			} else {
+				if (batteryData.level > 0.5) {
+					// not charging but high
+					score = Math.min(score, Quality.HIGH);
+				} else {
+					// not charging and low
+					score = Math.min(score, Quality.LOW);
+				}
+			}
+		}
+
+		if (gpuData) {
+			if (gpuData.tier === 3) {
+				score = Math.min(score, Quality.HIGH);
+			} else if (gpuData.tier === 2) {
+				score = Math.min(score, Quality.MEDIUM);
+			} else if (gpuData.tier === 1) {
+				score = Math.min(score, Quality.LOW);
+			}
+		}
+
+		useAppStore.setState({
+			qualityConfig: score,
+		});
+	}, [deviceData, gpuData, batteryData]);
+}
+
+// this hook will save the device information in the store
+export const DeviceDetector = memo(function MemoDetector() {
+	const battery = useBattery();
+
+	useEffect(() => {
+		if (battery.isSupported && battery.fetched) {
+			useDevice.setState({
+				battery: {
+					charging: battery.charging,
+					level: battery.level,
+				},
+			});
+		}
+	}, [battery]);
+
+	useEffect(() => {
+		if (typeof window === "undefined") return;
+		const abortController = new AbortController();
+		const signal = abortController.signal;
+
+		void import("react-device-detect").then((module) => {
+			if (signal.aborted) return;
+
+			const newState = module.getSelectorsByUserAgent(
+				navigator.userAgent,
+			) as DeviceType;
+
+			useDevice.setState({
+				device: newState,
+			});
+		});
+
+		void import("detect-gpu").then(({ getGPUTier }) => {
+			if (signal.aborted) return;
+
+			getGPUTier().then((gpu) => {
+				if (signal.aborted) return;
+				useDevice.setState({
+					gpu,
+				});
+			});
+		});
+
+		return () => {
+			abortController.abort();
+		};
+	}, []);
+
+	useSyncDeviceScore();
+
+	return null;
+});

package/template-hooks/use-intersection-observer.ts

@@ -0,0 +1,32 @@
+import * as React from "react";
+
+export const useIntersectionObserver = <T extends Element>(
+	options: IntersectionObserverInit & { triggerOnce?: boolean },
+) => {
+	const ref = React.useRef<T>(null);
+	const [inView, setInView] = React.useState(false);
+
+	React.useEffect(() => {
+		const elementToObserve = ref.current;
+		if (!elementToObserve) return;
+		const handleObserve: IntersectionObserverCallback = ([element]) => {
+			if (element) {
+				setInView((p) => {
+					// trigger once?
+					if (options?.triggerOnce && p === true) return p;
+					else return element.isIntersecting;
+				});
+			}
+		};
+
+		const observer = new IntersectionObserver(handleObserve, options);
+
+		observer.observe(elementToObserve);
+
+		return () => {
+			observer.disconnect();
+		};
+	}, [options]);
+
+	return [ref, inView] as const;
+};

package/template-hooks/use-media.ts

@@ -0,0 +1,33 @@
+import * as React from "react";
+
+import { isApiSupported } from "@/utils";
+
+export const useMedia = (mediaQuery: string, initialValue?: boolean) => {
+	const [isVerified, setIsVerified] = React.useState<boolean | undefined>(
+		initialValue,
+	);
+
+	React.useEffect(() => {
+		if (!isApiSupported("matchMedia")) {
+			console.warn("matchMedia is not supported by your current browser");
+			return;
+		}
+		const mediaQueryList = window.matchMedia(mediaQuery);
+		const changeHandler = () => setIsVerified(!!mediaQueryList.matches);
+
+		changeHandler();
+		if (typeof mediaQueryList.addEventListener === "function") {
+			mediaQueryList.addEventListener("change", changeHandler);
+			return () => {
+				mediaQueryList.removeEventListener("change", changeHandler);
+			};
+		} else if (typeof mediaQueryList.addListener === "function") {
+			mediaQueryList.addListener(changeHandler);
+			return () => {
+				mediaQueryList.removeListener(changeHandler);
+			};
+		}
+	}, [mediaQuery]);
+
+	return isVerified;
+};