@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/elements/base.ts

@@ -0,0 +1,76 @@
+import type { Instance } from '../core/types';
+
+/*
+ * Base for motion-kit custom elements (Astro / plain HTML). Light DOM only, so
+ * themes and project CSS reach the markup. Attributes map to engine options
+ * (kebab-case → camelCase); the engine is created on connect, recreated when an
+ * observed attribute changes, and destroyed on disconnect.
+ */
+
+export type OptionType = 'string' | 'number' | 'boolean' | 'list' | 'json';
+
+/** `HTMLElement` in the browser; an empty class during SSR so importing never throws. */
+export const SafeHTMLElement = (typeof HTMLElement === 'undefined' ? class {} : HTMLElement) as typeof HTMLElement;
+
+const kebab = (name: string) => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+
+export abstract class MkElement<I extends Instance = Instance> extends SafeHTMLElement {
+  /** Option name (camelCase) → how to read its attribute. */
+  static options: Record<string, OptionType> = {};
+
+  static get observedAttributes() {
+    return Object.keys(this.options).map(kebab);
+  }
+
+  /** The live engine (null while disconnected). */
+  instance: I | null = null;
+
+  protected abstract create(options: Record<string, unknown>): I;
+
+  /** Options read from the attributes now. */
+  get options(): Record<string, unknown> {
+    const types = (this.constructor as typeof MkElement).options;
+    const options: Record<string, unknown> = {};
+    for (const [name, type] of Object.entries(types)) {
+      const raw = this.getAttribute(kebab(name));
+      if (type === 'boolean') {
+        if (raw !== null) options[name] = raw !== 'false';
+        continue;
+      }
+      if (raw === null) continue;
+      if (type === 'number') {
+        const value = Number(raw);
+        if (Number.isFinite(value)) options[name] = value;
+      } else if (type === 'list') options[name] = raw.split(',').map((item) => item.trim()).filter(Boolean);
+      else if (type === 'json') {
+        try {
+          options[name] = JSON.parse(raw);
+        } catch {
+          // Ignore malformed JSON: the engine keeps its default.
+        }
+      } else options[name] = raw;
+    }
+    return options;
+  }
+
+  connectedCallback() {
+    if (!this.instance) this.instance = this.create(this.options);
+  }
+
+  disconnectedCallback() {
+    this.instance?.destroy();
+    this.instance = null;
+  }
+
+  attributeChangedCallback(_name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    this.instance.destroy();
+    this.instance = this.create(this.options);
+  }
+}
+
+/** customElements.define once; later calls with the same name are ignored. */
+export function defineElement(name: string, ctor: CustomElementConstructor) {
+  if (typeof customElements === 'undefined' || customElements.get(name)) return;
+  customElements.define(name, ctor);
+}

package/src/elements/index.ts

@@ -0,0 +1,48 @@
+import { defineElement } from './base';
+import { MkThemePickerElement } from '../components/theme-picker/element';
+import { MkDialogElement } from '../components/dialog/element';
+import { MkMenuElement } from '../components/menu/element';
+import { MkToasterElement } from '../components/toast/element';
+import { MkChatBackgroundElement } from '../components/chat-background/element';
+import { MkChatElement } from '../components/chat/element';
+import { MkNavElement } from '../components/nav/element';
+import { MkStepsElement } from '../components/steps/element';
+import { MkCursorElement } from '../components/cursor/element';
+import { MkIslandElement } from '../components/island/element';
+// new-component:imports (scripts/new-component.mjs inserts above this line)
+
+export { MkElement, SafeHTMLElement, defineElement, type OptionType } from './base';
+export { MkThemePickerElement } from '../components/theme-picker/element';
+export { MkDialogElement } from '../components/dialog/element';
+export { MkMenuElement } from '../components/menu/element';
+export { MkToasterElement } from '../components/toast/element';
+export { MkChatBackgroundElement } from '../components/chat-background/element';
+export { MkChatElement } from '../components/chat/element';
+export { MkNavElement } from '../components/nav/element';
+export { MkStepsElement } from '../components/steps/element';
+export { MkCursorElement } from '../components/cursor/element';
+export { toast } from '../components/toast/store';
+export { MkIslandElement } from '../components/island/element';
+// new-component:exports
+
+/** Tag name → element class, for every component. */
+export const ELEMENTS = {
+  'mk-theme-picker': MkThemePickerElement,
+  'mk-dialog': MkDialogElement,
+  'mk-menu': MkMenuElement,
+  'mk-toaster': MkToasterElement,
+  'mk-chat-background': MkChatBackgroundElement,
+  'mk-chat': MkChatElement,
+  'mk-nav': MkNavElement,
+  'mk-steps': MkStepsElement,
+  'mk-cursor': MkCursorElement,
+  'mk-island': MkIslandElement,
+  // new-component:entries
+} as const;
+
+export type ElementName = keyof typeof ELEMENTS;
+
+/** Register every motion-kit element (or the ones named). Safe to call more than once. */
+export function defineElements(names: ElementName[] = Object.keys(ELEMENTS) as ElementName[]) {
+  for (const name of names) defineElement(name, ELEMENTS[name]);
+}

