svelte-kit-vice/docs/process/handoffs-2026-05.md

# Hand-offs — May 2026 (extracted from the layer READMEs)

These session hand-off notes used to live inline at the top of the layer
READMEs (UIX and arts). They were pulled out so those reference docs read as
timeless. Kept here for traceability; the rules they fixed are now reflected in
the docs themselves and enforced by `src/uix/contracts.ts` + `contracts.test.ts`.

> The `active_architecture.md` §0 hand-off (the largest one) is **not** here yet:
> it embeds the referenced "contratos mínimos" table that other docs link to, so
> it gets separated from its handoff framing during the architecture (E1) pass,
> not in this mechanical extraction.

---

## From `src/uix/README.md` (intro blockquote) — 2026-05-14

> **Visión de conjunto**: para entender las cuatro capas (morfo, soma, sema,
> eidos) en una sola lectura, motivaciones y articulación incluidas, ir a
> `active_architecture.md`. Este README mantiene la introducción más narrativa.
>
> **Hand-off de continuación**: el estado actual de migración y los próximos
> pasos viven en `continue.md`.
> **Handoff 2026-05-14**: pausa deliberada antes de seguir programando.
> Los contratos mínimos entre `active-uix`, `morfo`, `soma`, `sema`, `eidos`,
> `adom`, `langs`, `format` y `prefs` quedan descritos en
> `active_architecture.md`, sección "Handoff 2026-05-14". Ya queda fijada la
> regla principal de ownership: solo `ActiveApp` y `ActiveUix` standalone crean
> servicios compartidos. La tabla ejecutable de contratos vive en `contracts.ts`
> y se valida en `contracts.test.ts`. La tabla de naming canónico vive en
> `active_architecture.md#01-naming-canonico`. Ownership DOM P1 queda cerrado:
> las escrituras gestionadas por UIX pasan por `ActiveDom`.
>
> **Convenciones doctrinales del API** (intent ↔ color, subset por componente,
> root visual con partes attached en eidos, sound prepare-time priming): viven en
> `src/docs/GUIA_IMPLEMENTACION_SEMAUIX.md`. Autoritativo para todo wrapper /
> migración nueva.

---

## From `src/uix/morfo/README.md` — Handoff 2026-05-14

Morfo debe seguir siendo declarativo: no instancia servicios y no conoce
`ActiveUix`. Sus campos solo entran en el contrato cuando son superficie
cross-layer real; si un dato pertenece a una sola capa, vive en esa capa.

Decisiones cerradas:

- `texts` declara las ranuras de texto del componente como idlangrefs absolutos
  (`'#?components.{kebab}.{key}|fallback'`). El catálogo multilingüe vive en
  `src/uix/langs/components/{kebab}.ts` (fuera del morfo).
- Textos comunes usan `v.commonRef(...)` o un idlangref absoluto; no se
  duplican en cada morfo.
- `registerMorfo(morfo)` registra el contrato `data-*`. El catálogo de strings
  (`componentLangs` + `commonLangs`) lo registra `ActiveUix` al arrancar; el
  morfo nunca extiende `ActiveLangs` dinámicamente.
- Si Soma, Sema y Eidos necesitan un dato compartido, pasa por morfo o por un
  contrato publico; no por imports laterales entre capas.
- La regla 2-de-3 sigue vigente para extender morfo.

---

## From `src/uix/sema/README.md` — Handoff 2026-05-13

Sema ya tiene contrato explicito de DOM: si el canal visual esta activo,
`EngineSemantic` debe recibir `dom` o `projector`. Si se construye desde
`ActiveUix`, recibe el `dom` de `ActiveUix`; si se usa directamente fuera de
UIX, el integrador debe pasar un writer explicito o usar `visual:false`.
Sema no cae a escrituras DOM directas por defecto.

Tambien queda por decidir si `emit` debe seguir siendo secuencial estricto de
forma global o si la secuenciacion pertenece al evento/morfo. No cambiar esto
sin documentar antes la tabla de contratos minimos en `../active_architecture.md`.

---

## From `src/uix/soma/README.md` — Handoff 2026-05-14

Soma no debe crecer ahora con `ActiveSoma`/`EngineSoma` por simetria. El
contrato minimo de `SomaRuntime` con `ActiveUix` (`dom`, `events`, `langs`,
`format`, `prefs`) queda descrito en `src/uix/contracts.ts`. La regla de
ownership ya queda cerrada: Soma no crea servicios compartidos. Recibe `dom`
desde el scope `Soma.runtime(...)`; si no hay una superficie `ActiveDom`, falla
en la raiz activa, no dentro de un componente.

