@sublimee/backgrounds 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Figueroa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,40 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties } from 'react';
+
+interface StarfieldBackgroundProps {
+    /** Canvas background color */
+    bgColor?: string;
+    /** Base star RGB color */
+    starColor?: string;
+    /** Secondary star RGB color (mixed in) */
+    accentColor?: string;
+    /** 0-1, fraction of accent stars */
+    accentRatio?: number;
+    /** Total number of stars */
+    starCount?: number;
+    /** Maximum drift speed (px/frame) */
+    maxSpeed?: number;
+    /** Smallest star radius */
+    minRadius?: number;
+    /** Largest star radius */
+    maxRadius?: number;
+    /** Enable opacity oscillation */
+    twinkle?: boolean;
+    /** Oscillation speed multiplier */
+    twinkleSpeed?: number;
+    /** Enable parallax size layers */
+    depth?: boolean;
+    /** Enable random shooting stars */
+    shootingStars?: boolean;
+    /** 0-1, spawn chance per frame */
+    shootingStarFrequency?: number;
+    /** Extra Tailwind / CSS classes */
+    className?: string;
+    /** Extra inline styles */
+    style?: CSSProperties;
+    /** Target frame rate (0 = uncapped) */
+    fps?: number;
+}
+declare function StarfieldBackground({ bgColor, starColor, accentColor, accentRatio, starCount, maxSpeed, minRadius, maxRadius, twinkle, twinkleSpeed, depth, shootingStars, shootingStarFrequency, className, style, fps, }: StarfieldBackgroundProps): react_jsx_runtime.JSX.Element;
+
+export { StarfieldBackground, type StarfieldBackgroundProps };

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties } from 'react';
+
+interface StarfieldBackgroundProps {
+    /** Canvas background color */
+    bgColor?: string;
+    /** Base star RGB color */
+    starColor?: string;
+    /** Secondary star RGB color (mixed in) */
+    accentColor?: string;
+    /** 0-1, fraction of accent stars */
+    accentRatio?: number;
+    /** Total number of stars */
+    starCount?: number;
+    /** Maximum drift speed (px/frame) */
+    maxSpeed?: number;
+    /** Smallest star radius */
+    minRadius?: number;
+    /** Largest star radius */
+    maxRadius?: number;
+    /** Enable opacity oscillation */
+    twinkle?: boolean;
+    /** Oscillation speed multiplier */
+    twinkleSpeed?: number;
+    /** Enable parallax size layers */
+    depth?: boolean;
+    /** Enable random shooting stars */
+    shootingStars?: boolean;
+    /** 0-1, spawn chance per frame */
+    shootingStarFrequency?: number;
+    /** Extra Tailwind / CSS classes */
+    className?: string;
+    /** Extra inline styles */
+    style?: CSSProperties;
+    /** Target frame rate (0 = uncapped) */
+    fps?: number;
+}
+declare function StarfieldBackground({ bgColor, starColor, accentColor, accentRatio, starCount, maxSpeed, minRadius, maxRadius, twinkle, twinkleSpeed, depth, shootingStars, shootingStarFrequency, className, style, fps, }: StarfieldBackgroundProps): react_jsx_runtime.JSX.Element;
+
+export { StarfieldBackground, type StarfieldBackgroundProps };

package/dist/index.js

