✨ (build): Introduce nuevas funciones de build

Añade `compile_scss()`, `copy_dir()`, `copy_file()`,
`copy_file_replacing()` y `minify_js()` para preparar activos en
`build.rs`. Adopta el patrón `assets/ -> static/`: los archivos
estáticos se mueven a `assets/` y `static/` se añade a `.gitignore`. Los
`build.rs` de *pagetop* y *pagetop-htmx* se actualizan con el nuevo
patrón.  La documentación del módulo se reescribe para reflejar los
nuevos cambios.

.gitignore

@@ -1,6 +1,9 @@
 # Ignora directorios de compilación
 **/target
 
+# Ignora directorios de archivos estáticos
+**/static
+
 # Archivos de log
 **/log/*.log*
 

Cargo.lock

@@ -20,6 +20,15 @@ dependencies = [
  "zerocopy",
 ]
 
+[[package]]
+name = "aho-corasick"
+version = "0.7.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc936419f96fa211c1b9166887b38e5e40b19958e5b895be7c1f93adec7071ac"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "aho-corasick"
 version = "1.1.4"
@@ -933,7 +942,7 @@ version = "0.4.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "52dfc19153a48bde0cbd630453615c8151bce3a5adfac7a0aebfbf0a1e1f57e3"
 dependencies = [
- "aho-corasick",
+ "aho-corasick 1.1.4",
  "bstr",
  "log",
  "regex-automata",
@@ -965,6 +974,16 @@ dependencies = [
  "rand",
 ]
 
+[[package]]
+name = "hashbrown"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43a3c133739dddd0d2990f9a4bdf8eb4b21ef50e4851ca85ab661199821d510e"
+dependencies = [
+ "ahash",
+ "bumpalo",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.14.5"
@@ -1495,6 +1514,17 @@ dependencies = [
  "unicase",
 ]
 
+[[package]]
+name = "minify-js"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1fa5546ee8bd66024113e506cabe4230e76635a094c06ea2051b66021dda92e"
+dependencies = [
+ "aho-corasick 0.7.20",
+ "lazy_static",
+ "parse-js",
+]
+
 [[package]]
 name = "miniz_oxide"
 version = "0.8.9"
@@ -1721,7 +1751,6 @@ version = "0.1.0"
 dependencies = [
  "pagetop",
  "pagetop-build",
- "tokio",
 ]
 
 [[package]]
@@ -1731,7 +1760,6 @@ dependencies = [
  "pagetop",
  "pagetop-build",
  "serde",
- "tokio",
 ]
 
 [[package]]
@@ -1739,9 +1767,18 @@ name = "pagetop-build"
 version = "0.3.2"
 dependencies = [
  "grass",
+ "minify-js",
  "pagetop-statics",
 ]
 
+[[package]]
+name = "pagetop-htmx"
+version = "0.1.0"
+dependencies = [
+ "pagetop",
+ "pagetop-build",
+]
+
 [[package]]
 name = "pagetop-macros"
 version = "0.3.0"
@@ -1812,6 +1849,19 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "parse-js"
+version = "0.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2742b5e32dcb5930447ed9f9e401a7dfd883867fc079c4fac44ae8ba3593710e"
+dependencies = [
+ "aho-corasick 0.7.20",
+ "bumpalo",
+ "hashbrown 0.13.2",
+ "lazy_static",
+ "memchr",
+]
+
 [[package]]
 name = "pastey"
 version = "0.2.2"
@@ -2094,7 +2144,7 @@ version = "0.4.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
 dependencies = [
- "aho-corasick",
+ "aho-corasick 1.1.4",
  "memchr",
  "regex-syntax",
 ]

Cargo.toml

@@ -36,6 +36,7 @@ indexmap = "2.14"
 indoc = "2.0"
 itoa = "1.0"
 mime_guess = "2.0"
+minify-js = "0.6"
 parking_lot = "0.12"
 pastey = "0.2"
 path-slash = "0.2"

README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/banner.png" />
+<img src="https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/banner.png" />
 
 <h1>PageTop</h1>
 

build.rs

@@ -1,6 +1,12 @@
-use pagetop_build::StaticFilesBundle;
+use pagetop_build::{StaticFilesBundle, copy_dir};
 
 fn main() -> std::io::Result<()> {
+    // Regenera `static/` desde cero sólo si hay cambios en `assets/`.
+    println!("cargo:rerun-if-changed=assets");
+    let _ = std::fs::remove_dir_all("static");
+
+    copy_dir("assets", "static")?;
+
     StaticFilesBundle::from_dir("./static", None)
         .with_name("assets")
         .build()

extensions/pagetop-htmx/build.rs

@@ -1,6 +1,12 @@
-use pagetop_build::StaticFilesBundle;
+use pagetop_build::{StaticFilesBundle, copy_dir};
 
 fn main() -> std::io::Result<()> {
+    // Regenera `static/` desde cero sólo si hay cambios en `assets/`.
+    println!("cargo:rerun-if-changed=assets");
+    let _ = std::fs::remove_dir_all("static");
+
+    copy_dir("assets", "static")?;
+
     StaticFilesBundle::from_dir("./static", None)
         .with_name("htmx")
         .build()

extensions/pagetop-seaorm/src/lib.rs

@@ -148,7 +148,7 @@ async fn example() -> Result<(), DbErr> {
 */
 
 #![doc(
