diff --git a/README.md b/README.md index 9a319a7..60fb8fc 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,50 @@ # Musify -Music streaming platform: upload your own tracks, process them asynchronously -(audio transcoded to `.m4a`, thumbnails generated) and stream them without the -bytes ever going through the API. +A music streaming app. Upload your own tracks, organize them into playlists +and albums, and stream them back with a web player built around your +listening habits: auto-generated mixes, a home feed, search, likes, and an +Explore page for finding something new. + +## What it does + +- **Upload and organize your own music**: tracks, albums, cover art, artist credits. +- **Playlists**, likes, and a "recently played" history. +- **Mixes**, playlists generated automatically from what you actually listen to. +- **Explore**, genre browsing and search across tracks, albums, playlists and people. +- **Real streaming**, not just file downloads: seek, queue, shuffle, repeat. +- **Accounts via OIDC login**, with an optional anonymous listening mode. +- Light and dark themes, and a layout that works on both desktop and mobile. + +## How it's built + +**Backend**: .NET 10, split into a REST API, a background worker, and a +dedicated streaming gateway. +- Clean architecture (Domain / Application / Infrastructure) with CQRS (Mediator) and `ErrorOr` results. +- PostgreSQL via EF Core for metadata. RabbitMQ and MassTransit handle async processing (audio transcoding, thumbnails) with saga-based rollback. +- SeaweedFS (S3-compatible) for file storage. Uploads and downloads go straight between the client and storage, never through the API. +- ffmpeg for audio transcoding, ImageSharp for thumbnails. +- A YARP reverse proxy that streams the audio and checks a signed, short-lived ticket on every request. +- Zitadel for login (OIDC/OAuth2). + +**Web client**: SvelteKit 2 on Svelte 5 (runes), TypeScript, Tailwind 4. +The session lives on the server, so the backend access token never reaches the browser. + +**Infrastructure**: the whole stack runs from Docker Compose (dev and +production overlays), with Postgres, RabbitMQ, SeaweedFS, Zitadel and Jaeger +alongside the apps. + +## Project layout ``` -backend/ .NET 10 — Domain / Application / Infrastructure / Api / Worker / StreamingGateway / Tests -web-player/ SvelteKit 2 + Svelte 5 + Tailwind 4 web client -deploy/ Docker Compose stacks — self-contained, no wrapper scripts -docs/ What each piece does and why (in Spanish) +backend/ .NET solution: Api, Worker, StreamingGateway, and the shared Domain/Application/Infrastructure +web-player/ the SvelteKit web client +deploy/ Docker Compose stacks for dev and production +docs/ architecture notes, one file per area ``` -```sh -dotnet test backend/Musify.slnx # backend/Tests/ — Docker running (Testcontainers: Postgres, SeaweedFS) -``` +## Digging deeper -## Run it - -Development (Docker Desktop): - -```sh -docker compose -f deploy/compose.yml -f deploy/compose.dev.yml up -d -``` - -Infrastructure plus stream-ticket keys, database migrations and Zitadel OIDC -provisioning — all as one-shot jobs baked into the compose file. Apps run from -the IDE by default; add `--profile apps up -d --build` as a second command to -run them in Docker instead. - -Production, on a server with a domain: - -```sh -cp deploy/.env.prod.example deploy/.env.prod # fill in the domain and secrets -docker compose --env-file deploy/.env.prod -f deploy/compose.yml -f deploy/compose.prod.yml up -d -docker compose --env-file deploy/.env.prod -f deploy/compose.yml -f deploy/compose.prod.yml --profile apps up -d --build -``` - -Idempotent — run the same commands again to deploy an update. See -[deploy/README.md](deploy/README.md) for the details, the port map and the -production prerequisites. - -## Components - -| Service | Port (dev) | Role | -|---|---|---| -| `Musify.Api` | 5111 | REST API, issues presigned upload URLs and stream tickets | -| `Musify.StreamingGateway` | 8081 | YARP proxy that validates the stream ticket and serves the audio | -| `Musify.Worker` | — | MassTransit consumers: transcoding, thumbnails | -| `web-player` | 5173 / 3000 | Web client (SvelteKit, server-side OIDC session) | -| Zitadel | 8080 | Identity (OIDC/OAuth2) | -| PostgreSQL / RabbitMQ / SeaweedFS / Jaeger | 59000 / 5672 / 8333 / 16686 | Metadata, messaging, object storage, traces | - -More in [docs/](docs/README.md): [architecture](docs/architecture.md), -[authentication](docs/authentication.md), [storage](docs/storage.md), -[streaming](docs/streaming.md), [media processing](docs/media-processing.md), -[development](docs/development.md). +[docs/](docs/README.md) covers how each piece works and why: architecture, +authentication, storage, streaming, media processing, and the local dev +setup. [deploy/README.md](deploy/README.md) has the full instructions for +running the stack, in development or on a production server. diff --git a/docs/README.md b/docs/README.md index 316215f..80547bf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,47 +1,51 @@ -# Musify — Documentación +# Musify documentation -Musify es un backend de streaming de música: subir pistas, procesarlas (transcodificar el audio a `.m4a` y generar miniaturas), organizarlas en playlists y reproducirlas en streaming sin que los bytes pasen por la API. +Musify is a music streaming backend: upload tracks, process them (transcode +the audio to `.m4a`, generate thumbnails), organize them into playlists, and +stream them without the bytes ever passing through the API. -Esta carpeta explica **qué hace cada pieza, su propósito y por qué está diseñada así**. +This folder explains **what each piece does, its purpose, and why it's built +this way**. -## Índice +## Index -- [architecture.md](architecture.md) — Visión global: componentes, cómo encajan y los flujos principales. -- [projects.md](projects.md) — Qué es y para qué sirve cada proyecto/solución. -- [authentication.md](authentication.md) — Zitadel (OIDC), validación de JWT, provisioning/sync de usuarios. -- [storage.md](storage.md) — SeaweedFS (S3), estructura de claves, URLs prefirmadas, qué es público y qué privado. -- [streaming.md](streaming.md) — Streaming del audio (`.m4a` por HTTP range) con stream-ticket (RS256) y el reverse proxy (StreamingGateway). -- [media-processing.md](media-processing.md) — El worker y los workflows de MassTransit (transcode de audio, miniaturas). -- [development.md](development.md) — Cómo levantar todo en local: contenedores, puertos y comandos. -- [../deploy/README.md](../deploy/README.md) — El deploy en detalle: compose, scripts y producción. +- [architecture.md](architecture.md): overview, components, how they fit together, and the main flows. +- [projects.md](projects.md): what each project/solution is and what it's for. +- [authentication.md](authentication.md): Zitadel (OIDC), JWT validation, user provisioning/sync. +- [storage.md](storage.md): SeaweedFS (S3), key layout, presigned URLs, what's public vs. private. +- [streaming.md](streaming.md): audio streaming (`.m4a` over HTTP range) with stream tickets (RS256) and the reverse proxy (StreamingGateway). +- [media-processing.md](media-processing.md): the worker and its MassTransit workflows (audio transcoding, thumbnails). +- [development.md](development.md): running everything locally, containers, ports, commands. +- [../deploy/README.md](../deploy/README.md): deployment in detail, compose, scripts, and production. -## Mapa de componentes (alto nivel) +## Component map (high level) ``` ┌─────────────────────────────────────────────┐ - Cliente ───► │ Musify.Api (:5111) API REST + emite tickets │ + Client ───► │ Musify.Api (:5111) REST API + issues tickets│ └─────────────────────────────────────────────┘ - │ EF Core │ presigned (subidas) │ MassTransit (eventos) + │ EF Core │ presigned (uploads) │ MassTransit (events) ▼ ▼ ▼ - PostgreSQL SeaweedFS S3 (:8333) RabbitMQ ──► Worker (procesa) - (metadatos) (objetos) audio→.m4a, imágenes + PostgreSQL SeaweedFS S3 (:8333) RabbitMQ ──► Worker (processes) + (metadata) (objects) audio→.m4a, images ▲ - Cliente ───► StreamingGateway (:8081) ┘ sirve audio .m4a (valida ticket, proxy al filer) + Client ───► StreamingGateway (:8081) ┘ serves .m4a audio (validates ticket, proxies to the filer) - Login: Cliente ◄──► Zitadel (:8080, OIDC) → Musify.Api valida el JWT + Login: Client ◄──► Zitadel (:8080, OIDC) → Musify.Api validates the JWT ``` ## Stack - **.NET 10**, C#. Minimal APIs (`Musify.Api`), Worker Service (`Musify.Worker`), ASP.NET + YARP (`Musify.StreamingGateway`). -- **CQRS** con [Mediator] (source-generator) y resultados con **ErrorOr**. -- **EF Core 10** + **PostgreSQL** (metadatos). -- **MassTransit 8** + **RabbitMQ** (procesado asíncrono con routing slips/sagas). -- **SeaweedFS** (almacenamiento de objetos compatible con S3, vía AWSSDK.S3). -- **ffmpeg** (transcode de audio a AAC/`.m4a`), **SixLabors.ImageSharp** (miniaturas). -- **Zitadel** (OIDC/OAuth2) para identidad. +- **CQRS** with [Mediator] (source generator) and results via **ErrorOr**. +- **EF Core 10** + **PostgreSQL** (metadata). +- **MassTransit 8** + **RabbitMQ** (async processing with routing slips/sagas). +- **SeaweedFS** (S3-compatible object storage, via AWSSDK.S3). +- **ffmpeg** (audio transcoding to AAC/`.m4a`), **SixLabors.ImageSharp** (thumbnails). +- **Zitadel** (OIDC/OAuth2) for identity. -## Estructura del repositorio +## Repository layout -Un solo repo: `backend/` (los seis proyectos .NET), `web-player/` (cliente web -SvelteKit), `deploy/` (stacks de Docker Compose y scripts) y `docs/`. +A single repo: `backend/` (the six .NET projects), `web-player/` (the +SvelteKit web client), `deploy/` (Docker Compose stacks and scripts), and +`docs/`. diff --git a/docs/architecture.md b/docs/architecture.md index bff0579..5f04818 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,55 +1,55 @@ -# Arquitectura +# Architecture -## Principios +## Principles -- **Clean architecture / capas** en `backend/`: el dominio y la aplicación no dependen de infraestructura; la infraestructura implementa las interfaces (`Application/Contracts`). -- **CQRS**: cada operación es un `Command` o `Query` con su handler (Mediator). Los handlers devuelven `Ardalis.Result` (Ok/NotFound/Unauthorized/Conflict/Invalid…), que la API traduce a códigos HTTP. -- **Los bytes pesados no pasan por la API**: subidas con URLs prefirmadas (cliente → S3) y reproducción vía un reverse proxy dedicado (gateway → S3). La API solo mueve metadatos y emite permisos. -- **Procesado asíncrono**: crear una pista no transcodifica en caliente; publica un evento y un worker hace el trabajo pesado con compensación (sagas/routing slips de MassTransit). +- **Clean architecture / layers** in `backend/`: the domain and application layers don't depend on infrastructure; infrastructure implements their interfaces (`Application/Contracts`). +- **CQRS**: every operation is a `Command` or `Query` with its own handler (Mediator). Handlers return `Ardalis.Result` (Ok/NotFound/Unauthorized/Conflict/Invalid…), which the API translates into HTTP status codes. +- **Heavy bytes never touch the API**: uploads use presigned URLs (client → S3) and playback goes through a dedicated reverse proxy (gateway → S3). The API only moves metadata and issues permissions. +- **Async processing**: creating a track doesn't transcode it on the spot. It publishes an event, and a worker does the heavy lifting, with compensation (MassTransit sagas/routing slips). -## Componentes +## Components -| Componente | Responsabilidad | Por qué separado | +| Component | Responsibility | Why it's separate | |---|---|---| -| **Musify.Api** | API REST (usuarios, pistas, playlists), autoriza, emite presigned URLs y stream-tickets | Punto de entrada fino; no procesa medios ni sirve bytes | -| **Domain/Application/Infrastructure** | Dominio + casos de uso + infraestructura compartida (EF, S3, MassTransit, ffmpeg) | Lógica reutilizada por la API y el Worker | -| **StreamingGateway** | Reverse proxy (YARP) que valida el ticket y sirve el audio (`.m4a`) desde SeaweedFS | Escala con el tráfico de bytes, independiente de la API; SeaweedFS queda privado detrás | -| **Worker** | Consume eventos de MassTransit: transcodifica audio a `.m4a` y genera miniaturas | Trabajo CPU/IO intensivo fuera del request HTTP | -| **PostgreSQL** | Metadatos (usuarios, pistas, playlists, upload intents) | — | -| **RabbitMQ** | Cola de eventos + outbox transaccional | Desacopla creación de procesado | -| **SeaweedFS** | Almacenamiento de objetos (S3 + filer) | Guarda originales y derivados (audio `.m4a`, miniaturas) | -| **Zitadel** | Identidad (OIDC/OAuth2) | Login y emisión de JWT | +| **Musify.Api** | REST API (users, tracks, playlists), authorizes requests, issues presigned URLs and stream tickets | A thin entry point, it doesn't process media or serve bytes | +| **Domain/Application/Infrastructure** | Domain + use cases + shared infrastructure (EF, S3, MassTransit, ffmpeg) | Logic shared between the API and the Worker | +| **StreamingGateway** | Reverse proxy (YARP) that validates the ticket and serves the audio (`.m4a`) from SeaweedFS | Scales with byte traffic independently of the API, and keeps SeaweedFS private behind it | +| **Worker** | Consumes MassTransit events: transcodes audio to `.m4a` and generates thumbnails | Keeps CPU/IO-heavy work off the HTTP request path | +| **PostgreSQL** | Metadata (users, tracks, playlists, upload intents) | n/a | +| **RabbitMQ** | Event queue + transactional outbox | Decouples creation from processing | +| **SeaweedFS** | Object storage (S3 + filer) | Stores originals and derivatives (`.m4a` audio, thumbnails) | +| **Zitadel** | Identity (OIDC/OAuth2) | Login and JWT issuance | -## Flujos principales +## Main flows -### 1. Subida de una pista -1. Cliente pide `POST /tracks/upload-urls` → la API crea **UploadIntents** (reservas) y devuelve **URLs prefirmadas PUT** (imagen + audio). -2. Cliente sube los ficheros **directo a SeaweedFS** con esas URLs (no pasan por la API). -3. Cliente llama `POST /tracks` con los `intentId`s → la API valida los intents, crea el `Track` (+ `UserHasTrack`) y publica `CreateTrackResourcesEvent`. -4. El **Worker** consume el evento: mueve los originales a su sitio, genera miniaturas y transcodifica el audio a `.m4a`, y actualiza el estado del track. +### 1. Uploading a track +1. The client requests `POST /tracks/upload-urls`. The API creates **UploadIntents** (reservations) and returns **presigned PUT URLs** (image + audio). +2. The client uploads the files **directly to SeaweedFS** using those URLs (never through the API). +3. The client calls `POST /tracks` with the `intentId`s. The API validates the intents, creates the `Track` (+ `UserHasTrack`), and publishes `CreateTrackResourcesEvent`. +4. The **Worker** consumes the event: moves the originals into place, generates thumbnails, transcodes the audio to `.m4a`, and updates the track's status. -Ver detalle en [media-processing.md](media-processing.md) y [storage.md](storage.md). +See [media-processing.md](media-processing.md) and [storage.md](storage.md) for details. -### 2. Reproducción (streaming) -1. Cliente pide `GET /tracks/{id}/stream` (autenticado) → la API autoriza y devuelve `{ manifestUrl, ticket }` (URL al `.m4a` + ticket RS256 acotado a la carpeta de esa pista). -2. El reproductor abre la URL del audio añadiendo `?t=` (o cabecera `X-Stream-Ticket`) y descarga por HTTP range. -3. El **StreamingGateway** valida el ticket y reenvía al filer de SeaweedFS; los bytes van storage → cliente. +### 2. Playback (streaming) +1. The client requests `GET /tracks/{id}/stream` (authenticated). The API authorizes it and returns `{ manifestUrl, ticket }` (a URL to the `.m4a` plus an RS256 ticket scoped to that track's folder). +2. The player opens the audio URL with `?t=` appended (or an `X-Stream-Ticket` header) and downloads it via HTTP range requests. +3. The **StreamingGateway** validates the ticket and forwards the request to the SeaweedFS filer. The bytes flow storage → client. -Ver [streaming.md](streaming.md). +See [streaming.md](streaming.md). -### 3. Autenticación -1. Cliente hace login OIDC contra **Zitadel** y obtiene un access token (JWT). -2. La Musify.Api valida la firma/iss/aud del JWT. -3. En cada token validado, se **sincroniza** el usuario local (crea/actualiza nombre y foto) — provisioning just-in-time. +### 3. Authentication +1. The client logs in via OIDC against **Zitadel** and gets an access token (JWT). +2. Musify.Api validates the JWT's signature, issuer and audience. +3. On every validated token, the local user is **synced** (name and picture created or updated). This is just-in-time provisioning. -Ver [authentication.md](authentication.md). +See [authentication.md](authentication.md). -## Modelo de datos (entidades) +## Data model (entities) -- **User** — `Id` es el `sub` numérico de Zitadel (`long`), más nombre y `ProfilePictureUrl`. -- **Track** — pista: nombres de originales/derivados, `AudioFolderName` (carpeta del `.m4a` transcodificado), estados de procesado (`ProcessingStatus`), `LifeCycleStatus`. -- **PlayList** — lista del usuario (`UserId`). -- **PlayListHasTrack** — pistas dentro de una playlist (con `Position`). -- **UserHasTrack** — propiedad: qué usuario posee qué pista. -- **UploadIntent** — reserva de subida (clave, bucket, tamaño esperado, estado, expiración) para validar y aplicar cuota. -- **Upload** — registro de objetos subidos/transferidos al storage. +- **User**: `Id` is Zitadel's numeric `sub` (`long`), plus a name and `ProfilePictureUrl`. +- **Track**: original/derivative file names, `AudioFolderName` (the transcoded `.m4a`'s folder), processing state (`ProcessingStatus`), `LifeCycleStatus`. +- **PlayList**: a user's playlist (`UserId`). +- **PlayListHasTrack**: the tracks inside a playlist (with `Position`). +- **UserHasTrack**: ownership, which user owns which track. +- **UploadIntent**: an upload reservation (key, bucket, expected size, status, expiration) used for validation and quota. +- **Upload**: a record of objects uploaded or transferred to storage. diff --git a/docs/authentication.md b/docs/authentication.md index 372d043..c0376b8 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -1,40 +1,40 @@ -# Autenticación e identidad +# Authentication and identity -## Proveedor: Zitadel (OIDC/OAuth2) +## Provider: Zitadel (OIDC/OAuth2) -El login y la emisión de tokens los hace **Zitadel** (no la API). La API es un **resource server**: solo **valida** el access token (JWT) que le llega en `Authorization: Bearer`. +Login and token issuance are handled by **Zitadel**, not the API. The API is a **resource server**: it only **validates** the access token (JWT) it receives in `Authorization: Bearer`. -- Config en la sección `Authentication` (`AuthenticationConfiguration`): metadata address, issuer, audience, client id, endpoints de authorize/token, scopes. -- `JwtBearerOptionsSetup` configura la validación (issuer, audience, claves vía metadata OIDC). -- En dev, `RequireHttpsMetadata = false`. +- Configured under the `Authentication` section (`AuthenticationConfiguration`): metadata address, issuer, audience, client id, authorize/token endpoints, scopes. +- `JwtBearerOptionsSetup` sets up validation (issuer, audience, keys via OIDC metadata). +- In dev, `RequireHttpsMetadata = false`. -### Requisito clave en la app de Zitadel -- **Auth Token Type = JWT** (si no, Zitadel emite un token **opaco** sin puntos y `JwtBearer` no lo puede validar → 401 en todo lo protegido). -- **User Info inside Token** activado si quieres que el access token traiga claims de perfil (`name`, `email`, `picture`). Por defecto el access token es mínimo (`sub`, `aud`, `iss`, `exp`…), sin perfil. +### Key requirement in the Zitadel app +- **Auth Token Type = JWT** (otherwise Zitadel issues an **opaque** token with no dots, which `JwtBearer` can't validate → 401 on everything protected). +- **User Info inside Token** enabled if you want the access token to carry profile claims (`name`, `email`, `picture`). By default the access token is minimal (`sub`, `aud`, `iss`, `exp`…), with no profile info. -## El `sub` es numérico → `User.Id` es `long` +## `sub` is numeric → `User.Id` is `long` -El `sub` de Zitadel es un entero de 64 bits en string (p. ej. `371953080444977155`), **no un GUID**. Por eso: -- `User.Id` y todas las FKs de usuario (`PlayList.UserId`, `UserHasTrack.UserId`, `UploadIntent.UserId`) son **`long`**. -- `User.Id` lleva `[DatabaseGenerated(None)]` para que EF **no** lo autogenere: se asigna el `sub`. -- `CurrentUser.Id` es `long?` (parsea con `long.TryParse`); `RequiredId` lanza si falta. +Zitadel's `sub` is a 64-bit integer encoded as a string (e.g. `371953080444977155`), **not a GUID**. Because of that: +- `User.Id` and every user-related FK (`PlayList.UserId`, `UserHasTrack.UserId`, `UploadIntent.UserId`) are **`long`**. +- `User.Id` has `[DatabaseGenerated(None)]` so EF doesn't autogenerate it: it's assigned from the `sub`. +- `CurrentUser.Id` is `long?` (parsed with `long.TryParse`); `RequiredId` throws if it's missing. -**Por qué**: el código antiguo hacía `Guid.Parse(sub)` y reventaba (FormatException) → 401 en cada endpoint protegido. Se decidió guardar el `sub` tal cual como número. +**Why**: the original code did `Guid.Parse(sub)`, which threw a `FormatException` → 401 on every protected endpoint. The fix was to store the `sub` as-is, as a number. -## Provisioning / sincronización de usuarios +## User provisioning / sync -En cada token validado, `JwtBearerEventsHandler.TokenValidated`: -1. Lee `sub` (id), `name`/`preferred_username`/`email` (con fallback) y el claim OIDC `picture`. -2. Envía un `SyncUserCommand`. +On every validated token, `JwtBearerEventsHandler.TokenValidated`: +1. Reads `sub` (id), `name`/`preferred_username`/`email` (with fallback), and the OIDC `picture` claim. +2. Sends a `SyncUserCommand`. -`SyncUserCommandHandler` hace un **upsert idempotente**: -- Si el usuario no existe → lo crea. -- Si existe → actualiza nombre/apellidos/`ProfilePictureUrl` **solo si cambiaron** (escribe en DB únicamente cuando hay cambios). +`SyncUserCommandHandler` does an **idempotent upsert**: +- If the user doesn't exist yet → creates it. +- If it exists → updates the name and `ProfilePictureUrl` **only if they changed** (a DB write only happens when something is different). -**Por qué upsert con "escribe solo si cambió"**: `TokenValidated` se ejecuta en **cada request**; sin ese guardado condicional estaríamos escribiendo en cada petición. Y debe ser resiliente: si el provisioning falla, se loguea pero **no** tumba la autenticación. +**Why "write only if changed"**: `TokenValidated` runs on **every request**; without that guard we'd be writing to the DB on every single call. It also needs to be resilient: if provisioning fails, it's logged but authentication **doesn't** fail because of it. -> Nota: `CreateUserCommand` (endpoint manual `POST /users`) sigue siendo create-only; el sync del login usa `SyncUserCommand`. +> Note: `CreateUserCommand` (the manual `POST /users` endpoint) is still create-only; login sync uses `SyncUserCommand`. -## Foto de perfil +## Profile picture -`User.ProfilePictureUrl` se rellena desde el claim `picture` del token. Si Zitadel no mete la info de perfil en el access token (ver arriba), llega `null` — el código es correcto, pero no hay nada que sincronizar hasta activar esa opción. +`User.ProfilePictureUrl` is filled from the token's `picture` claim. If Zitadel doesn't include profile info in the access token (see above), it arrives as `null`. The code is correct, there's just nothing to sync until that option is turned on. diff --git a/docs/development.md b/docs/development.md index 1acbc55..3a15444 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,21 +1,21 @@ -# Entorno de desarrollo +# Development environment -Cómo levantar todo en local y probarlo. El detalle completo del deploy (y el de -producción) está en [deploy/README.md](../deploy/README.md). +How to run everything locally and test it. The full deployment details (dev +and prod) live in [deploy/README.md](../deploy/README.md). -## Arranque +## Startup ```sh docker compose -f deploy/compose.yml -f deploy/compose.dev.yml up -d ``` -Ese único comando levanta la infraestructura y corre los jobs *one-shot* de -bootstrap: genera las claves RS256 de stream-ticket en `deploy/keys/`, aplica -las migraciones EF Core y provisiona Zitadel (proyecto + apps OIDC), dejando -los client ids en `deploy/.env`. Detalle completo, incluido cómo arrancar las -apps en Docker con `--profile apps`, en [deploy/README.md](../deploy/README.md). +That one command brings up the infrastructure and runs the one-shot bootstrap +jobs: generates the RS256 stream-ticket keys in `deploy/keys/`, applies the +EF Core migrations, and provisions Zitadel (project + OIDC apps), writing the +client ids into `deploy/.env`. Full details, including how to run the apps in +Docker with `--profile apps`, are in [deploy/README.md](../deploy/README.md). -## Aplicaciones +## Applications ```powershell dotnet run --project backend/Hosts/Musify.Api # :5111 @@ -24,45 +24,46 @@ dotnet run --project backend/Hosts/Musify.Worker # background npm --prefix web-player run dev # :5173 ``` -## Mapa de puertos +## Port map -| Servicio | Puerto | +| Service | Port | |---|---| | Musify.Api | 5111 (`/scalar/v1`, `/openapi/v1.json`) | | Musify.StreamingGateway | 8081 (`/health`, `/media/...`) | -| web-player | 5173 (`npm run dev`) o 3000 (contenedor) | +| web-player | 5173 (`npm run dev`) or 3000 (container) | | SeaweedFS S3 / filer / master | 8333 / 8888 / 9333 | | Zitadel | 8080 | -| PostgreSQL | 59000 (→ 5432 en el contenedor) | +| PostgreSQL | 59000 (→ 5432 in the container) | | RabbitMQ AMQP / management | 5672 / 15672 | | Jaeger UI / OTLP | 16686 / 4317 | | pgAdmin (`-Tools`) | 5050 | -DB: `musify_db`, usuario `postgres`/`postgres`. Bucket S3: `webapi-storage` -(credenciales `admin_access_key`/`admin_secret_key`). Todos los valores salen de +DB: `musify_db`, user `postgres`/`postgres`. S3 bucket: `webapi-storage` +(credentials `admin_access_key`/`admin_secret_key`). All of these come from `deploy/.env`. -## Migraciones +## Migrations -El servicio `migrate` de `deploy/compose.yml` las aplica en cada `docker -compose up -d` (no-op si el esquema ya está al día). A mano, tras cambios de -esquema, contra la base local: +The `migrate` service in `deploy/compose.yml` applies them on every `docker +compose up -d` (a no-op if the schema is already current). To run them by +hand after a schema change, against the local database: ```powershell dotnet ef database update --project backend/Core/Musify.Infrastructure --startup-project backend/Core/Musify.Infrastructure --context Database ``` -`Musify.Infrastructure` es a la vez el proyecto de migraciones y el de arranque: -tiene el `IDesignTimeDbContextFactory` y el paquete `EFCore.Design`. La cadena -de conexión se lee de sus user-secrets, o de la variable de entorno -`Database__ConnectionString` si no hay user-secrets (así es como la usa el -contenedor `migrate`, ver `backend/Musify.Migrator.Dockerfile`). +`Musify.Infrastructure` is both the migrations project and the startup +project: it has the `IDesignTimeDbContextFactory` and the `EFCore.Design` +package. The connection string is read from its user-secrets, or from the +`Database__ConnectionString` environment variable if there are no +user-secrets (which is how the `migrate` container uses it, see +`backend/Musify.Migrator.Dockerfile`). -## Stream-tickets (claves RS256) +## Stream tickets (RS256 keys) -La API firma los stream-tickets con la clave privada y el gateway los valida con -la pública. El servicio `keys-init` de `deploy/compose.yml` las genera en -`deploy/keys/` si no existen; a mano: +The API signs stream tickets with the private key, and the gateway validates +them with the public one. The `keys-init` service in `deploy/compose.yml` +generates them in `deploy/keys/` if they don't exist yet; to do it by hand: ```powershell openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out deploy/keys/stream_private.pem @@ -78,74 +79,74 @@ openssl rsa -in deploy/keys/stream_private.pem -pubout -out deploy/keys/stream_p dotnet test backend/Musify.slnx ``` -`backend/Tests/` (carpeta `/Tests/` en el `.slnx`) tiene cinco proyectos xUnit: +`backend/Tests/` (the `/Tests/` folder in the `.slnx`) has five xUnit projects: -| Proyecto | Cubre | Docker | +| Project | Covers | Docker | |---|---|---| -| `Musify.Domain.Tests` | Lógica de los value objects (`TrackAudio`/`TrackPictures`: `IsProcessed`, `IsFailed`, `IsInProgress`). Las entidades son en su mayoría anémicas — sin comportamiento propio, nada más que testear ahí. | No | -| `Musify.Application.Tests` | Los ~45 handlers y servicios de `Musify.Application` (Albums, Tracks, PlayLists, Users, Mixes). | No | -| `Musify.Infrastructure.Tests` | `Database`/migraciones, `StorageService`, `StreamTicketService`, `AuditableEntityInterceptor`, `PictureService`, `SingleFlightCache`, `PlayListPresetSeeder`. | **Sí** | -| `Musify.Api.Tests` | Endpoints HTTP reales (routing, auth, `ValidationFilter`, mapeo `ErrorOr`→HTTP) vía `WebApplicationFactory`, más `ErrorOrHttpExtensions`/`CurrentUser`/validators FluentValidation en aislado. | **Sí** | -| `Musify.StreamingGateway.Tests` | `TicketValidator` (RS256) y `TicketValidationMiddleware` (traversal, límites de prefijo, extracción de ticket). | No | +| `Musify.Domain.Tests` | Value object logic (`TrackAudio`/`TrackPictures`: `IsProcessed`, `IsFailed`, `IsInProgress`). Entities are mostly anemic, with no behavior of their own beyond that. | No | +| `Musify.Application.Tests` | The ~45 handlers and services in `Musify.Application` (Albums, Tracks, PlayLists, Users, Mixes). | No | +| `Musify.Infrastructure.Tests` | `Database`/migrations, `StorageService`, `StreamTicketService`, `AuditableEntityInterceptor`, `PictureService`, `SingleFlightCache`, `PlayListPresetSeeder`. | **Yes** | +| `Musify.Api.Tests` | Real HTTP endpoints (routing, auth, `ValidationFilter`, `ErrorOr`→HTTP mapping) via `WebApplicationFactory`, plus `ErrorOrHttpExtensions`/`CurrentUser`/FluentValidation validators in isolation. | **Yes** | +| `Musify.StreamingGateway.Tests` | `TicketValidator` (RS256) and `TicketValidationMiddleware` (traversal, prefix limits, ticket extraction). | No | -`Musify.Worker` no tiene proyecto de test: su `Program.cs` es puro *wiring* de -DI/host (Hangfire, MassTransit, jobs) — la lógica real que ejecuta vive en -`Musify.Infrastructure`, ya cubierta ahí. +`Musify.Worker` has no test project: its `Program.cs` is pure DI/host wiring +(Hangfire, MassTransit, jobs). The actual logic it runs lives in +`Musify.Infrastructure`, already covered there. -### Application.Tests: por qué SQLite en memoria y no mocks +### Application.Tests: why in-memory SQLite instead of mocks -`IDatabase` expone `DbSet` directamente, así que los handlers arman LINQ -real (`Where`, `Include`, `Select`...) contra él — no se puede mockear eso con -NSubstitute, no hay `IQueryable` detrás de un mock. En su lugar, -`TestSupport/TestDatabase.cs` es un `DbContext` real sobre SQLite en memoria -(una conexión `:memory:` nueva por test, con foreign keys reales — a diferencia -del proveedor InMemory de EF Core, SQLite además soporta transacciones, que dos -handlers usan). `TestSupport/TestEntities.cs` y `TestConfigurations.cs` -construyen entidades y configuración con valores por defecto sensatos. -`IStorageService`, `IEventBus`, etc. sí se mockean con NSubstitute, al ser -interfaces normales. +`IDatabase` exposes `DbSet` directly, so handlers build real LINQ +(`Where`, `Include`, `Select`...) against it. That can't be mocked with +NSubstitute, since there's no `IQueryable` behind a mock. Instead, +`TestSupport/TestDatabase.cs` is a real `DbContext` on top of in-memory +SQLite (a fresh `:memory:` connection per test, with real foreign keys, +unlike EF Core's InMemory provider, SQLite also supports transactions, +which two handlers rely on). `TestSupport/TestEntities.cs` and +`TestConfigurations.cs` build entities and configuration with sensible +defaults. `IStorageService`, `IEventBus`, etc. are mocked with NSubstitute, +since those are plain interfaces. -### Infrastructure.Tests y Api.Tests: Testcontainers +### Infrastructure.Tests and Api.Tests: Testcontainers -Estos dos sí necesitan Docker corriendo. Levantan un Postgres real -(`Testcontainers.PostgreSql`) y, en `Infrastructure.Tests`, también un -SeaweedFS real (mismo `chrislusf/seaweedfs:latest` e imagen/comando que -`deploy/compose.yml`, no MinIO) — así `StorageService` se prueba contra el -mismo backend S3-compatible que usa producción, no contra AWS S3. Los -contenedores se levantan una vez por corrida (`ICollectionFixture`), con -migraciones EF Core reales aplicadas contra el Postgres efímero. +These two need Docker running. They spin up a real Postgres +(`Testcontainers.PostgreSql`) and, in `Infrastructure.Tests`, a real +SeaweedFS too (the same `chrislusf/seaweedfs:latest` image/command as +`deploy/compose.yml`, not MinIO), so `StorageService` is tested against the +same S3-compatible backend production uses, not against AWS S3. Containers +are started once per run (`ICollectionFixture`), with real EF Core +migrations applied against the ephemeral Postgres. -`Api.Tests` usa `WebApplicationFactory` contra ese mismo Postgres — -routing, auth y validación reales — pero sustituye por fakes los servicios que -hablan por red (`IStorageService`, `IEventBus`, `IStreamTicketService`) y el -esquema de autenticación JWT real por un handler -de prueba (ver `TestSupport/FakeAuthenticationHandler.cs`) que autentica según -un header, sin necesitar un Zitadel real. +`Api.Tests` uses `WebApplicationFactory` against that same +Postgres, with real routing, auth, and validation, but replaces the services +that talk over the network with fakes (`IStorageService`, `IEventBus`, +`IStreamTicketService`), and swaps the real JWT auth scheme for a test +handler (see `TestSupport/FakeAuthenticationHandler.cs`) that authenticates +based on a header, with no real Zitadel needed. -Escribir estos tests contra el backend real encontró y arregló dos bugs reales -(no simulados): `StorageService.RemoveFolderAsync` reventaba con -`NullReferenceException` contra SeaweedFS (su respuesta `DeleteObjects` omite -la lista `` cuando no hay errores, a diferencia de AWS S3), y -`AuditableEntityInterceptor` nunca actualizaba `UpdatedAt` en una actualización -normal (carga → modifica → guarda) porque corría antes de que EF detectara los -cambios pendientes. +Writing these tests against the real backend found and fixed two actual +bugs (not staged ones): `StorageService.RemoveFolderAsync` threw a +`NullReferenceException` against SeaweedFS (its `DeleteObjects` response +omits the `` list when there are no errors, unlike AWS S3), and +`AuditableEntityInterceptor` never updated `UpdatedAt` on a normal update +(load → modify → save) because it ran before EF had detected the pending +changes. ## Config (AppSettings) -Convención: `AppSettings.json` es la plantilla con valores vacíos o neutros; -`AppSettings.Development.json` tiene los valores reales de dev; en Docker todo -se sobreescribe con variables de entorno (`Seccion__Clave`) desde -`deploy/compose.yml`. Para correr `Musify.Api` desde el IDE, los valores de -`Authentication` van en user-secrets (no en el repo) — cópialos de -`deploy/.env` una vez que `zitadel-init` los haya generado (ver +Convention: `AppSettings.json` is the template, with empty or neutral +values; `AppSettings.Development.json` has the real dev values; in Docker +everything is overridden with environment variables (`Section__Key`) from +`deploy/compose.yml`. To run `Musify.Api` from the IDE, the `Authentication` +values go into user-secrets (not the repo). Copy them from `deploy/.env` +once `zitadel-init` has generated them (see [deploy/README.md](../deploy/README.md)). -Secciones clave: `Authentication` (Zitadel), `Database`, `MassTransit`, +Key sections: `Authentication` (Zitadel), `Database`, `MassTransit`, `InfrastructureStorage` (S3), `ApplicationStorage` (bucket), `Track`, `PlayList`, `UploadIntent`, `AudioTranscoder`, `Workers`, `StreamGateway` / `StreamTicket`. -## Requisitos del host +## Host requirements -- .NET 10 SDK y Node 22. -- **ffmpeg** en el PATH (transcode de audio del Worker). +- .NET 10 SDK and Node 22. +- **ffmpeg** on the PATH (for the Worker's audio transcoding). - Docker Desktop. diff --git a/docs/media-processing.md b/docs/media-processing.md index 717ba11..8de9e30 100644 --- a/docs/media-processing.md +++ b/docs/media-processing.md @@ -1,46 +1,46 @@ -# Procesado de medios (Worker + MassTransit) +# Media processing (Worker + MassTransit) -El procesado pesado (transcode de audio, miniaturas, transferencias en el bucket) ocurre **fuera del request HTTP**, en el **Worker**, orquestado con **MassTransit** sobre RabbitMQ. +Heavy processing (audio transcoding, thumbnails, bucket transfers) happens **outside the HTTP request**, in the **Worker**, orchestrated with **MassTransit** on top of RabbitMQ. -## Por qué asíncrono y con routing slips +## Why async, and why routing slips -- Transcodificar audio y redimensionar imágenes es CPU/IO intensivo: no debe bloquear una llamada a la API. -- Es un proceso **multi-paso con efectos secundarios** (descargar de S3 → transcodificar → subir resultados → actualizar DB). Si un paso falla, hay que **deshacer** los anteriores. Para eso se usan **routing slips** (patrón Saga de MassTransit): cada paso es una *activity* con su **compensación**. -- **Outbox transaccional** (EF + MassTransit): el evento se publica de forma consistente con el cambio en la DB (no se pierde ni se duplica). +- Transcoding audio and resizing images is CPU/IO-intensive: it shouldn't block an API call. +- It's a **multi-step process with side effects** (download from S3 → transcode → upload results → update the DB). If a step fails, the previous ones need to be **undone**. That's what **routing slips** are for (MassTransit's Saga pattern): each step is an *activity* with its own **compensation**. +- **Transactional outbox** (EF + MassTransit): the event is published consistently with the DB change (never lost, never duplicated). -## Disparo +## Trigger -Al crear/actualizar una pista o playlist, el handler publica un evento (p. ej. `CreateTrackResourcesEvent`). Un **consumer** (`CreateTrackConsumer`, `UpdateTrackPictureConsumer`, …) construye un **routing slip** con la secuencia de activities y lo lanza. +When a track or playlist is created or updated, the handler publishes an event (e.g. `CreateTrackResourcesEvent`). A **consumer** (`CreateTrackConsumer`, `UpdateTrackPictureConsumer`, …) builds a **routing slip** with the sequence of activities and executes it. -## Builders de routing slip +## Routing slip builders -- `CreateTrackRoutingSlipBuilder` — alta de pista (consume intents, mueve ficheros, dispara procesado). -- `PictureWorkflowRoutingSlipBuilder` — pipeline de imágenes (descargar → redimensionar → subir → actualizar). -- `AudioWorkflowRoutingSlipBuilder` — pipeline de audio (descargar → transcodificar a `.m4a` → subir carpeta → actualizar). +- `CreateTrackRoutingSlipBuilder`: creating a track (consumes intents, moves files, kicks off processing). +- `PictureWorkflowRoutingSlipBuilder`: image pipeline (download → resize → upload → update). +- `AudioWorkflowRoutingSlipBuilder`: audio pipeline (download → transcode to `.m4a` → upload folder → update). - `DeleteTrackRoutingSlipBuilder`, `DeletePlayListRoutingSlipBuilder`, `PlayListPictureSourceRoutingSlipBuilder`. -## Activities (pasos) +## Activities (steps) -Agrupadas por área: +Grouped by area: - **Files**: `DownloadFileFromBucketActivity`, `UploadFileToBucketActivity`, `TransferFilesToBucketActivity`, `CopyFileInBucketActivity`, `RemoveFileFromBucketActivity`. -- **Audio**: `GenerateAudioWorkflowPathsActivity`, `TranscodeAudioActivity` (ffmpeg → `.m4a`), `UpdateTrackAudioActivity` (guarda `AudioFolderName` y marca `Completed`). +- **Audio**: `GenerateAudioWorkflowPathsActivity`, `TranscodeAudioActivity` (ffmpeg → `.m4a`), `UpdateTrackAudioActivity` (saves `AudioFolderName` and marks it `Completed`). - **Pictures**: `GeneratePictureWorkflowPathsActivity`, `ResizePictureActivity` (ImageSharp), `UpdateTrackPictureActivity`, `UpdatePlayListPictureActivity`. -- **Tracks/PlayLists**: `MarkTrackAsRemovingActivity`, `DeleteTrackFromDbActivity`, `PublishTrackProcessingEventsActivity`, y equivalentes de playlist. +- **Tracks/Playlists**: `MarkTrackAsRemovingActivity`, `DeleteTrackFromDbActivity`, `PublishTrackProcessingEventsActivity`, and their playlist equivalents. - **UploadIntents**: `ConsumeUploadIntentsActivity`. -`RoutingSlipCleanUpConsumer` reacciona a `Completed`/`Faulted` para limpiar (p. ej. borrar el directorio temporal de trabajo). +`RoutingSlipCleanUpConsumer` reacts to `Completed`/`Faulted` to clean up (e.g. deleting the temporary working directory). -## Transcode de audio +## Audio transcoding -`AudioTranscoderService` invoca **ffmpeg** leyendo el original por stdin y produciendo en un directorio de trabajo un único `audio.m4a`: AAC con codec/bitrate/sample-rate/profile configurables y `-movflags +faststart` (moov al inicio → seek por range). Luego `TransferFilesToBucketActivity` sube esa carpeta a `Tracks/ProcessedAudios/{folder}/` y `UpdateTrackAudioActivity` guarda el `AudioFolderName` (la carpeta **de destino en S3**, no la local) y pone el estado en `Completed`. +`AudioTranscoderService` calls **ffmpeg**, reading the original from stdin and producing a single `audio.m4a` in a working directory: AAC with a configurable codec/bitrate/sample-rate/profile, and `-movflags +faststart` (moov at the start, so range-based seeking works). `TransferFilesToBucketActivity` then uploads that folder to `Tracks/ProcessedAudios/{folder}/`, and `UpdateTrackAudioActivity` saves the `AudioFolderName` (the **destination folder in S3**, not the local one) and sets the status to `Completed`. -## Configuración que necesita el Worker +## What the Worker needs configured -El Worker registra: storage (S3), transcoder (ffmpeg), pictures, DB, los consumers de MassTransit y los jobs de upload intents. Su `AppSettings` debe tener las secciones correctas: `Bucket` (= `webapi-storage`, el mismo que la API), `PlayList`, `Track`, `MassTransit`, `AudioTranscoder`, `UploadIntent`, `Workers` (directorio temporal), `InfrastructureStorage`, `Database`. +The Worker registers: storage (S3), transcoder (ffmpeg), pictures, the DB, the MassTransit consumers, and the upload-intent jobs. Its `AppSettings` needs the right sections: `Bucket` (= `webapi-storage`, same as the API), `PlayList`, `Track`, `MassTransit`, `AudioTranscoder`, `UploadIntent`, `Workers` (temp directory), `InfrastructureStorage`, `Database`. -## Jobs de fondo +## Background jobs -- `UploadIntentExpirationJob` — marca intents caducados como expirados (libera cuota) cada `ExpirationJobIntervalSeconds`. -- `TemporalUploadsCleanUpJob` — limpia subidas temporales antiguas. +- `UploadIntentExpirationJob`: marks expired intents as such (freeing quota) every `ExpirationJobIntervalSeconds`. +- `TemporalUploadsCleanUpJob`: cleans up old temporary uploads. -Corren en el host del Worker (`AddUploadIntentJobs`). Si no se registran en ningún proceso, los intents colgados no se limpian solos. +Both run on the Worker host (`AddUploadIntentJobs`). If they aren't registered anywhere, stale intents never get cleaned up on their own. diff --git a/docs/projects.md b/docs/projects.md index 10c196b..0891c33 100644 --- a/docs/projects.md +++ b/docs/projects.md @@ -1,74 +1,74 @@ -# Proyectos +# Projects -Los proyectos .NET viven en `backend/` (solución `Musify.slnx`, carpetas -`Core/`, `Hosts/` y `Tests/`); el cliente web en `web-player/`. +The .NET projects live under `backend/` (solution `Musify.slnx`, folders +`Core/`, `Hosts/` and `Tests/`); the web client lives under `web-player/`. ## Musify.Api (`:5111`) -API REST pública (Minimal APIs, .NET 10). Es la fachada fina del sistema. +The public REST API (Minimal APIs, .NET 10). The thin public face of the system. - **Endpoints**: `UserEndpoints`, `TrackEndpoints`, `PlayListEndpoints`. -- **Autenticación**: JWT Bearer contra Zitadel (`Authentication/`), con `JwtBearerEventsHandler` que sincroniza el usuario en cada token validado. -- **`CurrentUser`**: abstracción que se enlaza como parámetro de endpoint (`IBindableFromHttpContext`) y expone los claims básicos (`Id` como `long?`, `RequiredId`, nombre, etc.) sin tener que leer `ClaimsPrincipal` a mano. -- **Emite**: presigned URLs de subida (vía `IStorageService`) y **stream-tickets** (vía `IStreamTicketService`, RS256). -- **OpenAPI + Scalar** para documentación/prueba; OAuth2 (PKCE) configurado para login desde Scalar. -- **CORS** totalmente abierto **solo en Development** (para el front local). -- Traduce `ErrorOr` → HTTP en `ResultHttpExtensions`. +- **Authentication**: JWT Bearer against Zitadel (`Authentication/`), with a `JwtBearerEventsHandler` that syncs the user on every validated token. +- **`CurrentUser`**: an abstraction bound as an endpoint parameter (`IBindableFromHttpContext`) that exposes the basic claims (`Id` as `long?`, `RequiredId`, name, etc.) without reading `ClaimsPrincipal` by hand. +- **Issues**: presigned upload URLs (via `IStorageService`) and **stream tickets** (via `IStreamTicketService`, RS256). +- **OpenAPI + Scalar** for docs/testing; OAuth2 (PKCE) set up for logging in from Scalar. +- **CORS** wide open, but **only in Development** (for the local frontend). +- Translates `ErrorOr` into HTTP in `ResultHttpExtensions`. -**Propósito/porqué**: separar la cara pública (autorización + metadatos) del procesado y del servido de bytes. +**Purpose**: keep the public surface (authorization + metadata) separate from processing and byte-serving. ## Musify.Domain + Musify.Application + Musify.Infrastructure -El núcleo, en tres proyectos (clean architecture): +The core, split into three projects (clean architecture): ### Domain -Entidades (`Entities/`) y value objects/enums (`ValueObjects/`: `ProcessingStatus`, `LifeCycleStatus`, `UploadIntentStatus`, …). Sin dependencias de infraestructura. +Entities (`Entities/`) and value objects/enums (`ValueObjects/`: `ProcessingStatus`, `LifeCycleStatus`, `UploadIntentStatus`, …). No infrastructure dependencies. ### Application -Casos de uso (CQRS con Mediator): +Use cases (CQRS with Mediator): - `Tracks/`, `PlayLists/`, `Users/` → `Commands`, `Queries`, `Handlers`, `Responses`. -- `Contracts/` → interfaces que implementa la infraestructura (`IDatabase`, `IStorageService`, `IAudioTranscoderService`, `IPictureService`, `IEventBus`, `IStreamTicketService`). -- `Configuration/` → opciones tipadas (Track, PlayList, ApplicationStorage, UploadIntent…) bindeadas y validadas al arranque. -- `Shared/` → helpers transversales (`StorageKey.Combine`, `ImageSize`). +- `Contracts/` → interfaces that infrastructure implements (`IDatabase`, `IStorageService`, `IAudioTranscoderService`, `IPictureService`, `IEventBus`, `IStreamTicketService`). +- `Configuration/` → typed options (Track, PlayList, ApplicationStorage, UploadIntent…) bound and validated at startup. +- `Shared/` → cross-cutting helpers (`StorageKey.Combine`, `ImageSize`). - `Pagination/` → `PaginatedResponse`. -**Porqué**: la lógica de negocio no conoce EF, S3 ni RabbitMQ; solo interfaces. Reutilizable por la API y el Worker. +**Why**: business logic doesn't know about EF, S3, or RabbitMQ, only interfaces. Shared by both the API and the Worker. ### Infrastructure -Implementaciones concretas: -- `Persistence/` → `Database` (EF Core/Npgsql), migraciones. -- `Services/` → `StorageService` (AWSSDK.S3 contra SeaweedFS), `AudioTranscoderService` (ffmpeg → `.m4a`), `PictureService` (ImageSharp), `StreamTicketService` (firma RS256). -- `MassTransit/` → consumers, activities y routing slips (ver [media-processing.md](media-processing.md)). +Concrete implementations: +- `Persistence/` → `Database` (EF Core/Npgsql), migrations. +- `Services/` → `StorageService` (AWSSDK.S3 against SeaweedFS), `AudioTranscoderService` (ffmpeg → `.m4a`), `PictureService` (ImageSharp), `StreamTicketService` (RS256 signing). +- `MassTransit/` → consumers, activities, and routing slips (see [media-processing.md](media-processing.md)). - `Jobs/` → `UploadIntentExpirationJob`, `TemporalUploadsCleanUpJob`. ## Musify.StreamingGateway (`:8081`) -Reverse proxy (ASP.NET + **YARP**) que sirve el audio (`.m4a`) desde SeaweedFS. Valida el stream-ticket (RS256, clave pública) y, si el objeto pedido cae bajo el prefijo autorizado, reenvía al filer. +A reverse proxy (ASP.NET + **YARP**) that serves audio (`.m4a`) from SeaweedFS. Validates the stream ticket (RS256, public key) and, if the requested object falls under the authorized prefix, forwards it to the filer. -**Porqué un proyecto aparte**: escala con el tráfico de bytes independientemente de la API, tiene superficie mínima (solo sabe validar un JWT y proxiar) y permite que SeaweedFS quede en red privada. Ver [streaming.md](streaming.md). +**Why a separate project**: it scales with byte traffic independently of the API, has a minimal surface (it only knows how to validate a JWT and proxy), and lets SeaweedFS stay on a private network. See [streaming.md](streaming.md). ## Musify.Worker -Worker Service (host de fondo) que consume los eventos de MassTransit y ejecuta el procesado pesado: transcode de audio a `.m4a` (ffmpeg), generación de miniaturas (ImageSharp), transferencias de ficheros en el bucket, y los jobs de expiración/limpieza de upload intents. +A background Worker Service that consumes MassTransit events and runs the heavy processing: audio transcoding to `.m4a` (ffmpeg), thumbnail generation (ImageSharp), file transfers within the bucket, and the upload-intent expiration/cleanup jobs. -**Porqué aparte**: el trabajo CPU/IO no debe ocurrir dentro de un request HTTP; se escala y reinicia por separado. (Antes se llamaba `Musify.PictureWorker`; se renombró porque hace más que imágenes.) +**Why separate**: CPU/IO-heavy work shouldn't happen inside an HTTP request; it scales and restarts independently. (Previously named `Musify.PictureWorker`; renamed once it started doing more than just images.) -## web-player (`:5173` en dev, `:3000` en contenedor) +## web-player (`:5173` in dev, `:3000` in a container) -Cliente web (SvelteKit 2 + Svelte 5 + Tailwind 4). La sesión OIDC vive en el -servidor (cookie cifrada); las llamadas al backend salen del servidor con el -access token, y las subidas se hacen contra las URLs prefirmadas de S3. +The web client (SvelteKit 2 + Svelte 5 + Tailwind 4). The OIDC session lives +on the server (an encrypted cookie); backend calls go out from the server +with the access token, and uploads go straight to the presigned S3 URLs. ## Tests -`backend/Tests/`, carpeta `/Tests/` en el `.slnx`: cinco proyectos xUnit — -`Musify.Domain.Tests`, `Musify.Application.Tests` (SQLite en memoria, sin -Docker), `Musify.Infrastructure.Tests` y `Musify.Api.Tests` (Testcontainers: -Postgres + SeaweedFS reales) y `Musify.StreamingGateway.Tests`. Detalle en +`backend/Tests/` (the `/Tests/` folder in the `.slnx`) has five xUnit projects: +`Musify.Domain.Tests`, `Musify.Application.Tests` (in-memory SQLite, no +Docker), `Musify.Infrastructure.Tests` and `Musify.Api.Tests` (Testcontainers: +real Postgres + SeaweedFS), and `Musify.StreamingGateway.Tests`. Details in [development.md](development.md#tests). -## Otras carpetas +## Other folders -- **`deploy/`** — stacks de Docker Compose (dev y prod), autocontenidos. Ver +- **`deploy/`**: self-contained Docker Compose stacks (dev and prod). See [../deploy/README.md](../deploy/README.md). -- **`docs/`** — esta documentación. +- **`docs/`**: this documentation. diff --git a/docs/storage.md b/docs/storage.md index 5d72b83..7f80bbf 100644 --- a/docs/storage.md +++ b/docs/storage.md @@ -1,48 +1,48 @@ -# Almacenamiento (SeaweedFS / S3) +# Storage (SeaweedFS / S3) -## Qué es +## What it is -**SeaweedFS** es el almacén de objetos, compatible con la API S3. Guarda los originales subidos y los derivados (audio `.m4a`, miniaturas). Se accede vía `AWSSDK.S3` desde `StorageService` (`IStorageService`). +**SeaweedFS** is the object store, S3-API compatible. It holds the uploaded originals and their derivatives (`.m4a` audio, thumbnails). Accessed via `AWSSDK.S3` from `StorageService` (`IStorageService`). -Expone: -- **S3 API** (`:8333`) — operaciones S3 (presigned URLs, put/get/list…). -- **filer HTTP** (`:8888`) — sirve los ficheros por ruta; lo usa el **StreamingGateway**. -- master (`:9333`) y volume server — internos. +It exposes: +- **S3 API** (`:8333`): S3 operations (presigned URLs, put/get/list…). +- **filer HTTP** (`:8888`): serves files by path, used by the **StreamingGateway**. +- master (`:9333`) and volume server, internal only. -Bucket de la app: **`webapi-storage`** (`ApplicationStorage:Bucket`). Importante: la API y el Worker usan **el mismo bucket** (el worker procesa lo que sube la API). +App bucket: **`webapi-storage`** (`ApplicationStorage:Bucket`). Important: the API and the Worker use **the same bucket** (the worker processes whatever the API uploads). -## Estructura de claves (layout) +## Key layout -- `temp/{userId}/Tracks/{guid}.{ext}` — subidas temporales (objetivo de las presigned PUT, antes de consumir el intent). -- `uploads/{userId}/Tracks/OriginalPictures|OriginalAudios/...` — originales ya consumidos. -- `Tracks/SmallPictures|MediumPictures|LargePictures/...` — miniaturas generadas. -- `Tracks/ProcessedAudios/{AudioFolderName}/` — audio transcodificado (`audio.m4a`, AAC con faststart). +- `temp/{userId}/Tracks/{guid}.{ext}`: temporary uploads, the target of presigned PUTs, before the intent is consumed. +- `uploads/{userId}/Tracks/OriginalPictures|OriginalAudios/...`: originals that have already been consumed. +- `Tracks/SmallPictures|MediumPictures|LargePictures/...`: generated thumbnails. +- `Tracks/ProcessedAudios/{AudioFolderName}/`: transcoded audio (`audio.m4a`, AAC with faststart). -Las claves se construyen **siempre** con el helper `StorageKey.Combine(...)` (en `Application/Shared`), que une segmentos con `/` limpiando espacios y barras. Está centralizado para estandarizar y no repetir lógica. +Keys are always built with the `StorageKey.Combine(...)` helper (in `Application/Shared`), which joins segments with `/` and trims stray spaces and slashes. It's centralized to keep the logic consistent and avoid repeating it. -> En el filer, los objetos S3 viven bajo `/buckets/{bucket}/{key}` — de ahí que el gateway reescriba `/media/{key}` → `/buckets/webapi-storage/{key}`. +> In the filer, S3 objects live under `/buckets/{bucket}/{key}`, which is why the gateway rewrites `/media/{key}` → `/buckets/webapi-storage/{key}`. -## URLs prefirmadas (presigned) +## Presigned URLs -Para **no** hacer pasar ficheros grandes por la API, el cliente habla directo con S3 mediante URLs firmadas de corta vida: +To **avoid** routing large files through the API, the client talks to S3 directly using short-lived signed URLs: -- **Subidas (PUT)**: `RequestTrackUploadUrls` / `RequestPlayListPictureUpload` generan presigned PUT (con `Content-Type` y `If-None-Match: *` firmados, expiración ~120s). El cliente sube directo a S3. -- **Imágenes (GET)**: las miniaturas se sirven con presigned GET (un objeto = una URL). +- **Uploads (PUT)**: `RequestTrackUploadUrls` / `RequestPlayListPictureUpload` generate presigned PUTs (with signed `Content-Type` and `If-None-Match: *`, ~120s expiry). The client uploads straight to S3. +- **Images (GET)**: thumbnails are served via presigned GETs (one object = one URL). -**Por qué presigned y no proxiar**: subir un audio de ~100 MB a través de la API consumiría memoria/ancho de banda de los servidores de aplicación y escalaría mal. La presigned PUT directa a S3 es el patrón estándar y correcto. +**Why presigned instead of proxying**: routing a ~100 MB audio file through the API would burn memory and bandwidth on the application servers and wouldn't scale well. A direct presigned PUT to S3 is the standard, correct pattern here. -### Upload intents y cuota -Cada `upload-urls` crea **UploadIntents** (reservas en estado `Issued`) y devuelve las URLs. Al crear la pista/playlist se **consumen**. Hay cuota por usuario (`MaxActiveUploadIntentsPerUser`, bytes…) para evitar abuso. El `UploadIntentExpirationJob` (en el Worker) marca como expirados los intents caducados y libera la cuota; si ese job no corre, los intents colgados se acumulan y bloquean nuevas subidas. +### Upload intents and quota +Every `upload-urls` call creates **UploadIntents** (reservations in the `Issued` state) and returns the URLs. They're **consumed** when the track/playlist is created. There's a per-user quota (`MaxActiveUploadIntentsPerUser`, byte limits…) to prevent abuse. The `UploadIntentExpirationJob` (in the Worker) marks expired intents and frees up quota. If that job isn't running, stale intents pile up and block new uploads. -## Qué es público y qué privado (despliegue) +## What's public and what's private (deployment) -| Exponer a internet | Mantener privado | +| Expose to the internet | Keep private | |---|---| -| S3 API `:8333` (tras TLS) — necesario para presigned PUT/GET del cliente | filer `:8888` (solo el gateway, en red interna) | -| StreamingGateway `:8081` | master `:9333`, volume server, UI de admin | +| S3 API `:8333` (behind TLS), needed for the client's presigned PUT/GET | filer `:8888` (internal network, gateway only) | +| StreamingGateway `:8081` | master `:9333`, volume server, admin UI | -- **El audio** se sirve por el gateway → SeaweedFS puede quedar privado para ese flujo. -- **Subidas e imágenes** usan presigned → el cliente toca el endpoint S3 directamente, así que `:8333` debe ser alcanzable (pero inútil sin firma válida; es el modelo de cualquier bucket S3/MinIO). -- En **producción**: `InfrastructureStorage:Address` debe ser el **endpoint S3 público** (la firma se calcula para ese host); si los servidores no lo alcanzan internamente, se usa config dividida (host público para firmar / interno para operaciones server-side). +- **Audio** is served through the gateway, so SeaweedFS can stay private for that flow. +- **Uploads and images** use presigned URLs, so the client talks to the S3 endpoint directly and `:8333` has to be reachable (though useless without a valid signature, this is the standard model for any S3/MinIO bucket). +- In **production**: `InfrastructureStorage:Address` must be the **public S3 endpoint** (the signature is computed for that host). If the servers can't reach it internally, use split config: public host for signing, internal host for server-side operations. -**Regla**: el gateway y, como mucho, el `:8333` firmado son la única superficie pública; master/volume/filer/admin **nunca** se exponen. +**Rule of thumb**: the gateway, and at most the signed `:8333`, are the only public surface. Master, volume, filer and admin are **never** exposed. diff --git a/docs/streaming.md b/docs/streaming.md index 5f28c27..1f6ba1a 100644 --- a/docs/streaming.md +++ b/docs/streaming.md @@ -1,55 +1,55 @@ -# Streaming de audio +# Audio streaming -## Objetivo +## Goal -Reproducir el audio **sin que los bytes pasen por la API**, pero con control de acceso. La API solo emite un permiso corto; el reverse proxy sirve los bytes desde SeaweedFS. +Play audio **without the bytes passing through the API**, while still controlling access. The API only issues a short-lived permission; the reverse proxy serves the bytes from SeaweedFS. -## Formato: fichero único AAC (.m4a) por HTTP range +## Format: a single AAC file (.m4a), served via HTTP range -El audio se transcodifica a **un único `audio.m4a`** (AAC, contenedor MP4 con `+faststart` para que el átomo `moov` quede al inicio y el seek por range funcione), dentro de la carpeta `Tracks/ProcessedAudios/{AudioFolderName}/`. No hay manifest ni segmentos: el reproductor descarga el fichero por **HTTP range requests** (modelo tipo Spotify para VOD musical). +Audio is transcoded into **one `audio.m4a`** (AAC, MP4 container with `+faststart` so the `moov` atom sits at the start and range-based seeking works), stored under `Tracks/ProcessedAudios/{AudioFolderName}/`. There's no manifest or segments: the player downloads the file via **HTTP range requests** (the same model Spotify uses for on-demand music). -Multi-bitrate no está implementado hoy; el camino para añadirlo es transcodificar varias calidades (`audio_96.m4a`, …) y que el cliente elija una al iniciar (sin ABR fluido a mitad de pista, igual que Spotify). +Multi-bitrate isn't implemented yet; the path to add it is transcoding several qualities (`audio_96.m4a`, …) and letting the client pick one at playback start (no seamless mid-track ABR, same as Spotify). -## El acceso: stream-ticket de prefijo +## Access control: a prefix-scoped stream ticket -Se autoriza **el prefijo de la carpeta** de la pista con un *stream-ticket* de corta vida, y el proxy lo valida en cada petición. Aunque hoy sea un único objeto, el ticket sigue acotado al prefijo `Tracks/ProcessedAudios//` (cubre el fichero actual y cualquier calidad futura). +Access is authorized for **the track's folder prefix** via a short-lived *stream ticket*, validated by the proxy on every request. Even though there's only one object today, the ticket is still scoped to the prefix `Tracks/ProcessedAudios//` (covering the current file and any future quality variants). -## Flujo +## Flow -1. `GET /tracks/{id}/stream` (autenticado) → la API autoriza y devuelve: +1. `GET /tracks/{id}/stream` (authenticated) → the API authorizes the request and returns: ```json { "manifestUrl": "http:///media/Tracks/ProcessedAudios//audio.m4a", "ticket": "", "expiresInSeconds": 3600 } ``` - El ticket lleva el claim `prefix = "Tracks/ProcessedAudios//"`. -2. El reproductor abre la URL del audio añadiéndole `?t=` (o la cabecera `X-Stream-Ticket`). -3. El **StreamingGateway** (YARP) valida el ticket y reenvía al filer; los bytes van SeaweedFS → cliente (con range/seek). + The ticket carries the claim `prefix = "Tracks/ProcessedAudios//"`. +2. The player opens the audio URL with `?t=` appended (or the `X-Stream-Ticket` header). +3. The **StreamingGateway** (YARP) validates the ticket and forwards the request to the filer; the bytes flow SeaweedFS → client (with range/seek support). -## El ticket (RS256) +## The ticket (RS256) -- Lo firma la API con clave **privada** (`StreamTicketService`); el gateway valida con la **pública** (`TicketValidator`). Así el gateway **no puede emitir** tickets, solo verificarlos. -- Claims: `sub`, `prefix`, `aud = media-gateway`, `iss = musify-webapi`, `exp` (TTL ~1h). +- Signed by the API with a **private** key (`StreamTicketService`); validated by the gateway with the **public** one (`TicketValidator`). That way the gateway **can't issue** tickets, only verify them. +- Claims: `sub`, `prefix`, `aud = media-gateway`, `iss = musify-webapi`, `exp` (~1h TTL). -**Por qué RS256 (asimétrica)**: separa responsabilidades — emisor (la API) y verificador (gateway) no comparten secreto; el gateway, aunque se comprometa, no puede crear permisos. +**Why RS256 (asymmetric)**: it separates responsibilities. The issuer (API) and the verifier (gateway) don't share a secret, so even if the gateway is compromised, it can't mint permissions. -## El gateway (validación + proxy) +## The gateway (validation + proxy) -`TicketValidationMiddleware` en cada petición a `/media/**`: -1. Lee `?t=`, valida firma/aud/iss/exp. -2. Comprueba que la clave pedida **empieza por** el `prefix` del ticket (`StartsWith`). Si no → 403. -3. Quita el `?t=` y deja pasar a YARP, que reescribe `/media/{key}` → `/buckets/webapi-storage/{key}` del filer. +`TicketValidationMiddleware`, on every request to `/media/**`: +1. Reads `?t=`, validates its signature/aud/iss/exp. +2. Checks that the requested key **starts with** the ticket's `prefix`. If not → 403. +3. Strips the `?t=` and passes the request on to YARP, which rewrites `/media/{key}` → `/buckets/webapi-storage/{key}` for the filer. -- Sin ticket → **401**; fuera de prefijo → **403**; ok → **200** (y **206** en range requests, así que el seek funciona). -- Pasa `Range`/`Accept-Ranges` y expone esos headers por CORS. +- No ticket → **401**; outside the prefix → **403**; ok → **200** (and **206** for range requests, so seeking works). +- Passes through `Range`/`Accept-Ranges` and exposes those headers via CORS. -## ¿Un ticket por canción? +## One ticket per track? -Sí. Cada ticket está acotado a **una** carpeta (una pista). Para reproducir otra, se pide otro ticket. Es barato (la API solo firma un JWT) y es lo más seguro: cada permiso abre solo lo que vas a reproducir. +Yes. Each ticket is scoped to **one** folder (one track). Playing a different one means requesting a new ticket. It's cheap (the API just signs a JWT) and it's the safest option: every permission only unlocks what you're about to play. -- Si algún día molesta (muchísimos cambios de pista), el mismo mecanismo del claim `prefix` permite ampliar el alcance: a nivel de playlist o de toda la biblioteca (`Tracks/ProcessedAudios/`). Trade-off seguridad ↔ comodidad. Por defecto, **por canción**. +- If that ever becomes a problem (very frequent track switching), the same `prefix` claim mechanism can widen the scope to a whole playlist or the whole library (`Tracks/ProcessedAudios/`). It's a security/convenience trade-off. The default is **per track**. -## Pendiente / notas de seguridad +## Open items / security notes -- La política de quién puede pedir el ticket es hoy "cualquier autenticado" (TODO: restringir con `UserHasTrack`/visibilidad). -- El check de prefijo es `StartsWith` literal; conviene endurecer rechazando claves con `..` (path traversal), aunque navegadores y ASP.NET normalizan `..`. -- El ticket viaja en la query (`?t=`); el gateway lo elimina antes de reenviar (no llega a los logs del filer). +- Today, the policy for who can request a ticket is "any authenticated user" (TODO: restrict it with `UserHasTrack`/visibility). +- The prefix check is a literal `StartsWith`; it would be worth hardening it against `..` path traversal, even though browsers and ASP.NET normalize `..`. +- The ticket travels in the query string (`?t=`); the gateway strips it before forwarding, so it never reaches the filer's logs. diff --git a/web-player/design_handoff_musify_player/Crear playlist.dc.html b/web-player/design_handoff_musify_player/Crear playlist.dc.html deleted file mode 100644 index 43fa0e7..0000000 --- a/web-player/design_handoff_musify_player/Crear playlist.dc.html +++ /dev/null @@ -1,183 +0,0 @@ - - - - - - - - - - - - - - -
- -
- -
- -
- - -
-
-
Tu biblioteca
-
Crear playlist
-
-
- -
-
- - -
- - -
-
- -
-
- -
- -
-
Subir imagen
-
- - -
- - -
{{ counter }}
- - - -
-
- - -
-
-
-
Visibilidad
-
{{ visHint }}
-
-
- -
{{ v.label }}
- -
-
- -
-
-
Colaborativa
-
Quien tenga el enlace puede añadir canciones
-
-
-
-
-
-
- - -
-
Podrás añadir canciones desde cualquier pantalla.
-
-
Cancelar
-
- - Crear playlist -
-
-
-
- - -
-
-
Playlist «{{ createdName }}» creada
-
- -
- - - - - diff --git a/web-player/design_handoff_musify_player/Musify.dc.html b/web-player/design_handoff_musify_player/Musify.dc.html deleted file mode 100644 index e7bf466..0000000 --- a/web-player/design_handoff_musify_player/Musify.dc.html +++ /dev/null @@ -1,1127 +0,0 @@ - - - - - - - - - - - - - - -
- -
-
- -
- - - - - -
- -
-
-
- -
-
- -
-
- -
- - -
- -
- -
- - Cola -
-
- -
-
- -
- - - -
-
- -
-
-
- -
-
-
-
-
- -
-
- -
- - - - -
-
!
-
No se pudo cargar tu música
-
La conexión se interrumpió. Lo que tengas descargado sigue disponible sin conexión.
-
-
Reintentar
-
Ver descargas
-
-
- - - - -
- - -
-
-
-