Punto critico para manana: confirmar que todo atributo mutable sigue pasando
por el servicio DOM activo, y que ninguna ausencia de `dom` hace que Soma o
Sema caigan a escrituras directas.

---

## From `src/uix/eidos/README.md` — Handoff 2026-05-14

Eidos queda congelado a nivel de componentes hasta reauditar la arquitectura
de UIX. No tocar `src/uix/eidos/components/*` salvo orden explicita.

Actualización 2026-05-17: la migración de componentes se reanudó por orden
explícita. La regla vigente no cambia: cada componente nuevo debe seguir
`components/README.md`, envolver partes públicas de Soma directamente y añadir
sólo superficie visual de Eidos.

Antes de seguir con wrappers o recipes por componente hay que respetar estas
decisiones:

- que contrato minimo consume `Eidos` desde `ActiveUix`;
- `ActiveEidos` asume authoring, validacion, generacion CSS, persistencia y
  contexto visual;
- `events` es el servicio perceptivo runtime y `morfo.translations` es el
  catalogo declarativo de texto owned por el componente;
- que parte se genera desde codigo y que parte puede venir solo por CSS;
- como se mantiene la regla de escritura DOM unica en standalone `dom:false`.

La referencia de arranque esta en `../active_architecture.md`, seccion
`Handoff 2026-05-14`.

---

## From `src/uix/active-uix/README.md` — Handoff 2026-05-14

La regla de ownership queda cerrada:

> Solo los composition roots crean servicios compartidos. Si hay `ActiveApp`,
> `attachActiveUix(app)` consume sus servicios y falla si falta alguno
> requerido. Si no hay app, `createActiveUix(...)` es el composition root local
> y crea los servicios/prefs de UIX. `morfo`, `soma`, `sema`, `eidos` y los
> componentes no crean `dom`, `langs`, `prefs`, `format`, `clipboard` ni
> equivalentes.

La revision de naming queda cerrada asi: `events` es el nombre publico del
motor perceptivo en `ActiveUix` y tambien el nombre del servicio que
`defineUixServices(...)` registra en `ActiveApp`. `semantic` queda reservado
para el payload declarativo de `morfo.events[].semantic`, no para servicios
runtime. `morfo.translations` queda como catalogo declarativo owned por el
componente. `prefs` es el unico nombre para preferencias: `ActiveUix` expone
el `ActivePrefs` bruto y las capas inferiores consumen vistas acotadas cuando
no deben mutar.

---

## From `src/arts/README.md` — Handoff 2026-05-14

La frontera entre `arts` y `uix` queda fijada por la tabla de contratos de
`src/uix/contracts.ts`. `ActiveApp` compone servicios y mantiene `prefs`;
`ActiveUix` consume esos servicios cuando se adjunta a una app o los crea en
modo standalone. El antiguo artefacto `frontend` queda retirado: la proyeccion
cross-modal pertenece a `arts/prefs` (`createActivePrefsDomProjection(...)`) y
la proyeccion visual pertenece a `ActiveEidos`.

---

## From `src/arts/active-app/README.md` — Handoff 2026-05-13

`ActiveApp` no absorbe decisiones propias de UIX. Mantiene el core
(`logger`, `bus`, `timers`, `orca`, `prefs`) y compone solo los servicios que
la aplicacion declara en `services`.

El antiguo servicio `frontend` fue retirado. Las preferencias transversales
(`direction`, `motion`, `sound`, `haptic`) se proyectan mediante
`createActivePrefsDomProjection(...)` cuando la app lo cablea con un
`ActiveDom`. Las preferencias visuales (`theme`, `mode`, `density`) pertenecen
a Eidos. Si una ruta UIX necesita un toggle claro/oscuro, debe pasarlo a
`ActiveEidos.modeSource`; no debe declarar ni escribir `App.prefs.theme` salvo
que sea una dimension custom de una app ajena a UIX.

La tabla ejecutable de contratos entre `ActiveApp`, `ActiveUix` y las capas
UIX vive en `src/uix/contracts.ts`.

---

## From `src/arts/adom/README.md` — Handoff 2026-05-14

`ActiveDom` es la unica superficie permitida para mutar DOM gestionado desde
UIX. La decision P1 queda cerrada en `ActiveUix`: `dom:false` inyecta un
`disabledDom` no-op compartido por Soma/Sema/Eidos. No puede haber fallback
silencioso a escrituras directas dentro de UIX.