-    html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/favicon.ico"
+    html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/favicon.ico"
 )]
 
 use pagetop::prelude::*;

helpers/pagetop-build/Cargo.toml

@@ -3,8 +3,7 @@ name = "pagetop-build"
 version = "0.3.2"
 
 description = """
-    Prepara un conjunto de archivos estáticos o archivos SCSS compilados para ser incluidos en el
+    Genera o prepara archivos estáticos para servirlos o incluirlos en un proyecto PageTop.
-    binario de un proyecto PageTop.
 """
 categories = ["development-tools::build-utils"]
 keywords = ["pagetop", "build", "assets", "resources", "static"]
@@ -17,4 +16,5 @@ authors.workspace = true
 
 [dependencies]
 grass.workspace = true
+minify-js.workspace = true
 pagetop-statics.workspace = true

helpers/pagetop-build/README.md

@@ -2,7 +2,7 @@
 
 <h1>PageTop Build</h1>
 
-<p>Prepara un conjunto de archivos estáticos o archivos SCSS compilados para ser incluidos en el binario de un proyecto <strong>PageTop</strong>.</p>
+<p>Genera o prepara archivos estáticos para servirlos o incluirlos en un proyecto <strong>PageTop</strong>.</p>
 
 [![Doc API](https://img.shields.io/docsrs/pagetop-build?label=Doc%20API&style=for-the-badge&logo=Docs.rs)](https://docs.rs/pagetop-build)
 [![Crates.io](https://img.shields.io/crates/v/pagetop-build.svg?style=for-the-badge&logo=ipfs)](https://crates.io/crates/pagetop-build)
@@ -19,81 +19,77 @@ configurables, basadas en HTML, CSS y JavaScript.
 
 ## Guía rápida
 
-Añadir en el archivo `Cargo.toml` del proyecto:
+La convención recomendada para extensiones, temas o aplicaciones basadas en **PageTop** es separar
+los archivos fuente de los generados siguiendo el patrón `assets/` -> `static/`:
 
-```toml
+- **`assets/`** - archivos versionados en el repositorio, por ejemplo archivos SCSS, JavaScript de
-[build-dependencies]
+  terceros, fuentes, etc. Todo lo que hay aquí se sube al repositorio y será la fuente para generar
-pagetop-build = { ... }
+  el directorio final `static/`.
-```
+- **`static/`** - archivos generados en tiempo de compilación a partir de `assets/`. Se añade a
+  `.gitignore` y nunca se sube al repositorio.
+- **`build.rs`** - orquesta la transformación: genera `static/` desde `assets/` para servirlos o
+  incluirlos en el proyecto.
 
-Y crear un archivo `build.rs` a la altura de `Cargo.toml` para indicar cómo se van a incluir los
+Durante el desarrollo, `static/` existe en disco y los archivos se sirven desde ahí. En producción,
-archivos estáticos o cómo se van a compilar los archivos SCSS para el proyecto. Casos de uso:
+el directorio no existe y los recursos salen del binario. La macro
+[`serve_static_files!`](https://docs.rs/pagetop/latest/pagetop/macro.serve_static_files.html)
+gestiona esta dualidad de forma transparente.
 
-### Incluir archivos estáticos desde un directorio
+### Funciones de transformación
 
-Hay que preparar una carpeta en el proyecto con todos los archivos que se quieren incluir, por
+Estas funciones se usan en el `build.rs` de cada proyecto para generar `static/` a partir de
-ejemplo `static`, y añadir el siguiente código en `build.rs` para crear el conjunto de recursos:
+`assets/`. Todas crean el directorio padre del destino si no existe y devuelven `io::Result<()>`
+para poder propagarse con `?` en caso de error.
+
+- `compile_scss()` - compila un archivo SCSS a CSS minificado.
+- `copy_dir()` - copia recursivamente un directorio completo. Útil para copiar todos los archivos de
+  `assets/` o de un subdirectorio a `static/` sin transformación.
+- `copy_file()` - copia un archivo al destino.
+- `copy_file_replacing()` - copia un archivo aplicando una lista de sustituciones de texto en su
+  contenido; útil para actualizar referencias internas (p.ej. `sourceMappingURL`) al renombrar
+  archivos.
+- `minify_js()` - minifica un archivo JavaScript.
+
+### Incluir los archivos estáticos en el proyecto
+
+Una vez generado `static/`, usaremos `StaticFilesBundle` para incluir su contenido en el binario. Se
+pueden crear tantos paquetes de recursos como sea necesario, siempre que tengan nombres distintos:
 
 ```rust,no_run
 use pagetop_build::StaticFilesBundle;
 
 fn main() -> std::io::Result<()> {
-    StaticFilesBundle::from_dir("./static", None)
+    StaticFilesBundle::from_dir("./static/css", None)
-        .with_name("guides")
+        .with_name("app_css")
+        .build()?;
+    StaticFilesBundle::from_dir("./static/fonts", None)
+        .with_name("app_fonts")
         .build()
 }
 ```
 
-Si es necesario, se puede añadir un filtro para seleccionar archivos específicos de la carpeta, por
+Si es necesario excluir algunos archivos del paquete de recursos (p. ej. los archivos `.map` que no
-ejemplo:
+son necesarios en producción), se puede pasar una función de filtro:
 
 ```rust,no_run
 use pagetop_build::StaticFilesBundle;
 use std::path::Path;
 
 fn main() -> std::io::Result<()> {
-    fn only_pdf_files(path: &Path) -> bool {
+    StaticFilesBundle::from_dir("./static/js", Some(only_js))
-        // Selecciona únicamente los archivos con extensión `.pdf`.
+        .with_name("app_js")
-        path.extension().map_or(false, |ext| ext == "pdf")
-    }
-
-    StaticFilesBundle::from_dir("./static", Some(only_pdf_files))
-        .with_name("guides")
         .build()
 }
+
+fn only_js(path: &Path) -> bool {
+    path.extension().map_or(false, |ext| ext == "js")
+}
 ```
 
-### Compilar archivos SCSS a CSS
+Cada paquete de recursos genera un archivo `.rs` en
-
+[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts).
-Se puede compilar un archivo SCSS, que podría importar otros a su vez, para preparar un recurso con
+No es necesario acceder a él directamente: el nombre asignado con `.with_name()` se usa como
-el archivo CSS minificado obtenido. Por ejemplo:
+identificador en `serve_static_files!` para configurar la ruta del servicio:
-
-```rust,no_run
-use pagetop_build::StaticFilesBundle;
-
-fn main() -> std::io::Result<()> {
-    StaticFilesBundle::from_scss("./styles/main.scss", "styles.min.css")
-        .with_name("main_styles")
-        .build()
-}
-```
-
-Este código compila el archivo `main.scss` de la carpeta `static` del proyecto, y prepara un recurso
-llamado `main_styles` que contiene el archivo `styles.min.css` obtenido.
-
-## Archivos generados
-
-Cada conjunto de recursos [`StaticFilesBundle`] genera un archivo en el directorio estándar
-[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts)
-donde se incluye el código necesario para compilar el proyecto. Por ejemplo, para
-`with_name("guides")` se genera un archivo llamado `guides.rs`.
-
-No hay ningún problema en generar más de un conjunto de recursos para cada proyecto siempre que se
-usen nombres diferentes.
-
-Normalmente no habrá que acceder a estos módulos; sólo declarar el nombre del conjunto de recursos
-en [`serve_static_files!`](https://docs.rs/pagetop/latest/pagetop/macro.serve_static_files.html)
-para configurar un servicio web que sirva los archivos desde la ruta indicada. Por ejemplo:
 
 ```rust,ignore
 use pagetop::prelude::*;
@@ -101,14 +97,47 @@ use pagetop::prelude::*;
 pub struct MyExtension;
 
 impl Extension for MyExtension {
-    /// Registra los recursos de `guides` en el router bajo `/ruta/a/guides`.
     fn configure_router(&self, mut router: Router) -> Router {
-        serve_static_files!(router, [guides] => "/ruta/a/guides");
+        serve_static_files!(router, ["./static/css", app_css] => "/public/css");
         router
     }
 }
 ```
 
+## Ejemplo completo
+
+```rust,no_run
+use pagetop_build::StaticFilesBundle;
+use pagetop_build::{compile_scss, copy_file, copy_file_replacing, minify_js};
+use std::path::Path;
+
+fn main() -> std::io::Result<()> {
+    // Regenera `static/` desde cero sólo si hay cambios en `assets/`.
+    println!("cargo:rerun-if-changed=assets");
+    let _ = std::fs::remove_dir_all("static");
+
+    // Genera `static/` a partir de `assets/`.
+    compile_scss("assets/main.scss", "static/css/main.min.css")?;
+    copy_file("assets/fonts/icon.woff2", "static/fonts/icon.woff2")?;
+    copy_file_replacing(
+        "assets/lib.min.js",
+        "static/js/app.min.js",
+        &[("lib.min.js.map", "app.min.js.map")],
+    )?;
+    minify_js("assets/shell.js", "static/js/shell.min.js")?;
+
+    // Prepara los paquetes de recursos para incluir en el proyecto.
+    StaticFilesBundle::from_dir("./static/css", None).with_name("app_css").build()?;
+    StaticFilesBundle::from_dir("./static/js", Some(only_js)).with_name("app_js").build()?;
+    StaticFilesBundle::from_dir("./static/fonts", None).with_name("app_fonts").build()
+}
+
+// Los `.map` no se incluyen, se servirán desde disco durante el desarrollo.
+fn only_js(path: &Path) -> bool {
+    path.extension().map_or(false, |ext| ext == "js")
+}
+```
+
 ## Advertencia
 
 **PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su

helpers/pagetop-build/src/lib.rs

@@ -3,7 +3,7 @@
 
 <h1>PageTop Build</h1>
 
-<p>Prepara un conjunto de archivos estáticos o archivos SCSS compilados para ser incluidos en el binario de un proyecto <strong>PageTop</strong>.</p>
+<p>Genera o prepara archivos estáticos para servirlos o incluirlos en un proyecto <strong>PageTop</strong>.</p>
 
 [![Doc API](https://img.shields.io/docsrs/pagetop-build?label=Doc%20API&style=for-the-badge&logo=Docs.rs)](https://docs.rs/pagetop-build)
 [![Crates.io](https://img.shields.io/crates/v/pagetop-build.svg?style=for-the-badge&logo=ipfs)](https://crates.io/crates/pagetop-build)
@@ -20,81 +20,77 @@ configurables, basadas en HTML, CSS y JavaScript.
 
 ## Guía rápida
 
-Añadir en el archivo `Cargo.toml` del proyecto:
+La convención recomendada para extensiones, temas o aplicaciones basadas en **PageTop** es separar
+los archivos fuente de los generados siguiendo el patrón `assets/` -> `static/`:
 
-```toml
+- **`assets/`** - archivos versionados en el repositorio, por ejemplo archivos SCSS, JavaScript de
-[build-dependencies]
+  terceros, fuentes, etc. Todo lo que hay aquí se sube al repositorio y será la fuente para generar
-pagetop-build = { ... }
+  el directorio final `static/`.
-```
+- **`static/`** - archivos generados en tiempo de compilación a partir de `assets/`. Se añade a
+  `.gitignore` y nunca se sube al repositorio.
+- **`build.rs`** - orquesta la transformación: genera `static/` desde `assets/` para servirlos o
+  incluirlos en el proyecto.
 
-Y crear un archivo `build.rs` a la altura de `Cargo.toml` para indicar cómo se van a incluir los
+Durante el desarrollo, `static/` existe en disco y los archivos se sirven desde ahí. En producción,
-archivos estáticos o cómo se van a compilar los archivos SCSS para el proyecto. Casos de uso:
+el directorio no existe y los recursos salen del binario. La macro
+[`serve_static_files!`](https://docs.rs/pagetop/latest/pagetop/macro.serve_static_files.html)
+gestiona esta dualidad de forma transparente.
 
-### Incluir archivos estáticos desde un directorio
+### Funciones de transformación
 
-Hay que preparar una carpeta en el proyecto con todos los archivos que se quieren incluir, por
+Estas funciones se usan en el `build.rs` de cada proyecto para generar `static/` a partir de
-ejemplo `static`, y añadir el siguiente código en `build.rs` para crear el conjunto de recursos:
+`assets/`. Todas crean el directorio padre del destino si no existe y devuelven `io::Result<()>`
+para poder propagarse con `?` en caso de error.
+
+- `compile_scss()` - compila un archivo SCSS a CSS minificado.
+- `copy_dir()` - copia recursivamente un directorio completo. Útil para copiar todos los archivos de
+  `assets/` o de un subdirectorio a `static/` sin transformación.
+- `copy_file()` - copia un archivo al destino.
+- `copy_file_replacing()` - copia un archivo aplicando una lista de sustituciones de texto en su
+  contenido; útil para actualizar referencias internas (p.ej. `sourceMappingURL`) al renombrar
+  archivos.
+- `minify_js()` - minifica un archivo JavaScript.
+
+### Incluir los archivos estáticos en el proyecto
+
+Una vez generado `static/`, usaremos `StaticFilesBundle` para incluir su contenido en el binario. Se
+pueden crear tantos paquetes de recursos como sea necesario, siempre que tengan nombres distintos:
 
 ```rust,no_run
 use pagetop_build::StaticFilesBundle;
 
 fn main() -> std::io::Result<()> {
-    StaticFilesBundle::from_dir("./static", None)
+    StaticFilesBundle::from_dir("./static/css", None)
-        .with_name("guides")
+        .with_name("app_css")
+        .build()?;
+    StaticFilesBundle::from_dir("./static/fonts", None)
+        .with_name("app_fonts")
         .build()
 }
 ```
 
-Si es necesario, se puede añadir un filtro para seleccionar archivos específicos de la carpeta, por
+Si es necesario excluir algunos archivos del paquete de recursos (p. ej. los archivos `.map` que no
-ejemplo:
+son necesarios en producción), se puede pasar una función de filtro:
 
 ```rust,no_run
 use pagetop_build::StaticFilesBundle;
 use std::path::Path;
 
 fn main() -> std::io::Result<()> {
-    fn only_pdf_files(path: &Path) -> bool {
+    StaticFilesBundle::from_dir("./static/js", Some(only_js))
-        // Selecciona únicamente los archivos con extensión `.pdf`.
+        .with_name("app_js")
-        path.extension().map_or(false, |ext| ext == "pdf")
-    }
-
-    StaticFilesBundle::from_dir("./static", Some(only_pdf_files))
-        .with_name("guides")
         .build()
 }
+
+fn only_js(path: &Path) -> bool {
+    path.extension().map_or(false, |ext| ext == "js")
+}
 ```
 
-### Compilar archivos SCSS a CSS
+Cada paquete de recursos genera un archivo `.rs` en
-
+[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts).
-Se puede compilar un archivo SCSS, que podría importar otros a su vez, para preparar un recurso con
+No es necesario acceder a él directamente: el nombre asignado con `.with_name()` se usa como
-el archivo CSS minificado obtenido. Por ejemplo:
+identificador en `serve_static_files!` para configurar la ruta del servicio:
-
-```rust,no_run
-use pagetop_build::StaticFilesBundle;
-
-fn main() -> std::io::Result<()> {
-    StaticFilesBundle::from_scss("./styles/main.scss", "styles.min.css")
-        .with_name("main_styles")
-        .build()
-}
-```
-
-Este código compila el archivo `main.scss` de la carpeta `static` del proyecto, y prepara un recurso
-llamado `main_styles` que contiene el archivo `styles.min.css` obtenido.
-
-## Archivos generados
-
-Cada conjunto de recursos [`StaticFilesBundle`] genera un archivo en el directorio estándar
-[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts)
-donde se incluye el código necesario para compilar el proyecto. Por ejemplo, para
-`with_name("guides")` se genera un archivo llamado `guides.rs`.
-
-No hay ningún problema en generar más de un conjunto de recursos para cada proyecto siempre que se
-usen nombres diferentes.
-
-Normalmente no habrá que acceder a estos módulos; sólo declarar el nombre del conjunto de recursos
-en [`serve_static_files!`](https://docs.rs/pagetop/latest/pagetop/macro.serve_static_files.html)
-para configurar un servicio web que sirva los archivos desde la ruta indicada. Por ejemplo:
 
 ```rust,ignore
 use pagetop::prelude::*;
@@ -102,39 +98,77 @@ use pagetop::prelude::*;
 pub struct MyExtension;
 
 impl Extension for MyExtension {
-    /// Registra los recursos de `guides` en el router bajo `/ruta/a/guides`.
     fn configure_router(&self, mut router: Router) -> Router {
-        serve_static_files!(router, [guides] => "/ruta/a/guides");
+        serve_static_files!(router, ["./static/css", app_css] => "/public/css");
         router
     }
 }
 ```
+
+## Ejemplo completo
+
+```rust,no_run
+use pagetop_build::StaticFilesBundle;
+use pagetop_build::{compile_scss, copy_file, copy_file_replacing, minify_js};
+use std::path::Path;
+
+fn main() -> std::io::Result<()> {
+    // Regenera `static/` desde cero sólo si hay cambios en `assets/`.
+    println!("cargo:rerun-if-changed=assets");
+    let _ = std::fs::remove_dir_all("static");
+
+    // Genera `static/` a partir de `assets/`.
+    compile_scss("assets/main.scss", "static/css/main.min.css")?;
+    copy_file("assets/fonts/icon.woff2", "static/fonts/icon.woff2")?;
+    copy_file_replacing(
+        "assets/lib.min.js",
+        "static/js/app.min.js",
+        &[("lib.min.js.map", "app.min.js.map")],
+    )?;
+    minify_js("assets/shell.js", "static/js/shell.min.js")?;
+
+    // Prepara los paquetes de recursos para incluir en el proyecto.
+    StaticFilesBundle::from_dir("./static/css", None).with_name("app_css").build()?;
+    StaticFilesBundle::from_dir("./static/js", Some(only_js)).with_name("app_js").build()?;
+    StaticFilesBundle::from_dir("./static/fonts", None).with_name("app_fonts").build()
+}
+
+// Los `.map` no se incluyen, se servirán desde disco durante el desarrollo.
+fn only_js(path: &Path) -> bool {
+    path.extension().map_or(false, |ext| ext == "js")
+}
+```
 */
 
 #![doc(
-    html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/favicon.ico"
+    html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/favicon.ico"
 )]
 
 use grass::{Options, OutputStyle, from_path};
-use pagetop_statics::{ResourceDir, resource_dir};
+use minify_js::{Session, TopLevelMode, minify};
+use pagetop_statics::resource_dir;
 
-use std::fs::{File, create_dir_all, remove_dir_all};
+use std::fs::{File, copy as fs_copy, create_dir_all, read_dir};
-use std::io::Write;
+use std::io::{self, Write};
-use std::path::Path;
+use std::path::{Path, PathBuf};
 
-/// Prepara un conjunto de recursos para ser incluidos en el binario del proyecto.
+// **< StaticFilesBundle >**************************************************************************
+
+/// Prepara un paquete de recursos para incluir en el binario del proyecto.
 pub struct StaticFilesBundle {
-    resource_dir: ResourceDir,
+    dir: PathBuf,
+    filter: Option<fn(&Path) -> bool>,
+    name: Option<String>,
 }
 
 impl StaticFilesBundle {
-    /// Prepara el conjunto de recursos con los archivos de un directorio. Opcionalmente se puede
+    /// Crea el paquete de recursos con los archivos del directorio indicado.
-    /// aplicar un filtro para seleccionar un subconjunto de los archivos.
     ///
     /// # Argumentos
     ///
-    /// * `dir` - Directorio que contiene los archivos.
+    /// * `dir` - Ruta al directorio con los archivos a incluir, normalmente `static/` o un
-    /// * `filter` - Una función opcional para aceptar o no un archivo según su ruta.
+    ///   directorio dentro de este.
+    /// * `filter` - Función opcional para seleccionar qué archivos incluir en el paquete.
     ///
     /// # Ejemplo
     ///
@@ -143,124 +177,227 @@ impl StaticFilesBundle {
     /// use std::path::Path;
     ///
     /// fn main() -> std::io::Result<()> {
-    ///     fn only_images(path: &Path) -> bool {
-    ///         matches!(
-    ///             path.extension().and_then(|ext| ext.to_str()),
-    ///             Some("jpg" | "png" | "gif")
-    ///         )
-    ///     }
-    ///
     ///     StaticFilesBundle::from_dir("./static", Some(only_images))
     ///         .with_name("images")
     ///         .build()
     /// }
+    ///
+    /// fn only_images(path: &Path) -> bool {
+    ///     matches!(
+    ///         path.extension().and_then(|ext| ext.to_str()),
+    ///         Some("jpg" | "png" | "gif")
+    ///     )
+    /// }
     /// ```
     pub fn from_dir<P>(dir: P, filter: Option<fn(&Path) -> bool>) -> Self
     where
         P: AsRef<Path>,
     {
-        let dir_path = dir.as_ref();
+        Self {
-        let dir_str = dir_path.to_str().unwrap_or_else(|| {
+            dir: dir.as_ref().to_path_buf(),
-            panic!(
+            filter,
-                "Resource directory path is not valid UTF-8: {}",
+            name: None,
-                dir_path.display()
-            );
-        });
-
-        let mut resource_dir = resource_dir(dir_str);
-
-        // Aplica el filtro si está definido.
-        if let Some(f) = filter {
-            resource_dir.with_filter(f);
         }
-
-        // Identifica el directorio temporal de recursos.
-        StaticFilesBundle { resource_dir }
     }
 
-    /// Prepara un recurso CSS minimizado a partir de la compilación de un archivo SCSS (que puede a
+    /// Asigna un nombre al paquete de recursos.
-    /// su vez importar otros archivos SCSS).
     ///
-    /// # Argumentos
+    /// El nombre debe ser un identificador Rust válido que se convertirá en nombre del módulo y de
+    /// la función del archivo `.rs` generado en `OUT_DIR`. Si no se llama a este método, el nombre
+    /// por defecto será `"bundle"`.
     ///
-    /// * `path` - Archivo SCSS a compilar.
+    /// Este nombre es el que hay que declarar en
-    /// * `target_name` - Nombre para el archivo CSS.
+    /// [`serve_static_files!`](https://docs.rs/pagetop/latest/pagetop/macro.serve_static_files.html)
+    /// para configurar la ruta del servicio:
     ///
-    /// # Ejemplo
+    /// ```rust,ignore
-    ///
+    /// serve_static_files!(router, ["./static/css", app_css] => "/public/css");
-    /// ```rust,no_run
+    /// //                                           ^^^^^^^
-    /// use pagetop_build::StaticFilesBundle;
+    /// //                                           debe coincidir con .with_name("app_css")
-    ///
-    /// fn main() -> std::io::Result<()> {
-    ///     StaticFilesBundle::from_scss("./bootstrap/scss/main.scss", "bootstrap.min.css")
-    ///         .with_name("bootstrap_css")
-    ///         .build()
-    /// }
     /// ```
-    pub fn from_scss<P>(path: P, target_name: &str) -> Self
-    where
-        P: AsRef<Path>,
-    {
-        // Crea un directorio temporal único para el archivo CSS (basado en su nombre, para que
-        // varias llamadas a from_scss en el mismo build.rs no se pisen).
-        let out_dir = std::env::var("OUT_DIR").unwrap();
-        let safe_name = target_name.replace(['.', '-'], "_");
-        let temp_dir = Path::new(&out_dir).join(format!("from_scss_{safe_name}"));
-
-        // Limpia el directorio temporal de ejecuciones previas, si existe.
-        if temp_dir.exists() {
-            remove_dir_all(&temp_dir).unwrap_or_else(|e| {
-                panic!(
-                    "Failed to clean temporary directory `{}`: {e}",
-                    temp_dir.display()
-                );
-            });
-        }
-        create_dir_all(&temp_dir).unwrap_or_else(|e| {
-            panic!(
-                "Failed to create temporary directory `{}`: {e}",
-                temp_dir.display()
-            );
-        });
-
-        // Compila SCSS a CSS.
-        let css_content = from_path(
-            path.as_ref(),
-            &Options::default().style(OutputStyle::Compressed),
-        )
-        .unwrap_or_else(|e| {
-            panic!(
-                "Failed to compile SCSS file `{}`: {e}",
-                path.as_ref().display(),
-            )
-        });
-
-        // Guarda el archivo CSS compilado en el directorio temporal.
-        let css_path = temp_dir.join(target_name);
-        File::create(&css_path)
-            .unwrap_or_else(|_| panic!("Failed to create CSS file `{}`", css_path.display()))
-            .write_all(css_content.as_bytes())
-            .unwrap_or_else(|_| panic!("Failed to write CSS content to `{}`", css_path.display()));
-
-        // Identifica el directorio temporal de recursos.
-        StaticFilesBundle {
-            resource_dir: resource_dir(temp_dir.to_str().unwrap()),
-        }
-    }
-
-    /// Asigna un nombre al conjunto de recursos.
     pub fn with_name(mut self, name: impl AsRef<str>) -> Self {
-        let name = name.as_ref();
+        self.name = Some(name.as_ref().to_string());
-        let out_dir = std::env::var("OUT_DIR").unwrap();
-        let filename = Path::new(&out_dir).join(format!("{name}.rs"));
-        self.resource_dir.with_generated_filename(filename);
-        self.resource_dir.with_module_name(format!("bundle_{name}"));
-        self.resource_dir.with_generated_fn(name);
         self
     }
 
-    /// Contruye finalmente el conjunto de recursos para incluir en el binario de la aplicación.
+    /// Genera el archivo `.rs` en `OUT_DIR` para incluir los recursos del directorio en el binario.
     pub fn build(self) -> std::io::Result<()> {
-        self.resource_dir.build()
+        let out_dir = std::env::var("OUT_DIR").unwrap();
+        let name = self.name.as_deref().unwrap_or("bundle");
+
+        let mut rd = resource_dir(&self.dir);
+        if let Some(f) = self.filter {
+            rd.with_filter(f);
+        }
+
+        let generated_filename = PathBuf::from(&out_dir).join(format!("{name}.rs"));
+        rd.with_generated_filename(generated_filename);
+        rd.with_module_name(format!("bundle_{name}"));
+        rd.with_generated_fn(name);
+        rd.build()
     }
 }
+
+// **< compile_scss / copy_dir / copy_file / copy_file_replacing / minify_js >**********************
+
+/// Compila un archivo SCSS a CSS minificado y lo escribe en la ruta de destino.
+///
+/// Crea el directorio padre del destino si no existe.
+///
+/// # Ejemplo
+///
+/// ```rust,no_run
+/// fn main() -> std::io::Result<()> {
+///     pagetop_build::compile_scss("assets/main.scss", "static/css/main.min.css")
+/// }
+/// ```
+pub fn compile_scss<P, Q>(src: P, dst: Q) -> io::Result<()>
+where
+    P: AsRef<Path>,
+    Q: AsRef<Path>,
+{
+    let src = src.as_ref();
+    let dst = dst.as_ref();
+
+    if let Some(parent) = dst.parent() {
+        create_dir_all(parent)?;
+    }
+
+    let options = Options::default().style(OutputStyle::Compressed);
+    let css = from_path(src, &options)
+        .map_err(|e| io::Error::other(format!("failed to compile `{}`: {e}", src.display())))?;
+    File::create(dst)?.write_all(css.as_bytes())
+}
+
+/// Copia recursivamente el contenido de un directorio a otro destino.
+///
+/// Crea el directorio destino y todos los subdirectorios necesarios.
+///
+/// # Ejemplo
+///
+/// ```rust,no_run
+/// fn main() -> std::io::Result<()> {
+///     pagetop_build::copy_dir("assets", "static")
+/// }
+/// ```
+pub fn copy_dir<P, Q>(src: P, dst: Q) -> io::Result<()>
+where
+    P: AsRef<Path>,
+    Q: AsRef<Path>,
+{
+    let src = src.as_ref();
+    let dst = dst.as_ref();
+    create_dir_all(dst)?;
+    for entry in read_dir(src)? {
+        let entry = entry?;
+        let src_path = entry.path();
+        let dst_path = dst.join(entry.file_name());
+        if src_path.is_dir() {
+            copy_dir(&src_path, &dst_path)?;
+        } else {
+            fs_copy(&src_path, &dst_path)?;
+        }
+    }
+    Ok(())
+}
+
+/// Copia un archivo a su destino.
+///
+/// Crea el directorio padre del destino si no existe.
+///
+/// # Ejemplo
+///
+/// ```rust,no_run
+/// fn main() -> std::io::Result<()> {
+///     pagetop_build::copy_file("assets/fonts/icon.woff2", "static/fonts/icon.woff2")
+/// }
+/// ```
+pub fn copy_file<P, Q>(src: P, dst: Q) -> io::Result<()>
+where
+    P: AsRef<Path>,
+    Q: AsRef<Path>,
+{
+    let src = src.as_ref();
+    let dst = dst.as_ref();
+
+    if let Some(parent) = dst.parent() {
+        create_dir_all(parent)?;
+    }
+
+    fs_copy(src, dst)?;
+    Ok(())
+}
+
+/// Copia un archivo a su destino con una lista de sustituciones de texto en su contenido.
+///
+/// El archivo fuente se lee como texto UTF-8; no debe usarse con archivos binarios. Las
+/// sustituciones de texto se aplican en orden y de forma encadenada: el resultado de cada
+/// sustitución puede ser entrada de la siguiente.
+///
+/// Crea el directorio padre del destino si no existe.
+///
+/// # Ejemplo
+///
+/// ```rust,no_run
+/// fn main() -> std::io::Result<()> {
+///     pagetop_build::copy_file_replacing(
+///         "assets/adminlte.min.js",
+///         "static/js/myapp.min.js",
+///         &[("adminlte.min.js.map", "myapp.min.js.map")],
+///     )
+/// }
+/// ```
+pub fn copy_file_replacing<P, Q>(src: P, dst: Q, replacements: &[(&str, &str)]) -> io::Result<()>
+where
+    P: AsRef<Path>,
+    Q: AsRef<Path>,
+{
+    let src = src.as_ref();
+    let dst = dst.as_ref();
+
+    if let Some(parent) = dst.parent() {
+        create_dir_all(parent)?;
+    }
+
+    let content = std::fs::read_to_string(src)?;
+    let patched = replacements
+        .iter()
+        .fold(content, |acc, (old, new)| acc.replace(old, new));
+    File::create(dst)?.write_all(patched.as_bytes())
+}
+
+/// Minifica un archivo JavaScript y lo escribe en la ruta de destino.
+///
+/// El archivo se procesa en modo de ámbito global (`TopLevelMode::Global`), adecuado para scripts
+/// sin `import`/`export`. Los archivos con sintaxis de módulo ES deben procesarse con
+/// `TopLevelMode::Module`, que el *crate* subyacente (`minify-js`) también soporta pero esta
+/// función no expone actualmente.
+///
+/// Crea el directorio padre del destino si no existe.
+///
+/// # Ejemplo
+///
+/// ```rust,no_run
+/// fn main() -> std::io::Result<()> {
+///     pagetop_build::minify_js("assets/shell.js", "static/js/shell.min.js")
+/// }
+/// ```
+pub fn minify_js<P, Q>(src: P, dst: Q) -> io::Result<()>
+where
+    P: AsRef<Path>,
+    Q: AsRef<Path>,
+{
+    let src = src.as_ref();
+    let dst = dst.as_ref();
+
+    if let Some(parent) = dst.parent() {
+        create_dir_all(parent)?;
+    }
+
+    let source = std::fs::read(src)?;
+    let session = Session::new();
+    let mut output = Vec::new();
+    minify(&session, TopLevelMode::Global, &source, &mut output)
+        .map_err(|e| io::Error::other(format!("failed to minify `{}`: {e:?}", src.display())))?;
+    File::create(dst)?.write_all(&output)
+}

helpers/pagetop-macros/src/lib.rs

@@ -31,7 +31,7 @@ cada proyecto PageTop.
 */
 
 #![doc(
-    html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/favicon.ico"
+    html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/favicon.ico"
 )]
 
 mod maud;

helpers/pagetop-minimal/src/lib.rs

@@ -40,7 +40,7 @@ La macro para generar identificadores dinámicos **`paste!`** se reexporta del *
 */
 
 #![doc(
-    html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/favicon.ico"
+    html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/favicon.ico"
 )]
 
 #[doc(hidden)]

helpers/pagetop-statics/src/lib.rs

@@ -35,7 +35,7 @@ como dependencia en su `Cargo.toml`.
 
 #![doc(test(no_crate_inject))]
 #![doc(
-    html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/favicon.ico"
+    html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/favicon.ico"
 )]
 #![allow(clippy::needless_doctest_main)]
 

src/lib.rs

@@ -1,7 +1,7 @@
 /*!
 <div align="center">
 
-<img src="https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/banner.png" />
+<img src="https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/banner.png" />
 
 <h1>PageTop</h1>
 
@@ -86,7 +86,7 @@ estructurar e inicializar la aplicación de forma modular.
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
 #![doc(
-    html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/favicon.ico"
+    html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/favicon.ico"
 )]
 
 // Alias para que las rutas absolutas `::pagetop::...` generadas por las macros funcionen en el
@@ -138,14 +138,14 @@ pub use pagetop_statics::{StaticFile, resource};
 
 pub use getter_methods::Getters;
 
-/// Contenedor para un conjunto de recursos embebidos.
+/// Contenedor para un paquete de recursos embebidos.
 #[derive(AutoDefault)]
 pub struct StaticResources {
     bundle: HashMap<&'static str, StaticFile>,
 }
 
 impl StaticResources {
-    /// Crea un contenedor para un conjunto de recursos generado por `build.rs` (consultar
+    /// Crea un contenedor para un paquete de recursos generado por `build.rs` (consultar
     /// [`pagetop_build`](https://docs.rs/pagetop-build)).
     pub fn new(bundle: HashMap<&'static str, StaticFile>) -> Self {
         Self { bundle }