@@ -0,0 +1,244 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  StarfieldBackground: () => StarfieldBackground
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/starfield-background.tsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var HEX_REGEX = /^#?([a-fA-F0-9]{6})$/;
+function hexToRgb(hex) {
+  const match = hex.trim().match(HEX_REGEX);
+  if (!match) {
+    console.warn(`[StarfieldBackground] Invalid hex color "${hex}", defaulting to white`);
+    return { r: 255, g: 255, b: 255 };
+  }
+  const h = match[1];
+  return {
+    r: parseInt(h.substring(0, 2), 16),
+    g: parseInt(h.substring(2, 4), 16),
+    b: parseInt(h.substring(4, 6), 16)
+  };
+}
+function lerp(a, b, t) {
+  return a + (b - a) * t;
+}
+function rand(min, max) {
+  return Math.random() * (max - min) + min;
+}
+function StarfieldBackground({
+  bgColor = "#000000",
+  starColor = "#ffffff",
+  accentColor = "#facc15",
+  accentRatio = 0.15,
+  starCount = 600,
+  maxSpeed = 0.35,
+  minRadius = 0.4,
+  maxRadius = 2.2,
+  twinkle = true,
+  twinkleSpeed = 1,
+  depth = true,
+  shootingStars = true,
+  shootingStarFrequency = 3e-3,
+  className = "",
+  style = {},
+  fps = 60
+}) {
+  const canvasRef = (0, import_react.useRef)(null);
+  const animRef = (0, import_react.useRef)(0);
+  const starsRef = (0, import_react.useRef)([]);
+  const shootingRef = (0, import_react.useRef)([]);
+  const sizeRef = (0, import_react.useRef)({ w: 0, h: 0 });
+  const makeStar = (0, import_react.useCallback)(
+    (w, h) => {
+      const isAccent = Math.random() < accentRatio;
+      const layer = depth ? rand(0.3, 1) : 1;
+      return {
+        x: rand(0, w),
+        y: rand(0, h),
+        r: lerp(minRadius, maxRadius, layer),
+        vx: rand(-maxSpeed, maxSpeed) * layer,
+        vy: rand(-maxSpeed, maxSpeed) * layer,
+        opacity: rand(0.4, 1),
+        phase: rand(0, Math.PI * 2),
+        twinkleRate: rand(5e-3, 0.025) * twinkleSpeed,
+        color: isAccent ? accentColor : starColor,
+        layer
+      };
+    },
+    [
+      accentRatio,
+      starColor,
+      accentColor,
+      minRadius,
+      maxRadius,
+      maxSpeed,
+      depth,
+      twinkleSpeed
+    ]
+  );
+  const makeShootingStar = (0, import_react.useCallback)(
+    (w, h) => {
+      const angle = rand(Math.PI * 0.15, Math.PI * 0.35);
+      const speed = rand(6, 14);
+      return {
+        x: rand(-w * 0.1, w * 0.7),
+        y: rand(-h * 0.1, h * 0.3),
+        vx: Math.cos(angle) * speed,
+        vy: Math.sin(angle) * speed,
+        life: 1,
+        decay: rand(8e-3, 0.02),
+        length: rand(40, 120),
+        width: rand(1, 2.5)
+      };
+    },
+    []
+  );
+  (0, import_react.useEffect)(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+    const dpr = window.devicePixelRatio || 1;
+    const resize = () => {
+      const rect = canvas.parentElement?.getBoundingClientRect() ?? {
+        width: window.innerWidth,
+        height: window.innerHeight
+      };
+      const w2 = rect.width;
+      const h2 = rect.height;
+      canvas.width = w2 * dpr;
+      canvas.height = h2 * dpr;
+      canvas.style.width = `${w2}px`;
+      canvas.style.height = `${h2}px`;
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+      sizeRef.current = { w: w2, h: h2 };
+    };
+    resize();
+    const { w, h } = sizeRef.current;
+    starsRef.current = Array.from({ length: starCount }, () => makeStar(w, h));
+    const interval = fps > 0 ? 1e3 / fps : 0;
+    let last = 0;
+    const draw = (now) => {
+      animRef.current = requestAnimationFrame(draw);
+      if (interval > 0 && now - last < interval) return;
+      last = now;
+      const { w: cw, h: ch } = sizeRef.current;
+      if (cw === 0 || ch === 0) return;
+      ctx.fillStyle = bgColor;
+      ctx.fillRect(0, 0, cw, ch);
+      const stars = starsRef.current;
+      for (let i = 0; i < stars.length; i++) {
+        const s = stars[i];
+        s.x += s.vx;
+        s.y += s.vy;
+        if (s.x < -4) s.x = cw + 4;
+        if (s.x > cw + 4) s.x = -4;
+        if (s.y < -4) s.y = ch + 4;
+        if (s.y > ch + 4) s.y = -4;
+        let alpha = s.opacity;
+        if (twinkle) {
+          s.phase += s.twinkleRate;
+          alpha = s.opacity * (0.5 + 0.5 * Math.sin(s.phase));
+        }
+        const { r, g, b } = hexToRgb(s.color);
+        ctx.fillStyle = `rgba(${r},${g},${b},${alpha.toFixed(3)})`;
+        if (s.r > 1.2) {
+          ctx.shadowBlur = s.r * 3;
+          ctx.shadowColor = `rgba(${r},${g},${b},${(alpha * 0.5).toFixed(3)})`;
+        } else {
+          ctx.shadowBlur = 0;
+        }
+        ctx.beginPath();
+        ctx.arc(s.x, s.y, s.r, 0, Math.PI * 2);
+        ctx.fill();
+      }
+      ctx.shadowBlur = 0;
+      if (shootingStars) {
+        if (Math.random() < shootingStarFrequency) {
+          shootingRef.current.push(makeShootingStar(cw, ch));
+        }
+        const shots = shootingRef.current;
+        for (let i = shots.length - 1; i >= 0; i--) {
+          const ss = shots[i];
+          ss.x += ss.vx;
+          ss.y += ss.vy;
+          ss.life -= ss.decay;
+          if (ss.life <= 0) {
+            shots.splice(i, 1);
+            continue;
+          }
+          const tailX = ss.x - ss.vx / Math.hypot(ss.vx, ss.vy) * ss.length;
+          const tailY = ss.y - ss.vy / Math.hypot(ss.vx, ss.vy) * ss.length;
+          const grad = ctx.createLinearGradient(tailX, tailY, ss.x, ss.y);
+          grad.addColorStop(0, `rgba(255,255,255,0)`);
+          grad.addColorStop(1, `rgba(255,255,255,${ss.life.toFixed(3)})`);
+          ctx.strokeStyle = grad;
+          ctx.lineWidth = ss.width;
+          ctx.lineCap = "round";
+          ctx.beginPath();
+          ctx.moveTo(tailX, tailY);
+          ctx.lineTo(ss.x, ss.y);
+          ctx.stroke();
+        }
+      }
+    };
+    animRef.current = requestAnimationFrame(draw);
+    const ro = new ResizeObserver(() => {
+      resize();
+      const { w: nw, h: nh } = sizeRef.current;
+      starsRef.current.forEach((s) => {
+        if (s.x > nw) s.x = rand(0, nw);
+        if (s.y > nh) s.y = rand(0, nh);
+      });
+    });
+    if (canvas.parentElement) ro.observe(canvas.parentElement);
+    return () => {
+      cancelAnimationFrame(animRef.current);
+      ro.disconnect();
+    };
+  }, [
+    bgColor,
+    starCount,
+    twinkle,
+    shootingStars,
+    shootingStarFrequency,
+    fps,
+    makeStar,
+    makeShootingStar
+  ]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "canvas",
+    {
+      ref: canvasRef,
+      className: `absolute inset-0 ${className}`,
+      style: { pointerEvents: "none", ...style },
+      "aria-hidden": "true"
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StarfieldBackground
+});