---

## From `src/arts/format/README.md` — Handoff 2026-05-14

`Format` debe seguir `prefs.locale`, no `prefs.language` ni el servicio
`langs`. Los ejemplos historicos que hablan de `App.langs.setLocale(...)`
representan el modelo viejo y no son doctrina actual.

El objetivo es que una app tenga una sola verdad:

```ts
App.prefs.locale.set('es-AR');

App.format.numbers.format(1234.5);
App.format.currency.getCurrency(); // ARS
App.format.units.getSystem(); // metric
App.format.dates.getDateOrder();
```

---

## From `src/uix/eidos/README.md` — Cambios 2026-05-21

> Extracted 2026-07-02 (docs reconciliation): dated change-log block that lived
> inline in the eidos README. Kept verbatim; counts and citations reflect the
> state at the time (e.g. `DEMO_AUTHORING_GUIDE §12.8` is the v1 guide — the v2
> replaced it with §6/§7).

- **Tokens muted añadidos al contrato.** `SurfaceColorRoles` y
  `ContentColorRoles` ahora incluyen `muted` (entre `overlay`+`backdrop`
  y entre `secondary`+`disabled` respectivamente). Mapeo base:
  `--color-surface-muted: var(--primitive-neutral-3)` (light + dark) y
  `--color-content-muted: var(--primitive-neutral-10)`. Antes existían
  17+3 referencias rotas en recipes/components que el browser caía a
  initial-value (texto invisible para placeholders, separadores,
  weekday del calendar, group-heading del select, etc.). Solucionado
  vía `themes/base.ts` + `render-css.ts` + regen.
- **Typo `--color-neutral-element-hover` corregido** en `form.css:76`
  → `--color-neutral-hover` (el token correcto existente).
- **Raw colors removidos.** `archetypes.css:122` (hsl indigo fijo para
  `[aria-selected]`) y `events.css:eidos-commit-settle` (rgba indigo
  fijo) sustituidos por `color-mix(var(--color-primary-solid) …)`. Ya
  no quedan hex/rgb/hsl crudos en `src/uix/eidos/**/*.css` ni en
  `recipes/base.ts`.
- **Cobertura de tamaños expandida.** 20 componentes pasan de
  `sm·md·lg` a `xs·sm·md·lg·xl` (form controls + text inputs +
  progress/meter + field/form) o a `xs·sm·md·lg` (nav controls:
  breadcrumb, pagination, tag-group, toolbar). Categorización
  documentada en `DEMO_AUTHORING_GUIDE §12.8` (v1). Paneles compuestos
  (calendar, date-picker, date-range-picker, file-upload, stepper,
  tooltip) mantienen `sm·md·lg`. La elección responde a uso real, no a
  artificio: barras y controles tactiles escalan limpio en 5 escalones;
  paneles compuestos no se benefician por debajo de `sm`.
- **Paridad de chips en demos.** `field.variant` y `toolbar.variant`
  dejaron de narrowar `ControlVariant` a 2 valores; ahora exponen los
  3 (`surface | outline | ghost`). El CSS añade selectores
  `[data-variant='outline']` con bg transparente + border visible para
  ambos componentes. La norma queda fijada en CHECKLIST §D-7.4.
- **Scrollbar portaled.** Las reglas `::-webkit-scrollbar*` viven sin
  scope en `web/routes/uix/uix.css` (sólo se carga bajo `/uix`).
  `--uix-line` se duplica en `:root` con override
  `:root[data-mode='dark']` (atributo escrito por `ActiveEidos`),
  permitiendo que portals (Combobox listbox, Popover, Dialog, Drawer)
  resuelvan el token aunque vivan fuera de `[data-uix-docs]`.

---

## From `src/uix/eidos/README.md` — Estado actual (2026-05-17)

> Extracted 2026-07-02 (docs reconciliation): frozen status snapshot (the
> wrapper list stops at ~20; the real catalog kept growing). The live component
> inventory is the directory tree + `npm run component:audit`, never a list in
> a doc.

- **ActiveEidos**: implementado como runtime/contexto visual y superficie de
  configuracion. Gestiona primitivas, roles canonicos, themes, validacion,
  contrato CSS, persistencia y render CSS (`renderStaticCss`,
  `renderThemeCss`).
