@mhmo91/schmancy 0.10.31 → 0.10.33

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mhmo91/schmancy",
-	"version": "0.10.31",
+	"version": "0.10.33",
 	"description": "UI library build with web components",
 	"main": "./dist/index.js",
 	"customElements": "custom-elements.json",
@@ -89,42 +89,42 @@
 	"dependencies": {
 		"@floating-ui/dom": "^1.7.6",
 		"@lit-labs/motion": "^1.1.0",
-		"@lit-labs/signals": "^0.2.0",
+		"@lit-labs/signals": "^0.3.0",
 		"@lit-labs/virtualizer": "^2.1.1",
 		"@lit/context": "^1.1.6",
 		"@material/material-color-utilities": "^0.4.0",
 		"@material/web": "^2.4.1",
 		"dayjs": "^1.11.20",
-		"immer": "^11.1.4",
-		"lit": "^3.3.2",
+		"immer": "^11.1.8",
+		"lit": "^3.3.3",
 		"rxjs": "^7.8.2",
 		"ts-is-present": "^1.2.2"
 	},
 	"devDependencies": {
 		"@rollup/plugin-strip": "^3.0.4",
 		"@rollup/plugin-terser": "^1.0.0",
-		"@tailwindcss/postcss": "^4.2.1",
-		"@tailwindcss/vite": "^4.2.1",
-		"@types/node": "^25.5.0",
-		"@vitest/browser-playwright": "^4.1.4",
-		"@vitest/coverage-v8": "^4.1.5",
-		"@vitest/ui": "^4.1.0",
-		"axe-core": "^4.11.3",
-		"happy-dom": "^20.8.4",
-		"knip": "^6.6.0",
+		"@tailwindcss/postcss": "^4.3.0",
+		"@tailwindcss/vite": "^4.3.0",
+		"@types/node": "^25.8.0",
+		"@vitest/browser-playwright": "^4.1.6",
+		"@vitest/coverage-v8": "^4.1.6",
+		"@vitest/ui": "^4.1.6",
+		"axe-core": "^4.11.4",
+		"happy-dom": "^20.9.0",
+		"knip": "^6.13.1",
 		"lit-analyzer": "^2.0.3",
-		"oxlint": "^1.61.0",
-		"playwright": "^1.59.1",
-		"postcss": "^8.5.8",
-		"prettier": "^3.8.1",
+		"oxlint": "^1.64.0",
+		"playwright": "^1.60.0",
+		"postcss": "^8.5.14",
+		"prettier": "^3.8.3",
 		"rollup-plugin-copy": "^3.5.0",
-		"sass": "^1.98.0",
-		"tailwindcss": "^4.2.1",
+		"sass": "^1.99.0",
+		"tailwindcss": "^4.3.0",
 		"ts-lit-plugin": "^2.0.2",
 		"ts-morph": "^28.0.0",
 		"typescript": "^5.9.3",
-		"vite": "^8.0.0",
-		"vitest": "^4.1.0",
+		"vite": "^8.0.13",
+		"vitest": "^4.1.6",
 		"web-component-analyzer": "^2.0.0"
 	},
 	"peerDependencies": {

package/src/directives/art/art.directive.ts

@@ -29,14 +29,15 @@ class ArtDirective extends AsyncDirective {
 
 	override update(part: ElementPart, [options]: [ArtOptions]) {
 		const element = part.element as HTMLElement
-		const { name, color, intensity = 1, speed = 1 } = options
+		const { name, color, intensity = 1, speed = 1, density = 1 } = options
 
 		if (
 			this.state &&
 			(this.state.effect !== name ||
 				this.state.color !== color ||
 				this.state.intensity !== intensity ||
-				this.state.speed !== speed)
+				this.state.speed !== speed ||
+				this.state.density !== density)
 		) {
 			this.cleanup()
 		}
@@ -49,6 +50,7 @@ class ArtDirective extends AsyncDirective {
 				color,
 				intensity,
 				speed,
+				density,
 				element,
 				isVisible: true,
 				initialized: false,

package/src/directives/art/effects/starfield.ts

@@ -1,107 +1,252 @@
 /**
- * Starfield Effect — Night sky with twinkling stars.
+ * Starfield Effect — surreal deep-space drift with rare comets.
  *
- * 6 groups × 7 stars using CSS radial-gradient backgrounds.
- * Wave-by-wave fade-in (group 0 first, then 1, 2, …); gentle twinkle once visible.
- * Opacity driven by RAF instead of CSS @keyframes to avoid Shadow DOM scoping.
+ * A recessive page backdrop. One <canvas>; stars live in
+ * structure-of-arrays Float32Array tables (zero per-frame allocation) and
+ * render as pre-rendered glow sprites via drawImage — no gradient is built
+ * inside the RAF loop. Three parallax depth layers drift on slow orbit paths;
+ * colour temperature runs blue-white → warm; entrance reveals far→near in
+ * waves behind a faint corner nebula; a pooled comet streaks by rarely.
+ * Sparse and dim by design — tune reach with the `density` ArtOption.
+ *
+ * Performance budget: ≤ MAX_STAR_COUNT drawImage calls + one nebula blit per
+ * frame, dpr capped at 2, the whole field idle under prefers-reduced-motion.
  */
 
 import type { ArtState } from '../types'
 import { createOverlayContainer } from '../utils'
 
-const GROUP_COUNT = 6
-const STARS_PER_GROUP = 7
-
-function generateStarGroups() {
-	return Array.from({ length: GROUP_COUNT }, (_, g) => {
-		const stops: string[] = []
-		for (let i = 0; i < STARS_PER_GROUP; i++) {
-			const x = Math.random() * 96 + 2
-			const y = Math.random() * 94 + 3
-			const size = 0.8 + Math.random() * 1.5
-			const alpha = 0.3 + Math.random() * 0.7
-			stops.push(
-				`radial-gradient(circle ${size}px at ${x}% ${y}%, rgba(255,255,255,${alpha}) 0%, transparent 100%)`,
-			)
-		}
-		const appearDelay = g * 0.6
-		return {
-			bg: stops.join(','),
-			appearDelay,
-			twinkleDuration: 5 + g * 0.7,
-			twinkleDelay: appearDelay + 2.5,
-		}
-	})
-}
+const BASE_STAR_COUNT = 90
+// Hard ceiling: a wide monitor must never carpet, whatever the density prop asks.
+const MAX_STAR_COUNT = 140
+const COMET_POOL = 3
+const APPEAR_DURATION = 2.5
+const SPRITE_PX = 64
+// Cool → warm. Index 0 is the dominant blue-white; the tail warms toward amber.
+const TEMPERATURE_RGB = [
+	[205, 222, 255],
+	[224, 233, 255],
+	[255, 255, 255],
+	[255, 240, 214],
+	[255, 222, 184],
+]
 
 export function createStarfieldOverlay(state: ArtState): void {
 	const { element } = state
 	const overlay = createOverlayContainer('starfield-overlay')
 
-	const starArea = document.createElement('div')
-	starArea.style.cssText = 'position:absolute;bottom:0;right:0;width:66vw;height:66vw;'
-	overlay.appendChild(starArea)
-
-	const generated = generateStarGroups()
-	const groups: NonNullable<ArtState['starfield']>['groups'] = []
-
-	for (const g of generated) {
-		const div = document.createElement('div')
-		div.style.cssText = `position:absolute;inset:0;opacity:0;will-change:opacity;background:${g.bg};`
-		starArea.appendChild(div)
-		groups.push({
-			element: div,
-			appearDelay: g.appearDelay,
-			twinkleDuration: g.twinkleDuration,
-			twinkleDelay: g.twinkleDelay,
-		})
+	const canvas = document.createElement('canvas')
+	canvas.style.cssText = 'position:absolute;inset:0;width:100%;height:100%;'
+	overlay.appendChild(canvas)
+	element.appendChild(overlay)
+
+	const ctx = canvas.getContext('2d')
+	if (!ctx) return
+
+	const dpr = Math.min(window.devicePixelRatio || 1, 2)
+	const rect = element.getBoundingClientRect()
+	const deviceWidth = Math.max(1, Math.round(rect.width * dpr))
+	const deviceHeight = Math.max(1, Math.round(rect.height * dpr))
+	canvas.width = deviceWidth
+	canvas.height = deviceHeight
+
+	const sprites = TEMPERATURE_RGB.map(([r, g, b]) => {
+		const s = document.createElement('canvas')
+		s.width = SPRITE_PX
+		s.height = SPRITE_PX
+		const sc = s.getContext('2d')!
+		const grad = sc.createRadialGradient(SPRITE_PX / 2, SPRITE_PX / 2, 0, SPRITE_PX / 2, SPRITE_PX / 2, SPRITE_PX / 2)
+		grad.addColorStop(0, `rgba(${r},${g},${b},1)`)
+		grad.addColorStop(0.18, `rgba(${r},${g},${b},0.35)`)
+		grad.addColorStop(0.5, `rgba(${r},${g},${b},0)`)
+		sc.fillStyle = grad
+		sc.fillRect(0, 0, SPRITE_PX, SPRITE_PX)
+		return s
+	})
+
+	const nebula = document.createElement('canvas')
+	nebula.width = 512
+	nebula.height = 512
+	const nc = nebula.getContext('2d')!
+	const ng = nc.createRadialGradient(256, 256, 0, 256, 256, 256)
+	ng.addColorStop(0, 'rgba(150,170,255,0.16)')
+	ng.addColorStop(0.4, 'rgba(120,110,210,0.07)')
+	ng.addColorStop(1, 'rgba(0,0,0,0)')
+	nc.fillStyle = ng
+	nc.fillRect(0, 0, 512, 512)
+
+	const starCount = Math.min(
+		MAX_STAR_COUNT,
+		Math.round(BASE_STAR_COUNT * Math.min(1, Math.max(0.5, (rect.width * rect.height) / (1280 * 720))) * state.density),
+	)
+	const sx = new Float32Array(starCount)
+	const sy = new Float32Array(starCount)
+	const sr = new Float32Array(starCount)
+	const sphase = new Float32Array(starCount)
+	const stwinkle = new Float32Array(starCount)
+	const sdepth = new Float32Array(starCount)
+	const sbucket = new Uint8Array(starCount)
+	const sappear = new Float32Array(starCount)
+
+	for (let i = 0; i < starCount; i++) {
+		const depthBand = i % 3 // 0 far, 1 mid, 2 near — even split across layers
+		const depth = depthBand === 0 ? 0.18 : depthBand === 1 ? 0.5 : 1
+		sx[i] = Math.random()
+		sy[i] = Math.random()
+		sr[i] = (0.7 + Math.random() * 1.6) * (0.6 + 0.7 * depth)
+		sphase[i] = Math.random() * Math.PI * 2
+		stwinkle[i] = 0.6 + Math.random() * 1.8
+		sdepth[i] = depth
+		// Field skews blue-white; only a minority warms — that asymmetry reads as authored.
+		sbucket[i] = Math.random() < 0.7 ? (Math.random() < 0.5 ? 0 : 1) : 2 + Math.floor(Math.random() * 3)
+		// Far layer arrives first, near layer last → the depth reveals as waves.
+		sappear[i] = (1 - depth) * 1.6 + Math.random() * 0.8
 	}
 
-	element.appendChild(overlay)
 	state.overlayElement = overlay
-	state.starfield = { groups, startTime: performance.now() }
+	state.starfield = {
+		canvas,
+		ctx,
+		sprites,
+		nebula,
+		starCount,
+		sx,
+		sy,
+		sr,
+		sphase,
+		stwinkle,
+		sdepth,
+		sbucket,
+		sappear,
+		cx: new Float32Array(COMET_POOL),
+		cy: new Float32Array(COMET_POOL),
+		cvx: new Float32Array(COMET_POOL),
+		cvy: new Float32Array(COMET_POOL),
+		clife: new Float32Array(COMET_POOL),
+		cometCount: COMET_POOL,
+		nextCometAt: performance.now() + 14000 + Math.random() * 16000,
+		dpr,
+		deviceWidth,
+		deviceHeight,
+		reducedMotion: window.matchMedia('(prefers-reduced-motion: reduce)').matches,
+		drawnStatic: false,
+		lastFrame: performance.now(),
+		startTime: performance.now(),
+	}
 }
 
 export function animateStarfield(state: ArtState, currentTime: number): void {
-	if (!state.starfield) return
+	const sf = state.starfield
+	if (!sf) return
 
 	const { intensity = 1, speed = 1 } = state
-	const { groups, startTime } = state.starfield
-	const elapsed = ((currentTime - startTime) / 1000) * speed
+	const { ctx, canvas } = sf
+
+	if (intensity <= 0) {
+		ctx.clearRect(0, 0, sf.deviceWidth, sf.deviceHeight)
+		return
+	}
 
-	for (const g of groups) {
-		if (intensity <= 0) {
-			g.element.style.opacity = '0'
+	// One layout read per frame; resize only when the backing store must change.
+	const cssW = canvas.clientWidth
+	const cssH = canvas.clientHeight
+	const wantW = Math.max(1, Math.round(cssW * sf.dpr))
+	const wantH = Math.max(1, Math.round(cssH * sf.dpr))
+	if (wantW !== sf.deviceWidth || wantH !== sf.deviceHeight) {
+		canvas.width = wantW
+		canvas.height = wantH
+		sf.deviceWidth = wantW
+		sf.deviceHeight = wantH
+		sf.drawnStatic = false
+	}
+
+	const W = sf.deviceWidth
+	const H = sf.deviceHeight
+
+	if (sf.reducedMotion && sf.drawnStatic) return
+
+	const elapsed = ((currentTime - sf.startTime) / 1000) * speed
+	const dt = Math.min((currentTime - sf.lastFrame) / 1000, 0.05)
+	sf.lastFrame = currentTime
+
+	ctx.clearRect(0, 0, W, H)
+
+	// Entrance nebula: blooms in over the first ~4s, then holds at a faint floor.
+	const nebulaAlpha = (Math.min(1, elapsed / 4) * 0.7 + 0.3) * 0.14 * intensity
+	if (nebulaAlpha > 0.001) {
+		const nSize = Math.max(W, H) * 1.3
+		ctx.globalAlpha = nebulaAlpha
+		ctx.drawImage(sf.nebula, W * 0.78 - nSize / 2, H * 0.28 - nSize / 2, nSize, nSize)
+	}
+
+	// Normal compositing — additive blend is what turned overlap into a glowing carpet.
+	for (let i = 0; i < sf.starCount; i++) {
+		const appear = sf.sappear[i]
+		let reveal: number
+		if (sf.reducedMotion) {
+			reveal = 1
+		} else if (elapsed < appear) {
 			continue
+		} else if (elapsed < appear + APPEAR_DURATION) {
+			const t = (elapsed - appear) / APPEAR_DURATION
+			reveal = 1 - (1 - t) * (1 - t) * (1 - t)
+		} else {
+			reveal = 1
 		}
 
-		const appearStart = g.appearDelay
-		const appearEnd = appearStart + 2.5
-		let opacity: number
+		const depth = sf.sdepth[i]
+		const twinkle = sf.reducedMotion ? 0.9 : 0.82 + 0.18 * Math.sin(elapsed * sf.stwinkle[i] + sf.sphase[i])
 
-		if (elapsed < appearStart) {
-			opacity = 0
-		} else if (elapsed < appearEnd) {
-			const t = (elapsed - appearStart) / 2.5
-			opacity = 1 - Math.pow(1 - t, 3)
-		} else {
-			const twinkleElapsed = elapsed - g.twinkleDelay
-			if (twinkleElapsed < 0) {
-				opacity = 1
-			} else {
-				const cycle = (twinkleElapsed % g.twinkleDuration) / g.twinkleDuration
-				if (cycle < 0.25) {
-					opacity = 1 - (cycle / 0.25) * 0.4
-				} else if (cycle < 0.5) {
-					opacity = 0.6 + ((cycle - 0.25) / 0.25) * 0.25
-				} else if (cycle < 0.75) {
-					opacity = 0.85 - ((cycle - 0.5) / 0.25) * 0.3
-				} else {
-					opacity = 0.55 + ((cycle - 0.75) / 0.25) * 0.45
-				}
+		// Slow orbit drift, amplitude scaled by depth — the parallax is the surreality.
+		const driftAmp = sf.reducedMotion ? 0 : depth * 14 * sf.dpr
+		const px = sf.sx[i] * W + Math.sin(elapsed * 0.05 + sf.sphase[i]) * driftAmp
+		const py = sf.sy[i] * H + Math.cos(elapsed * 0.04 + sf.sphase[i]) * driftAmp * 0.6
+
+		const size = sf.sr[i] * sf.dpr * 2.3
+		ctx.globalAlpha = reveal * twinkle * (0.3 + 0.5 * depth) * intensity
+		ctx.drawImage(sf.sprites[sf.sbucket[i]], px - size, py - size, size * 2, size * 2)
+	}
+
+	if (!sf.reducedMotion) {
+		if (currentTime >= sf.nextCometAt) {
+			for (let c = 0; c < sf.cometCount; c++) {
+				if (sf.clife[c] > 0) continue
+				const fromLeft = Math.random() < 0.5
+				sf.cx[c] = (fromLeft ? -0.05 : 1.05) * W
+				sf.cy[c] = Math.random() * 0.45 * H
+				const sp = (520 + Math.random() * 420) * sf.dpr
+				sf.cvx[c] = (fromLeft ? 1 : -1) * sp
+				sf.cvy[c] = (0.35 + Math.random() * 0.35) * sp
+				sf.clife[c] = 1
+				break
 			}
+			sf.nextCometAt = currentTime + (20000 + Math.random() * 25000) / speed
 		}
 
-		g.element.style.opacity = (opacity * intensity).toFixed(3)
+		for (let c = 0; c < sf.cometCount; c++) {
+			if (sf.clife[c] <= 0) continue
+			sf.cx[c] += sf.cvx[c] * dt * speed
+			sf.cy[c] += sf.cvy[c] * dt * speed
+			sf.clife[c] -= dt / 1.6
+
+			const tailX = sf.cx[c] - sf.cvx[c] * 0.16
+			const tailY = sf.cy[c] - sf.cvy[c] * 0.16
+			const grad = ctx.createLinearGradient(sf.cx[c], sf.cy[c], tailX, tailY)
+			const headA = Math.max(0, Math.min(1, sf.clife[c])) * 0.55 * intensity
+			grad.addColorStop(0, `rgba(255,255,255,${headA})`)
+			grad.addColorStop(0.4, `rgba(190,210,255,${headA * 0.4})`)
+			grad.addColorStop(1, 'rgba(190,210,255,0)')
+			ctx.globalAlpha = 1
+			ctx.strokeStyle = grad
+			ctx.lineWidth = 2 * sf.dpr
+			ctx.lineCap = 'round'
+			ctx.beginPath()
+			ctx.moveTo(sf.cx[c], sf.cy[c])
+			ctx.lineTo(tailX, tailY)
+			ctx.stroke()
+		}
 	}
+
+	ctx.globalAlpha = 1
+	sf.drawnStatic = true
 }

package/src/directives/art/types.ts

@@ -15,6 +15,8 @@ export interface ArtOptions {
 	intensity?: number
 	/** Animation speed multiplier: 0.5 = half speed, 1 = normal, 2 = double (default: 1) */
 	speed?: number
+	/** Particle density multiplier: 0.5 = sparse, 1 = baseline, 2 = dense (default: 1; starfield only) */
+	density?: number
 }
 
 export interface Particle<T extends SVGElement = SVGElement> {
@@ -52,6 +54,7 @@ export interface ArtState {
 	color: string
 	intensity: number
 	speed: number
+	density: number
 	element: HTMLElement
 	overlayElement?: HTMLElement
 	animationId?: number
@@ -118,12 +121,44 @@ export interface ArtState {
 	}
 
 	starfield?: {
-		groups: Array<{
-			element: HTMLDivElement
-			appearDelay: number
-			twinkleDuration: number
-			twinkleDelay: number
-		}>
+		canvas: HTMLCanvasElement
+		ctx: CanvasRenderingContext2D
+		/** Pre-rendered glow sprites, cool→warm. Drawn per star so no per-frame gradient is built. */
+		sprites: HTMLCanvasElement[]
+		/** Pre-rendered entrance nebula bloom, drawn once per frame at a computed alpha. */
+		nebula: HTMLCanvasElement
+		starCount: number
+		/** Structure-of-arrays star table — cache-friendly, zero allocation per frame. */
+		sx: Float32Array
+		sy: Float32Array
+		sr: Float32Array
+		sphase: Float32Array
+		stwinkle: Float32Array
+		/** 0 = far (drifts least, dimmest) → 1 = near (drifts most, brightest). */
+		sdepth: Float32Array
+		/** Index into `sprites` — fixes each star's colour temperature for its life. */
+		sbucket: Uint8Array
+		/** Per-star entrance delay (s) so the field reveals far→near in waves. */
+		sappear: Float32Array
+		/** Fixed comet pool. `life <= 0` marks a free slot; no array churn. */
+		cx: Float32Array
+		cy: Float32Array
+		cvx: Float32Array
+		cvy: Float32Array
+		clife: Float32Array
+		cometCount: number
+		/** ms timestamp of the next comet spawn — gates the rare streak. */
+		nextCometAt: number
+		/** Capped device-pixel-ratio; bounds backing-store fill cost on retina. */
+		dpr: number
+		/** Cached device-pixel canvas size; a change is the only resize trigger. */
+		deviceWidth: number
+		deviceHeight: number
+		/** Static-render once, then idle the RAF loop. */
+		reducedMotion: boolean
+		drawnStatic: boolean
+		/** Previous frame ms — frame-rate-independent comet motion + jump clamp. */
+		lastFrame: number
 		startTime: number
 	}
 }

package/src/directives/magnetic.ts

@@ -1,7 +1,7 @@
 import { directive, type ElementPart, PartType } from 'lit/directive.js'
 import { AsyncDirective } from 'lit/async-directive.js'
 import { animationFrameScheduler, fromEvent, merge, Subject } from 'rxjs'
-import { auditTime, map, takeUntil } from 'rxjs/operators'
+import { auditTime, filter, map, takeUntil } from 'rxjs/operators'
 import { SPRING_SNAPPY } from '../utils/animation'
 import { reducedMotion$ } from './reduced-motion'
 
@@ -77,6 +77,13 @@ class MagneticDirective extends AsyncDirective {
 
 		const move$ = fromEvent<MouseEvent>(target, 'mousemove').pipe(
 			auditTime(0, animationFrameScheduler),
+			filter(() =>
+				this.element.checkVisibility?.({
+					contentVisibilityAuto: true,
+					checkOpacity: true,
+					checkVisibilityCSS: true,
+				} as CheckVisibilityOptions) ?? true,
+			),
 			map(e => {
 				const rect = this.cachedRect ?? this.element.getBoundingClientRect()
 				const centerX = rect.left + rect.width / 2

package/types/src/directives/art/effects/starfield.d.ts

@@ -1,9 +1,16 @@
 /**
- * Starfield Effect — Night sky with twinkling stars.
+ * Starfield Effect — surreal deep-space drift with rare comets.
  *
- * 6 groups × 7 stars using CSS radial-gradient backgrounds.
- * Wave-by-wave fade-in (group 0 first, then 1, 2, …); gentle twinkle once visible.
- * Opacity driven by RAF instead of CSS @keyframes to avoid Shadow DOM scoping.
+ * A recessive page backdrop. One <canvas>; stars live in
+ * structure-of-arrays Float32Array tables (zero per-frame allocation) and
+ * render as pre-rendered glow sprites via drawImage — no gradient is built
+ * inside the RAF loop. Three parallax depth layers drift on slow orbit paths;
+ * colour temperature runs blue-white → warm; entrance reveals far→near in
+ * waves behind a faint corner nebula; a pooled comet streaks by rarely.
+ * Sparse and dim by design — tune reach with the `density` ArtOption.
+ *
+ * Performance budget: ≤ MAX_STAR_COUNT drawImage calls + one nebula blit per
+ * frame, dpr capped at 2, the whole field idle under prefers-reduced-motion.
  */
 import type { ArtState } from '../types';
 export declare function createStarfieldOverlay(state: ArtState): void;

package/types/src/directives/art/types.d.ts

@@ -12,6 +12,8 @@ export interface ArtOptions {
     intensity?: number;
     /** Animation speed multiplier: 0.5 = half speed, 1 = normal, 2 = double (default: 1) */
     speed?: number;
+    /** Particle density multiplier: 0.5 = sparse, 1 = baseline, 2 = dense (default: 1; starfield only) */
+    density?: number;
 }
 export interface Particle<T extends SVGElement = SVGElement> {
     element: T;
@@ -46,6 +48,7 @@ export interface ArtState {
     color: string;
     intensity: number;
     speed: number;
+    density: number;
     element: HTMLElement;
     overlayElement?: HTMLElement;
     animationId?: number;
@@ -115,12 +118,44 @@ export interface ArtState {
         startTime: number;
     };
     starfield?: {
-        groups: Array<{
-            element: HTMLDivElement;
-            appearDelay: number;
-            twinkleDuration: number;
-            twinkleDelay: number;
-        }>;
+        canvas: HTMLCanvasElement;
+        ctx: CanvasRenderingContext2D;
+        /** Pre-rendered glow sprites, cool→warm. Drawn per star so no per-frame gradient is built. */
+        sprites: HTMLCanvasElement[];
+        /** Pre-rendered entrance nebula bloom, drawn once per frame at a computed alpha. */
+        nebula: HTMLCanvasElement;
+        starCount: number;
+        /** Structure-of-arrays star table — cache-friendly, zero allocation per frame. */
+        sx: Float32Array;
+        sy: Float32Array;
+        sr: Float32Array;
+        sphase: Float32Array;
+        stwinkle: Float32Array;
+        /** 0 = far (drifts least, dimmest) → 1 = near (drifts most, brightest). */
+        sdepth: Float32Array;
+        /** Index into `sprites` — fixes each star's colour temperature for its life. */
+        sbucket: Uint8Array;
+        /** Per-star entrance delay (s) so the field reveals far→near in waves. */
+        sappear: Float32Array;
+        /** Fixed comet pool. `life <= 0` marks a free slot; no array churn. */
+        cx: Float32Array;
+        cy: Float32Array;
+        cvx: Float32Array;
+        cvy: Float32Array;
+        clife: Float32Array;
+        cometCount: number;
+        /** ms timestamp of the next comet spawn — gates the rare streak. */
+        nextCometAt: number;
+        /** Capped device-pixel-ratio; bounds backing-store fill cost on retina. */
+        dpr: number;
+        /** Cached device-pixel canvas size; a change is the only resize trigger. */
+        deviceWidth: number;
+        deviceHeight: number;
+        /** Static-render once, then idle the RAF loop. */
+        reducedMotion: boolean;
+        drawnStatic: boolean;
+        /** Previous frame ms — frame-rate-independent comet motion + jump clamp. */
+        lastFrame: number;
         startTime: number;
     };
 }