svelte-kit-vice/src/packs/ambient/README.md

Ambient ($packs/ambient)

Decorative animated backgrounds as a pack — encapsulated, opt-in, outside the component canon (tier + admission rule: docs/architecture/packs.md). The effects themselves are shared resources in $scene/effects, mounted here decoratively and, in the agentic phase, semantically by the canonical Aura.

<script>
	import { Ambient } from '$packs/ambient';
	import '$packs/ambient/effects/aurora'; // import = opt-in (tree-shaken)
</script>

<Ambient
	effect="aurora"
	params={{
		colorStops: ['--color-primary-solid', '--color-tertiary-solid', '--color-affirm-solid']
	}}
	style="height: 320px"
>
	<h1>Content renders above the scene</h1>
</Ambient>

effect is type-safe via the augmentable AmbientEffects registry (the EidosMotionPresets pattern): importing an effect module both registers it and merges its param types, so a typo in effect or params is a compile error.

El contrato P (suelo de calidad del pack — guard: npm run packs:check)

P	Obligación	Quién la cumple
P-1	reduce obligatoria por efecto ('static-frame' | 'hide')	el tipo SceneEffect + EngineScene lanza sin ella
P-2	Teardown completo por handle	EngineScene (frames, observers, GL, listeners, canvas)
P-3	DOM solo por puerto — cero requestAnimationFrame/ResizeObserver/IntersectionObserver/addEventListener/setTimeout/matchMedia crudos en src/packs/	packs-check (grep-guard, error)
P-4	Params de color token-aware: aceptan nombres de custom property de eidos, resueltos vía eidos.resolveToken (resolve-params.ts); un token irresoluble CAE al default del efecto	<Ambient>
P-5	DOM decorativo aria-hidden + pointer-events: none (los hooks de puntero escuchan en el HOST, opt-in por efecto)	EngineScene
P-6	Pausa fuera de vista / pestaña oculta + presupuesto de escenas (un engine por superficie DOM — el budget cuenta TODOS los <Ambient>)	EngineScene + engineFor

También guardado por packs-check: sin <style> scoped en el pack (el consumidor estiliza el host vía class/style; el pack no compite con las recetas de eidos).

Catálogo (pilotos F2 + Tier A completo, D6)

Todos los efectos viven en $scene/effects/{name}.ts; aquí solo se registran (src/packs/ambient/effects/{name}.ts, import = opt-in). Demo: web/routes/uix/packs/ambient.

Parámetros por efecto: cada efecto exporta su interfaz de params tipada {Name}Params en $scene/effects/{name}.ts (con JSDoc por campo y sus defaults) — esa interfaz ES la referencia de parámetros; <Ambient> la type-checkea vía el registro AmbientEffects. Ejemplos trabajados con colores por token: el mapa paramsByEffect en el catálogo demo (web/routes/uix/packs/ambient/+page.svelte).

Efecto	Driver	Carácter
aurora	webgl2	agéntico: thinking (piloto F2)
silk	webgl	agéntico: thinking (alternativa serena)
orb	webgl	agéntico: listening (presencia con hover)
lumen	webgl	agéntico: acting (el cursor pinta la estela)
radar	webgl	agéntico: searching
threads	webgl	agéntico: streaming (parallax de puntero)
waves	canvas2d	campo de líneas Perlin reactivo al cursor
mesh	webgl	gradiente malla en deriva (piloto F2)
dot-grid	canvas2d	retícula interactiva con shockwave (piloto F2)
fog	webgl	niebla mono-color con domain-warp
grainient	webgl2	gradiente granulado de 3 colores
veil	webgl	CPPN orgánico (hue/scanlines/noise/warp)
dots	canvas2d	retícula con bulge, glow y sparkle
beam	webgl	cintas 3D especulares — primer efecto custom-pipeline (vertexShader + draw + depth)
ray	webgl	rayo procedural fbm
snow-pixels	webgl	nevada volumétrica pixelada (raymarch DDA)

Tier B (F4b)

Efecto	Driver	Carácter
galaxy	webgl	campo estelar por capas con repulsión de puntero
eter	webgl2	simulación de fluidos real (advección + Poisson) — custom-pipeline, requiere EXT_color_buffer_float
hyperspeed	webgl2	carretera nocturna instanciada + bloom — custom-pipeline; press = acelerar (hooks down/up/leave)
particles	webgl	nube de puntos 3D — custom-pipeline (gl.POINTS)
pixel-blast	webgl	campo dithered con ondas por click + distorsión líquida — custom-pipeline
grid	webgl2	corredor 3D con pulso de escaneo + composite (aberración/bloom) — custom-pipeline
prismatic	webgl	estallido volumétrico de rayos con gradiente por textura
pillar	webgl	pilar de luz raymarched (preset high fijo; quality del seed = adaptación por dispositivo → futura opción del engine)
dither	webgl2	campo de olas Bayer-dithered — custom-pipeline; declara glContext.dprCap: 1 (look chunky del seed)
blinds	webgl	gradiente en lamas con spotlight
balastro	webgl	pintura arremolinada estilo Balatro
iridiscence	webgl	bandas de película de jabón
liquid-metal	webgl	cromo líquido con ripple de puntero
water	webgl	mármol líquido: vetas incandescentes marmoladas sobre negro con viñeta + ripple de puntero (look "Liquid UI")
line-waves	webgl	teselado de líneas warpeadas con ciclo RGB
floating-lines	webgl2	familias de ondas con bend/parallax de puntero
letters	canvas2d	retícula de letras glitcheantes

Re-tintado en vivo (modo / tema)

<Ambient> re-resuelve los params en un $effect que lee eidos.getThemeContext(): si la fuente de preferencias del shell es reactiva (el caso del shell UIX), cambiar light/dark re-tinta los efectos token-aware sin remount. Con una fuente no reactiva, vuelve a pasar params (o remonta) tras el cambio.

Encapsulación

Dependencia SOLO pack → framework ($scene, $uix/eidos). Borrar src/packs/ deja npm run check verde — nada del framework referencia el pack. Los originales de la colección semilla siguen intactos en web/routes/demos/animations como referencia comparativa (decisión D5, docs/process/PLAN-scene-ambient-pack.md).