package/src/gl/index.ts

@@ -0,0 +1,15 @@
+/*
+ * motion-kit/gl — optional WebGL effects. A separate entry so pages that never
+ * draw on the GPU never load these shaders.
+ */
+export {
+  createParticleHero,
+  type ParticleHeroOptions,
+  type ParticleHeroInstance,
+  type ParticleHeroMode,
+} from './particle-hero/create-particle-hero';
+export { createLiquidBlend, type LiquidBlendOptions, type LiquidBlendInstance } from './liquid-blend/create-liquid-blend';
+export { createMatcap, type MatcapOptions, type MatcapInstance } from './matcap/create-matcap';
+export { createShaderGrain, type ShaderGrainOptions, type ShaderGrainInstance } from './shader-grain/create-shader-grain';
+export { createShaderBlur, type ShaderBlurOptions, type ShaderBlurInstance } from './shader-blur/create-shader-blur';
+export type { ShaderEffectOptions, ShaderEffectInstance } from './shared/create-shader-effect';

package/src/gl/liquid-blend/README.md

@@ -0,0 +1,23 @@
+# liquid-blend
+
+Mezcla de dos texturas con deformación UV (OFFFICE, adaptación).
+
+```ts
+import { createLiquidBlend } from '@yewdiel21/motion-kit/gl';
+import { useLiquidBlend } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css';
+const effect = createLiquidBlend(root);
+effect.setProgress(.5);
+effect.setAmount(.15);
+effect.destroy();
+```
+
+Opciones compartidas: `images?: HTMLImageElement[]` (por defecto las dos primeras imágenes de root; una se repite), `progress` 0–1, `amount`, `maxDpr` 1.5. Las imágenes pueden terminar de cargar después de crear la instancia. Recursos del mismo origen o con CORS configurado antes de cargar la imagen. El kit no descarga imágenes. Root debe tener dimensiones; el canvas decorativo cubre su caja y deja el HTML accesible debajo.
+
+Controles: `setProgress(0..1)`, `setAmount(0..100)`, `pause()`, `resume()`, `mode: 'webgl' | 'none'`, `destroy()`. React: `useLiquidBlend(ref, options, deps)`, ref a la instancia. No usa `autoInit`: importar explícitamente desde `/gl` conserva la separación de GPU del paquete principal.
+
+Pausa fuera de pantalla y con pestaña oculta. Movimiento reducido: frame fijo, con controles manuales. Sin WebGL, error de textura o contexto perdido: canvas oculto, HTML original disponible. Contexto restaurado: recompila y vuelve a cargar texturas. Destroy libera texturas, buffer, shaders y programa, desconecta observers y restaura la clase original.
+
+OFFFICE `liquid-swap`: mezcla de las imágenes renderizadas, UV deformadas en torno al centro. Adaptación: dos texturas de imagen y ondas propias, sin modelos, ruido cnoise ni render targets. Amount .15; progreso 0/1 conserva exactamente la primera/segunda imagen.
+
+Desde 0.9.0. Fuentes de parámetros: `REA - Dousan OFFFICE Siena/`. Shaders originales, sin redistribuir código ni assets de terceros.

package/src/gl/liquid-blend/create-liquid-blend.ts