{{ heroGreeting }}

-
{{ heroBlurb }}
-
-
- - Reanudar {{ heroResume }} -
-
Ver resumen semanal
-
-
-
- -
-
{{ s.v }}
-
{{ s.k }}
-
- -
-
-
- - -
-
-

Continuar escuchando

-
-
- -
-
-
-
-
-
{{ c.title }}
-
{{ c.sub }}
-
-
- -
-
- -
-
- - -
-
-
-
-
-
-
-
-
Playlist destacada
-
{{ spotlight.name }}
-
{{ spotlight.meta }}
-
-
-
{{ spotlight.blurb }}
-
-
- Reproducir -
-
Mezclar
-
-
-
- -
-
{{ t.n }}
-
-
{{ t.title }}
-
{{ t.artist }}
-
-
{{ t.dur }}
-
- -
-
-
- - -
-
-
-

Mixes

-
Generados a partir de lo que más repites
-
-
-
- -
-
-
-
-
- -
-
-
{{ it.title }}
-
{{ it.sub }}
-
- -
-
- - -
-

Artistas que sigues

-
- -
-
-
-
-
{{ a.title }}
-
{{ a.sub }}
-
- -
-
- - -
-
-
-

Populares esta semana

-
Lo más escuchado entre quienes comparten tu gusto
-
-
-
- -
-
- -
-
-
-
-
- - - {{ t.n }} - -
-
-
-
-
-
{{ t.title }}
-
{{ t.artist }}
-
-
{{ t.plays }}
-
{{ t.dur }}
-
- -
-
- - -
-
-
-