package/dist/index.mjs

@@ -0,0 +1,217 @@
+// src/starfield-background.tsx
+import { useRef, useEffect, useCallback } from "react";
+import { jsx } from "react/jsx-runtime";
+var HEX_REGEX = /^#?([a-fA-F0-9]{6})$/;
+function hexToRgb(hex) {
+  const match = hex.trim().match(HEX_REGEX);
+  if (!match) {
+    console.warn(`[StarfieldBackground] Invalid hex color "${hex}", defaulting to white`);
+    return { r: 255, g: 255, b: 255 };
+  }
+  const h = match[1];
+  return {
+    r: parseInt(h.substring(0, 2), 16),
+    g: parseInt(h.substring(2, 4), 16),
+    b: parseInt(h.substring(4, 6), 16)
+  };
+}
+function lerp(a, b, t) {
+  return a + (b - a) * t;
+}
+function rand(min, max) {
+  return Math.random() * (max - min) + min;
+}
+function StarfieldBackground({
+  bgColor = "#000000",
+  starColor = "#ffffff",
+  accentColor = "#facc15",
+  accentRatio = 0.15,
+  starCount = 600,
+  maxSpeed = 0.35,
+  minRadius = 0.4,
+  maxRadius = 2.2,
+  twinkle = true,
+  twinkleSpeed = 1,
+  depth = true,
+  shootingStars = true,
+  shootingStarFrequency = 3e-3,
+  className = "",
+  style = {},
+  fps = 60
+}) {
+  const canvasRef = useRef(null);
+  const animRef = useRef(0);
+  const starsRef = useRef([]);
+  const shootingRef = useRef([]);
+  const sizeRef = useRef({ w: 0, h: 0 });
+  const makeStar = useCallback(
+    (w, h) => {
+      const isAccent = Math.random() < accentRatio;
+      const layer = depth ? rand(0.3, 1) : 1;
+      return {
+        x: rand(0, w),
+        y: rand(0, h),
+        r: lerp(minRadius, maxRadius, layer),
+        vx: rand(-maxSpeed, maxSpeed) * layer,
+        vy: rand(-maxSpeed, maxSpeed) * layer,
+        opacity: rand(0.4, 1),
+        phase: rand(0, Math.PI * 2),
+        twinkleRate: rand(5e-3, 0.025) * twinkleSpeed,
+        color: isAccent ? accentColor : starColor,
+        layer
+      };
+    },
+    [
+      accentRatio,
+      starColor,
+      accentColor,
+      minRadius,
+      maxRadius,
+      maxSpeed,
+      depth,
+      twinkleSpeed
+    ]
+  );
+  const makeShootingStar = useCallback(
+    (w, h) => {
+      const angle = rand(Math.PI * 0.15, Math.PI * 0.35);
+      const speed = rand(6, 14);
+      return {
+        x: rand(-w * 0.1, w * 0.7),
+        y: rand(-h * 0.1, h * 0.3),
+        vx: Math.cos(angle) * speed,
+        vy: Math.sin(angle) * speed,
+        life: 1,
+        decay: rand(8e-3, 0.02),
+        length: rand(40, 120),
+        width: rand(1, 2.5)
+      };
+    },
+    []
+  );
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+    const dpr = window.devicePixelRatio || 1;
+    const resize = () => {
+      const rect = canvas.parentElement?.getBoundingClientRect() ?? {
+        width: window.innerWidth,
+        height: window.innerHeight
+      };
+      const w2 = rect.width;
+      const h2 = rect.height;
+      canvas.width = w2 * dpr;
+      canvas.height = h2 * dpr;
+      canvas.style.width = `${w2}px`;
+      canvas.style.height = `${h2}px`;
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+      sizeRef.current = { w: w2, h: h2 };
+    };
+    resize();
+    const { w, h } = sizeRef.current;
+    starsRef.current = Array.from({ length: starCount }, () => makeStar(w, h));
+    const interval = fps > 0 ? 1e3 / fps : 0;
+    let last = 0;
+    const draw = (now) => {
+      animRef.current = requestAnimationFrame(draw);
+      if (interval > 0 && now - last < interval) return;
+      last = now;
+      const { w: cw, h: ch } = sizeRef.current;
+      if (cw === 0 || ch === 0) return;
+      ctx.fillStyle = bgColor;
+      ctx.fillRect(0, 0, cw, ch);
+      const stars = starsRef.current;
+      for (let i = 0; i < stars.length; i++) {
+        const s = stars[i];
+        s.x += s.vx;
+        s.y += s.vy;
+        if (s.x < -4) s.x = cw + 4;
+        if (s.x > cw + 4) s.x = -4;
+        if (s.y < -4) s.y = ch + 4;
+        if (s.y > ch + 4) s.y = -4;
+        let alpha = s.opacity;
+        if (twinkle) {
+          s.phase += s.twinkleRate;
+          alpha = s.opacity * (0.5 + 0.5 * Math.sin(s.phase));
+        }
+        const { r, g, b } = hexToRgb(s.color);
+        ctx.fillStyle = `rgba(${r},${g},${b},${alpha.toFixed(3)})`;
+        if (s.r > 1.2) {
+          ctx.shadowBlur = s.r * 3;
+          ctx.shadowColor = `rgba(${r},${g},${b},${(alpha * 0.5).toFixed(3)})`;
+        } else {
+          ctx.shadowBlur = 0;
+        }
+        ctx.beginPath();
+        ctx.arc(s.x, s.y, s.r, 0, Math.PI * 2);
+        ctx.fill();
+      }
+      ctx.shadowBlur = 0;
+      if (shootingStars) {
+        if (Math.random() < shootingStarFrequency) {
+          shootingRef.current.push(makeShootingStar(cw, ch));
+        }
+        const shots = shootingRef.current;
+        for (let i = shots.length - 1; i >= 0; i--) {
+          const ss = shots[i];
+          ss.x += ss.vx;
+          ss.y += ss.vy;
+          ss.life -= ss.decay;
+          if (ss.life <= 0) {
+            shots.splice(i, 1);
+            continue;
+          }
+          const tailX = ss.x - ss.vx / Math.hypot(ss.vx, ss.vy) * ss.length;
+          const tailY = ss.y - ss.vy / Math.hypot(ss.vx, ss.vy) * ss.length;
+          const grad = ctx.createLinearGradient(tailX, tailY, ss.x, ss.y);
+          grad.addColorStop(0, `rgba(255,255,255,0)`);
+          grad.addColorStop(1, `rgba(255,255,255,${ss.life.toFixed(3)})`);
+          ctx.strokeStyle = grad;
+          ctx.lineWidth = ss.width;
+          ctx.lineCap = "round";
+          ctx.beginPath();
+          ctx.moveTo(tailX, tailY);
+          ctx.lineTo(ss.x, ss.y);
+          ctx.stroke();
+        }
+      }
+    };
+    animRef.current = requestAnimationFrame(draw);
+    const ro = new ResizeObserver(() => {
+      resize();
+      const { w: nw, h: nh } = sizeRef.current;
+      starsRef.current.forEach((s) => {
+        if (s.x > nw) s.x = rand(0, nw);
+        if (s.y > nh) s.y = rand(0, nh);
+      });
+    });
+    if (canvas.parentElement) ro.observe(canvas.parentElement);
+    return () => {
+      cancelAnimationFrame(animRef.current);
+      ro.disconnect();
+    };
+  }, [
+    bgColor,
+    starCount,
+    twinkle,
+    shootingStars,
+    shootingStarFrequency,
+    fps,
+    makeStar,
+    makeShootingStar
+  ]);
+  return /* @__PURE__ */ jsx(
+    "canvas",
+    {
+      ref: canvasRef,
+      className: `absolute inset-0 ${className}`,
+      style: { pointerEvents: "none", ...style },
+      "aria-hidden": "true"
+    }
+  );
+}
+export {
+  StarfieldBackground
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@sublimee/backgrounds",
+  "version": "0.1.0",
+  "description": "Animated background components for Sublime",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/juancrfig/sublime.git",
+    "directory": "packages/backgrounds"
+  },
+  "keywords": [
+    "react",
+    "background",
+    "animation",
+    "canvas",
+    "starfield",
+    "ui",
+    "components"
+  ],
+  "author": "Sublime Team",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "tsup": "^8",
+    "typescript": "^5"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { StarfieldBackground } from "./starfield-background";
+export type { StarfieldBackgroundProps } from "./starfield-background";