@@ -0,0 +1,7 @@
+import { createShaderEffect, type ShaderEffectInstance, type ShaderEffectOptions } from '../shared/create-shader-effect';
+import { liquidFragment } from './shader';
+
+export type LiquidBlendOptions = ShaderEffectOptions;
+export type LiquidBlendInstance = ShaderEffectInstance;
+export const createLiquidBlend = (root: HTMLElement | null, options: LiquidBlendOptions = {}): LiquidBlendInstance =>
+  createShaderEffect(root, liquidFragment, { amount: 0.15, ...options });

package/src/gl/liquid-blend/shader.ts

@@ -0,0 +1,9 @@
+export const liquidFragment = `
+void main() {
+  float center = 1. - smoothstep(0., .5, distance(vUv, vec2(.5)));
+  vec2 wave = vec2(sin(vUv.y * 18. + uTime), cos(vUv.x * 20. - uTime));
+  vec2 distortion = wave * center * uAmount;
+  vec2 currentUv = cover(vUv + distortion * uProgress, uImageSize0);
+  vec2 nextUv = cover(vUv - distortion * (1. - uProgress), uImageSize1);
+  gl_FragColor = mix(texture2D(uImage0, currentUv), texture2D(uImage1, nextUv), uProgress);
+}`;

package/src/gl/matcap/README.md

@@ -0,0 +1,23 @@
+# matcap
+
+Superficie esférica iluminada con matcap y hemisferio (OFFFICE, adaptación).
+
+```ts
+import { createMatcap } from '@yewdiel21/motion-kit/gl';
+import { useMatcap } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css';
+const effect = createMatcap(root);
+effect.setProgress(.5);
+effect.setAmount(.15);
+effect.destroy();
+```
+
+Opciones compartidas: `images?: HTMLImageElement[]` (por defecto las dos primeras imágenes de root; una se repite), `progress` 0–1, `amount`, `maxDpr` 1.5. Las imágenes pueden terminar de cargar después de crear la instancia. Recursos del mismo origen o con CORS configurado antes de cargar la imagen. El kit no descarga imágenes. Root debe tener dimensiones; el canvas decorativo cubre su caja y deja el HTML accesible debajo.
+
+Controles: `setProgress(0..1)`, `setAmount(0..100)`, `pause()`, `resume()`, `mode: 'webgl' | 'none'`, `destroy()`. React: `useMatcap(ref, options, deps)`, ref a la instancia. No usa `autoInit`: importar explícitamente desde `/gl` conserva la separación de GPU del paquete principal.
+
+Pausa fuera de pantalla y con pestaña oculta. Movimiento reducido: frame fijo, con controles manuales. Sin WebGL, error de textura o contexto perdido: canvas oculto, HTML original disponible. Contexto restaurado: recompila y vuelve a cargar texturas. Destroy libera texturas, buffer, shaders y programa, desconecta observers y restaura la clase original.
+
+OFFFICE `matcap`: normales en UV .495+.5, hemisferio y ganancia .15. Adaptación: esfera analítica y luz propia si no hay imagen; una imagen opcional actúa como matcap. Progreso gira el matcap; amount regula el brillo. No es un cargador de modelos ni reflexión de escena.
+
+Desde 0.9.0. Fuentes de parámetros: `REA - Dousan OFFFICE Siena/`. Shaders originales, sin redistribuir código ni assets de terceros.

package/src/gl/matcap/create-matcap.ts

@@ -0,0 +1,7 @@
+import { createShaderEffect, type ShaderEffectInstance, type ShaderEffectOptions } from '../shared/create-shader-effect';
+import { matcapFragment } from './shader';
+
+export type MatcapOptions = ShaderEffectOptions;
+export type MatcapInstance = ShaderEffectInstance;
+export const createMatcap = (root: HTMLElement | null, options: MatcapOptions = {}): MatcapInstance =>
+  createShaderEffect(root, matcapFragment, { amount: 0.15, ...options });

package/src/gl/matcap/shader.ts