- **Authoring API**: `defineEidosConfig`, `extendEidosConfig` y
  `createThemeBaseEidosConfig`
  permiten crear configuraciones completas o extender el theme base sin
  mutar las constantes del sistema. `getCssContract()` expone el contrato
  estructurado, `renderContractCss()` lo materializa como CSS para themes
  externos, `renderCssVariables()` permite escribir overrides runtime
  contract-aware y `toDocument()` / `serialize()` exponen el envelope
  versionado para persistencia.
- **Runtime CSS**: `ActiveEidos` reacciona a su `preferences` compuesto o a
  fuentes explicitas `modeSource` / `densitySource`, soporta themes de config
  y CSS-only via `themeSource`, acepta variables runtime en un style block
  propio, y con `applyDom:false` no escribe en el DOM.
- **Wrappers por componente**: la superficie migrada desde Soma ya incluye
  `toggle`, `switch`, `collapsible`, `dialog`, `drawer`, `popover`, `toast`,
  `accordion`, `avatar`, `tooltip`, `tabs`, `checkbox`, `radio-group`,
  `meter`, `progress`, `slider`, `pagination`, `rating-group`,
  `search-field`, `number-field` y `breadcrumb`. Todos usan root visual +
  partes attached, sin `Provider` público ni API flat.
- **Color**: basado en roles canonicos de jerarquia e intents
  (`primary`, `secondary`, `tertiary`, `neutral`, `affirm`, `fulfill`,
  `risk`, `threat`, `loss`) y escalas de 12 pasos. Por cada escala genera
  alpha tokens `a1..a12`, derivadas automaticamente o sobrescribibles con
  `color.alphaScales` por theme. Los roles semanticos validos son solo los
  declarados por el contrato de Eidos.
- **Size**: `xxs..xxl` se renderiza como map global coordinado
  (`control-height`, font, icon, padding, gap, radius). `full` queda como
  valor de layout, no como primitiva fisica. Cada componente declara
  el sub-rango que su recipe mapea — la categorización canónica está
  en `DEMO_AUTHORING_GUIDE.md §12.8` (v1; form controls + text inputs +
  progress/meter + field/form usan `xs..xl`; nav controls usan
  `xs..lg`; paneles compuestos mantienen `sm..lg`).
- **Border / opacity / z-index / shadow**: ya forman parte del contrato
  generado. Border define escala de width/style y aliases globales; opacity
  cubre estados de UI y overlays; z-index cubre capas comunes; shadow combina
  escala fisica `1..6` con aliases semanticos por theme.
- **Layout**: ya forma parte del contrato generado. Incluye
  `containerWidth`, `containerPaddingInline`, `contentWidth` y `aspectRatio`
  como tokens estables y authorables desde `EidosConfig`.
- **Density**: ya forma parte del contrato generado. Incluye
  `spaceScale` y `controlScale` para los tres niveles canonicos
  `compact`, `comfortable` y `spacious`, conectados al `data-density`
  que proyecta `ActiveEidos`. Mueve ritmo de layout y altura de
  controles; NO escala la tipografia.
- **Scaling**: eje de zoom global independiente de la densidad (paridad
  con el `scaling` de Radix). Niveles `90` / `95` / `100` / `105` / `110`
  proyectados via `data-scaling`; escala `space`, `control-height`,
  `font-size` e `icon-size` (SI incluye tipografia), no radius/border/
  sombra. Se multiplica con la densidad. Ver THEMING.md §23.
- **Tipografia**: usa tamaños canonicos `xxs` a `xxxl`, familias
  libres por key y estilos tipograficos (`h1`, `h2`, `body`, etc.) como
  `Record<string, TypographyStyle>`.
- **Convencion del API de componentes**: disciplined option C esta
  documentada en `components/README.md`. La migracion
  de componentes avanza por tandas pequenas y no debe arrastrar cambios de
  demos/rutas ni reimplementar comportamiento que pertenece a Soma.
- **CSS generado**: `generated/base.css` ya se genera desde la config
  base de Eidos con `npm run generate:eidos-css` y se importa como foundation
  estatica. Los CSS historicos de `contracts/` y `themes/base/` ya no existen
  en el arbol activo; el contrato se publica desde `ActiveEidos` y los valores
  base desde `generated/base.css`. Los antiguos `tokens/components/*` tambien
  salen del entrypoint: `EidosConfig.recipes` genera los aliases de recipe
  estables.
- **Recipes**: quedan deliberadamente como `RecipeTokenSet` plano. No se crea
  jerarquia estructurada hasta que una recipe tenga un builder/consumer real
  que necesite mas semantica que aliases CSS. La guardia
  `recipe-css-contract.test.ts` evita que el theme base declare aliases no
  consumidos o que un CSS de componente use variables fuera del contrato.