package/src/starfield-background.tsx

@@ -0,0 +1,317 @@
+"use client";
+
+import { useRef, useEffect, useCallback, CSSProperties } from "react";
+
+export interface StarfieldBackgroundProps {
+  /** Canvas background color */
+  bgColor?: string;
+  /** Base star RGB color */
+  starColor?: string;
+  /** Secondary star RGB color (mixed in) */
+  accentColor?: string;
+  /** 0-1, fraction of accent stars */
+  accentRatio?: number;
+  /** Total number of stars */
+  starCount?: number;
+  /** Maximum drift speed (px/frame) */
+  maxSpeed?: number;
+  /** Smallest star radius */
+  minRadius?: number;
+  /** Largest star radius */
+  maxRadius?: number;
+  /** Enable opacity oscillation */
+  twinkle?: boolean;
+  /** Oscillation speed multiplier */
+  twinkleSpeed?: number;
+  /** Enable parallax size layers */
+  depth?: boolean;
+  /** Enable random shooting stars */
+  shootingStars?: boolean;
+  /** 0-1, spawn chance per frame */
+  shootingStarFrequency?: number;
+  /** Extra Tailwind / CSS classes */
+  className?: string;
+  /** Extra inline styles */
+  style?: CSSProperties;
+  /** Target frame rate (0 = uncapped) */
+  fps?: number;
+}
+
+interface Star {
+  x: number;
+  y: number;
+  r: number;
+  vx: number;
+  vy: number;
+  opacity: number;
+  phase: number;
+  twinkleRate: number;
+  color: string;
+  layer: number;
+}
+
+interface ShootingStar {
+  x: number;
+  y: number;
+  vx: number;
+  vy: number;
+  life: number;
+  decay: number;
+  length: number;
+  width: number;
+}
+
+// ── helpers ──────────────────────────────────────────────────────
+
+const HEX_REGEX = /^#?([a-fA-F0-9]{6})$/;
+
+function hexToRgb(hex: string): { r: number; g: number; b: number } {
+  const match = hex.trim().match(HEX_REGEX);
+  if (!match) {
+    console.warn(`[StarfieldBackground] Invalid hex color "${hex}", defaulting to white`);
+    return { r: 255, g: 255, b: 255 };
+  }
+  const h = match[1];
+  return {
+    r: parseInt(h.substring(0, 2), 16),
+    g: parseInt(h.substring(2, 4), 16),
+    b: parseInt(h.substring(4, 6), 16),
+  };
+}
+
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t;
+}
+
+function rand(min: number, max: number): number {
+  return Math.random() * (max - min) + min;
+}
+
+// ── component ────────────────────────────────────────────────────
+
+export function StarfieldBackground({
+  bgColor = "#000000",
+  starColor = "#ffffff",
+  accentColor = "#facc15",
+  accentRatio = 0.15,
+  starCount = 600,
+  maxSpeed = 0.35,
+  minRadius = 0.4,
+  maxRadius = 2.2,
+  twinkle = true,
+  twinkleSpeed = 1,
+  depth = true,
+  shootingStars = true,
+  shootingStarFrequency = 0.003,
+  className = "",
+  style = {},
+  fps = 60,
+}: StarfieldBackgroundProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const animRef = useRef<number>(0);
+  const starsRef = useRef<Star[]>([]);
+  const shootingRef = useRef<ShootingStar[]>([]);
+  const sizeRef = useRef({ w: 0, h: 0 });
+
+  // ── star factory ────────────────────────────────────────────
+
+  const makeStar = useCallback(
+    (w: number, h: number): Star => {
+      const isAccent = Math.random() < accentRatio;
+      const layer = depth ? rand(0.3, 1) : 1;
+      return {
+        x: rand(0, w),
+        y: rand(0, h),
+        r: lerp(minRadius, maxRadius, layer),
+        vx: rand(-maxSpeed, maxSpeed) * layer,
+        vy: rand(-maxSpeed, maxSpeed) * layer,
+        opacity: rand(0.4, 1),
+        phase: rand(0, Math.PI * 2),
+        twinkleRate: rand(0.005, 0.025) * twinkleSpeed,
+        color: isAccent ? accentColor : starColor,
+        layer,
+      };
+    },
+    [
+      accentRatio,
+      starColor,
+      accentColor,
+      minRadius,
+      maxRadius,
+      maxSpeed,
+      depth,
+      twinkleSpeed,
+    ]
+  );
+
+  // ── shooting star factory ───────────────────────────────────
+
+  const makeShootingStar = useCallback(
+    (w: number, h: number): ShootingStar => {
+      const angle = rand(Math.PI * 0.15, Math.PI * 0.35);
+      const speed = rand(6, 14);
+      return {
+        x: rand(-w * 0.1, w * 0.7),
+        y: rand(-h * 0.1, h * 0.3),
+        vx: Math.cos(angle) * speed,
+        vy: Math.sin(angle) * speed,
+        life: 1,
+        decay: rand(0.008, 0.02),
+        length: rand(40, 120),
+        width: rand(1, 2.5),
+      };
+    },
+    []
+  );
+
+  // ── main effect ─────────────────────────────────────────────
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+
+    const dpr = window.devicePixelRatio || 1;
+
+    const resize = () => {
+      const rect = canvas.parentElement?.getBoundingClientRect() ?? {
+        width: window.innerWidth,
+        height: window.innerHeight,
+      };
+      const w = rect.width;
+      const h = rect.height;
+      canvas.width = w * dpr;
+      canvas.height = h * dpr;
+      canvas.style.width = `${w}px`;
+      canvas.style.height = `${h}px`;
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+      sizeRef.current = { w, h };
+    };
+
+    resize();
+
+    const { w, h } = sizeRef.current;
+    starsRef.current = Array.from({ length: starCount }, () => makeStar(w, h));
+
+    const interval = fps > 0 ? 1000 / fps : 0;
+    let last = 0;
+
+    const draw = (now: number) => {
+      animRef.current = requestAnimationFrame(draw);
+
+      if (interval > 0 && now - last < interval) return;
+      last = now;
+
+      const { w: cw, h: ch } = sizeRef.current;
+      if (cw === 0 || ch === 0) return;
+
+      ctx.fillStyle = bgColor;
+      ctx.fillRect(0, 0, cw, ch);
+
+      const stars = starsRef.current;
+      for (let i = 0; i < stars.length; i++) {
+        const s = stars[i];
+
+        s.x += s.vx;
+        s.y += s.vy;
+
+        if (s.x < -4) s.x = cw + 4;
+        if (s.x > cw + 4) s.x = -4;
+        if (s.y < -4) s.y = ch + 4;
+        if (s.y > ch + 4) s.y = -4;
+
+        let alpha = s.opacity;
+        if (twinkle) {
+          s.phase += s.twinkleRate;
+          alpha = s.opacity * (0.5 + 0.5 * Math.sin(s.phase));
+        }
+
+        const { r, g, b } = hexToRgb(s.color);
+        ctx.fillStyle = `rgba(${r},${g},${b},${alpha.toFixed(3)})`;
+
+        if (s.r > 1.2) {
+          ctx.shadowBlur = s.r * 3;
+          ctx.shadowColor = `rgba(${r},${g},${b},${(alpha * 0.5).toFixed(3)})`;
+        } else {
+          ctx.shadowBlur = 0;
+        }
+
+        ctx.beginPath();
+        ctx.arc(s.x, s.y, s.r, 0, Math.PI * 2);
+        ctx.fill();
+      }
+
+      ctx.shadowBlur = 0;
+
+      if (shootingStars) {
+        if (Math.random() < shootingStarFrequency) {
+          shootingRef.current.push(makeShootingStar(cw, ch));
+        }
+
+        const shots = shootingRef.current;
+        for (let i = shots.length - 1; i >= 0; i--) {
+          const ss = shots[i];
+          ss.x += ss.vx;
+          ss.y += ss.vy;
+          ss.life -= ss.decay;
+
+          if (ss.life <= 0) {
+            shots.splice(i, 1);
+            continue;
+          }
+
+          const tailX = ss.x - (ss.vx / Math.hypot(ss.vx, ss.vy)) * ss.length;
+          const tailY = ss.y - (ss.vy / Math.hypot(ss.vx, ss.vy)) * ss.length;
+
+          const grad = ctx.createLinearGradient(tailX, tailY, ss.x, ss.y);
+          grad.addColorStop(0, `rgba(255,255,255,0)`);
+          grad.addColorStop(1, `rgba(255,255,255,${ss.life.toFixed(3)})`);
+
+          ctx.strokeStyle = grad;
+          ctx.lineWidth = ss.width;
+          ctx.lineCap = "round";
+          ctx.beginPath();
+          ctx.moveTo(tailX, tailY);
+          ctx.lineTo(ss.x, ss.y);
+          ctx.stroke();
+        }
+      }
+    };
+
+    animRef.current = requestAnimationFrame(draw);
+
+    const ro = new ResizeObserver(() => {
+      resize();
+      const { w: nw, h: nh } = sizeRef.current;
+      starsRef.current.forEach((s) => {
+        if (s.x > nw) s.x = rand(0, nw);
+        if (s.y > nh) s.y = rand(0, nh);
+      });
+    });
+    if (canvas.parentElement) ro.observe(canvas.parentElement);
+
+    return () => {
+      cancelAnimationFrame(animRef.current);
+      ro.disconnect();
+    };
+  }, [
+    bgColor,
+    starCount,
+    twinkle,
+    shootingStars,
+    shootingStarFrequency,
+    fps,
+    makeStar,
+    makeShootingStar,
+  ]);
+
+  return (
+    <canvas
+      ref={canvasRef}
+      className={`absolute inset-0 ${className}`}
+      style={{ pointerEvents: "none", ...style }}
+      aria-hidden="true"
+    />
+  );
+}