@@ -0,0 +1,16 @@
+export const matcapFragment = `
+void main() {
+  vec2 point = (vUv - .5) * 2.5;
+  point.x *= uSize.x / uSize.y;
+  float radius = length(point);
+  if (radius > 1.) { gl_FragColor = vec4(.04, .06, .08, 1.); return; }
+  vec3 normal = normalize(vec3(point, sqrt(max(0., 1. - dot(point, point)))));
+  float angle = uTime * .2 + uProgress * 6.28318;
+  vec2 rotated = mat2(cos(angle), -sin(angle), sin(angle), cos(angle)) * normal.xy;
+  vec2 matcapUv = rotated * .495 + .5;
+  float hemisphere = clamp(1. - dot(normalize(vec3(1., -1., 1.)), normal), 0., 1.);
+  vec3 metal = mix(vec3(.1), vec3(1.), hemisphere) + pow(normal.z, 24.) * uAmount;
+  vec3 mapped = texture2D(uImage0, matcapUv).rgb;
+  metal = mix(metal, mapped + metal * .15, uHasImage);
+  gl_FragColor = vec4(metal, 1.);
+}`;

package/src/gl/particle-hero/README.md

@@ -0,0 +1,41 @@
+# particle-hero
+
+Una nube de puntos simulada en la GPU que se posa sobre las líneas de un patrón de interferencia que cambia solo (modos de Chladni de [3, 5, 7] cada 6–12 s, frecuencia 20–45 cada 5–10 s, distorsión 0–5 en 1.2–3 s) mientras una parte de los puntos (40–80 %) se va a dibujar una palabra y luego vuelve. El puntero los empuja según su velocidad. Aparece en 1 s tras 0.3 s.
+
+Origen: iyo.ai, hero de la home (escena `wK`, sistema `YW`, simulación `dE`): dos texturas de estado RGBA alternadas (posición XY, velocidad ZW), proyección tipo Newton hacia los ceros del campo, destino por hash estable según `texturePercent`, repulsión del puntero, ciclo de palabras en cuatro fases. Es una **implementación propia**: iyo mueve 1 638 400 puntos con Three.js y nueve imágenes de palabras; aquí son `size²` puntos (16 384 por defecto, hasta 65 536), palabras dibujadas en local con `system-ui`, tres campos base y tiempos aproximados. Sin WebGL2 con texturas float cae a unos 1800 puntos en un canvas 2D (un círculo que respira, sin Chladni); sin canvas no hace nada.
+
+Vive en la entrada opcional `@yewdiel21/motion-kit/gl`, así las páginas sin él no cargan sus shaders.
+
+## HTML / Astro
+
+```html
+<section id="hero" style="height: 80vh; background: #15130f">
+  <h1>Objetos que escuchan</h1>
+</section>
+<script>
+  import { createParticleHero } from '@yewdiel21/motion-kit/gl';
+  const hero = createParticleHero(document.getElementById('hero'), { words: ['ESCUCHA', 'CREA'] });
+  // hero.setWord('HOLA'); hero.setTextureMix(0.7); hero.setPattern(1); hero.destroy();
+</script>
+```
+
+El anfitrión fija la altura y el fondo; el canvas se coloca debajo de su contenido (`.mk-particle-hero`).
+
+## React
+
+```tsx
+const ref = useRef<HTMLElement>(null);
+const hero = useParticleHero(ref, { words: ['ESCUCHA', 'CREA'], size: 128 });
+```
+
+## API
+
+`createParticleHero(root, { words, size, pointSize, color, seed, forceFallback, onMode })` → `{ mode, setWord(text), setTextureMix(0…1 | null), setPattern(0|1|2), pause(), resume(), destroy }`. `mode`: `webgl2`, `canvas2d` o `none`; también en `data-mk-mode` de la raíz (`context-lost` si la GPU pierde el contexto: desmonta y vuelve a montar). Una segunda llamada con la misma raíz devuelve la misma instancia.
+
+## Rendimiento
+
+El estado ocupa `size² × 16` bytes por textura (256 KB con 128). DPR limitado a 1.5. Corre en el ticker compartido solo mientras el hero está cerca de la pantalla y la pestaña visible. Mide en las GPU de tu público antes de subir `size`.
+
+## Accesibilidad
+
+El canvas es decorativo (`aria-hidden`): el texto y el nombre del hero van en HTML. Con movimiento reducido dibuja una composición quieta (la palabra formada) sin bucle.