svelte-kit-vice/docs/process/PLAN-text-effects.md

# PLAN — Efectos de texto (F5 del plan Scene/Ambient, desgajado por D9)

> **Tipo**: plan de ejecución por fases (process — efímero, no fuente de verdad).
> **Fecha**: 2026-07-12 · **Estado**: **PLAN COMPLETO — D-T1…D-T4 resueltas · FT0–FT7 EJECUTADAS (2026-07-12)**.
> FT7: **6 demos** en `web/routes/uix/components/{kebab}/` (frame de 6 pestañas de los pasivos shipped — patrón box/format-number; cada prop pública = control vivo; snippet con paridad; sema empty-state justificado; CountUp con `demoLocale` propio por chips — convención service-demos). Matriz **141/0/0 con Demo ✓ y 0 warns en los 6** · check 0 propios · docs:check 0/0 · contracts 38/38. **Verificado en navegador**: 6 rutas SSR 200 + hidratadas; CountUp formatea por locale del ecosistema EN VIVO (`0,00` es-ES → chip en-US → `0.00`); TextGradient resuelve tokens→OKLCH del tema vía `var()` con `background-clip:text` + animación activa; TextCircular `role=img`+33 chars posicionados; TextFocus SIN botones falsos dentro y el auto-avance de `timers.interval` CORRE (palabra activa cambia — los timers no son rAF); TextBlur segmentos `aria-hidden` + SR completo + estado inicial sin flash; TextScramble SR surface correcta. Cero errores de consola. Los caminos rAF/IO-dependientes (count visual, flicker, marco) quedan bajo el pendiente visual de pestaña visible ya conocido (pane oculto suspende rAF/IO/measure). Ajuste de tipos post-demo: los 5 visuales aceptan `style` (fijar tokens por instancia); text-gradient fusiona su style interno con el del consumidor.
> FT0–FT6: **los 6 componentes construidos y verdes en toda la maquinaria** — matriz component-audit **141/0/0** (los 6 PASS con README F-1 completo: Baseline/Comparativa/Gaps/Passive justification) · contracts 38/38 (enumeración morfo + scope) · check 0 errores propios. `CountUp` (servicio patrón FormatNumber: morfo 1-part, `uix.format.numbers` reactivo cada frame con fallback Intl, spring DHO analítico — el de `$motion` es element/CSS-bound, anotado —, IO/rAF vía `eidos.dom`, timers vía `eidos.timers`; `separator` del seed NO portado: el locale posee los separadores) · `TextGradient` (receta CSS + tokens públicos, stops `var()`-interpolados + `preset` → `--gradient-{name}` S9, borde interior `#000`→`--color-surface-default` token, keyframes R-4.5 anotados, `margin:0 auto` del seed fuera) · `TextCircular` (rAF vía dom, reduce-motion AÑADIDO — el seed no paraba nunca —, `currentColor` default, nota Aura en morfo/README) · `TextBlur` (**SR hardening**: texto real visually-hidden + segmentos aria-hidden; WAAPI directa = primitivo del driver waapi de $motion, migrará al dominio content cuando el RFC aterrice; IO vía dom) · `TextFocus` (**a11y fix**: fuera los `role="button"`+tabindex falsos del seed; `timers.interval` + `dom.measure` + `observeResize`; tokens border/glow; reduce = marco quieto; 1 `!important` anotado R-4.7) · `TextScramble` (**rediseño de medición**: cache de centros por carácter vía `dom.measure` invalidado por RO — el seed medía N rects POR pointermove; 1 lectura por move; SR hardening; `text: string` en vez de children — el split solo es honesto con texto plano, declarado). Extensión de vocabulario: `MorfoElement` + `'p'` (primer párrafo del catálogo).
> **Origen**: `docs/process/PLAN-scene-ambient-pack.md` D9 — los 6 efectos de texto de
> `web/routes/demos/animations/text/` NO van al pack Ambient: **envuelven contenido
> real → superficie a11y = superficie de contrato → canon**, con destinos
> heterogéneos. La colección seed queda intacta como referencia comparativa (D5/D7).