Tus playlists

-
Creadas y guardadas por ti
-
-
Ver todas
-
-
- -
-
-
-
-
-
{{ p.name }}
-
{{ p.meta }}
-
{{ p.artistsLine }}
-
-
- -
-
- -
-
-
- - - - -
-

Descubrir

-
Rutas de escucha fuera de tu historial. Se renuevan cada 12 horas.
-
- -
-
{{ g.name }}
-
{{ g.meta }}
-
-
-
-
- -
-
-

Fuera de tu burbuja

-
Álbumes que tu historial nunca te habría servido
-
- -
-
-
-
- -
-
-
{{ it.title }}
-
{{ it.sub }}
-
- -
-
-
- - - - -
-
-
-
-
-
-
{{ listKind }}
-

{{ listTitle }}

-
{{ listMeta }}
-
-
- Reproducir -
-
- -
-
-
-
- -
-
#
Título
Álbum
Duración
-
- -
-
- -
-
-
-
-
- - - {{ t.n }} - -
-
-
-
-
-
-
{{ t.title }}
-
{{ t.artist }}
-
-
-
{{ t.album }}
-
-
- -
-
{{ t.dur }}
-
-
- -
- - - - -
-
-
-

Tus playlists

-
7 playlists · 564 canciones · 38 h 12 min
-
-
Nueva playlist
-
-
- -
-
-
-
-
- -
-
-
{{ p.name }}
-
{{ p.meta }}
-
{{ p.artistsLine }}
-
- -
-
- - - - -
-
- -
-
{{ emptyTitle }}
-
{{ emptyBody }}
-
-
{{ emptyCta }}
-
Volver al inicio
-
-
- - - - -
-
-
Resultados de búsqueda
-

