Texto del ADR

Leído de docs/decisions/dec-0084-experience-contract-pi3-reference.md, el fichero canónico.

r58 — Styx Experience Contract (renderer-agnostic) + Raspberry Pi 3 como reference efficiency platformCopiar enlace

• Status: locked 2026-07-15 (AskUserQuestion con previews, sesión axon cont. 40; paquete styx-platform-player-executable-2026-07-15.zip)
• Layer: product parity (cross-renderer)
• Origin: paquete docs/design/styx-platform-player-executable-2026-07-15/adr-candidates/ADR-CANDIDATE-experience-contract-pi3-reference.md
• Bloquea: F-UI (input extra), F-WEB-PLAYER-ENGINE.W5, F-APPLIANCE-PI3.P1 + P4
• Extiende: r25 (federated media runtime marco §0), r28 §3 (principio anti-especulativo), r23 (CMF incluye experiencia de motion — ahora ampliado)
• Absorbe como INPUT: F-UI UX direction v0 APROBADA 2026-07-12 (vocabulario LOCKED 12/12, docs/design/ux-direction-v0.md)
• ABSORBE como fase F-UI owner: F-UI produce contrato Y reference artifacts (no sólo componentes)

TL;DRCopiar enlace

Existirá un Styx Experience Contract renderer-agnostic. La web es la autoridad inicial de diseño y prototipado. Raspberry Pi 3 es la reference efficiency platform, NO un cliente degradado. React y QML implementarán el mismo contrato con renderers distintos. Paridad medida en semántica, motion, visual, performance y resiliencia — no pixel-exact cross-rasterizer.

Experience Contract contentsCopiar enlace

Canonical journeys (initial 10)Copiar enlace

1. Home initial render
2. Horizontal and vertical navigation
3. Focus animation
4. Card → detail shared transition
5. Detail → player
6. Player controls
7. Scrubbing/previews
8. Fullscreen → mini-player
9. Back
10. Original card and exact focus restoration

Allowed variation (renderer/platform)Copiar enlace

• texture resolution; cache size; live object count; blur implementation;
• decode capabilities; renderer internals; image derivative chosen;
• memory budgets.

Forbidden degradationCopiar enlace

• eliminar transiciones compartidas;
• sustituir la jerarquía por una UI "embedded-lite";
• introducir blank screens/loaders entre estados ya preparados;
• perder focus restoration;
• cambiar navigation semantics;
• reducir la Pi 3 a listas funcionales sin identidad Styx.

Acción inmediata:

• F-UI (en curso) produce contrato Y reference artifacts (no sólo componentes) — ampliado por este ADR.
• F-APPLIANCE-PI3.P1 (TKT-043) implementa QML graphics tracer bullet consumiendo el Experience Contract.
• G-PI3-SEM, G-PI3-MOTION, G-PI3-VIS, G-PI3-PERF, G-PI3-RES son los 5 gates del contract (ver paquete execution/02-WEB-PI3-PARITY-GATES.md).

ContextoCopiar enlace

Compartir componentes React entre plataformas no es viable ni deseable. Sin un contrato independiente del renderer, la web se convierte en una autoridad implícita imposible de verificar (anti-patrón que r28 §3 prohíbe), y la Pi 3 tendería a degradarse visualmente para cumplir budgets (anti-patrón r25 §0 de "owned e2e").

Waxin tiene UX direction v0 (APROBADA 2026-07-12, vocab LOCKED 12/12) en memoria de proyecto (f-ui-ux-direction-v0.md → docs/design/ux-direction-v0.md). Ese doc cubre:

• tokens + typography + journeys + motion (subconjunto del contract).
• vocabulario LOCKED (12/12).

Pero NO cubre (huecos que este ADR cierra):

• motion graphs formales (canonical sequence + interruption/reversal).
• asset contracts (derivatives + sizes + formats + budget per asset).
• golden artifacts (screenshots/keyframes/recordings).
• G-PI3-* parity gates (semantic, motion, visual, perf, resilience).
• semantic traces (state IDs + transition order).
• allowed renderer-specific tolerances (vs forbidden degradation).

Este ADR absorbe UX v0 como input y añade las 4 capas formales que faltan. F-UI owner + Pi 3 renderer co-firman el contract; F-UI produce contrato Y reference artifacts (no sólo componentes — ampliación honesta de la scope actual).

DecisiónCopiar enlace

D6.1 — Renderer-agnostic Experience ContractCopiar enlace