## Los 6 seeds, analizados

| Seed | Sustrato | Qué hace | Interacción | A11y del seed | Ciudadanía a corregir |
| --- | --- | --- | --- | --- | --- |
| `count` (Count Up) | rAF spring analítico | Cuenta from→to al entrar en viewport | — | ✓ texto real (números) | `Intl.NumberFormat('en-US')` **hardcoded** → debe componer `uix.format.numbers` (locale-aware); `setTimeout`→`uix.timers`; IO→`$adom`; reduce ✓ ya salta al final |
| `gradient` (Gradient Text) | CSS puro (`background-clip:text` + keyframes) | Gradiente animado sobre el texto (+ borde opcional) | pause-on-hover | ✓ texto real intacto | Colores crudos→tokens; `#000` del borde interior = phantom→token de superficie; `@keyframes`→R-4.5 (anotación functional / registro motion); reduce ✓ ya |
| `blur` (Blur Text) | WAAPI por segmento | Entrada staggered blur→nítido por palabras/letras al entrar en viewport | — | ⚠️ trocea en spans (por letras fragmenta lectura SR) | **SR hardening**: `aria-label` en contenedor + segmentos `aria-hidden`; WAAPI/stagger vía dominio content de `$motion`; IO→`$adom`; reduce ✓ ya |
| `circular` (Circular Text) | rAF + transforms | Caracteres en círculo girando; hover cambia velocidad | hover (slowDown/speedUp/pause/goBonkers) | ✓ `role="img"` + `aria-label` (buena base) | rAF→`dom.requestFrame`; escrituras transform→`dom.apply`; colores/tamaños crudos→tokens. **Nota Aura**: texto orbital alrededor de un shape redondo = pieza candidata de la periferia del indicador de agente |
| `focus` (True Focus) | CSS transitions + JS | Palabras difuminadas salvo la activa; marco de esquinas viaja (auto o hover) | hover en modo manual | ⚠️ `role="button"` + `tabindex=0` en CADA palabra sin acción real = anti-patrón | Quitar role=button (o darle semántica real); `setInterval`→`uix.timers`; `getBoundingClientRect`→**`dom.measure`** (regla dura de layout reads); RO→`dom.observe`; border/glow crudos→tokens; reduce ✓ ya |
| `scrambled` (Scrambled Text) | rAF + DOM textContent | Scramble de caracteres cerca del puntero | pointermove | ⚠️ SR puede leer los caracteres scrambled; split destruye el HTML original | **SR hardening** (aria-label + chars aria-hidden); **reflow storm**: mide `getBoundingClientRect` POR CARÁCTER en CADA pointermove → rediseño obligado: cache de rects vía `dom.measure` invalidado por RO; rAF→`dom.requestFrame`; pointer→`dom.listen` |

Precedente real del canon para servicios: `formatNumberMorfo` — morfo de **1 part,
`scope: ['eidos']`, sin CSS/eventos** («grep-friendly typed wrapper»,
`src/uix/morfo/components/format-number.ts`). Confirma que *morfo-first* aplica
incluso a componentes de servicio, con coste mínimo. Los efectos con interacción
(circular/focus/scrambled) añaden data-attrs de estado y, si procede, eventos sema.

## Decisiones (gate del usuario)