{{ searchHeading }}

-
{{ searchMeta }}
-
- -
- -
- {{ c.label }} - {{ c.count }} -
- -
- - -
-
-
-
-
-
Mejor resultado · {{ top.kind }}
-
{{ top.title }}
-
{{ top.sub }}
-
-
- -
-
- - - -
-
-
{{ g.label }}
-
-
{{ g.count }}
-
- -
-
-
-
- -
-
-
-
-
{{ r.title }}
-
{{ r.badge }}
-
-
{{ r.sub }}
-
-
{{ r.meta }}
-
- -
- -
- - - - -
-
Sin resultados para “{{ query }}”
-
Revisa la ortografía o prueba con un término más corto. También puedes buscar por álbum o por playlist.
-
- -
{{ s.label }}
- -
-
- - -
-
- - - - - -
- - -
-
- -
-
-
-
-
-
{{ curTitle }}
-
{{ curArtist }}
-
-
- -
-
- -
-
-
- -
-
- -
-
- - - - - - -
-
- -
-
- -
-
-
- {{ elapsed }} -
-
-
-
-
- {{ total }} -
-
- -
-
- -
-
- -
-
-
-
-
-
-
- -
-
-
- - -
- -
- - {{ n.label }} -
- -
-
-
- - - - diff --git a/web-player/design_handoff_musify_player/README.md b/web-player/design_handoff_musify_player/README.md deleted file mode 100644 index 2e3de53..0000000 --- a/web-player/design_handoff_musify_player/README.md +++ /dev/null @@ -1,399 +0,0 @@ -# Handoff: Musify — Web Music Player - -## Overview - -Musify es un reproductor de música web: un player permanente, navegación lateral, y vistas de Home / Descubrir / Playlists / Me gusta / Reciente, más estados de carga, error, vacío y sin resultados. Su rasgo de identidad es que **toda la paleta de acento y los fondos derivan de la canción en reproducción**: al cambiar de pista, el tinte del hero, el glow ambiental, el sidebar, la barra del player, el logo, la barra de progreso y los acentos viran en bloque con una transición de 0.6s. - -## About the Design Files - -Los archivos de este paquete son **referencias de diseño hechas en HTML** — prototipos que muestran aspecto y comportamiento previstos, **no código de producción para copiar tal cual**. La tarea es **recrear estos diseños en el entorno del codebase destino** (React, Vue, SwiftUI, nativo…) siguiendo sus patrones y librerías ya establecidos. Si todavía no hay entorno, elige el framework más apropiado para el proyecto e implementa allí. - -El prototipo está escrito como un componente único con estado local y estilos inline. En producción conviene separarlo en componentes (Sidebar, TopBar, Player, Queue, TrackRow, MediaCard, sections de Home) y mover los tokens a la solución de estilos del proyecto. - -## Fidelity - -**Alta fidelidad (hifi).** Colores, tipografía, espaciado, radios, estados y microinteracciones son definitivos. Se espera una recreación fiel usando las librerías del codebase. Las carátulas son fotografías genéricas de marcador de posición; el contenido musical (artistas, álbumes, canciones, playlists, duraciones, reproducciones) es **mock data** y debe sustituirse por datos reales. - -**Regla de producto:** la UI nunca menciona la procedencia de la música. Sin etiquetas de fuente, proveedor ni "powered by". Para el usuario esto es solo Musify. - ---- - -## Layout global - -Altura fija de viewport, sin scroll de página; solo el área de contenido y la cola scrollean. - -``` -┌──────────┬──────────────────────────────┬──────────┐ -│ Sidebar │ TopBar │ Queue │ -│ 254px ├──────────────────────────────┤ 304px │ -│ │ Main (scroll) │ (258px │ -│ │ │ <1180) │ -└──────────┴──────────────────────────────┴──────────┘ - Player flotante (absolute, left/right 0, bottom 0, padding 0 16px 16px) -``` - -- Raíz: `position:relative; height:100vh; overflow:hidden; background: pageBg; transition: background .6s ease`. -- Dos capas decorativas absolutas y no interactivas sobre el fondo: el **ambient glow** y un scrim inferior `radial-gradient(130% 85% at 50% 118%, rgba(0,0,0,.8), transparent 62%)`. -- Fila principal `display:flex; height:100%`. -- El main tiene `padding: 6px 26px` y `padding-bottom` dinámico: `126px` en desktop, `206px` cuando hay barra de pestañas móvil. - -### Breakpoints - -| Ancho | Comportamiento | -|---|---| -| `>= 1180px` | Sidebar visible (254px), cola 304px, player completo | -| `< 1180px` (tablet) | Sidebar oculto → barra de pestañas bajo el player; cola 258px; padding inferior 206px | -| `< 760px` (móvil) | Cola oculta; se ocultan shuffle/repeat/volumen/letra/cola del player (queda carátula + título + transporte + progreso); el bloque de info del player pasa a `width:auto` | - ---- - -## Sistema de color dinámico - -Cada pista lleva un `hue` (0–360) asignado. Todo el color de la app se deriva de ese hue en oklch. Los valores están repartidos por la rueda para que el cambio entre pistas consecutivas sea evidente (paso mínimo ~50°). - -```js -// hue = hue de la pista en reproducción -accent = oklch(0.74 0.145 H) // acción, barra de progreso, corazón activo, EQ -accentTitle = oklch(0.87 0.07 H) // títulos sobre superficie tintada -accentMuted = oklch(0.79 0.035 H) // título de la pista activa en tarjetas -accentSoft = oklch(0.74 0.145 H / .08) // fondo de fila/tarjeta activa -accentLine = oklch(0.74 0.145 H / .2) // borde de superficie acentuada -accentHair = oklch(0.74 0.145 H / .09) // borde de tarjeta activa -accentBtnBg = oklch(0.74 0.145 H / .15) -accentBtnBgHover = oklch(0.74 0.145 H / .24) - -// superficies -pageBg = oklch(0.068 0.008 H) -sidebarBg = linear-gradient(180deg, oklch(0.095 0.012 H), oklch(0.068 0.007 H)) -panelBg = oklch(0.09 0.010 H / .28) // panel de cola -barBg = oklch(0.105 0.012 H / .9) // player y tabs (con backdrop-filter: blur(22px)) -hairline = oklch(0.62 0.030 H / .08) // todos los separadores - -// gradientes: tc(a, l) = oklch(0.34 - l/380 , 0.11 - l/1600 , H / a) -ambient = radial-gradient(52% 38% at 14% 0%, tc(.26,30), transparent 54%), - radial-gradient(46% 34% at 78% 0%, tc(.20,40), transparent 56%) -heroBg = linear-gradient(105deg, tc(.34,42) 0%, tc(.11,70) 28%, tc(.03,88) 50%, rgba(6,6,9,0) 70%) -spotlightBg = linear-gradient(100deg, tc(.28,46) 0%, tc(.10,74) 30%, tc(.03,88) 52%, rgba(6,6,9,0) 72%) -logoGrad = linear-gradient(140deg, oklch(0.78 0.15 H), oklch(0.62 0.13 H+40) 92%) -logoGlow = 0 0 20px oklch(0.74 0.145 H / .3) -``` - -**Importante:** hero y spotlight terminan en `alpha 0` antes del borde derecho (70–72%) y **no llevan borde**, para fundirse con el fondo sin corte visible. - -Los elementos que cambian de color reciben `transition: background .6s ease` (y `box-shadow .6s ease` en el logo): raíz, sidebar, panel de cola, barra del player, tabs. - -### Grises fijos (no dependen del hue) - -| Rol | Hex | -|---|---| -| Texto principal (títulos de sección, h1/h2) | `#d3d2d6` – `#d9d8dc` | -| Texto de tarjeta / fila | `#cbcacf` / `#cdccd1` | -| Texto base del documento | `#c9c8cc` | -| Secundario | `#8a8a8e`, `#8f8f93`, `#919195` | -| Terciario | `#7f7f83`, `#7d7d81`, `#848488` | -| Cuaternario / contadores | `#6c6c70`, `#696a6d`, `#646468`, `#616165`, `#5c5c60` | -| Iconos inactivos player | `#747478` | -| Botón primario (fondo) | `#c6c4cb`, hover `#d8d7dc`; texto `#0a0a0d` | -| Superficies neutras | `rgba(255,255,255,.022)` base, `.045` hover; bordes `rgba(255,255,255,.04)` / `.075` | - -Los grises son **neutros a propósito** (sin tinte), para que solo el acento lleve color. - ---- - -## Tipografía - -- Display / títulos: **Sora** 400/500/600/700. -- UI / texto: **Plus Jakarta Sans** 400/500/600/700. -- `-webkit-font-smoothing: antialiased`. - -| Uso | Fuente | Tamaño | Peso | Tracking | -|---|---|---|---|---| -| H1 hero | Sora | 36px / 1.1 | 600 | -0.035em | -| H1 vista (Descubrir, Playlists, Tracklist) | Sora | 28–33px | 600 | -0.03 / -0.035em | -| H2 sección | Sora | 17.5px | 600 | -0.025em | -| Título spotlight | Sora | 23px | 600 | -0.03em | -| Wordmark | Sora | 17.5px | 600 | -0.02em | -| Subtítulo de sección | Jakarta | 12px | 400 | — | -| Eyebrow / cabecera de columna | Jakarta | 10.5px uppercase | 600 | 0.12–0.17em | -| Título de tarjeta | Jakarta | 13–13.5px | 600 | -0.01em | -| Fila de canción (título) | Jakarta | 12.5–13px | 500 | — | -| Meta / artista | Jakarta | 11–11.5px | 400 | — | -| Números (duración, índice, reproducciones) | Jakarta | 11–12px | 400 | `font-variant-numeric: tabular-nums` | - -Todo texto de una línea en tarjetas y filas usa `white-space:nowrap; overflow:hidden; text-overflow:ellipsis` con `min-width:0` en el contenedor flex. Los titulares llevan `text-wrap: pretty`. - ---- - -## Escalas - -**Radios:** 8px (miniaturas pequeñas, chips) · 9–11px (carátulas 36–48px, botones) · 12–13px (filas activas, carátulas de tarjeta) · 14–16px (tarjetas, portadas grandes) · 18px (player, tabs, portada de cabecera) · 22–24px (hero, spotlight) · 50% (avatares, botón de play, artistas) · 999px (chips de sugerencia). - -**Sombras:** carátula de tarjeta `0 14px 32px rgba(0,0,0,.45)` · artista `0 12px 28px rgba(0,0,0,.4)` · portada de cabecera `0 24px 56px rgba(0,0,0,.55)` · player `0 20px 56px rgba(0,0,0,.6)` · botón primario hero `0 10px 28px rgba(0,0,0,.45)`. - -**Gaps de grid:** tarjetas 20px · artistas 18px · playlists 14–22px · filas compactas 6–14px. - -**Anchos mínimos de columna (auto-fill):** mixes/álbumes/descubrir 164px · artistas 132px · playlists (tarjeta ancha) 258px · playlists (índice) 196px · continuar escuchando 268px · populares 330px · géneros 228px. - ---- - -## Pantallas - -### 1. Sidebar (`>= 1180px`) - -`width:254px; padding:22px 12px 0 20px; border-right:1px solid hairline; background: sidebarBg`. - -- **Wordmark**: cuadrado 24px con `logoGrad` + `logoGlow`, gap 11px, texto "Musify". Padding inferior 26px. -- **Nav** (columna, gap 2px). Ítem: `padding:9px 12px; border-radius:10px; font-size:13.5px; weight:500`, icono SVG 17px stroke 1.6, etiqueta flexible, contador a la derecha (11px, `#5c5c60`, tabular). - - Activo: color `#d5d4d8`, fondo `rgba(255,255,255,.06)`. - - Inactivo: color `#8b8b8f`, fondo transparente. Hover: fondo `rgba(255,255,255,.04)`, color `#d5d4d8`. Transición `.16s`. - - Ítems: Inicio · Descubrir · Playlists (7) · Me gusta (312) · Reciente. -- **Separador**: `margin:24px 12px 14px; height:1px; background:rgba(255,255,255,.05)`. -- **Cabecera "TUS PLAYLISTS"** (10.5px uppercase, 0.13em, `#616165`) con un "+" a la derecha que navega al índice de playlists. -- **Lista de playlists** (scroll, gap 1px). Fila: miniatura 34px radio 8px (imagen `opacity:.88`), nombre 12.5px, meta 11px `#6c6c70`. Si esa playlist está sonando, un ecualizador de 3 barras de 2px a la derecha. - -### 2. TopBar - -`padding:16px 26px 12px; gap:14px`. - -- Atrás / adelante: círculos de 30px, fondo `rgba(255,255,255,.035)`, borde `rgba(255,255,255,.05)`, icono 15px. Atrás activo (`#8b8b8f`, hover `#dbdadf`), adelante deshabilitado (`#555559`). -- Buscador: `flex:1; max-width:480px; height:38px; radius:11px`, fondo `rgba(255,255,255,.035)`, borde `rgba(255,255,255,.055)`, lupa 15px `#737377`, input 13px transparente. Placeholder: "Canciones, artistas, álbumes o playlists". -- Spacer. -- Botón "Cola": alto 33px, radio 10px, 12.5px/500, icono 15px. Activo: color `#d6d5da`, fondo `rgba(255,255,255,.06)`. Inactivo: `#8b8b8f`, fondo `rgba(255,255,255,.028)`. -- Avatar 33px circular con borde `rgba(255,255,255,.1)`. - -### 3. Home - -Ritmo editorial deliberado — no filas iguales encadenadas: - -**a) Hero** — `border-radius:24px; margin-bottom:42px; background: heroBg`, sin borde, `padding:38px 36px 34px; max-width:620px`. -- Saludo H1 dinámico por hora y día (ver *Copy dinámico*). -- Blurb 13.5px `#8a8a8e`, `line-height:1.65`, `max-width:440px`. -- Botones: primario "Reproducir" (`#c6c4cb` sobre `#0a0a0d`, 12px 21px, radio 12px, icono play 14px) + secundario "Guardar" (borde `rgba(255,255,255,.11)`), y un meta a la derecha en 12px. -- Tres métricas: valor Sora 26px/600 y etiqueta 11.5px — "Canciones esta semana", "Tiempo de escucha", "Artistas nuevos". - -**b) Continuar escuchando** — grid `auto-fill minmax(268px,1fr)`, gap 10px. Fila-tarjeta: `padding:9px 14px 9px 9px; radius:13px`, carátula 46px radio 9px, título 13px/600, sub 11.5px, y un icono play 15px en `accent` que aparece en hover. La pista en curso usa `accentSoft` de fondo, `accentHair` de borde y `accentMuted` en el título. - -**c) Playlist destacada (spotlight)** — grid de dos columnas `auto-fit minmax(290px,1fr)`, `radius:22px`, `background: spotlightBg`, sin borde ni divisor central. -- Izquierda: portada 88px radio 14px, eyebrow "PLAYLIST DESTACADA", nombre Sora 23px, meta 12px, blurb 13px/1.7, botón "Reproducir" (`accentBtnBg` + `accentLine` + `accentTitle`, hover `accentBtnBgHover`) y "Mezclar" secundario. -- Derecha: 5 canciones con índice 20px, título 12.5px, artista 11px, duración tabular; fondo `rgba(0,0,0,.26)` que se desvanece a transparente hacia la derecha. - -**d) Mixes** — H2 "Mixes" + sub "Generados a partir de lo que más repites". Grid `minmax(164px,1fr)` gap 20px. Tarjeta cuadrada radio 13px con scrim `linear-gradient(180deg,transparent 45%,rgba(0,0,0,.42))` y botón de play circular 38px abajo a la derecha (`rgba(10,10,13,.76)`, blur 8px, borde `rgba(255,255,255,.12)`) que aparece en hover. - -**e) Artistas que sigues** — grid `minmax(132px,1fr)` gap 18px, retratos circulares, texto centrado, nombre 12.5px/600, oyentes 11px. - -**f) Populares esta semana** — grid de dos columnas `auto-fit minmax(330px,1fr)`, `gap:6px 34px`. Fila: índice/EQ 18px, carátula 38px, título + artista, reproducciones 11px y duración 11.5px. - -**g) Tus playlists** — tarjetas anchas `minmax(258px,1fr)` gap 14px: portada 62px radio 11px, nombre 13.5px/600, nº de canciones 11.5px, artistas principales 11px `#696a6d`, play en hover. Enlace "VER TODAS" en la cabecera. - -### 4. Descubrir - -H1 28px + sub. Mosaico de géneros `minmax(228px,1fr)` gap 14px: tarjetas de 112px, radio 16px, fondo `linear-gradient(140deg, oklch(0.24 0.07 Hgénero), rgba(9,9,12,.95))`, borde `rgba(255,255,255,.05)`, nombre Sora 15.5px, meta 11.5px, y una miniatura de 80px rotada 20° asomando en la esquina inferior derecha (`opacity:.82`). Debajo, "Fuera de tu burbuja" con la misma tarjeta cuadrada de Mixes. - -### 5. Tracklist (Me gusta / Reciente / Playlist) - -Cabecera: portada 164px radio 18px + eyebrow (`Colección` / `Historial` / `Playlist`), H1 33px, meta 12.5px, botón "Reproducir" y un botón cuadrado 40px de "aleatorio". - -Tabla: `grid-template-columns: 32px 1fr 1fr 92px; gap:16px`. Cabecera 10.5px uppercase `#616165` con borde inferior `rgba(255,255,255,.05)`. Fila `padding:10px 14px; radius:12px`: -- Col 1: número o, si es la pista activa, EQ de 3 barras de 2.5px en `accent`. -- Col 2: carátula 40px radio 9px + título 13px/500 + artista 11.5px. -- Col 3: álbum (o `—` si falta). -- Col 4: corazón (14px; visible siempre si está marcado, si no solo en hover) + duración tabular. -- Activa: fondo `accentSoft`, título `accentTitle`. Hover: `rgba(255,255,255,.032)`. - -### 5b. Resultados de búsqueda - -**Vista propia, no una tracklist.** La búsqueda devuelve canciones, álbumes, artistas y playlists, así que no lleva portada-hero ni columnas de tabla: es una lista agrupada donde cada tipo se reconoce a simple vista. - -**Cabecera** (`margin:12px 0 18px`): eyebrow `RESULTADOS DE BÚSQUEDA` (10.5px uppercase, tracking .16em, `#8a8a8e`, 600) · H1 Sora 26px/600 tracking -0.03em `#d9d8dc` con el texto `Resultados para «{query}»` · meta 12.5px `#8a8a8e`: `{n} coincidencias en canciones, álbumes, artistas y playlists` (singular "coincidencia" con 1). - -**Chips de filtro** (`display:flex; gap:7px; flex-wrap:wrap; margin-bottom:26px`): `Todo`, `Canciones`, `Álbumes`, `Artistas`, `Playlists`. Cada chip `padding:7px 14px; radius:999px; font-size:12px/500` y lleva a su derecha el contador en 10.5px tabular-nums. -- Activo: fondo `#cfccd9`, texto `#0a0a0d`, contador `rgba(10,10,13,.55)`, sin borde. -- Inactivo: fondo `rgba(255,255,255,.03)`, texto `#9b9b9f`, contador `#65656a`, borde `1px solid rgba(255,255,255,.07)`. -- Transición `background .16s, color .16s`. - -**Mejor resultado** (solo con el filtro `Todo`): fila-tarjeta `display:flex; gap:20px; padding:18px; radius:18px; border:1px solid rgba(255,255,255,.06)`, fondo `rgba(255,255,255,.025)` → `.05` en hover, `margin-bottom:34px`. Miniatura 88px con el radio del tipo y `box-shadow:0 14px 34px rgba(0,0,0,.5)`. Eyebrow `Mejor resultado · {Tipo}` 10.5px uppercase tracking .14em en el **tinte del tipo**; título Sora 22px/600 tracking -0.03em `#dcdbe0`; subtítulo 12.5px `#84848a`. A la derecha, botón circular 46px `#c6c4cb` / icono `#0a0a0d`, `opacity .55` → `1` en hover. -Selección: el primer elemento cuyo nombre **empieza** por la consulta, recorriendo Artista → Canción → Álbum → Playlist; si ninguno empieza por ella, el primer resultado del primer grupo no vacío. - -**Grupos** (`margin-bottom:30px` cada uno). Cabecera de grupo: título Sora 14.5px/600 `#cfccd9` + regla `1px rgba(255,255,255,.06)` que ocupa el espacio libre + contador 11px `#6e6e74` (`{n} resultados`). Con filtro `Todo` cada grupo muestra **máximo 4** elementos; al filtrar por un tipo se muestran todos los de ese tipo. - -**Fila de resultado:** `grid-template-columns: 52px 1fr auto; gap:15px; padding:9px 12px; radius:12px; border-bottom:1px solid rgba(255,255,255,.035)`; fondo transparente → `rgba(255,255,255,.035)` en hover (`.15s ease`), sin elevación. -- Miniatura 52px con degradado de respaldo del hue del elemento y overlay `rgba(6,6,9,.55)` + play 15px `#e2e1e6` que aparece en hover (`opacity 0 → 1`). -- Título 13.5px/500 `#cbcacf` → `#e0dfe4` en hover, seguido del **badge de tipo**: 9.5px uppercase, tracking .1em, 600, `padding:3px 7px; radius:5px`, color del tinte del tipo sobre el mismo tinte al 11%. -- Subtítulo 11.5px `#7f7f83` (una línea, ellipsis). -- Meta a la derecha 11.5px `#76767c` tabular-nums. - -**Diferenciación por tipo** — la forma de la miniatura es la señal primaria; el badge la confirma. El tinte se deriva del hue de la canción en reproducción con un desplazamiento fijo, así que la vista sigue siendo cromáticamente coherente con el resto de la app: - -| Tipo | Radio de miniatura | Tinte | Subtítulo | Meta | -|---|---|---|---|---| -| Canción | `9px` (cuadrado suave) | `oklch(0.80 0.10 H)` | `artista · álbum` | duración | -| Álbum | `5px` (casi recto) | `oklch(0.80 0.10 H+46)` | `artista · año` | `Álbum` | -| Artista | `50%` (círculo) | `oklch(0.80 0.10 H-52)` | oyentes | `Artista` | -| Playlist | `13px` (muy redondeado) | `oklch(0.80 0.10 H+92)` | artistas principales | `{n} canciones` | - -Orden de los grupos: Canciones, Álbumes, Artistas, Playlists. Los grupos vacíos no se renderizan. - -**Coincidencias:** canciones por título + artista + álbum; álbumes por título + `artista · año`; artistas por nombre; playlists por nombre + artistas principales. Todo en minúsculas, `includes`. - -**Acciones:** canción → fija la pista y reproduce; álbum y artista → reproducen; playlist → abre la vista de playlist con su contexto y limpia la búsqueda. - -### 6. Índice de playlists - -H1 "Tus playlists" + meta agregada, botón "Nueva playlist" secundario, grid `minmax(196px,1fr)` gap 22px de tarjetas cuadradas con nombre, nº de canciones y artistas principales. - -### 7. Cola (aside derecho) - -`border-left:1px solid hairline; background: panelBg; padding:20px 16px` + padding inferior dinámico. -- Cabecera "En cola" (Sora 14.5px) + cerrar "×". -- "REPRODUCIENDO": tarjeta con fondo `accentSoft`, borde `accentLine`, carátula 40px, título en `accentTitle`. -- Cabecera "A CONTINUACIÓN · {playlist}" con `gap:12px`; la etiqueta trunca con elipsis (`flex:1 1 auto; min-width:0; nowrap`) y "Vaciar" es `flex:0 0 auto`. -- Lista scrollable: miniatura 36px, título 12px, artista 11px, duración. - -### 8. Player (siempre visible) - -Barra flotante: `radius:18px; padding:11px 16px; background: barBg; backdrop-filter: blur(22px); border:1px solid hairline; box-shadow:0 20px 56px rgba(0,0,0,.6)`; `pointer-events:none` en el contenedor y `auto` en la barra. - -- **Izquierda (256px):** carátula 48px radio 11px, título 13px/600, artista · álbum 11.5px, corazón 16px (activo en `accent`). -- **Centro (flex:1):** shuffle · anterior · play/pausa · siguiente · repetir, gap 14px. Play: círculo 40px `#c6c4cb` con icono `#0a0a0d`, hover `#d6d5da` (**sin scale**). Shuffle/repeat activos en `accent`, inactivos `#747478`. - Progreso: tiempo transcurrido (10.5px tabular, ancho mín. 32px) · pista `rgba(255,255,255,.09)` de 3.5px con relleno en `accent` · duración. Clic en la pista = seek proporcional. -- **Derecha (256px):** letra, volumen (icono + pista de 84px con relleno `#8e8c98`), y botón de cola. Oculto por completo en móvil. - -### 9. Barra de pestañas (`< 1180px`) - -Bajo el player, `margin-top:10px; padding:7px; radius:18px`, mismo `barBg` y blur. Icono 17px + etiqueta 10px, distribuidos con `space-around`. Muestra los 5 ítems de navegación. - ---- - -## Estados - -- **Loading (skeleton):** bloque de hero de 260px + 2 secciones de 6 tarjetas. Gradiente `linear-gradient(90deg, rgba(255,255,255,.025), .055, .025)` con `background-size:420px 100%` y `animation: shim 1.25s linear infinite` (`-420px 0` → `420px 0`). Se muestra 900ms al arrancar. -- **Error:** cuadro 52px con "!" (`rgba(226,130,130,.08)` / borde `.18` / texto `#e09292`), título 20px, cuerpo 13px, botones "Reintentar" (primario) y "Ver descargas". Copy: "No se pudo cargar tu música" / "La conexión se interrumpió. Lo que tengas descargado sigue disponible sin conexión." Reintentar vuelve al skeleton 800ms. -- **Vacío:** icono 70px radio 19px con degradado tenue, título 20px, cuerpo 13px, CTA primario + "Volver al inicio". Dos variantes de copy: playlists sin crear y "me gusta" sin canciones. -- **Sin resultados:** se muestra cuando **ningún** tipo tiene coincidencias (canciones + álbumes + artistas + playlists = 0). Título `Sin resultados para "{query}"`, cuerpo de ayuda y 4 chips de sugerencia (radio 999px, borde `rgba(255,255,255,.08)`, 12px). -- **Datos incompletos:** si falta el álbum, la columna muestra `—` y el player omite el `· álbum`; si falta el subtítulo de una tarjeta, "Sin información". Toda carátula tiene un degradado de respaldo detrás de la imagen. - ---- - -## Interacciones - -| Elemento | Comportamiento | -|---|---| -| Nav / tabs | Cambia de vista y limpia la búsqueda | -| Playlist (sidebar, tarjeta, índice, spotlight) | Abre la vista de playlist con su contexto | -| Tarjeta / fila de canción | Fija la pista, `pos = 0`, `playing = true` | -| Play/pausa | Alterna reproducción (el reloj avanza 1s por segundo) | -| Siguiente / anterior | Cíclicos sobre el array de pistas, resetean la posición | -| Pista de progreso | Clic → `pos = (x / ancho) * duración` | -| Pista de volumen | Clic → `vol` entre 0 y 1 | -| Corazón (fila o player) | Alterna en el mapa `liked` | -| Shuffle / repeat | Alternan, se tiñen de `accent` | -| Botón "Cola" | Abre/cierra el aside | -| Buscar | Filtra canciones, álbumes, artistas y playlists → vista de resultados agrupada; vacío → vuelve a la vista normal; 0 coincidencias en total → estado "sin resultados" | -| Chip de filtro de resultados | Fija `sfilter`; `Todo` recorta cada grupo a 4, un tipo concreto muestra todos | -| Nueva playlist (sidebar / índice) | Abre el modal de crear playlist | - -**Animación — reglas:** -- **Nada de elevación en hover.** Se eliminó a propósito: el feedback es solo un cambio de fondo y la aparición del botón de play. -- Hover de fondo/color: `.15–.18s ease`. Play del player: `.14s` solo de color, sin `scale`. -- Cambio de tinte por canción: `.6s ease`. -- Entrada de vista: `rise` (`opacity 0 → 1`, `translateY(12px) → 0`) en `.3s ease`. Cola: `.22s`. -- EQ de pista activa: `eq` `.9s ease-in-out infinite` alternando `scaleY(.25)` y `scaleY(1)`, con desfases de 0.25/0.5s (0.3/0.6s en el sidebar). - ---- - -## Estado necesario - -``` -view 'home' | 'explore' | 'playlists' | 'playlist' | 'liked' | 'recent' -listCtx nombre de la playlist abierta -idx índice de la pista en reproducción -playing boolean -pos segundos transcurridos (intervalo de 1s, vuelve a 0 al llegar a la duración) -vol 0..1 -queueOpen boolean (forzado a false por debajo de 760px) -query texto de búsqueda -sfilter 'Todo' | 'Canciones' | 'Álbumes' | 'Artistas' | 'Playlists' (filtro de resultados) -liked { [trackId]: true } -shuffle / repeat boolean -hover clave del elemento con hover (o null) -w ancho de ventana (listener de resize) -demoState 'normal' | 'loading' | 'error' | 'empty' (solo para demostrar estados) -``` - -### Datos esperados - -`Track { id, title, artist, album?, duration, cover?, hue, plays? }` · -`Album { title, artist, year, cover? }` · -`Artist { name, listeners, photo? }` · -`Playlist { name, trackCount, topArtists, cover?, isPlaying? }` - -Todos los campos opcionales deben tener degradado o texto de respaldo. El `hue` debería calcularse en backend desde la carátula (color dominante, con saturación mínima garantizada) y venir en el payload; en el prototipo está precalculado por pista. - ---- - -## Modal: crear playlist - -Diseño aparte en `Crear playlist.dc.html`. Se invoca desde "Nueva playlist" (sidebar e índice de playlists). - -**Scrim:** `rgba(4,4,6,.55)` + `backdrop-filter: blur(3px)` sobre el fondo `radial-gradient(120% 90% at 50% 0%, #15131c, #08080b 58%, #050507)`. Modal centrado con `display:grid; place-items:center; padding:40px 20px`. - -**Contenedor:** `max-width:560px; radius:24px; border:1px solid rgba(255,255,255,.075)`, fondo `linear-gradient(180deg,#141419,#0d0d11 62%,#0b0b0e)`, `box-shadow:0 32px 90px rgba(0,0,0,.66)` + `inset 0 2px 0 rgba(255,255,255,.035)`. Entrada `modalIn .28s cubic-bezier(.2,.8,.3,1)` (`opacity 0 → 1`, `translateY(14px) scale(.985)` → sin transformar). - -**Aura:** capa absoluta no interactiva `radial-gradient(110% 60% at 18% -10%, oklch(.55 .13 H / .16), transparent 62%)`, con `transition: background .5s` — vira con el acento elegido. - -**Header** (`padding:24px 26px 0`): eyebrow `TU BIBLIOTECA` 10.5px uppercase tracking .16em `#8f8f93`; título Sora 21px/600 tracking -0.03em `#d8d7db` "Crear playlist". Cerrar: 32px, radio 10px, borde `rgba(255,255,255,.06)`, fondo `rgba(255,255,255,.025)` → `.07` y color `#87878c` → `#d0cfd4` en hover. - -**Portada** (columna izquierda, 124px): -- Cuadrado 124px radio 16px, `linear-gradient(150deg, oklch(.66 .16 H), oklch(.34 .11 H) 58%, #0e0e13)`, borde `rgba(255,255,255,.07)`, `box-shadow:0 14px 34px oklch(.5 .13 H / .22)`, con el icono de nota 26px `rgba(255,255,255,.62)` centrado. Transición `.45s` al cambiar de acento. -- **Selector de acento:** 5 franjas `flex:1; height:20px; radius:7px` (gap 6px, `margin-top:11px`), cada una `linear-gradient(145deg, oklch(.66 .16 h), oklch(.38 .11 h))`. Hues: Ámbar 68, Violeta 288 (por defecto), Azul 244, Verde 158, Rojo 22. Seleccionada: `box-shadow:0 0 0 1.5px rgba(255,255,255,.85), 0 0 0 4px rgba(0,0,0,.5)`; el resto `0 0 0 1px rgba(255,255,255,.07)`. -- **Subir imagen:** botón de texto 11px `#8a8a8f`, `padding:7px 0; radius:9px`, borde `1px dashed rgba(255,255,255,.1)`; hover texto `#cfccd9` y borde `rgba(255,255,255,.2)`. - -**Campos** (columna derecha, `gap:20px` respecto a la portada): -- Etiquetas 11px/600 `#87878c`. -- Nombre: `padding:12px 14px; radius:12px`, fondo `rgba(255,255,255,.035)`, borde `rgba(255,255,255,.075)`, texto **Sora 16px/600** tracking -0.02em `#dcdbe0`, placeholder "Playlist sin título" `#5d5d63`, `maxlength 60`. Foco: borde `rgba(255,255,255,.2)`, fondo `.055`. Contador `{n}/60` 10.5px `#65656a` alineado a la derecha. -- Descripción (opcional): `textarea` 3 filas, `resize:none`, 12.5px/1.6 `#c4c3c9`, mismo tratamiento de superficie y foco. Placeholder "Para qué sirve esta playlist, cuándo la escuchas…". - -**Opciones** (`padding:20px 26px 0`, dos bloques `radius:13px; padding:13px 15px`, fondo `rgba(255,255,255,.026)`, borde `rgba(255,255,255,.055)`, gap 9px): -- **Visibilidad** — segmentado de 2 (`Privada` por defecto / `Pública`) en un riel `radius:10px` `rgba(0,0,0,.34)`; opción activa fondo `#cfccd9` texto `#0a0a0d`, inactiva `#8e8e94`. El texto de ayuda cambia: "Solo tú la ves en tu biblioteca" / "Aparece en tu perfil y se puede compartir". -- **Colaborativa** — toggle 40×23px, riel `rgba(255,255,255,.12)` → `oklch(.68 .15 H)` al activar, perilla 17px `#0c0c10` con `translateX(17px)`, `.2s cubic-bezier(.3,.8,.3,1)`. Ayuda: "Quien tenga el enlace puede añadir canciones". Toda la fila es clicable. - -**Footer** (`border-top:1px solid rgba(255,255,255,.055)`, fondo `rgba(0,0,0,.2)`, `padding:17px 26px 20px`): nota 11px `#6e6e74` "Podrás añadir canciones desde cualquier pantalla."; a la derecha "Cancelar" (secundario, borde `rgba(255,255,255,.1)`, `#a9a7b2`) y "Crear playlist" (primario con icono +). - -**Validación:** el CTA solo se habilita con nombre no vacío (`trim`). Deshabilitado: fondo `rgba(255,255,255,.08)`, texto `#6c6c72`, `cursor:not-allowed`. Habilitado: `#c6c4cb` sobre `#0a0a0d`. - -**Confirmación:** al crear, toast fijo abajo-centro (`bottom:34px`, `radius:13px`, fondo `#16161c`, borde `rgba(255,255,255,.09)`, `box-shadow:0 18px 46px rgba(0,0,0,.6)`, `fadeIn .22s`) con un cuadrado 26px del degradado elegido y el texto «{nombre}» creada. Se oculta a los 2.6s. - -**Estado:** `{ name, desc, hue: 0..4, vis: 'Privada'|'Pública', collab: boolean, created: boolean, createdName }`. -**Salida esperada:** `POST /playlists { name, description, coverHue, visibility, collaborative }` → redirigir a la playlist recién creada. - ---- - -## Copy dinámico - -Saludo del hero según hora y día de la semana: - -- `< 5h` → "¿Sesión de madrugada, {nombre}?" -- `< 13h` → "Buenos días, {nombre}" -- `< 20h` → "Buenas tardes, {nombre}" (miércoles → "Feliz miércoles"; viernes → "Feliz viernes") -- `>= 20h` → "Buenas noches, {nombre}" -- Sábado/domingo → "Que tengas buen finde, {nombre}" (o "¿Madrugada de finde, {nombre}?" antes de las 5h) - ---- - -## Assets - -- **Carátulas y retratos:** marcadores de posición fotográficos servidos por `picsum.photos` con una semilla por elemento, pintados como `background-image` (no ``) para evitar peticiones fallidas mientras se resuelven los datos. Sustituir por las imágenes reales del catálogo. -- **Iconos:** SVG inline, `stroke-width` 1.6–1.8, `stroke-linecap:round`. Reemplazables por el icon set del codebase. -- **Fuentes:** Sora y Plus Jakarta Sans (Google Fonts). -- Sin logotipos de terceros. El wordmark de Musify es tipográfico + el cuadrado con degradado. - -## Files - -- `Crear playlist.dc.html` — modal de creación de playlist (diseño aparte). -- `Musify.dc.html` — prototipo completo (plantilla + lógica + datos de ejemplo). Contiene todas las vistas y estados; el selector `demoState` permite ver loading / error / empty. -- `support.js` — runtime del prototipo. **No portar**: solo hace funcionar el HTML de referencia. -- `screenshots/` — capturas de referencia (viewport ~924px, es decir en modo tablet: sidebar plegado a barra de pestañas inferior): - - `01-home-hero.png` … `04-home-populares-playlists.png` — recorrido vertical de Home - - `05-descubrir.png`, `06-playlists.png`, `07-tracklist-me-gusta.png`, `08-sin-resultados.png` - Nota: las capturas son anteriores al rediseño de la vista de resultados de búsqueda (5b) y al modal de crear playlist; para esos dos, la referencia son los archivos HTML y este documento. - Todas con "Yankee" sonando, de ahí el tinte ámbar: con otra pista el mismo layout se ve en otro color. diff --git a/web-player/design_handoff_musify_player/screenshots/01-home-hero.png b/web-player/design_handoff_musify_player/screenshots/01-home-hero.png deleted file mode 100644 index deed3a9..0000000 Binary files a/web-player/design_handoff_musify_player/screenshots/01-home-hero.png and /dev/null differ diff --git a/web-player/design_handoff_musify_player/screenshots/02-home-continuar-spotlight.png b/web-player/design_handoff_musify_player/screenshots/02-home-continuar-spotlight.png deleted file mode 100644 index 614e61f..0000000 Binary files a/web-player/design_handoff_musify_player/screenshots/02-home-continuar-spotlight.png and /dev/null differ diff --git a/web-player/design_handoff_musify_player/screenshots/03-home-mixes-artistas.png b/web-player/design_handoff_musify_player/screenshots/03-home-mixes-artistas.png deleted file mode 100644 index f7a6ecf..0000000 Binary files a/web-player/design_handoff_musify_player/screenshots/03-home-mixes-artistas.png and /dev/null differ diff --git a/web-player/design_handoff_musify_player/screenshots/04-home-populares-playlists.png b/web-player/design_handoff_musify_player/screenshots/04-home-populares-playlists.png deleted file mode 100644 index 8ad3399..0000000 Binary files a/web-player/design_handoff_musify_player/screenshots/04-home-populares-playlists.png and /dev/null differ diff --git a/web-player/design_handoff_musify_player/screenshots/05-descubrir.png b/web-player/design_handoff_musify_player/screenshots/05-descubrir.png deleted file mode 100644 index a5f9424..0000000 Binary files a/web-player/design_handoff_musify_player/screenshots/05-descubrir.png and /dev/null differ diff --git a/web-player/design_handoff_musify_player/screenshots/06-playlists.png b/web-player/design_handoff_musify_player/screenshots/06-playlists.png deleted file mode 100644 index 37e8b8c..0000000 Binary files a/web-player/design_handoff_musify_player/screenshots/06-playlists.png and /dev/null differ diff --git a/web-player/design_handoff_musify_player/screenshots/07-tracklist-me-gusta.png b/web-player/design_handoff_musify_player/screenshots/07-tracklist-me-gusta.png deleted file mode 100644 index 125a458..0000000 Binary files a/web-player/design_handoff_musify_player/screenshots/07-tracklist-me-gusta.png and /dev/null differ diff --git a/web-player/design_handoff_musify_player/screenshots/08-sin-resultados.png b/web-player/design_handoff_musify_player/screenshots/08-sin-resultados.png deleted file mode 100644 index 98ebf7f..0000000 Binary files a/web-player/design_handoff_musify_player/screenshots/08-sin-resultados.png and /dev/null differ diff --git a/web-player/design_handoff_musify_player/support.js b/web-player/design_handoff_musify_player/support.js deleted file mode 100644 index cb009b6..0000000 --- a/web-player/design_handoff_musify_player/support.js +++ /dev/null @@ -1,1911 +0,0 @@ -// GENERATED from dc-runtime/src/*.ts — do not edit. Rebuild with `cd dc-runtime && bun run build`. -"use strict"; -(() => { - var __defProp = Object.defineProperty; - var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value; - var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value); - - // src/react.ts - function getReact() { - const R = window.React; - if (!R) throw new Error("dc-runtime: window.React is not available yet"); - return R; - } - function getReactDOM() { - const RD = window.ReactDOM; - if (!RD) throw new Error("dc-runtime: window.ReactDOM is not available yet"); - return RD; - } - var h = ((...args) => getReact().createElement( - ...args - )); - - // src/parse.ts - function parseDcDocument(doc) { - const dc = doc.querySelector("x-dc"); - if (!dc) return null; - const scriptEl = doc.querySelector("script[data-dc-script]"); - const { props, preview } = parseDataProps( - scriptEl?.getAttribute("data-props") ?? null - ); - return { - template: dc.innerHTML, - js: scriptEl ? scriptEl.textContent || "" : "", - props, - preview - }; - } - function parseDcText(src) { - const openMatch = /]*)?>/.exec(src); - if (!openMatch) return null; - const close = src.lastIndexOf(""); - if (close === -1 || close < openMatch.index) return null; - const template = src.slice(openMatch.index + openMatch[0].length, close); - const doc = new DOMParser().parseFromString(src, "text/html"); - const scriptEl = doc.querySelector("script[data-dc-script]"); - const { props, preview } = parseDataProps( - scriptEl?.getAttribute("data-props") ?? null - ); - return { - template, - js: scriptEl ? scriptEl.textContent || "" : "", - props, - preview - }; - } - function parseDataProps(raw) { - if (!raw) return { props: null, preview: null }; - let parsed; - try { - parsed = JSON.parse(raw); - } catch { - return { props: null, preview: null }; - } - if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) { - return { props: null, preview: null }; - } - const obj = parsed; - const preview = obj.$preview && typeof obj.$preview === "object" ? obj.$preview : null; - const rest = {}; - for (const k of Object.keys(obj)) { - if (k[0] !== "$") rest[k] = obj[k]; - } - return { props: Object.keys(rest).length ? rest : null, preview }; - } - function dcNameFromPath(pathname) { - let p = pathname || ""; - try { - p = decodeURIComponent(p); - } catch { - } - const base = p.split("/").pop() || "Root"; - return base.replace(/\.dc\.html$/, "").replace(/\.html?$/, "") || "Root"; - } - - // src/boot.ts - var BASE_CSS = ` - .sc-placeholder{background:color-mix(in srgb,currentColor 8%,transparent); - border:1px solid color-mix(in srgb,currentColor 50%,transparent); - border-radius:2px;box-sizing:border-box;overflow:hidden} - @keyframes sc-shine{0%{background-position:100% 50%}100%{background-position:0% 50%}} - html.sc-dc-streaming .sc-placeholder, - html.sc-dc-streaming .sc-interp.sc-missing{position:relative; - background:color-mix(in srgb,currentColor 5%,transparent); - border-color:transparent} - html.sc-dc-streaming .sc-placeholder::before, - html.sc-dc-streaming .sc-interp.sc-missing::before{content:''; - position:absolute;inset:0;pointer-events:none; - background:linear-gradient(90deg,rgba(217,119,87,0) 25%,rgba(247,225,211,.95) 37%,rgba(217,119,87,0) 63%); - background-size:400% 100%;animation:sc-shine 1.4s ease infinite} - html.sc-dc-streaming .sc-placeholder:nth-child(n+9 of .sc-placeholder)::before, - html.sc-dc-streaming .sc-interp.sc-missing:nth-child(n+9 of .sc-interp.sc-missing)::before{animation:none; - background:color-mix(in srgb,currentColor 8%,transparent)} - .sc-placeholder-error{padding:4px 8px;font:11px/1.4 ui-monospace,monospace; - color:color-mix(in srgb,currentColor 70%,transparent);word-break:break-word} - .sc-interp.sc-missing{display:inline-block;width:2em;height:1em;overflow:hidden; - vertical-align:text-bottom;background:rgba(255,255,255,.3);border:1px solid rgba(0,0,0,.5); - border-radius:2px;box-sizing:border-box;color:transparent; - user-select:none} - .sc-interp.sc-unresolved{font-family:ui-monospace,monospace;font-size:.85em; - color:color-mix(in srgb,currentColor 50%,transparent); - background:color-mix(in srgb,currentColor 10%,transparent);border-radius:3px; - padding:0 3px} - .sc-host.sc-has-error{position:relative} - .sc-logic-error{position:absolute;top:8px;left:8px;z-index:2147483647;max-width:60ch; - padding:6px 10px;background:#b00020;color:#fff;font:12px/1.4 ui-monospace,monospace; - border-radius:4px;white-space:pre-wrap;pointer-events:none} - /* Mirrors PRINT_BASELINE_CSS in apps/web deck-stage-export.ts \u2014 keep both - in sync until dc-runtime regains a build step. */ - @media print { - @page { margin: 0.5cm; } - figure, table { break-inside: avoid; } - #dc-root, #dc-root > .sc-host { height: auto; } - *, *::before, *::after { - print-color-adjust: exact; -webkit-print-color-adjust: exact; - backdrop-filter: none !important; -webkit-backdrop-filter: none !important; - animation-delay: -99s !important; animation-duration: .001s !important; - animation-iteration-count: 1 !important; animation-fill-mode: both !important; - animation-play-state: running !important; transition-duration: 0s !important; - } - } - `; - var FULL_PAGE_CSS = "html,body{height:100%;margin:0}#dc-root,#dc-root>.sc-host{height:100%}"; - function rootNameForDocument(doc, loc) { - let bootPath = loc.pathname || ""; - if (!/\.dc\.html?$/i.test(safeDecode(bootPath))) { - try { - bootPath = new URL(doc.baseURI || "/").pathname; - } catch { - } - } - return dcNameFromPath(bootPath); - } - function safeDecode(s) { - try { - return decodeURIComponent(s); - } catch { - return s; - } - } - function boot(runtime, doc = document) { - const parsed = parseDcDocument(doc); - if (!parsed) return null; - const React = getReact(); - const rootName = rootNameForDocument(doc, location); - runtime.markFetched(rootName); - runtime.setRootName(rootName); - runtime.adoptParsed(rootName, parsed); - if (!window.__resources) { - fetch(location.href).then((res) => res.ok ? res.text() : "").then((t) => { - const raw = t ? parseDcText(t) : null; - if (raw?.template) runtime.updateHtml(rootName, raw.template); - }).catch(() => { - }); - } - const dc = doc.querySelector("x-dc"); - const hostEl = doc.createElement("div"); - hostEl.id = "dc-root"; - dc.replaceWith(hostEl); - if (!parsed.preview) { - const s = doc.createElement("style"); - s.textContent = FULL_PAGE_CSS; - doc.head.appendChild(s); - } - const Root = runtime.getDC(rootName); - const entry = runtime.registry.get(rootName); - function StandaloneRoot() { - const [, setTick] = React.useState(0); - React.useEffect(() => { - const sub = () => setTick((n) => n + 1); - entry.subs.add(sub); - return () => { - entry.subs.delete(sub); - }; - }, []); - const defaults = React.useMemo(() => { - const d = {}; - for (const k in entry.propsMeta || {}) { - const v = entry.propsMeta?.[k]?.default; - if (v !== void 0) d[k] = v; - } - return d; - }, [entry.propsMeta]); - return h(Root, { ...defaults, ...entry.propOverrides || {} }); - } - const ReactDOM = getReactDOM(); - if (ReactDOM.createRoot) - ReactDOM.createRoot(hostEl).render(h(StandaloneRoot)); - else ReactDOM.render(h(StandaloneRoot), hostEl); - return rootName; - } - - // src/expr.ts - var IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*/; - var NUMBER_RE = /^-?\d+(\.\d+)?$/; - function resolve(vals, src) { - const expr = String(src).trim(); - if (!expr) return void 0; - if (expr[0] === "(" && expr[expr.length - 1] === ")" && parensWrapWhole(expr)) { - return resolve(vals, expr.slice(1, -1)); - } - const eq = findTopLevelEquality(expr); - if (eq) { - const lv = resolve(vals, expr.slice(0, eq.index)); - const rv = resolve(vals, expr.slice(eq.index + eq.op.length)); - switch (eq.op) { - case "===": - return lv === rv; - case "!==": - return lv !== rv; - case "==": - return lv == rv; - default: - return lv != rv; - } - } - if (expr[0] === "!") return !resolve(vals, expr.slice(1)); - if (expr === "true") return true; - if (expr === "false") return false; - if (expr === "null") return null; - if (expr === "undefined") return void 0; - if (NUMBER_RE.test(expr)) return Number(expr); - if (expr.length >= 2 && (expr[0] === '"' || expr[0] === "'") && expr[expr.length - 1] === expr[0]) { - return expr.slice(1, -1); - } - return resolvePath(vals, expr); - } - function parensWrapWhole(expr) { - let depth = 0; - for (let i = 0; i < expr.length - 1; i++) { - if (expr[i] === "(") depth++; - else if (expr[i] === ")") { - depth--; - if (depth === 0) return false; - } - } - return true; - } - function findTopLevelEquality(expr) { - let depth = 0; - for (let i = 0; i < expr.length; i++) { - const c = expr[i]; - if (c === "[" || c === "(") depth++; - else if (c === "]" || c === ")") depth--; - else if (depth === 0 && (c === "=" || c === "!") && expr[i + 1] === "=") { - if (i > 0 && (expr[i - 1] === "=" || expr[i - 1] === "!")) continue; - if (!expr.slice(0, i).trim()) continue; - const op = expr[i + 2] === "=" ? c + "==" : c + "="; - return { index: i, op }; - } - } - return null; - } - function resolvePath(vals, expr) { - const head = expr.match(IDENT_RE); - if (!head) return void 0; - let cur = vals == null ? void 0 : vals[head[0]]; - let i = head[0].length; - while (i < expr.length) { - if (expr[i] === ".") { - const m = expr.slice(i + 1).match(IDENT_RE) || expr.slice(i + 1).match(/^\d+/); - if (!m) return void 0; - cur = cur == null ? void 0 : cur[m[0]]; - i += 1 + m[0].length; - } else if (expr[i] === "[") { - let depth = 1; - let j = i + 1; - while (j < expr.length && depth > 0) { - if (expr[j] === "[") depth++; - else if (expr[j] === "]") { - depth--; - if (depth === 0) break; - } - j++; - } - if (depth !== 0) return void 0; - const key = resolve(vals, expr.slice(i + 1, j)); - cur = cur == null ? void 0 : cur[key]; - i = j + 1; - } else { - return void 0; - } - } - return cur; - } - - // src/encode.ts - var CAMEL_ATTR = "sc-camel-"; - var INLINE_TEXT_TAGS = new Set( - "a abbr b bdi bdo br cite code del dfn em i ins kbd mark q s samp small span strike strong sub sup u var wbr".split( - " " - ) - ); - var RAW_WRAP = { - select: "sc-raw-select", - table: "sc-raw-table", - tbody: "sc-raw-tbody", - thead: "sc-raw-thead", - tfoot: "sc-raw-tfoot", - tr: "sc-raw-tr", - td: "sc-raw-td", - th: "sc-raw-th", - caption: "sc-raw-caption" - }; - var RAW_UNWRAP = Object.fromEntries( - Object.entries(RAW_WRAP).map(([k, v]) => [v, k]) - ); - var EVENT_MAP = { - onclick: "onClick", - onchange: "onChange", - oninput: "onInput", - onsubmit: "onSubmit", - onkeydown: "onKeyDown", - onkeyup: "onKeyUp", - onkeypress: "onKeyPress", - onmousedown: "onMouseDown", - onmouseup: "onMouseUp", - onmouseenter: "onMouseEnter", - onmouseleave: "onMouseLeave", - onfocus: "onFocus", - onblur: "onBlur", - ondoubleclick: "onDoubleClick", - oncontextmenu: "onContextMenu", - onmousemove: "onMouseMove", - onmouseover: "onMouseOver", - onmouseout: "onMouseOut", - onpointerdown: "onPointerDown", - onpointerup: "onPointerUp", - onpointermove: "onPointerMove", - onpointerenter: "onPointerEnter", - onpointerleave: "onPointerLeave", - onpointercancel: "onPointerCancel", - onpointerover: "onPointerOver", - onpointerout: "onPointerOut", - ongotpointercapture: "onGotPointerCapture", - onlostpointercapture: "onLostPointerCapture", - ontouchstart: "onTouchStart", - ontouchend: "onTouchEnd", - ontouchmove: "onTouchMove", - ontouchcancel: "onTouchCancel", - ondragstart: "onDragStart", - ondragend: "onDragEnd", - ondragenter: "onDragEnter", - ondragleave: "onDragLeave", - ondragover: "onDragOver", - onanimationstart: "onAnimationStart", - onanimationend: "onAnimationEnd", - onanimationiteration: "onAnimationIteration", - ontransitionend: "onTransitionEnd" - }; - var ATTRS = `(?:[^>"']|"[^"]*"|'[^']*')*`; - var IMPORT_SELF_CLOSE_RE = new RegExp( - "<(x-import|dc-import)(" + ATTRS + ")/>", - "gi" - ); - var CAMEL_ATTR_RE = /(\s)([a-z]+[A-Z][A-Za-z0-9]*)(\s*=)/g; - function encodeCamelAttrs(html) { - return html.replace( - CAMEL_ATTR_RE, - (_, sp, name, eq) => sp + CAMEL_ATTR + name.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase()) + eq - ); - } - function encodeCase(html) { - html = html.replace( - IMPORT_SELF_CLOSE_RE, - (_, t, a) => "<" + t + a + ">" - ); - html = html.replace(/)/gi, "/gi, ""); - html = encodeCamelAttrs(html); - for (const [real, alias] of Object.entries(RAW_WRAP)) { - html = html.replace( - new RegExp("(])", "gi"), - "$1" + alias - ); - } - return html; - } - function kebabToCamel(s) { - return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase()); - } - function cssToObj(css) { - const o = {}; - for (const decl of css.split(";")) { - const i = decl.indexOf(":"); - if (i < 0) continue; - const prop = decl.slice(0, i).trim(); - o[prop.startsWith("--") ? prop : kebabToCamel(prop)] = decl.slice(i + 1).trim(); - } - return o; - } - function compileAttr(raw) { - const whole = raw.match(/^\s*\{\{([\s\S]+?)\}\}\s*$/); - if (whole) { - const path = whole[1]; - return (vals) => resolve(vals, path); - } - if (raw.includes("{{")) { - const parts = raw.split(/\{\{([\s\S]+?)\}\}/g); - return (vals) => parts.map((s, i) => i & 1 ? resolve(vals, s) ?? "" : s).join(""); - } - return () => raw; - } - - // src/compile.ts - function collectProps(node, kind, host) { - const propGetters = []; - const pseudoClasses = []; - let hintSize = null; - for (const { name, value } of [...node.attributes]) { - if (name === "sc-name" || name === "data-dc-tpl") continue; - let key = name; - if (key.startsWith(CAMEL_ATTR)) - key = kebabToCamel(key.slice(CAMEL_ATTR.length)); - if (key === "hint-size") { - hintSize = value; - continue; - } - if (key.startsWith("style-")) { - pseudoClasses.push(host.pseudoClass(key.slice(6), value)); - continue; - } - if (kind !== "dom") { - if (key.includes("-") && !(kind === "x-import" && (key.startsWith("aria-") || key.startsWith("data-")))) - key = kebabToCamel(key); - } else { - if (key === "class") key = "className"; - else if (key === "for") key = "htmlFor"; - else if (key.startsWith("on")) - key = EVENT_MAP[key] || "on" + key[2].toUpperCase() + key.slice(3); - } - propGetters.push([key, compileAttr(value)]); - } - return { propGetters, pseudoClasses, hintSize }; - } - var HOST_STYLE_PROPS = /* @__PURE__ */ new Set([ - "position", - "left", - "right", - "top", - "bottom", - "inset", - "width", - "height", - "z-index", - "transform" - ]); - function hostPositionStyle(style) { - const all = typeof style === "string" ? cssToObj(style) : style != null && typeof style === "object" ? style : null; - if (!all) return void 0; - const out = {}; - for (const [k, v] of Object.entries(all)) { - const kebab = k.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase()); - if (HOST_STYLE_PROPS.has(kebab)) out[k] = v; - } - return Object.keys(out).length ? out : void 0; - } - function compileTemplate(html, host) { - const tpl = document.createElement("template"); - //! nosemgrep: direct-inner-html-assignment - tpl.innerHTML = encodeCase(html); - let tplN = 0; - (function stamp(node) { - if (node.nodeType === Node.ELEMENT_NODE) { - node.setAttribute("data-dc-tpl", String(tplN++)); - } - for (const c of node.childNodes) stamp(c); - })(tpl.content); - const builders = walkChildren(tpl.content, host); - const render = ((vals, ctx) => builders.map((b, i) => b(vals || {}, ctx, i))); - render.__annotated = tpl.innerHTML; - return render; - } - function walkChildren(node, host) { - return [...node.childNodes].map((c) => walk(c, host)).filter((b) => b != null); - } - var SLIDE_ID_VALUE_RE = /^[0-9a-f]{8}$/; - var DECK_CONTROL_FLOW_RE = /^(sc-if|sc-for|sc-else|dc-import|x-import)$/; - var DECK_AUX_RE = /^(template|script|style|sc-helmet|helmet)$/; - function isDeckMountTag(el) { - if (el.localName === "deck-stage") return true; - return el.localName === "x-import" && (el.getAttribute("component-from-global-scope") || "") === "deck-stage"; - } - function walkDeckChildren(el, host) { - const pairs = [...el.childNodes].map((c) => ({ c, b: walk(c, host) })).filter((p) => p.b !== null); - const kids = pairs.map((p) => p.b); - const seen = /* @__PURE__ */ new Set(); - const wsSeen = /* @__PURE__ */ new Map(); - const keys = []; - const nextSlideId = new Array(pairs.length); - { - let upcoming = null; - for (let j = pairs.length - 1; j >= 0; j--) { - const n = pairs[j].c; - if (n.nodeType === Node.ELEMENT_NODE) { - const t = n.localName; - upcoming = !DECK_AUX_RE.test(t) && !DECK_CONTROL_FLOW_RE.test(t) ? n.getAttribute("data-om-slide-id") : null; - } - nextSlideId[j] = upcoming; - } - } - for (let j = 0; j < pairs.length; j++) { - const { c } = pairs[j]; - if (c.nodeType === Node.TEXT_NODE) { - if ((c.nodeValue ?? "").trim() === "") { - const base = nextSlideId[j] ? "omid-ws:" + nextSlideId[j] : "omid-ws:aux"; - const n = wsSeen.get(base) ?? 0; - wsSeen.set(base, n + 1); - keys.push(n === 0 ? base : base + ":" + n); - continue; - } - return { kids, keys: null }; - } - if (c.nodeType !== Node.ELEMENT_NODE) { - keys.push(j); - continue; - } - const child = c; - const tag = child.localName; - if (DECK_AUX_RE.test(tag)) { - keys.push(j); - continue; - } - if (DECK_CONTROL_FLOW_RE.test(tag)) return { kids, keys: null }; - const v = child.getAttribute("data-om-slide-id"); - if (!v || !SLIDE_ID_VALUE_RE.test(v) || seen.has(v)) { - return { kids, keys: null }; - } - seen.add(v); - keys.push("omid:" + v); - } - return { kids, keys }; - } - function renderDeckKids(kids, kidKeys, vals, ctx) { - return kids.map((b, j) => { - const k = kidKeys ? kidKeys[j] : j; - const out = b(vals, ctx, k); - return kidKeys != null && typeof out === "string" ? h(getReact().Fragment, { key: k }, out) : out; - }); - } - function walk(node, host) { - if (node.nodeType === Node.TEXT_NODE) return walkText(node); - if (node.nodeType !== Node.ELEMENT_NODE) return null; - const el = node; - const tag = el.tagName.toLowerCase(); - if (tag === "sc-for") return walkFor(el, host); - if (tag === "sc-if") return walkIf(el, host); - if (tag === "x-import") return walkXImport(el, host); - if (tag === "sc-helmet") return host.helmet(el); - if (tag === "dc-import") return walkComponent(el, host); - return walkElement(el, host); - } - var warnedHoles = /* @__PURE__ */ new Set(); - function warnUnresolved(ctx, what) { - const key = (ctx?.__name || "?") + "\0" + what; - if (warnedHoles.has(key)) return; - warnedHoles.add(key); - console.warn("[dc-runtime] " + (ctx?.__name || "template") + ": " + what); - } - function walkText(node) { - const txt = node.nodeValue ?? ""; - if (!txt.includes("{{")) { - if (!txt.trim() && !txt.includes(" ")) return null; - return () => txt; - } - const parts = txt.split(/\{\{([\s\S]+?)\}\}/g); - return (vals, ctx, key) => h( - getReact().Fragment, - { key }, - ...parts.map((p, i) => { - if (!(i & 1)) return p; - const v = resolve(vals, p); - if (v === void 0) { - if (!ctx?.__streamingNow) { - if (document.body?.hasAttribute("data-dc-editor-on")) { - return h( - "span", - { key: i, className: "sc-interp sc-unresolved" }, - "{{ " + p.trim() + " }}" - ); - } - warnUnresolved( - ctx, - "{{ " + p.trim() + " }} never resolved \u2014 rendered as empty" - ); - return null; - } - return h( - "span", - { key: i, className: "sc-interp sc-missing" }, - p.trim() - ); - } - if (getReact().isValidElement(v) || Array.isArray(v)) { - return h(getReact().Fragment, { key: i }, v); - } - if (v === null || typeof v === "boolean") return null; - return h("span", { key: i, className: "sc-interp" }, String(v)); - }) - ); - } - function walkFor(el, host) { - const listGet = compileAttr(el.getAttribute("list") || ""); - const asName = el.getAttribute("as") || "item"; - const hintN = parseInt(el.getAttribute("hint-placeholder-count") || "0", 10); - const kids = walkChildren(el, host); - const listSrc = el.getAttribute("list") || ""; - return (vals, ctx, key) => { - let list = listGet(vals); - if (!Array.isArray(list)) { - if (!ctx?.__streamingNow) { - if (list !== void 0 && list !== null) { - warnUnresolved( - ctx, - 'sc-for list="' + listSrc + '" is not an array (' + typeof list + ")" - ); - } - list = []; - } else { - list = hintN > 0 ? Array(hintN).fill(void 0) : []; - } - } - return h( - getReact().Fragment, - { key }, - list.map((item, i) => { - const sub = { ...vals, [asName]: item, $index: i }; - return h( - getReact().Fragment, - { key: i }, - kids.map((b, j) => b(sub, ctx, j)) - ); - }) - ); - }; - } - function walkIf(el, host) { - const valGet = compileAttr(el.getAttribute("value") || ""); - const hintRaw = el.getAttribute("hint-placeholder-val"); - const hintGet = hintRaw != null ? compileAttr(hintRaw) : null; - const kids = walkChildren(el, host); - return (vals, ctx, key) => { - let v = valGet(vals); - if (v === void 0 && hintGet && ctx?.__streamingNow) v = hintGet(vals); - return v ? h( - getReact().Fragment, - { key }, - kids.map((b, j) => b(vals, ctx, j)) - ) : null; - }; - } - function walkComponent(el, host) { - const name = el.getAttribute("name") || el.getAttribute("component") || ""; - el.removeAttribute("name"); - el.removeAttribute("component"); - const tplId = el.getAttribute("data-dc-tpl"); - const styleRaw = el.getAttribute("style"); - el.removeAttribute("style"); - const styleGet = styleRaw != null ? compileAttr(styleRaw) : null; - const { propGetters, hintSize } = collectProps(el, "dc-import", host); - const kids = walkChildren(el, host); - return (vals, ctx, key) => { - const props = { - key, - __hintSize: hintSize, - __tplId: tplId, - __hostStyle: styleGet ? hostPositionStyle(styleGet(vals)) : void 0 - }; - for (const [k, g] of propGetters) { - const v = g(vals); - if (k === "dcProps") { - if (v && typeof v === "object") Object.assign(props, v); - continue; - } - props[k] = v; - } - if (kids.length) props.children = kids.map((b, j) => b(vals, ctx, j)); - return h(host.component(name), props); - }; - } - function walkXImport(el, host) { - const globalNameGet = compileAttr( - el.getAttribute("component-from-global-scope") || "" - ); - const exportNameGet = compileAttr( - el.getAttribute("component") || el.getAttribute("name") || "" - ); - const fromRaw = el.getAttribute("from") || (el.getAttribute("component-from-global-scope") ? "" : el.getAttribute("src") || el.getAttribute("import") || ""); - const urls = fromRaw.trim() ? fromRaw.trim().split(/\s+/) : []; - const url = urls.length ? urls[urls.length - 1] : ""; - const kindOf = (u) => /\.(jsx|tsx)(\?|#|$)/i.test(u) ? "jsx" : "js"; - const tplId = el.getAttribute("data-dc-tpl"); - const styleRaw = el.getAttribute("style"); - el.removeAttribute("style"); - const styleGet = styleRaw != null ? compileAttr(styleRaw) : null; - const wrap = tplId != null || styleGet != null; - const { propGetters, hintSize } = collectProps(el, "x-import", host); - const hasContent = el.children.length > 0 || !!(el.textContent || "").trim(); - const deckKeyed = hasContent && isDeckMountTag(el) ? walkDeckChildren(el, host) : null; - const kids = deckKeyed ? deckKeyed.kids : hasContent ? walkChildren(el, host) : []; - const kidKeys = deckKeyed?.keys ?? null; - const urlBindable = fromRaw.includes("{{"); - if (urls.length && !urlBindable) { - let prev; - for (const u of urls) prev = host.loadExternal(kindOf(u), u, prev); - } - const evalName = (g, vals) => { - const v = g(vals); - const s = v == null ? "" : String(v); - return s.includes("{{") ? "" : s; - }; - return (vals, ctx, key) => { - const globalName = evalName(globalNameGet, vals); - const name = globalName || evalName(exportNameGet, vals); - const C = !name || urlBindable ? null : globalName ? host.resolveExternalGlobal(url, globalName) : host.resolveExternal(url, name); - const hostStyle = styleGet ? hostPositionStyle(styleGet(vals)) : void 0; - const wrapper = wrap ? { - key, - className: "sc-host-x", - "data-dc-tpl": tplId, - style: hostStyle || { display: "contents" } - } : null; - if (!C) { - const error = urlBindable ? "x-import `from` cannot contain {{ \u2026 }} \u2014 module URLs are resolved at parse time; use a literal URL" : host.resolveExternalError(url, name); - const ph = host.placeholder({ - key: wrapper ? void 0 : key, - name, - hintSize, - error - }); - return wrapper ? h("div", wrapper, ph) : ph; - } - const props = wrapper ? {} : { key }; - let unresolvedHole = false; - for (const [k, g] of propGetters) { - if (k === "component" || k === "componentFromGlobalScope" || k === "from") { - continue; - } - const v = g(vals); - if (v === void 0) unresolvedHole = true; - if (k === "dcProps") { - if (v && typeof v === "object") Object.assign(props, v); - continue; - } - props[k] = v; - } - if (unresolvedHole && ctx?.__htmlStreamingNow) { - const ph = host.placeholder({ - key: wrapper ? void 0 : key, - name, - hintSize, - error: null - }); - return wrapper ? h("div", wrapper, ph) : ph; - } - if (kids.length) { - props.children = renderDeckKids(kids, kidKeys, vals, ctx); - } - return wrapper ? h("div", wrapper, h(C, props)) : h(C, props); - }; - } - function contentKey(el) { - const clone = el.cloneNode(true); - for (const d of clone.querySelectorAll("*")) { - while (d.attributes.length) d.removeAttribute(d.attributes[0].name); - } - const s = clone.innerHTML; - let h2 = 5381; - for (let i = 0; i < s.length; i++) h2 = (h2 << 5) + h2 + s.charCodeAt(i) | 0; - return s.length + "." + (h2 >>> 0).toString(36); - } - var NEVER_CONTENT_KEYED = new Set( - "script style textarea option title select canvas iframe video audio".split( - " " - ) - ); - var NOT_INLINE_SELECTOR = ":not(" + [...INLINE_TEXT_TAGS].join(",") + ")"; - function walkElement(el, host) { - const realTag = RAW_UNWRAP[el.localName] || el.localName; - const tplId = el.getAttribute("data-dc-tpl"); - const inlineOnly = el.childNodes.length > 0 && !NEVER_CONTENT_KEYED.has(realTag) && el.querySelector(NOT_INLINE_SELECTOR) === null; - const keySuffix = inlineOnly ? "|" + contentKey(el) : ""; - const { propGetters, pseudoClasses } = collectProps(el, "dom", host); - const deckKeyed = isDeckMountTag(el) ? walkDeckChildren(el, host) : null; - const kids = deckKeyed ? deckKeyed.kids : walkChildren(el, host); - const kidKeys = deckKeyed?.keys ?? null; - return (vals, ctx, key) => { - const props = { - key: key + keySuffix, - "data-dc-tpl": tplId - }; - for (const [k, g] of propGetters) { - let v = g(vals); - if (k === "style" && typeof v === "string") v = cssToObj(v); - if ((k === "value" || k === "checked") && v === void 0) { - v = k === "checked" ? false : ""; - } - props[k] = v; - } - if (pseudoClasses.length) { - props.className = [props.className, ...pseudoClasses].filter(Boolean).join(" "); - } - return h(realTag, props, ...renderDeckKids(kids, kidKeys, vals, ctx)); - }; - } - - // src/logic.ts - var StreamableLogic = class { - constructor(props) { - __publicField(this, "props"); - __publicField(this, "state", {}); - /** Back-pointer to the wrapper component, installed after construction. */ - __publicField(this, "__host"); - this.props = props || {}; - } - setState(update, cb) { - this.__host && this.__host.__setLogicState(update, cb); - } - forceUpdate() { - this.__host && this.__host.forceUpdate(); - } - componentDidMount() { - } - componentDidUpdate(_prevProps) { - } - componentWillUnmount() { - } - /** The flat object the template renders against (merged over props). */ - renderVals() { - return {}; - } - }; - function evalDcLogic(src) { - //! nosemgrep: eval-and-function-constructor - const fn = new Function( - "DCLogic", - "StreamableLogic", - "React", - src + '\n;return (typeof Component!=="undefined"&&Component)||undefined;' - ); - return fn(StreamableLogic, StreamableLogic, getReact()); - } - - // src/component.ts - function shallowEqual(a, b) { - if (!b) return false; - const ak = Object.keys(a).filter((k) => k !== "children"); - const bk = Object.keys(b).filter((k) => k !== "children"); - if (ak.length !== bk.length) return false; - for (const k of ak) if (a[k] !== b[k]) return false; - return true; - } - function Placeholder({ - name, - hintSize, - streaming, - error - }) { - const [w, hgt] = (hintSize || "100%,60px").split(","); - return h( - "div", - { - className: "sc-placeholder" + (streaming ? " sc-streaming" : ""), - style: { width: w.trim(), height: hgt && hgt.trim() }, - title: name - }, - error ? h( - "div", - { className: "sc-placeholder-error" }, - (name ? name + ": " : "") + error - ) : null - ); - } - function hintToMin(hint) { - if (!hint) return void 0; - const [w, hgt] = hint.split(","); - return { minWidth: w.trim(), minHeight: hgt && hgt.trim() }; - } - function createComponentFactory(registry, ensureFetched) { - const React = getReact(); - const AncestorContext = React.createContext([]); - class StreamableComponent extends React.Component { - constructor(props) { - super(props); - __publicField(this, "__name"); - __publicField(this, "__sub"); - __publicField(this, "__needsDidMount", false); - /** Snapshot of the registry's streaming flags taken at render time — - * builders read it off the RenderCtx (this) to pick placeholder vs - * render-nothing for unresolved values. */ - __publicField(this, "__streamingNow", false); - __publicField(this, "__htmlStreamingNow", false); - /** When a construct throws, remember the (class, registry.ver, props) - * triple so render-time reconcile doesn't re-attempt it on every parent - * re-render. A registry bump (new class, template, external module - * resolving via bumpAll) changes `ver` and breaks the memo so an - * env-dependent constructor can self-heal. */ - __publicField(this, "__failedLogic", null); - __publicField(this, "__failedUserProps", null); - __publicField(this, "__failedVer", -1); - /** Per-instance constructor error — kept here (not on the registry entry) - * so one instance's successful construct can't hide a sibling's failure, - * and a construct can never wipe an eval error `updateJs` recorded on - * `r.logicError`. */ - __publicField(this, "__ctorError", null); - __publicField(this, "logic"); - this.__name = props.__name; - this.state = { __v: 0, __err: null }; - this.__sub = () => { - if (this.state.__err) this.setState({ __err: null }); - this.forceUpdate(); - }; - this.__makeLogic(registry.get(this.__name).Logic, null); - ensureFetched(this.__name); - } - /** Error-boundary hook: a render crash anywhere in this DC's subtree - * (its own template, an x-import'd component, a child DC without its - * own deeper boundary) lands here instead of unmounting the page. */ - static getDerivedStateFromError(e) { - return { __err: e instanceof Error && e.message ? e.message : String(e) }; - } - componentDidCatch(e, info) { - console.error( - "[dc-runtime] render error in <" + this.__name + ">:", - e, - info?.componentStack || "" - ); - } - /** Instantiate the logic class (or the no-op base) and adopt `prevState` - * over its initial state — used both at mount and on hot-swap. */ - __makeLogic(Logic, prevState) { - const L = Logic || StreamableLogic; - try { - this.logic = new L(this.__userProps()); - this.__failedLogic = null; - this.__failedUserProps = null; - this.__ctorError = null; - } catch (e) { - console.error(e); - this.__failedLogic = Logic; - this.__failedUserProps = this.__userProps(); - this.__failedVer = registry.get(this.__name).ver; - this.__ctorError = this.__name + ": " + (e instanceof Error && e.message ? e.message : String(e)); - this.logic = new StreamableLogic( - this.__userProps() - ); - } - this.logic.__host = this; - if (prevState) - this.logic.state = { ...this.logic.state || {}, ...prevState }; - } - /** The props the author's logic + template see — internal __-prefixed - * wiring stripped. */ - __userProps() { - const { __name, __hintSize, __tplId, __hostStyle, ...rest } = this.props; - return rest; - } - __setLogicState(update, cb) { - const prev = this.logic.state; - const patch = typeof update === "function" ? update(prev) : update; - this.logic.state = { ...prev, ...patch }; - this.setState((s) => ({ __v: s.__v + 1 }), cb); - } - /** Swap the logic instance when the registry's Logic class changed - * (streaming completion, hot reload). State carries over; didMount - * re-fires after the swap commits so refs exist. */ - __reconcileLogic() { - const r = registry.get(this.__name); - const Next = r.Logic; - const Cur = this.logic.constructor; - if (Next === Cur || !Next && Cur === StreamableLogic || Next === this.__failedLogic && r.ver === this.__failedVer && shallowEqual(this.__userProps(), this.__failedUserProps)) { - return; - } - if (!this.__needsDidMount) { - try { - this.logic.componentWillUnmount(); - } catch (e) { - console.error(e); - } - } - this.__makeLogic(Next, this.logic.state); - this.__needsDidMount = true; - } - componentDidMount() { - registry.get(this.__name).subs.add(this.__sub); - try { - this.logic.componentDidMount(); - } catch (e) { - console.error(e); - } - } - componentDidUpdate(prevProps) { - this.logic.props = this.__userProps(); - if (this.__needsDidMount) { - if (this.state.__err || !registry.get(this.__name).tpl) return; - this.__needsDidMount = false; - try { - this.logic.componentDidMount(); - } catch (e) { - console.error(e); - } - } else { - try { - this.logic.componentDidUpdate(prevProps); - } catch (e) { - console.error(e); - } - } - } - componentWillUnmount() { - registry.get(this.__name).subs.delete(this.__sub); - if (!this.__needsDidMount) { - try { - this.logic.componentWillUnmount(); - } catch (e) { - console.error(e); - } - } - } - render() { - const r = registry.get(this.__name); - const cls = "sc-host" + (r.htmlStreaming ? " sc-streaming-html" : "") + (r.jsStreaming ? " sc-streaming-js" : ""); - const hintStyle = r.htmlStreaming ? hintToMin(this.props.__hintSize) : void 0; - const hostStyle = this.props.__hostStyle || hintStyle ? { ...hintStyle || {}, ...this.props.__hostStyle || {} } : void 0; - const hostBase = { - className: cls, - style: hostStyle, - "data-sc-name": this.__name, - "data-dc-tpl": this.props.__tplId - }; - const chain = Array.isArray(this.context) ? this.context : []; - if (chain.includes(this.__name)) { - const cycle = [ - ...chain.slice(chain.indexOf(this.__name)), - this.__name - ].join(" \u2192 "); - return h( - "div", - { ...hostBase, className: cls + " sc-has-error" }, - h(Placeholder, { - name: this.__name, - hintSize: this.props.__hintSize, - error: "circular import: " + cycle - }) - ); - } - if (this.state.__err) { - return h( - "div", - { ...hostBase, className: cls + " sc-has-error" }, - h( - "div", - { className: "sc-logic-error", "data-omelette-chrome": "" }, - this.__name + ": " + this.state.__err - ), - h(Placeholder, { - name: this.__name, - hintSize: this.props.__hintSize, - error: this.state.__err - }) - ); - } - this.__reconcileLogic(); - if (!r.tpl) { - return h( - "div", - hostBase, - h(Placeholder, { name: this.__name, hintSize: this.props.__hintSize }) - ); - } - const userProps = this.__userProps(); - this.logic.props = userProps; - let vals = userProps; - let renderErr = r.logicError || this.__ctorError; - try { - vals = { ...userProps, ...this.logic.renderVals() || {} }; - } catch (e) { - console.error(e); - renderErr = this.__name + ".renderVals(): " + (e instanceof Error && e.message ? e.message : String(e)); - } - this.__streamingNow = !!(r.htmlStreaming || r.jsStreaming); - this.__htmlStreamingNow = !!r.htmlStreaming; - return h( - "div", - { ...hostBase, className: cls + (renderErr ? " sc-has-error" : "") }, - renderErr && h( - "div", - { className: "sc-logic-error", "data-omelette-chrome": "" }, - renderErr - ), - h( - AncestorContext.Provider, - { value: [...chain, this.__name] }, - r.tpl(vals, this) - ) - ); - } - } - __publicField(StreamableComponent, "contextType", AncestorContext); - const named = /* @__PURE__ */ new Map(); - function getDC(name) { - const hit = named.get(name); - if (hit) return hit; - function Dispatcher(p) { - const [, setTick] = React.useState(0); - React.useEffect(() => { - const sub = () => setTick((n) => n + 1); - registry.get(name).subs.add(sub); - return () => { - registry.get(name).subs.delete(sub); - }; - }, []); - ensureFetched(name); - return h(StreamableComponent, { ...p, __name: name }); - } - Dispatcher.displayName = name; - named.set(name, Dispatcher); - return Dispatcher; - } - return { - getDC, - StreamableComponent - }; - } - - // src/bundled.ts - function bundledBlob(url) { - const blobs = window.__resourceBlobs; - const b = blobs ? blobs[url.split("#")[0]] : void 0; - return b instanceof Blob ? b : null; - } - - // src/cdn.ts - var REACT_URL = "https://unpkg.com/react@18.3.1/umd/react.production.min.js"; - var REACT_SRI = "sha384-DGyLxAyjq0f9SPpVevD6IgztCFlnMF6oW/XQGmfe+IsZ8TqEiDrcHkMLKI6fiB/Z"; - var REACT_DOM_URL = "https://unpkg.com/react-dom@18.3.1/umd/react-dom.production.min.js"; - var REACT_DOM_SRI = "sha384-gTGxhz21lVGYNMcdJOyq01Edg0jhn/c22nsx0kyqP0TxaV5WVdsSH1fSDUf5YJj1"; - var BABEL_URL = "https://unpkg.com/@babel/standalone@7.29.0/babel.min.js"; - var BABEL_SRI = "sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y"; - function cdnScriptFor(url, sri) { - const res = window.__resources; - const v = res ? res[url] : void 0; - return typeof v === "string" && v ? { src: v } : { src: url, integrity: sri }; - } - - // src/external.ts - var isCustomElementName = (n) => !n.includes(".") && n.includes("-"); - function isRenderableType(g) { - if (typeof g === "function") return !isElementClass(g); - return typeof g === "object" && g !== null && typeof g.$$typeof === "symbol"; - } - function resolveDottedPath(root, name) { - let cur = root; - for (const seg of name.split(".")) { - if (cur == null) return void 0; - cur = cur[seg]; - } - return cur; - } - var GLOBAL_POLL_INTERVAL_MS = 50; - var GLOBAL_POLL_TIMEOUT_MS = 3e4; - function createExternalModules(onResolved) { - const cache = /* @__PURE__ */ new Map(); - let babelLoading = null; - const reportedMissing = /* @__PURE__ */ new Map(); - const polling = /* @__PURE__ */ new Set(); - function ensureBabel() { - if (window.Babel) return Promise.resolve(); - if (babelLoading) return babelLoading; - const babel = cdnScriptFor(BABEL_URL, BABEL_SRI); - babelLoading = new Promise((res, rej) => { - const s = document.createElement("script"); - s.src = babel.src; - if (babel.integrity) { - s.integrity = babel.integrity; - s.crossOrigin = "anonymous"; - } - s.onload = () => res(); - s.onerror = rej; - document.head.appendChild(s); - }); - return babelLoading; - } - const pending = /* @__PURE__ */ new Map(); - function load(kind, url, after) { - const existing = pending.get(url); - if (existing) return existing; - cache.set(url, null); - console.info("[dc-runtime] x-import: loading", url, "(" + kind + ")"); - const ready = Promise.all([ - kind === "jsx" ? ensureBabel() : Promise.resolve(), - after ?? Promise.resolve() - ]); - const p = ready.then(() => { - const pre = bundledBlob(url); - if (pre) return pre.text(); - return fetch(url).then((r) => { - if (!r.ok) throw new Error("HTTP " + r.status); - return r.text(); - }); - }).then((src) => { - const code = kind === "jsx" ? window.Babel.transform(src, { - filename: url, - presets: ["react", "typescript"] - }).code : src; - const module = { exports: {} }; - const before = new Set(Object.keys(window)); - //! nosemgrep: eval-and-function-constructor - new Function("React", "module", "exports", "require", code)( - getReact(), - module, - module.exports, - () => ({}) - ); - const globals = {}; - for (const k of Object.keys(window)) { - if (!before.has(k) && typeof window[k] === "function") { - globals[k] = window[k]; - } - } - cache.set(url, { mod: module.exports, globals }); - console.info( - "[dc-runtime] x-import: loaded", - url, - "\u2014 exports:", - Object.keys(module.exports), - "window globals:", - Object.keys(globals) - ); - onResolved(); - }).catch((e) => { - cache.set(url, { - mod: {}, - globals: {}, - error: "failed to load: " + (e instanceof Error && e.message ? e.message : String(e)) - }); - console.error( - "[dc-runtime] x-import: FAILED to load", - url, - "(" + kind + ")", - e - ); - onResolved(); - }); - pending.set(url, p); - return p; - } - function resolve2(url, name) { - const entry = cache.get(url); - if (!entry) return null; - const { mod, globals } = entry; - const C = mod && mod[name] || globals && globals[name] || typeof window !== "undefined" && window[name] || mod && mod.default; - if (typeof C === "function") return C; - const key = url + "\0" + name; - if (!reportedMissing.has(key)) { - reportedMissing.set( - key, - entry.error || 'no export named "' + name + '" (has: ' + Object.keys(mod).join(", ") + ")" - ); - console.error( - "[dc-runtime] x-import: module", - url, - "loaded but has no component named", - JSON.stringify(name), - "\u2014 available exports:", - Object.keys(mod), - "window globals:", - Object.keys(globals), - ". The module must `module.exports = {" + name + "}` or set `window." + name + "`." - ); - } - return null; - } - function waitForGlobal(name) { - if (polling.has(name)) return; - polling.add(name); - const started = Date.now(); - const isCE = isCustomElementName(name); - const tick = () => { - const found = isCE ? customElements.get(name) : isRenderableType(resolveDottedPath(window, name)); - if (found) { - polling.delete(name); - onResolved(); - return; - } - if (Date.now() - started >= GLOBAL_POLL_TIMEOUT_MS) { - console.warn( - "[dc-runtime] x-import: global", - JSON.stringify(name), - "never appeared on window after " + GLOBAL_POLL_TIMEOUT_MS + "ms" - ); - return; - } - setTimeout(tick, GLOBAL_POLL_INTERVAL_MS); - }; - setTimeout(tick, GLOBAL_POLL_INTERVAL_MS); - } - function resolveGlobal(url, name) { - const isCE = isCustomElementName(name); - if (!url) { - if (isCE) { - if (customElements.get(name)) return name; - waitForGlobal(name); - return null; - } - const g2 = resolveDottedPath(window, name); - if (isRenderableType(g2)) return g2; - waitForGlobal(name); - return null; - } - const entry = cache.get(url); - if (!entry) return null; - if (isCE && customElements.get(name)) return name; - const g = entry.globals[name] ?? resolveDottedPath(window, name); - if (isRenderableType(g)) return g; - if (name.includes(".")) return null; - const key = url + "\0global\0" + name; - if (!reportedMissing.has(key)) { - reportedMissing.set(key, null); - if (isCE && !customElements.get(name)) { - console.warn( - "[dc-runtime] x-import:", - url, - "loaded but no custom element", - JSON.stringify(name), - "is registered and window." + name + " is not a function \u2014 rendering <" + name + "> as an unknown element." - ); - } - } - return name; - } - function getError(url, name) { - const entry = cache.get(url); - if (entry?.error) return entry.error; - return reportedMissing.get(url + "\0" + name) || null; - } - return { load, resolve: resolve2, resolveGlobal, getError }; - } - function isElementClass(g) { - try { - return typeof g === "function" && typeof HTMLElement !== "undefined" && g.prototype instanceof HTMLElement; - } catch { - return false; - } - } - - // src/atomics.ts - var ATOMIC_CSS = ( - // layout - ".fx{display:flex}.col{display:flex;flex-direction:column}.grid{display:grid}.ac{align-items:center}.jc{justify-content:center}.jb{justify-content:space-between}.f1{flex:1}.noshrink{flex-shrink:0}.wrap{flex-wrap:wrap}.fw5{font-weight:500}.fw6{font-weight:600}.fw7{font-weight:700}.fw8{font-weight:800}.fs11{font-size:11px}.fs12{font-size:12px}.fs13{font-size:13px}.fs14{font-size:14px}.fs15{font-size:15px}.fs16{font-size:16px}.fs20{font-size:20px}.fs22{font-size:22px}.upper{text-transform:uppercase}.tc{text-align:center}.nowrap{white-space:nowrap}.gap8{gap:8px}.gap10{gap:10px}.gap12{gap:12px}.gap16{gap:16px}.gap24{gap:24px}.m0{margin:0}.mt8{margin-top:8px}.mt12{margin-top:12px}.mt16{margin-top:16px}.mb8{margin-bottom:8px}.mb12{margin-bottom:12px}.mb16{margin-bottom:16px}.posrel{position:relative}.posabs{position:absolute}.round{border-radius:50%}.ohide{overflow:hidden}.bbox{box-sizing:border-box}.pointer{cursor:pointer}.w100{width:100%}.b0{border:none}" - ); - - // src/helmet.ts - var DESIGN_DOC_MODE_RE = /]*\bname\s*=\s*["']design_doc_mode["'][^>]*\b(?:content|value)\s*=\s*["'](\w+)["']/i; - var CANVAS_BG_LIGHT = "#f0eee6"; - var CANVAS_BG_DARK = "#2e2c26"; - function createHelmetManager(doc, isStreaming) { - const mounted = /* @__PURE__ */ new Set(); - const live = /* @__PURE__ */ new Map(); - let designDocMode = null; - let canvasStyleEl = null; - let appTheme = "light"; - try { - const ds = doc.documentElement.dataset.theme; - appTheme = ds === "dark" || ds === "light" ? ds : new URLSearchParams(doc.defaultView?.location.search ?? "").get( - "theme" - ) === "dark" ? "dark" : "light"; - } catch { - } - function applyCanvasBg() { - if (!canvasStyleEl) return; - const bg = appTheme === "dark" ? CANVAS_BG_DARK : CANVAS_BG_LIGHT; - canvasStyleEl.textContent = `html,body{background:${bg}}#dc-root>.sc-host{position:relative}`; - } - function postDesignMode(mode) { - if (window.parent === window) return; - try { - window.parent.postMessage({ type: "__dc_design_mode", mode }, "*"); - } catch { - } - } - function setDesignDocMode(mode) { - if (mode === designDocMode) return; - designDocMode = mode; - postDesignMode(mode); - if (mode === "canvas") { - doc.documentElement.setAttribute("data-dc-canvas", ""); - canvasStyleEl = doc.createElement("style"); - canvasStyleEl.setAttribute("data-dc-canvas", ""); - applyCanvasBg(); - doc.head.appendChild(canvasStyleEl); - } else { - doc.documentElement.removeAttribute("data-dc-canvas"); - canvasStyleEl?.remove(); - canvasStyleEl = null; - } - } - window.addEventListener("message", (e) => { - const type = e.data && e.data.type; - if (type === "__dc_theme") { - const t = e.data.theme; - if (t === "light" || t === "dark") { - appTheme = t; - applyCanvasBg(); - } - return; - } - if (!designDocMode || type !== "__dc_probe") return; - postDesignMode(designDocMode); - }); - function compile(node) { - const raw = [...node.children]; - const helmetClosed = node.nextSibling != null || node.parentNode?.nextSibling != null; - if (node.hasAttribute("data-dc-atomics") && !mounted.has("__dc-atomics")) { - mounted.add("__dc-atomics"); - const el = doc.createElement("style"); - el.id = "__dc-atomics"; - el.textContent = ATOMIC_CSS; - doc.head.appendChild(el); - } - return (_vals, ctx) => { - const name = ctx && ctx.__name || ""; - const streaming = !!(name && isStreaming(name)); - for (let i = 0; i < raw.length; i++) { - const child = raw[i]; - const tag = child.tagName; - const mayBePartial = streaming && !helmetClosed && i === raw.length - 1; - if (tag === "SCRIPT") { - if (mayBePartial) continue; - const key = "SCRIPT|" + (child.getAttribute("src") || child.textContent || ""); - if (mounted.has(key)) continue; - mounted.add(key); - const el = doc.createElement("script"); - for (const { name: an, value } of [...child.attributes]) - el.setAttribute(an, value); - if (child.textContent) el.textContent = child.textContent; - doc.head.appendChild(el); - } else if (tag === "LINK" || tag === "META") { - if (mayBePartial) continue; - const key = tag + "|" + (child.getAttribute("href") || child.getAttribute("src") || child.outerHTML); - if (mounted.has(key)) continue; - mounted.add(key); - if (tag === "LINK") { - const rel = (child.getAttribute("rel") || "").toLowerCase().split(/\s+/); - const href = (child.getAttribute("href") || "").trim(); - const res = window.__resources; - const pre = res && rel.includes("stylesheet") && !rel.includes("alternate") ? res[href] : void 0; - const blob = typeof pre === "string" && pre ? bundledBlob(pre) : null; - if (blob) { - const el = doc.createElement("style"); - if (child.hasAttribute("disabled")) { - el.setAttribute("media", "not all"); - } else if (child.getAttribute("media")) { - el.setAttribute("media", child.getAttribute("media")); - } - if (child.getAttribute("title")) - el.setAttribute("title", child.getAttribute("title")); - void blob.text().then((css) => { - el.textContent = css; - }); - doc.head.appendChild(el); - continue; - } - } - doc.head.appendChild(child.cloneNode(true)); - } else { - const key = name + "|" + i; - let el = live.get(key); - if (!el || el.tagName !== tag) { - if (el) el.remove(); - el = doc.createElement(tag.toLowerCase()); - live.set(key, el); - doc.head.appendChild(el); - } - for (const { name: an, value } of [...child.attributes]) { - if (el.getAttribute(an) !== value) el.setAttribute(an, value); - } - if (el.textContent !== child.textContent) - el.textContent = child.textContent; - } - } - return null; - }; - } - return { compile, setDesignDocMode }; - } - - // src/pseudo.ts - function scanUnquotedUrl(css, i) { - if (css[i] !== "u" && css[i] !== "U" || css.slice(i, i + 4).toLowerCase() !== "url(" || /[a-z0-9_-]/i.test(css[i - 1] ?? "")) { - return -1; - } - let j = i + 4; - while (j < css.length && /\s/.test(css[j])) j++; - if (css[j] === '"' || css[j] === "'") return -1; - while (j < css.length && css[j] !== ")") { - if (css[j] === "\\") j++; - j++; - } - return j < css.length ? j + 1 : css.length; - } - function stripComments(css) { - let out = ""; - let quote = ""; - for (let i = 0; i < css.length; i++) { - const c = css[i]; - if (quote) { - if (c === "\\") { - out += c + (css[i + 1] ?? ""); - i++; - continue; - } - if (c === quote) quote = ""; - out += c; - } else if (c === "'" || c === '"') { - quote = c; - out += c; - } else if (c === "/" && css[i + 1] === "*") { - const end = css.indexOf("*/", i + 2); - i = end === -1 ? css.length : end + 1; - out += " "; - } else { - const end = scanUnquotedUrl(css, i); - if (end === -1) out += c; - else { - out += css.slice(i, end); - i = end - 1; - } - } - } - return out; - } - function importantify(css) { - css = stripComments(css); - const decls = []; - let start = 0; - let depth = 0; - let quote = ""; - for (let i = 0; i < css.length; i++) { - const c = css[i]; - if (quote) { - if (c === "\\") i++; - else if (c === quote) quote = ""; - } else if (c === "'" || c === '"') quote = c; - else if (c === "(") depth++; - else if (c === ")") depth = Math.max(0, depth - 1); - else if (c === ";" && depth === 0) { - decls.push(css.slice(start, i)); - start = i + 1; - } else { - const end = scanUnquotedUrl(css, i); - if (end !== -1) i = end - 1; - } - } - decls.push(css.slice(start)); - return decls.map((d) => d.trim()).filter(Boolean).map((d) => /!\s*important$/i.test(d) ? d : d + " !important").join(";"); - } - function createPseudoSheet(doc) { - let el = null; - const cache = /* @__PURE__ */ new Map(); - let n = 0; - return (pseudo, css) => { - const k = pseudo + "|" + css; - const hit = cache.get(k); - if (hit) return hit; - if (!el) { - el = doc.createElement("style"); - doc.head.appendChild(el); - } - const cls = "scp" + (n++).toString(36); - const isPseudoElement = pseudo === "before" || pseudo === "after"; - const sel = isPseudoElement ? "." + cls + "::" + pseudo : "." + cls + ":" + pseudo; - el.sheet.insertRule( - sel + "{" + (isPseudoElement ? css : importantify(css)) + "}", - el.sheet.cssRules.length - ); - cache.set(k, cls); - return cls; - }; - } - - // src/registry.ts - function createRegistry() { - const entries = /* @__PURE__ */ Object.create(null); - function get(name) { - return entries[name] || (entries[name] = { - html: "", - tpl: null, - Logic: null, - jsStreaming: false, - htmlStreaming: false, - ver: 0, - subs: /* @__PURE__ */ new Set(), - fetched: false - }); - } - function bump(name) { - const r = get(name); - r.ver++; - for (const fn of r.subs) fn(); - } - return { - entries, - get, - bump, - bumpAll() { - for (const n in entries) bump(n); - } - }; - } - - // src/runtime.ts - var COMPONENT_DIR = "."; - function createRuntime(doc = document) { - const registry = createRegistry(); - const pseudoClass = createPseudoSheet(doc); - const helmet = createHelmetManager( - doc, - (name) => registry.get(name).htmlStreaming - ); - const external = createExternalModules(() => registry.bumpAll()); - const factory = createComponentFactory(registry, ensureFetched); - const host = { - component: (name) => factory.getDC(name), - placeholder: (props) => h(Placeholder, props), - helmet: (node) => helmet.compile(node), - loadExternal: (kind, url, after) => external.load(kind, url, after), - resolveExternal: (url, name) => external.resolve(url, name), - resolveExternalGlobal: (url, name) => external.resolveGlobal(url, name), - resolveExternalError: (url, name) => external.getError(url, name), - pseudoClass - }; - function ensureFetched(name) { - const r = registry.get(name); - if (r.fetched) return; - r.fetched = true; - const url = COMPONENT_DIR + "/" + encodeURIComponent(name) + ".dc.html"; - const res = window.__resources; - const pre = res ? res[url] : void 0; - const target = typeof pre === "string" && pre ? pre : url; - const blob = bundledBlob(target); - (blob ? blob.text() : fetch(target).then((res2) => { - if (!res2.ok) { - console.error( - '[dc-runtime] sibling fetch for "' + name + '" failed:', - url, - "returned", - res2.status, - "\u2014 the reference renders as an empty placeholder." - ); - return ""; - } - return res2.text(); - })).then((t) => { - if (!t) return; - const parsed = parseDcText(t); - if (!parsed) { - console.error( - '[dc-runtime] sibling fetch for "' + name + '":', - url, - "has no block \u2014 not a Design Component." - ); - return; - } - if (parsed.props) r.propsMeta = parsed.props; - if (parsed.preview) r.preview = parsed.preview; - if (parsed.template && !r.html) updateHtml(name, parsed.template); - if (parsed.js && !r.Logic) updateJs(name, parsed.js); - }).catch( - (e) => console.error( - '[dc-runtime] sibling fetch for "' + name + '" threw:', - url, - e - ) - ); - } - let rootName = null; - function updateHtml(name, html) { - const r = registry.get(name); - r.html = html; - if (name === rootName) { - const mode = DESIGN_DOC_MODE_RE.exec(html)?.[1] ?? null; - if (mode || !r.htmlStreaming) helmet.setDesignDocMode(mode); - } - try { - r.tpl = compileTemplate(html, host); - } catch (e) { - console.error("[dc-runtime] template compile FAILED for", name, e); - } - registry.bump(name); - } - function updateJs(name, src) { - const r = registry.get(name); - const seq = r.jsSeq = (r.jsSeq || 0) + 1; - try { - const Cls = evalDcLogic(src); - if (r.jsSeq !== seq) return; - if (typeof Cls !== "function") { - r.logicError = name + ".dc.html: