aurora-ui 0.2.0__tar.gz

aurora_ui-0.2.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml,json,md}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

aurora_ui-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,47 @@
+name: Reportar un bug
+description: Algo no funciona como esperabas.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Gracias por tomarte el tiempo de reportarlo. Cuanto más concreto, antes se arregla.
+  - type: textarea
+    id: what
+    attributes:
+      label: Qué pasa
+      description: Describe el problema. Si es visual, adjunta una captura (puedes usar `app.render_png()`).
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Qué esperabas que pasara
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Ejemplo mínimo
+      description: El programa más corto posible que reproduzca el problema.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Versión de Aurora
+      placeholder: "0.1.0 (o el commit)"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Sistema operativo
+      options: [Windows, macOS, Linux (X11), Linux (Wayland)]
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Versión de Python
+      placeholder: "3.13"

aurora_ui-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Preguntas y dudas de uso
+    url: https://github.com/<usuario>/aurora/discussions
+    about: Para preguntas generales, usa Discussions en lugar de issues.

aurora_ui-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,26 @@
+name: Proponer una funcionalidad
+description: Una idea para mejorar Aurora.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Antes de proponer, echa un vistazo a [VISION.md](../blob/main/VISION.md) y al
+        [ROADMAP.md](../blob/main/ROADMAP.md): puede que ya esté planificada.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Qué problema resuelve
+      description: Cuéntanos el caso de uso real. Es lo que más pesa al priorizar.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Cómo te gustaría usarlo
+      description: Un ejemplo de cómo se vería la API desde Python.
+      render: python
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternativas que consideraste

aurora_ui-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Qué cambia
+
+<!-- Describe el cambio y por qué es necesario. Enlaza el issue si existe: "Cierra #123". -->
+
+## Cómo se probó
+
+<!-- Tests añadidos, ejemplos ejecutados, capturas antes/después si es visual. -->
+
+## Checklist
+
+- [ ] `uv run pytest` pasa
+- [ ] `uv run ruff check .` y `cargo clippy --release -- -D warnings` sin avisos
+- [ ] Si es visual: hay un test de render y adjunto capturas
+- [ ] Si cambia la API pública: actualicé `docs/reference.md`, los stubs y el `CHANGELOG.md`

aurora_ui-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  lint:
+    name: Lint (Python + Rust)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: Dependencias del sistema
+        run: sudo apt-get update && sudo apt-get install -y libfontconfig1-dev libfreetype-dev
+      - name: Ruff
+        run: |
+          uvx ruff check .
+          uvx ruff format --check .
+      - name: rustfmt
+        run: cargo fmt --check
+      - name: Clippy
+        run: cargo clippy --release -- -D warnings
+
+  test:
+    name: Tests (${{ matrix.os }}, py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Dependencias del sistema (Linux)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y libfontconfig1-dev libfreetype-dev
+      - name: Compilar e instalar
+        run: uv sync
+      - name: Tests
+        run: uv run pytest -v
+      # Con `extension-module` el binario de tests de Rust no enlaza contra libpython en
+      # Linux/macOS; en Windows sí (python3.lib), así que los tests unitarios corren ahí.
+      - name: Tests de Rust (Windows)
+        if: runner.os == 'Windows'
+        run: uv run cargo test --release
+      - name: Renderizar los ejemplos (smoke test visual)
+        run: |
+          uv run examples/hello.py --png hello.png
+          uv run examples/studio.py --png studio-shots
+      - name: Subir capturas
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: capturas-${{ matrix.os }}-py${{ matrix.python }}
+          path: |
+            hello.png
+            studio-shots/
+          if-no-files-found: ignore

aurora_ui-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+# Publica wheels en PyPI al crear un tag vX.Y.Z.
+#
+# Requisitos (una sola vez):
+#   1. Crear el proyecto en PyPI y configurar "Trusted Publishing" para este repositorio
+#      y el workflow release.yml (sin tokens ni secretos).
+#   2. Crear el environment "pypi" en la configuración del repositorio.
+#
+# Nota: el wheel es abi3, así que basta uno por plataforma y arquitectura para todas
+# las versiones de Python >= 3.10.
+
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  wheels:
+    name: Wheel ${{ matrix.platform.name }}
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - { name: linux-x86_64, runner: ubuntu-latest, target: x86_64 }
+          - { name: windows-x64, runner: windows-latest, target: x64 }
+          - { name: macos-arm64, runner: macos-latest, target: aarch64 }
+          # macos-13 ya no existe en GitHub Actions; macos-15-intel es la última imagen Intel.
+          - { name: macos-x86_64, runner: macos-15-intel, target: x86_64 }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist
+          manylinux: 2_28
+          before-script-linux: dnf install -y fontconfig-devel freetype-devel
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheel-${{ matrix.platform.name }}
+          path: dist
+
+  sdist:
+    name: Source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+  publish:
+    name: Publicar en PyPI
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

aurora_ui-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+target/
+.venv/
+__pycache__/
+*.so
+*.pyd
+/*.png

aurora_ui-0.2.0/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+Todos los cambios relevantes de Aurora se documentan aquí.
+
+El formato sigue [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y el proyecto usa
+[Versionado Semántico](https://semver.org/lang/es/). Mientras la versión sea `0.x`, cualquier
+versión menor puede incluir cambios incompatibles, que siempre se señalarán aquí.
+
+## [Sin publicar]
+
+## [0.2.0] — 2026-10-15
+
+Apps de verdad: scroll, teclado y foco, campos de texto, imágenes y más componentes.
+
+### Añadido
+
+- Componentes `divider`, `avatar`, `checkbox`, `switch`, `tabs` (con ← →) y `select` (desplegable en
+  capa superior, con scroll, Esc y ↑ ↓), enlazados a `Signal` donde aplica.
+- `tooltip(child, tip)` y la propiedad `tooltip`: burbuja tras medio segundo de hover, colocada
+  dentro de la ventana, con colores heredables `tooltip_bg` y `tooltip_color`; `Pilot.tooltip`.
+- Primitiva `image(src, fit=...)`: PNG, JPEG, WebP, GIF, BMP, ICO y SVG (vectorial) desde una ruta
+  o desde `bytes`, con proporción automática, `fit` (`contain`, `cover`, `fill`, `none`), recorte a
+  las esquinas redondeadas, caché de decodificación que detecta cambios en disco y errores claros
+  (`FileNotFoundError`, `ValueError`).
+- Campos de texto `text_input` y `textarea`, enlazados en los dos sentidos a un `Signal[str]`:
+  cursor que parpadea, selección con teclado y ratón (doble y triple clic), recorrido por grafemas y
+  palabras, portapapeles, deshacer/rehacer agrupando lo escrito, composición con IME, placeholder,
+  `on_submit`, desplazamiento horizontal en una línea y crecimiento con el contenido en varias.
+- Propiedades `placeholder_color` y `selection_color`; cursor de texto del ratón sobre los campos.
+- `Pilot.type()`, `ime_preedit()`, `ime_commit()`, `selection()` y `clipboard`.
+- Teclado y foco: Tab / Shift+Tab en orden de pintura (atrapado dentro de barreras `capture`),
+  activación con Enter y Espacio, anillo de foco animado solo al navegar con teclado
+  (`focus_color`, heredable) y desplazamiento automático del `scroll` para mostrar el foco.
+- `on_key` con `KeyEvent` (`key`, `text`, modificadores, `matches("mod+s")`), que burbujea desde el
+  foco hasta la raíz; `on_focus`, `on_blur`, `focusable` y `autofocus`.
+- Desplazamiento con flechas, RePág/AvPág, Inicio/Fin y Espacio.
+- `Pilot.press()`, `key_down()`, `key_up()`, `focus()` y `focused`.
+- Contenedor `scroll(axis="y" | "x" | "both")`: recorte, rueda con desplazamiento suave, trackpad,
+  encadenado al `scroll` exterior en el límite y barra superpuesta que se oculta sola y se puede
+  arrastrar. La posición se conserva entre reconstrucciones.
+- Propiedades `min_height`, `max_height` y `scrollbar_color`.
+- `Pilot.wheel()`, `Pilot.scroll()` y `Pilot.scroll_offset()`.
+- `app.pilot()`: piloto headless para tests de interacción (`click`, `move_to`, `hovered`, `rect`,
+  `settle`, `png`…) que usa el mismo runtime que la ventana.
+- `Signal.set` es seguro desde cualquier hilo y despierta el bucle de eventos: la ventana se
+  actualiza sin esperar a un evento del usuario.
+- `app.spawn(coro)`: ejecuta corrutinas en un bucle `asyncio` en segundo plano.
+- Propiedad `layer="overlay"`: pinta un elemento y le da los eventos por encima de todo el árbol.
+- Manejadores genéricos: cualquier argumento `on_<evento>` de un elemento es un manejador.
+
+### Cambiado
+
+- `Element.to_spec()` serializa los manejadores en `"handlers": {"click": fn}` en lugar de
+  `"on_click"`. `Element.on_click` sigue disponible como propiedad de solo lectura.
+- El núcleo separa el estado de la app (`Runtime`) del bucle de ventana.
+- El hit-testing respeta el recorte de los contenedores `scroll`.
+- La demo `studio.py` desplaza el contenido de cada página y estrena búsqueda en el tablero, un
+  formulario de nueva tarea (Ctrl+N y el botón lo abren en vez de añadir una tarea de ejemplo),
+  una página de Ajustes y tooltips.
+- Nuevas dependencias del núcleo: `arboard` (portapapeles) y `unicode-segmentation`. Las features de
+  `skia-safe` cambian por sistema (`svg`, `webp` y, fuera de macOS, `ganesh` + `vulkan`) para
+  seguir usando binarios precompilados de Skia.
+
+### Corregido
+
+- `examples/studio.py --png` ya no falla en consolas de Windows sin UTF-8.
+
+## [0.1.0] — 2026-10-15
+
+Primera versión: la base del framework.
+
+### Añadido
+
+- Núcleo nativo en Rust expuesto como `aurora._core` (PyO3 + maturin, wheel abi3 para Python ≥ 3.10).
+- Layout flexbox con Taffy: `direction`, `gap`, `padding`, `align`, `justify`, `grow`, `shrink`,
+  `wrap`, tamaños en píxeles o porcentaje, `min_width`/`max_width` y `position="absolute"` con
+  `top`/`right`/`bottom`/`left`.
+- Render con Skia: esquinas redondeadas, bordes, sombras difuminadas, gradientes lineales y opacidad.
+- Texto con shaping real, fallback de fuentes, herencia de estilos de texto, alineación por baseline,
+  `max_lines` con elipsis y `text_align`.
+- Ventana nativa con winit; el bucle de eventos corre sin el GIL.
+- Estados hover y pressed animados en el núcleo (`bg_hover`, `bg_pressed`, `press_scale`).
+- Hit-testing con burbujeo al ancestro interactivo y barreras de eventos (`capture`).
+- API declarativa: `box`, `row`, `column`, `text`, `spacer`, hijos con `[...]`, `key` y `on_click`.
+- `Signal` para el estado reactivo.
+- Temas con tokens (`"$primary"`), temas `MIDNIGHT` y `DAYLIGHT`, y tema reactivo vía `Signal[Theme]`.
+- Componentes: `button` (variantes `primary`, `soft`, `ghost`), `card`, `badge` y `stat`.
+- `App.render_png()` para renderizar sin ventana.
+- Ejemplos: `hello.py`, `studio.py` (demo completa) y `brand.py` (genera las imágenes del README).
+- Documentación: guía, referencia, arquitectura, visión y roadmap.
+
+[Sin publicar]: https://github.com/<usuario>/aurora/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/<usuario>/aurora/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/<usuario>/aurora/releases/tag/v0.1.0

aurora_ui-0.2.0/CLAUDE.md

@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Aurora (`aurora-ui`, pre-alpha v0.2) is a declarative, reactive desktop UI library: the public API is
+Python (`python/aurora/`), and layout/render/animation/events run in a native Rust core
+(`src/`, built as the extension module `aurora._core` via PyO3 + maturin). Stack: Skia (`skia-safe`)
+for painting and text, Taffy for flexbox layout, winit + softbuffer for the window (CPU raster).
+
+## Commands
+
+```bash
+uv sync                                   # builds the Rust core (release) and installs editable + dev deps
+uv run pytest                             # all tests
+uv run pytest tests/test_render.py::test_name   # single test
+uv run examples/studio.py                 # full demo app (opens a window)
+uv run examples/studio.py --png studio-shots     # headless render of the demo (CI smoke test)
+uv run examples/hello.py --png hello.png
+```
+
+Full lint, same as CI:
+
+```bash
+uv run ruff check . && uv run ruff format --check .
+cargo fmt --check && cargo clippy --release -- -D warnings
+```
+
+- Python edits in `python/aurora/` apply immediately (editable install). Rust edits in `src/**/*.rs`
+  trigger an automatic rebuild on the next `uv run` (configured via `tool.uv.cache-keys`).
+- Rust unit tests (`uv run cargo test --release`) only link on Windows: with `extension-module`,
+  the test binary doesn't link libpython on Linux/macOS.
+- First build downloads prebuilt Skia binaries and takes minutes. The `skia-safe` features in
+  `Cargo.toml` (per OS) must match a combination published in rust-skia/skia-binaries; any other
+  combination silently falls back to building Skia from source (needs LLVM, very slow). Check the
+  release assets before adding a Skia feature. Linux needs
+  `libfontconfig-dev` and `libfreetype-dev`.
+
+## Architecture
+
+Core principle: **Python describes, Rust executes; the boundary is crossed once per update with a
+complete tree.** Never expose low-level operations (draw rect, measure text) to Python.
+
+Frame lifecycle:
+
+1. `App._build()` (`python/aurora/__init__.py`) calls the user's `view()`, applies root defaults,
+   and serializes the `Element` tree to nested dicts via `Element.to_spec(theme)` — this is where
+   `"$token"` theme values and text lambdas are resolved.
+2. `spec::parse` (`src/spec.rs`) is the **only** place in Rust that knows the shape of the Python
+   data: dicts → typed `Node`. Text style inheritance (`color`, `font_size`, `font_weight`,
+   `font_family`, `line_height`, `letter_spacing`) is resolved here once, CSS-style.
+3. `render.rs` `Engine`: builds a parallel Taffy tree (text nodes carry a shaped Skia `Paragraph`,
+   reused for both measuring and painting), ticks hover/pressed transitions (exponential smoothing,
+   τ = 70 ms, real `dt`), and `Painter` paints shadow → bg → border → text → children while
+   recording `HitRegion`s in paint order.
+4. `runtime.rs` `Runtime`: window-independent app state (tree, hit regions, pointer, event
+   dispatch by handler name via `dispatch(key, event, arg)`). Two drivers share it: `window.rs`
+   (winit loop, runs with the GIL released via `py.detach`; the GIL is taken only to run a handler or
+   rebuild the view; hover never touches Python) and `pilot.rs` (`Pilot`, headless, for interaction
+   tests via `app.pilot()`).
+
+`Signal.set` calls `_core.wake()` (any thread): an atomic flag that `Runtime::sync` consumes, plus an
+`EventLoopProxy` user event to request a frame. Nodes with `layer="overlay"` are deferred by `Painter`
+and painted (and hit-tested) after the whole tree.
+
+Hit-testing: take the last-painted region containing the point, bubble up through parents to the
+first node with a `click` handler; a node with `capture=True` stops the bubbling (e.g. modals).
+
+Node identity is stable (explicit `key` or tree path) and is used to keep animation state across
+full rebuilds — every event currently rebuilds the whole view.
+
+`App.render_png()` → `_core.render_png` renders without a window; this powers `tests/test_render.py`
+(which decodes PNG pixels without Pillow), CI smoke tests, and the README images (`examples/brand.py`).
+
+## Extending
+
+- **New component:** compose primitives in `components.py` in pure Python whenever possible. Only
+  push to Rust what can't be expressed otherwise (new node kinds, render effects, layout).
+- **New style property:** add the field to `spec::Style` and its parsing, its effect in
+  `taffy_style` (layout) or `Painter::paint` (paint), and document it in `docs/reference.md`.
+- **New node type:** new `spec::Kind` variant + its layout measurement + its painting.
+- Visual changes need a render test in `tests/test_render.py`; interaction changes need a `Pilot`
+  test in `tests/test_pilot.py`. Public API changes must update
+  `docs/reference.md`, `python/aurora/_core.pyi` stubs (if the native API changes), and the
+  "Sin publicar" section of `CHANGELOG.md`.
+
+## Conventions
+
+- Code identifiers in English (`bg`, `radius`, `on_click`, CSS-like); docs, comments and commit
+  messages in **Spanish**. Commits in imperative mood (`Añade contenedor scroll con clipping`).
+- Components must look good with default values. Optional parameters are keyword-only; positional
+  args only for essentials (`text(content)`, `button(label, on_click)`).
+- Children are attached with `[...]` (`column(gap=8)[a, b]`); theme colors use `"$token"` strings.
+- Rust: no `unwrap()` on paths that depend on user data — input errors must surface in Python as
+  clear exceptions.
+- Ruff line length is 110; Spanish typography rules (RUF001–003) and lambda assignment (E731) are
+  ignored on purpose.

aurora_ui-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# Código de conducta
+
+Aurora quiere ser un proyecto donde cualquier persona pueda participar con comodidad,
+independientemente de su experiencia, origen o identidad.
+
+## Lo que esperamos
+
+- Trato respetuoso y empático, también cuando no estamos de acuerdo.
+- Críticas dirigidas a las ideas y al código, nunca a las personas.
+- Paciencia con quien está aprendiendo: todos empezamos en algún momento.
+- Asumir buena fe, y pedir aclaraciones antes de sacar conclusiones.
+- Reconocer los errores propios y aprender de ellos.
+
+## Lo que no aceptamos
+
+- Insultos, burlas, comentarios despectivos o ataques personales.
+- Acoso, público o privado, de cualquier tipo.
+- Lenguaje o imágenes sexualizadas, y atención no deseada.
+- Publicar información privada de otras personas sin su permiso.
+- Cualquier conducta que sería inapropiada en un entorno profesional.
+
+## Ámbito y aplicación
+
+Este código se aplica en todos los espacios del proyecto (issues, pull requests, discusiones y
+canales de chat) y cuando alguien representa al proyecto en público.
+
+Para reportar un problema, escribe a las personas que mantienen el proyecto
+(**TODO: añadir un email de contacto**). Los reportes se tratarán con confidencialidad. Quienes
+mantienen el proyecto pueden editar o eliminar contribuciones que no respeten este código y, en
+casos graves o reiterados, excluir temporal o permanentemente a quien lo incumpla.
+
+Este código está inspirado en el [Contributor Covenant](https://www.contributor-covenant.org).

aurora_ui-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contribuir a Aurora
+
+¡Gracias por tu interés! Toda contribución suma: reportar un bug, mejorar la documentación,
+proponer una idea o implementar una funcionalidad.
+
+## Antes de empezar
+
+- **Bugs:** abre un issue con la plantilla de bug. Un ejemplo mínimo reproducible (y una captura
+  si es visual) ahorra mucho tiempo.
+- **Funcionalidades:** abre primero un issue para discutirla. Revisa [VISION.md](VISION.md) y el
+  [ROADMAP.md](ROADMAP.md): las propuestas alineadas con ellos tienen más recorrido.
+- **Cambios pequeños** (erratas, docs, tests): envía el PR directamente.
+
+## Entorno de desarrollo
+
+Necesitas Python ≥ 3.10, [uv](https://docs.astral.sh/uv/) y Rust estable
+([rustup](https://rustup.rs)). En Linux, además, `libfontconfig-dev` y `libfreetype-dev`.
+
+```bash
+git clone https://github.com/<usuario>/aurora.git
+cd aurora
+uv sync                     # compila el núcleo e instala todo (incluye pytest y ruff)
+uv run pytest               # tests
+uv run examples/studio.py   # demo completa
+```
+
+- Los cambios en `python/aurora/` se aplican al instante (instalación editable).
+- Los cambios en `src/*.rs` disparan la recompilación en el siguiente `uv run`.
+
+## Antes de enviar un PR
+
+Ejecuta lo mismo que la CI:
+
+```bash
+uv run ruff check . && uv run ruff format --check .
+cargo fmt --check && cargo clippy --release -- -D warnings
+uv run pytest
+```
+
+Y verifica a mano:
+
+- [ ] Si el cambio es **visual**, hay un test en `tests/test_render.py` que lo renderiza, y
+      `uv run examples/studio.py` sigue viéndose bien.
+- [ ] Si cambia la **API pública**, están actualizados `docs/reference.md`, la guía si aplica,
+      los stubs (`_core.pyi`) y el `CHANGELOG.md` (sección *Sin publicar*).
+- [ ] Si añades una **propiedad de estilo**, sigue los pasos de
+      [Extender Aurora](docs/architecture.md#extender-aurora).
+
+## Convenciones
+
+### Diseño de la API
+
+- **Bonito por defecto:** los valores por defecto de un componente nuevo deben verse bien sin
+  configurar nada.
+- **Componentes en Python** siempre que se puedan componer con primitivas. Al núcleo Rust solo
+  bajan capacidades que no se puedan expresar de otra forma (nuevos tipos de nodo, efectos de
+  render, layout).
+- **Nombres en inglés en el código** (`bg`, `radius`, `on_click`), siguiendo las convenciones
+  habituales de CSS y de otros frameworks de UI. Documentación y comentarios, en español.
+- **Keyword arguments** para todo lo opcional; los posicionales, solo para lo esencial
+  (`text(contenido)`, `button(label, on_click)`).
+
+### Código
+
+- **Python:** formateado con `ruff format` y con type hints en la API pública.
+- **Rust:** `cargo fmt` y `clippy` sin warnings. Nada de `unwrap()` en rutas que dependan de datos
+  del usuario: los errores de entrada deben llegar a Python como excepciones claras.
+- **Commits:** mensajes en imperativo y descriptivos (`Añade contenedor scroll con clipping`).
+  Un commit por cambio lógico.
+
+## Estructura del proyecto
+
+```
+python/aurora/   API pública en Python
+src/             Núcleo nativo en Rust (módulo aurora._core)
+tests/           Tests (pytest), incluidos tests de render headless
+examples/        Apps de ejemplo; brand.py genera las imágenes del README
+docs/            Guía, referencia, arquitectura y recursos gráficos
+```
+
+El recorrido completo por el núcleo está en [docs/architecture.md](docs/architecture.md).
+
+## Licencia
+
+Al contribuir aceptas que tu aportación se publique bajo la [licencia MIT](LICENSE) del proyecto.