| ID | Cuestión | Opciones analizadas | Recomendación |
| --- | --- | --- | --- |
| **D-T1** | Arquitectura por efecto | (a) canon completo ×6 (ruta 9 fases con soma+sema cada uno) · (b) familia "text effects" = wrappers eidos con morfo mínimo · (c) **mixto**: cada uno a su hogar natural — count=service component (patrón FormatNumber); gradient=eidos CSS con morfo mínimo; blur/circular/focus/scrambled=eidos decorativos con morfo (parts+data-attrs de estado) sin soma provider (no hay máquina de estados accesible que justifique soma; la interacción es decorativa) | **(c)** — (a) infla 4 componentes decorativos con capas vacías; (b) niega a count su hogar de servicio |
| **D-T2** | count: ¿componente nuevo o prop de FormatNumber? | (a) `<CountUp>` hermano de FormatNumber que compone el MISMO formatter (`uix.format.numbers`) · (b) prop `animate` en FormatNumber | **(a)** — FormatNumber es puro/inmediato; animar es otra responsabilidad. Ambos comparten formatter (sin duplicar lógica de locale) |
| **D-T3** | gradient: ¿API de colores cruda o sistema de gradientes del theming (S9)? | (a) `colors: string[]` con tokens resolubles (API del seed, theming vía tokens) · (b) integrar el vocabulario de gradientes S9 (presets canónicos) además de colores libres | **(b) con (a) dentro**: acepta stops libres (tokens o hex) Y presets del sistema de gradientes — canon presentado como opción, sin recortar la API del seed |
| **D-T4** | Naming de la familia | (a) prefijo `Text*`: `TextBlur` / `TextCircular` / `TextFocus` / `TextGradient` / `TextScramble` + `CountUp` aparte (servicio) · (b) nombres del seed (BlurText, TrueFocus…) · (c) compound `Text.Blur` | **(a)** — agrupa en el catálogo junto al primitivo `Text`, evita el genérico "True/Up" del seed; count no es de la familia visual |
| **D-T5** | Dónde vive la animación de cada uno | blur = **dominio content de motion** (entrada de contenido: consume `uix.motion` / WAAPI vía runtime, no keyframes CSS) · gradient = keyframes CSS de receta (loop ambiental, R-4.5) · circular/scrambled = rAF vía `dom.requestFrame` (estado continuo JS) · focus = CSS transitions + `uix.timers` · count = spring JS (¿reutilizar el spring de `$motion` si su API lo expone para valores numéricos? — se verifica en FT1; si no, spring local como el seed) | Se deriva de la doctrina motion (perceptual anchoring; animation = channel); no exige gate salvo desacuerdo |

## Fases (tras el gate)

- **FT0 — Doctrina**: asentar D-T\* en este plan; verificar precedentes (spring de `$motion`, sistema de gradientes S9, wrappers eidos-only) leyendo el código real; actualizar `docs/README.md` si la familia merece fila propia.
- **FT1 — `CountUp`** (servicio): morfo 1-part patrón FormatNumber · compone `uix.format.numbers` (locale reactivo del ecosistema, NO en-US fijo; el `separator` del seed se reevalúa contra la API real del formatter) · IO por `$adom` · `uix.timers` · spring (D-T5) · reduce = salto al final.
- **FT2 — `TextGradient`** (eidos): receta CSS con tokens + R-4.5 · stops libres + presets S9 (D-T3) · borde con token de superficie · reduce ya en CSS.
- **FT3 — `TextBlur`** (eidos + motion content): split words/letters con **SR hardening** (contenedor `aria-label`, segmentos `aria-hidden`) · stagger/WAAPI vía runtime motion · IO por `$adom`.
- **FT4 — `TextCircular`** (eidos): rAF vía `dom.requestFrame` · hover states como data-attrs del morfo · tokens de tipografía/tamaño · conserva `role="img"`. Anotar la conexión Aura (texto orbital del indicador).
- **FT5 — `TextFocus`** (eidos): `uix.timers` + `dom.measure` + `dom.observe` · fix a11y del role=button · border/glow por tokens.
- **FT6 — `TextScramble`** (eidos): **cache de rects** (dom.measure + invalidación por RO — mata el reflow storm) · SR hardening · pointer por `dom.listen` · charset/duración/radio como props.
- **FT7 — Cierre**: demos con profundidad DEMO_AUTHORING (cada prop = control vivo) · checklist de componente por cada uno · `npm run check` + vitest + eidos-lint + navegador · memoria + este plan con bloques EJECUTADA.

- **Verify por fase**: check 0 errores propios · component:audit verde para los nuevos · demo montada en navegador · SR hardening revisado (árbol de accesibilidad en devtools).

## Fuera de alcance

La fase Aura (el plan madre §F6.3) sigue sin construirse aquí; `TextCircular`
solo deja anotada la pieza orbital. Los 4 efectos de imagen (D8) siguen fuera.