Existirá un Styx Experience Contract documentado en docs/design/experience-contract/ con las 14 categorías enumeradas arriba. Versión semver. Cambios = ADR (o amend a este).

D6.2 — Web = autoridad inicial de diseñoCopiar enlace

La web es donde el contract se explora e itera primero, porque:

• Mayor velocidad de iteración (HMR + Vite stack de F-UI).
• Reference recordings + keyframes son capturables en tiempo real.
• Fable UI worktree (styx-fable-ui) está activo y dispuesto.

Web NO es autoridad de implementación para otras plataformas — sólo de exploración. La implementación final cross-platform se valida en gate P4 (F-APPLIANCE-PI3).

D6.3 — Pi 3 = reference efficiency platform, NO cliente degradadoCopiar enlace

Raspberry Pi 3 sirve como vara de medir eficiencia:

• implementa el mismo contract con renderer Qt Quick/QML.
• Memory budgets + frame budgets se fijan por hardware characterization (P0), no por presupuesto global.
• Forbidden degradation list (arriba) NO se elude con "embedido = UI lista".

D6.4 — Co-firma F-UI + Pi 3 rendererCopiar enlace

El contract se firma por:

• F-UI owner (architectural sign-off: tokens, motion, journeys).
• Pi 3 renderer owner (QML feasibility sign-off: lo que QML puede expresar honestamente).

Discrepancias se resuelven en AskUserQuestion con previews cross-renderer.

D6.5 — Parity gates G-PI3-* (cinco nuevos)Copiar enlace

InvariantesCopiar enlace

• Parity = misma semántica de producto y continuidad perceptual, no pixels idénticos.
• Pi 3 NO se "degrada" eliminando journeys, motion o continuity.
• Renderer-specific tolerance se documenta explícitamente (no se asume).
• Web NO impone arquitectura a Pi 3 (sin "shader port").
• Asset contract es propiedad del Experience Contract, NO de F-UI individual.

Razones + mitigacionesCopiar enlace

Acceptance criteriaCopiar enlace

• AC-D6.1: docs/design/experience-contract/00-INDEX.md existe con las 14 categorías.
• AC-D6.2: 10 canonical journeys documentados en JSON con state IDs + transition order.
• AC-D6.3: motion graph canónico inicial (LibraryCard → ... → LibraryCard) implementado en Web Y en Pi 3 QML.
• AC-D6.4: G-PI3-SEM/MOTION/VIS/PERF/RES definidos como tests (no documentados como intención).
• AC-D6.5: Pi 3 NO pasa ningún gate eliminando journeys (G-PI3-SEM raw = 100% pass con trace semantics equivalentes).
• AC-D6.6: motion tokens / typography / spacing/radii/elevation compartidos Web + Pi 3 (shared source-of-truth).
• AC-D6.7: cada allowed variation documentado (font rasterization differences, blur implementation, asset derivative choisi, etc.).
• AC-D6.8: cada forbidden degradation INCORPORADO en G-PI3-VIS test como negative control.

ReferenciasCopiar enlace

• Paquete canónico: docs/design/styx-platform-player-executable-2026-07-15/adr-candidates/ADR-CANDIDATE-experience-contract-pi3-reference.md
• 00 thesis: docs/design/styx-platform-player-executable-2026-07-15/00-CANONICAL-DECISIONS-AND-SUPERSESSION.md §6 ("se difiere" Pi 3 chronology)
• Gates canónicos: docs/design/styx-platform-player-executable-2026-07-15/execution/02-WEB-PI3-PARITY-GATES.md
• Input pre-existente: docs/design/ui-architecture-proposal.md (F-UI locked 2026-07-06), docs/design/ux-direction-v0.md (UX v0 APROBADA 2026-07-12), docs/handoffs/next-prompt-f-ui-fable-focus.md
• Memory waxin: f-ui-ux-direction-v0.md, f-ui-deferred-to-prototype.md, f-ui-vendor-components.md, f-ui-facelift-dock-library.md, f-ui-session-14c-ship.md
• r25 (federated media runtime §0), r28 §3 (anti-speculative), r23 (CMF codec-agnostic), r22 §7 (runtime family vision)
• r53 (Web Player/Engine first-party), r54 (Presentation contracts renderer-agnostic), r55 (execution profiles W1/W2)
• r57 (Platform Adapter backend policy, r57 NO posee experiencia), r59 (Pi 3 vs StyxOS split)