- **Check del repo**: `npm run check` no reporta errores ni warnings en este
  punto.

---

## From `src/uix/eidos/components/README.md` — Estado de la migración (2026-05-20)

> Extracted 2026-07-02 (docs reconciliation): frozen migration-status table.
> The migration completed on 2026-05-22 (every component + 5 pickers + 2
> grids); the live inventory is the `components/` tree + `npm run
component:audit`.

La tanda 2026-05-17 reanuda la migración Soma -> Eidos por orden explícita.
Los wrappers nuevos siguen el mismo criterio: envolver partes públicas de Soma,
añadir sólo props visuales (`size` en esta tanda) y dejar comportamiento,
estado, ARIA, traducciones y escritura headless en Soma/Morfo.

| Componente   | Forma canónica | Notas                                                                              |
| ------------ | -------------- | ---------------------------------------------------------------------------------- |
| toggle       | ✅ single-part | piloto                                                                             |
| switch       | ✅ multi-part  | Thumb                                                                              |
| collapsible  | ✅ multi-part  | Trigger, Content                                                                   |
| dialog       | ✅ multi-part  | Trigger, Portal, Overlay, Content, Title, Description, Close, Header, Footer       |
| drawer       | ✅ multi-part  | + Handle                                                                           |
| field        | ✅ multi-part  | Label, RequiredIndicator, Control, Input, HelperText, ErrorText, Prefix, Suffix    |
| form         | ✅ multi-part  | Submit, Reset, ErrorSummary, AutoFields                                            |
| popover      | ✅ multi-part  | Arrow, Anchor, Title, Description                                                  |
| toast        | ✅ multi-part  | + Toaster separate                                                                 |
| accordion    | ✅ multi-part  | Item, Header, Trigger, Content                                                     |
| avatar       | ✅ multi-part  | Image, Fallback (eidos-native)                                                     |
| breadcrumb   | ✅ multi-part  | List, Item, Link, Separator, Ellipsis                                              |
| calendar     | ✅ multi-part  | Header, Heading, Prev/Next, Month/YearSelect, Grid, Cell, Day                      |
| date-picker  | ✅ multi-part  | DateField + Popover + Calendar composition                                         |
| icon         | ✅ single-part | + 1697 lucide glyphs                                                               |
| meter        | ✅ multi-part  | Indicator                                                                          |
| number-field | ✅ multi-part  | Input, IncrementTrigger, DecrementTrigger, Scrubber                                |
| pagination   | ✅ multi-part  | FirstTrigger, PrevTrigger, NextTrigger, LastTrigger, Item, Ellipsis                |
| progress     | ✅ multi-part  | Label, ValueText, Indicator                                                        |
| rating-group | ✅ multi-part  | Item                                                                               |
| search-field | ✅ multi-part  | Input, ClearTrigger                                                                |
| select       | ✅ multi-part  | Trigger, Value, Indicator, Portal, Content, Viewport, Item, ItemIndicator, Group   |
| combobox     | ✅ multi-part  | Control, Input, Trigger, Indicator, Portal, Content, Viewport, Item, ItemIndicator |
| slider       | ✅ multi-part  | Range, Thumb, Tick                                                                 |
| tooltip      | ✅ multi-part  | + Group                                                                            |
| tabs         | ✅ multi-part  | List, Trigger, Content, Indicator                                                  |
| checkbox     | ✅ multi-part  | Indicator, HiddenInput, Group, GroupLabel                                          |
| radio-group  | ✅ multi-part  | Item, Indicator, HiddenInput, Label                                                |
| toolbar      | ✅ multi-part  | Button, Link, Group, GroupItem, Separator                                          |
| tag-group    | ✅ multi-part  | Label, Item, Link, RemoveButton                                                    |
| tags-input   | ✅ multi-part  | Control, Input, Item, ItemText, ItemDeleteTrigger, ClearTrigger                    |
| file-upload  | ✅ multi-part  | Label, Dropzone, Trigger, HiddenInput, FileList, Item, preview/progress/actions    |
| editable     | ✅ multi-part  | Area, Control, Preview, Input, EditTrigger, SubmitTrigger, CancelTrigger           |
| stepper      | ✅ multi-part  | List, Item, Trigger, Indicator, Separator, Content, CompletedContent, Prev/Next    |

### Orden recomendado para continuar

1. Componentes grandes sólo con tabla previa de migración:
   `date-range-picker`, `time-field`, `time-picker`.