@stackcraftmx/calcita 0.32.2 → 0.51.0

package/cli/checkTexts.js

@@ -0,0 +1,209 @@
+// calcita check:texts — revisa los textos del proyecto sin abrir la app:
+//   1. que cada t('llave') escrita tal cual en el código exista en todos los idiomas (con su namespace: el de
+//      useToolkitTranslation('orders') del archivo, o el que trae la llave, 'common:actions.save');
+//   2. que cada idioma tenga las mismas llaves que los demás (lo que falta en inglés se pintaría en español… o como llave).
+// Sin esto, una llave que no existe se descubre cuando alguien la ve en la pantalla («profile:tabs.documents»).
+//
+// Lo que NO revisa: las llaves armadas con una variable (t(`status.${value}`)) ni las que llevan defaultValue (son opcionales).
+// Para esas está el aviso de Calcita en la consola (onMissingText de ToolkitProvider).
+//
+// Lee los archivos de textos del proyecto (src/**/*Texts.js y src/**/texts.js: cada uno exporta {es: {...}, en: {...}}) con
+// node, así que no deben importar otros archivos; el que los junta (con import.meta.glob) se salta. Los namespaces de Calcita
+// (common, table, validation…) salen de su dist/.
+//
+// Solo node, sin dependencias (el CLI corre antes de que el proyecto tenga nada instalado): function (regla de la casa).
+// Pruebas en checkTexts.test.js.
+import {readdir, readFile} from 'node:fs/promises';
+import {join, relative} from 'node:path';
+import {pathToFileURL} from 'node:url';
+
+const SOURCE_EXTENSIONS = /\.(jsx?|tsx?)$/;
+const TEST_FILE = /\.test\.(jsx?|tsx?)$/;
+const TEXT_FILE = /(?:^|\/)(?:texts|[A-Za-z0-9]+Texts)\.js$/;
+const IGNORED_FOLDERS = new Set(['node_modules', 'dist', 'coverage', '.git']);
+// el namespace de un archivo: useToolkitTranslation('orders') o useToolkitTranslation(['orders', …])
+const NAMESPACE_CALL = /useToolkitTranslation\(\s*\[?\s*(['"])([\w-]+)\1/g;
+// una llave escrita tal cual: t('list.title') o t("common:actions.save"); con lo que sigue, para ver si trae defaultValue
+const KEY_CALL = /\bt\(\s*(['"])([^'"`$\n]+?)\1([^)]{0,200})/g;
+const PLURAL_SUFFIXES = ['', '_zero', '_one', '_two', '_few', '_many', '_other'];
+
+/**
+ * Los archivos de una carpeta y sus subcarpetas, sin node_modules ni dist.
+ *
+ * @param {string} folder
+ * @returns {Promise<string[]>}
+ */
+async function filesOf(folder) {
+    const entries = await readdir(folder, {withFileTypes: true}).catch(() => []);
+    const nested = await Promise.all(entries.map(async (entry) => {
+        const path = join(folder, entry.name);
+        if (entry.isDirectory()) {
+            return IGNORED_FOLDERS.has(entry.name) ? [] : filesOf(path);
+        }
+        return [path];
+    }));
+    return nested.flat();
+}
+
+/**
+ * Suma los textos de un archivo a los de todos (por idioma y namespace, objetos por dentro). Aquí no truena con un repetido:
+ * lo anota, para decirlo junto con lo demás.
+ */
+function addTexts(combined, fileTexts, duplicates, fileName) {
+    const mergeInto = (target, added, place) => {
+        for (const [key, value] of Object.entries(added)) {
+            const isObject = value && typeof value === 'object';
+            const keyPath = [...place.path, key];
+            if (isObject && target[key] && typeof target[key] === 'object') {
+                mergeInto(target[key], value, {...place, path: keyPath});
+            } else if (Object.hasOwn(target, key)) {
+                duplicates.push(`«${place.namespace}:${keyPath.join('.')}» en ${place.language} (otra vez en ${fileName})`);
+            } else {
+                target[key] = isObject ? structuredClone(value) : value;
+            }
+        }
+    };
+    for (const [language, namespaces] of Object.entries(fileTexts)) {
+        combined[language] ??= {};
+        for (const [namespace, keys] of Object.entries(namespaces ?? {})) {
+            combined[language][namespace] ??= {};
+            mergeInto(combined[language][namespace], keys, {language, namespace, path: []});
+        }
+    }
+}
+
+/**
+ * ¿Parece un objeto de textos? ({es: {namespace: {...}}, en: {...}}: llaves de idioma con objetos adentro)
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function looksLikeTexts(value) {
+    return Boolean(value) && typeof value === 'object' && Object.keys(value).length > 0
+        && Object.entries(value).every(([language, namespaces]) => /^[a-z]{2}(-[A-Z]{2})?$/.test(language) && namespaces && typeof namespaces === 'object');
+}
+
+/** Lo que hay en un camino con puntos ('list.title') dentro de un objeto. */
+function valueAt(object, dottedKey) {
+    return dottedKey.split('.').reduce((current, step) => (current && typeof current === 'object' ? current[step] : undefined), object);
+}
+
+/** ¿Existe la llave (o su plural) en ese namespace? */
+function hasKey(namespaceTexts, key) {
+    return PLURAL_SUFFIXES.some((suffix) => typeof valueAt(namespaceTexts, `${key}${suffix}`) === 'string');
+}
+
+/** Todas las llaves con texto de un objeto, con puntos (para comparar idiomas); los plurales cuentan como su llave base. */
+function leafKeysOf(object, prefix = '') {
+    return Object.entries(object ?? {}).flatMap(([key, value]) => {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (value && typeof value === 'object') {
+            return leafKeysOf(value, path);
+        }
+        return [path.replace(/_(zero|one|two|few|many|other)$/, '')];
+    });
+}
+
+/**
+ * Los textos de Calcita (common, table, validation…), del dist/ del paquete que corre este CLI. Sin dist/ (el repo del paquete
+ * sin construir), ninguno: las llaves de esos namespaces no se revisan.
+ *
+ * @returns {Promise<Record<string, object>>}
+ */
+async function packageTextsOf() {
+    const texts = {};
+    for (const language of ['es', 'en']) {
+        try {
+            const module = await import(new URL(`../dist/locales/${language}.js`, import.meta.url).href);
+            texts[language] = module.default ?? {};
+        } catch {
+            return {};
+        }
+    }
+    return texts;
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.projectRoot la carpeta del proyecto
+ * @param {string} [options.sourceFolder] dónde está el código (por omisión src)
+ * @param {Record<string, object>} [options.packageTexts] los textos de Calcita (por omisión, los de su dist/)
+ * @returns {Promise<{problems: string[], checkedKeys: number, textFiles: string[], languages: string[]}>}
+ */
+export async function checkTexts({projectRoot, sourceFolder = 'src', packageTexts}) {
+    const sourceRoot = join(projectRoot, sourceFolder);
+    const files = await filesOf(sourceRoot);
+    const problems = [];
+
+    // 1. los textos del proyecto
+    const projectTexts = {};
+    const duplicates = [];
+    const textFiles = files.filter((file) => TEXT_FILE.test(file.replaceAll('\\', '/')));
+    const readTextFiles = [];
+    for (const file of textFiles) {
+        const fileName = relative(projectRoot, file);
+        // el que JUNTA los textos (appTexts.js, con el glob de Vite) no es un archivo de textos: se salta
+        if ((await readFile(file, 'utf8')).includes('import.meta.glob')) {
+            continue;
+        }
+        readTextFiles.push(fileName);
+        try {
+            const module = await import(pathToFileURL(file).href);
+            const exported = Object.values(module).filter(looksLikeTexts);
+            if (exported.length === 0) {
+                problems.push(`${fileName}: no exporta textos con la forma {es: {...}, en: {...}}`);
+            }
+            exported.forEach((fileTexts) => addTexts(projectTexts, fileTexts, duplicates, fileName));
+        } catch (error) {
+            problems.push(`${fileName}: no se pudo leer (${error.message.split('\n')[0]}); un archivo de textos no debe importar otros archivos`);
+        }
+    }
+    problems.push(...duplicates.map((duplicate) => `texto repetido: ${duplicate}`));
+
+    const languages = Object.keys(projectTexts);
+    // 2. que cada idioma tenga las mismas llaves
+    for (const language of languages) {
+        for (const otherLanguage of languages.filter((other) => other !== language)) {
+            for (const namespace of Object.keys(projectTexts[language])) {
+                const otherKeys = new Set(leafKeysOf(projectTexts[otherLanguage][namespace]));
+                for (const key of new Set(leafKeysOf(projectTexts[language][namespace]))) {
+                    if (!otherKeys.has(key)) {
+                        problems.push(`«${namespace}:${key}» está en ${language} y falta en ${otherLanguage}`);
+                    }
+                }
+            }
+        }
+    }
+
+    // 3. cada t('llave') escrita tal cual
+    const calcitaTexts = packageTexts ?? await packageTextsOf();
+    const textsOf = (language, namespace) => projectTexts[language]?.[namespace] ?? calcitaTexts[language]?.[namespace];
+    let checkedKeys = 0;
+    for (const file of files.filter((path) => SOURCE_EXTENSIONS.test(path) && !TEST_FILE.test(path))) {
+        const code = await readFile(file, 'utf8');
+        const fileNamespaces = [...code.matchAll(NAMESPACE_CALL)].map((match) => match[2]);
+        for (const match of code.matchAll(KEY_CALL)) {
+            const [, , key, rest] = match;
+            // con defaultValue la llave es opcional; una llave con espacios es un texto, no una llave
+            if (/defaultValue/.test(rest) || /\s/.test(key)) {
+                continue;
+            }
+            const line = code.slice(0, match.index).split('\n').length;
+            const place = `${relative(projectRoot, file)}:${line}`;
+            const [explicitNamespace, plainKey] = key.includes(':') ? key.split(':', 2) : [null, key];
+            const candidates = explicitNamespace ? [explicitNamespace] : fileNamespaces;
+            if (candidates.length === 0) {
+                continue;
+            }
+            checkedKeys += 1;
+            for (const language of languages.length > 0 ? languages : ['es']) {
+                const found = candidates.some((namespace) => hasKey(textsOf(language, namespace), plainKey));
+                if (!found) {
+                    problems.push(`${place}  «${explicitNamespace ? key : `${candidates[0]}:${key}`}» no existe en ${language}`);
+                }
+            }
+        }
+    }
+
+    return {problems, checkedKeys, textFiles: readTextFiles, languages};
+}

package/cli/packageVersions.js

@@ -5,9 +5,23 @@
 import {readFile} from 'node:fs/promises';
 
 // Lo que el paquete no usa, así que no está en sus devDependencies: i18next (su adaptador recibe la instancia del proyecto;
-// versión con más de dos semanas publicada al escogerla, pnpm espera un día antes de instalar una recién salida) y qrcode
-// (el QR de la cuenta de demostración; la misma versión que usan los ejemplos)
-const VERSIONS_NOT_IN_PACKAGE = Object.freeze({i18next: '26.4.2', qrcode: '1.5.4'});
+// versión con más de dos semanas publicada al escogerla, pnpm espera un día antes de instalar una recién salida), qrcode
+// (el QR de la cuenta de demostración; la misma versión que usan los ejemplos) y las pruebas de pantalla del proyecto
+// (Vitest con jsdom y Testing Library), en las versiones que ya se probaron juntas con el mismo Vite 7 y React 19, y ESLint
+const VERSIONS_NOT_IN_PACKAGE = Object.freeze({
+    i18next: '26.4.2',
+    qrcode: '1.5.4',
+    vitest: '5.0.3',
+    jsdom: '30.1.2',
+    '@testing-library/dom': '10.4.2',
+    '@testing-library/react': '16.3.3',
+    '@testing-library/user-event': '14.6.7',
+    // ESLint del proyecto nuevo (pnpm lint): versiones con más de dos semanas publicadas al escogerlas (03/11/2026)
+    eslint: '10.13.0',
+    '@eslint/js': '10.0.1',
+    'eslint-plugin-react-hooks': '7.1.1',
+    globals: '17.13.0',
+});
 
 /**
  * El package.json de Calcita (el del CLI que corre). OJO: por ruta de archivo y no con import: el CLI se publica tal cual,

package/cli/projectFiles.js

@@ -15,7 +15,12 @@ const BASE_DEPENDENCIES = Object.freeze([
 const HOOK_FORM_DEPENDENCIES = Object.freeze(['@hookform/resolvers', 'react-hook-form']);
 // la cuenta: las llaves de acceso (las pide @stackcraftmx/calcita/account) y el QR de la demostración
 const ACCOUNT_DEPENDENCIES = Object.freeze(['@simplewebauthn/browser', 'qrcode']);
-const DEV_DEPENDENCIES = Object.freeze(['@vitejs/plugin-react', 'vite']);
+// las pruebas de pantalla (pnpm test): Vitest con jsdom como navegador y Testing Library para picar como una persona; y ESLint
+// (pnpm lint), que caza al escribir lo que si no se ve en la pantalla del cliente (una variable que no existe: «t is not defined»)
+const DEV_DEPENDENCIES = Object.freeze([
+    '@eslint/js', 'eslint', 'eslint-plugin-react-hooks', 'globals',
+    '@testing-library/dom', '@testing-library/react', '@testing-library/user-event', '@vitejs/plugin-react', 'jsdom', 'vite', 'vitest',
+]);
 
 /** Un objeto con sus llaves en orden alfabético (como los escribe npm). */
 const sortedByKey = (record) => Object.fromEntries(Object.entries(record).sort(([first], [second]) => first.localeCompare(second)));
@@ -40,7 +45,7 @@ export function packageJsonOf({packageName, answers, calcitaPackage}) {
         version: '0.1.0',
         private: true,
         type: 'module',
-        scripts: {dev: 'vite', build: 'vite build', preview: 'vite preview'},
+        scripts: {dev: 'vite', build: 'vite build', preview: 'vite preview', test: 'vitest run', lint: 'eslint .', 'check:texts': 'calcita check:texts'},
         dependencies: sortedByKey({'@stackcraftmx/calcita': `^${calcitaPackage.version}`, ...versionsOf(dependencyNames, calcitaPackage)}),
         devDependencies: sortedByKey(versionsOf([...DEV_DEPENDENCIES], calcitaPackage)),
         engines: {node: '>=22'},

package/cli/templates/module/__Name__Page.test.jsx.tpl

@@ -0,0 +1,24 @@
+// La prueba de pantalla de __LABEL_ES__ (la armó el CLI de Calcita con make:module): la app completa abre en su ruta, con su
+// servidor de mentira, enseña lo que manda el servidor y agrega uno. Cámbiela junto con la pantalla.
+//
+//     pnpm test
+import {screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+
+import {__NAME___PATH} from '@/modules/__name__/routes.js';
+import {openScreen} from '@/testing/openScreen.jsx';
+
+describe('__LABEL_ES__', () => {
+    it('enseña lo que manda el servidor', async () => {
+        await openScreen(__NAME___PATH);
+        expect(await screen.findByRole('heading', {name: '__LABEL_ES__'})).toBeTruthy();
+        expect(await screen.findByText('Primer ejemplo')).toBeTruthy();
+    });
+
+    it('agrega uno y sale en la lista', async () => {
+        const {user} = await openScreen(__NAME___PATH);
+        await user.type(await screen.findByRole('textbox', {name: 'Nombre'}), 'Uno nuevo');
+        await user.click(screen.getByRole('button', {name: 'Guardar'}));
+        expect(await screen.findByText('Uno nuevo')).toBeTruthy();
+    });
+});

package/cli/templates/project/README.md.tpl

@@ -31,7 +31,8 @@ src/
   app/                el único lugar donde se conecta el framework: proveedores, marco, rutas, tema y textos
   core/               lo que comparten dos o más módulos (se importa de '@/core')
   fakeServer/         el servidor de mentira: datos en memoria con la forma del API de verdad
-  modules/<módulo>/   cada módulo en su carpeta: menu.js, routes.js, sus pantallas, su *Api.js y sus *Texts.js
+  modules/<módulo>/   cada módulo en su carpeta: menu.js, routes.js, sus pantallas, su *Api.js, sus *Texts.js y sus pruebas
+  testing/            el kit de las pruebas de pantalla: abrir la app en una dirección (openScreen) y los huecos de jsdom
 ```
 
 - **Un módulo nuevo no edita nada fuera de su carpeta**: el menú, las rutas y los textos se descubren solos.
@@ -42,6 +43,29 @@ src/
   validaciones) ya vienen.
 - **Imports con el alias `@/`** (= `src/`), declarado en `vite.config.js` y en `jsconfig.json`.
 
+## Pruebas de pantalla
+
+```bash
+pnpm test
+```
+
+Cada `*.test.jsx` abre la app COMPLETA en una dirección (`openScreen`, en `src/testing`), con el servidor de mentira, y pica
+como una persona: busca lo que se ve por su papel y su nombre (`screen.findByRole('heading', {name: 'Bienvenida'})`) y da
+clic o escribe con `user`. Pasa por lo mismo que la persona (permisos, menú, textos, avisos). Vienen las del inicio y las del
+módulo de ejemplo, y `make:module` arma la de cada módulo nuevo. Corren con Vitest y jsdom (un navegador de mentira): lo que
+depende de medir o pintar se revisa en un navegador de verdad.
+
+## Revisar antes de subir
+
+```bash
+pnpm lint          # ESLint: una variable que no existe, los hooks de React fuera de orden
+pnpm check:texts   # que cada t('llave') exista en todos los idiomas y que los idiomas tengan las mismas llaves
+```
+
+Las dos cazan al escribir lo que si no se descubre en la pantalla del cliente («t is not defined», «orders:tabs.documents»).
+Una llave armada con una variable no se puede revisar así: para esas, Calcita avisa en la consola del navegador (y
+`onMissingText` de `ToolkitProvider` se lo dice a su proyecto).
+
 ## Publicar una versión nueva
 
 `pnpm build` deja la app en `dist/`, con `version.json` (la versión de esa compilación). La app publicada lo vuelve a leer al
@@ -68,7 +92,16 @@ location /ventas/ {
 }
 ```
 
-Con otro prefijo se vuelve a construir.
+Con otro prefijo se vuelve a construir… o, si el prefijo lo decide el servidor al servir la página (Laravel con
+`config('app.url')`, un proxy con su ruta), se construye una sola vez con archivos relativos y la página trae su `<base>`:
+
+```bash
+ASSET_URL=./ pnpm build
+```
+
+```html
+<base href="/ventas/">   <!-- lo pone el servidor en index.html; el router y publicUrlOf lo leen al abrir -->
+```
 
 ## Crecer la app con el CLI
 

package/cli/templates/project/eslint.config.js.tpl

@@ -0,0 +1,27 @@
+// Las reglas de ESLint del proyecto (pnpm lint): lo que se caza al escribir y no en la pantalla del cliente. La que más
+// ahorra: no-undef, una variable que no existe (un `t` que una función auxiliar se quedó sin recibir truena con «t is not
+// defined» hasta que alguien abre esa pantalla). Y las de los hooks de React (en el orden de siempre, con sus dependencias).
+import js from '@eslint/js';
+import reactHooks from 'eslint-plugin-react-hooks';
+import globals from 'globals';
+
+export default [
+    {ignores: ['dist/', 'coverage/']},
+    js.configs.recommended,
+    reactHooks.configs.flat.recommended,
+    {
+        files: ['**/*.{js,jsx}'],
+        languageOptions: {
+            ecmaVersion: 'latest',
+            sourceType: 'module',
+            globals: {...globals.browser},
+            parserOptions: {ecmaFeatures: {jsx: true}},
+        },
+        rules: {
+            // un parámetro que no se usa a propósito lleva «unused» en el nombre (unusedEvent)
+            'no-unused-vars': ['error', {argsIgnorePattern: '^unused', varsIgnorePattern: '^unused', caughtErrors: 'none'}],
+        },
+    },
+    // la configuración y las pruebas corren en node
+    {files: ['*.config.js', 'src/testing/**', '**/*.test.{js,jsx}'], languageOptions: {globals: {...globals.node}}},
+];

package/cli/templates/project/src/app/appRouter.jsx.tpl

@@ -28,7 +28,8 @@ const moduleRouteGroups = Object.entries(ROUTE_MODULES)
 // las pantallas sin el marco (entrar…)
 const publicRoutes = Object.values(ROUTE_MODULES).flatMap((routeModule) => routeModule.publicRoutes ?? []);
 
-export const appRouter = createBrowserRouter([
+/** Las rutas de la app: el router del navegador (abajo) y el de memoria de las pruebas de pantalla (src/testing). */
+export const appRoutes = [
     {
         path: APP_PATHS.home,
         element: <AppProviders />,
@@ -46,6 +47,8 @@ export const appRouter = createBrowserRouter([
             },
         ]),
     },
+];
+
 // detrás de un proxy con prefijo (ASSET_URL), el router lo quita al leer la dirección y lo pone en cada liga: las pantallas
 // siguen escribiendo sus rutas desde la raíz ('/contacts')
-], {basename: ROUTER_BASENAME});
+export const appRouter = createBrowserRouter(appRoutes, {basename: ROUTER_BASENAME});

package/cli/templates/project/src/app/appTexts.js.tpl

@@ -4,7 +4,8 @@
 //
 // OJO: constante de módulo. ToolkitProvider vuelve a configurar todo cuando cambian sus textos; un objeto nuevo en cada
 // pintada lo haría en cada pintada.
-import {combineTexts} from '@/app/combineTexts.js';
+// combineTexts es del paquete: un texto repetido entre módulos truena y los objetos de adentro (validation.fields) se suman
+import {combineTexts} from '@stackcraftmx/calcita';
 import {shellTexts} from '@/app/shellTexts.js';
 
 const MODULE_TEXT_FILES = import.meta.glob('@/modules/*/*Texts.js', {eager: true});

package/cli/templates/project/src/core/accountConnector.js.tpl

@@ -20,6 +20,9 @@ export const DEMO_USER = Object.freeze({
     id: 'user-demo', name: 'Ana Martínez Ruiz', email: 'ana.martinez@ejemplo.com', subtitle: 'Administración', phone: '',
 });
 
+/** Dónde recuerda la demostración la sesión en este navegador (con el nombre de la app, para no chocar con otra). */
+export const DEMO_SESSION_STORAGE_KEY = '__APP_SLUG__:session';
+
 /** Sin dirección del API, la app trabaja con la demostración. */
 export const USES_DEMO_ACCOUNT = !import.meta.env.VITE_API_URL;
 
@@ -27,8 +30,7 @@ export const accountConnector = USES_DEMO_ACCOUNT
     ? createDemoAccountConnector({
         user: DEMO_USER,
         labels: ['Administración'],
-        // la sesión de la demostración se recuerda en este navegador, con el nombre de la app para no chocar con otra
-        storageKey: '__APP_SLUG__:session',
+        storageKey: DEMO_SESSION_STORAGE_KEY,
         issuer: '__APP_TITLE__',
         // el QR que escanea la app autenticadora
         toQrImageUrl: (otpauthUrl) => QRCode.toDataURL(otpauthUrl, {margin: 1}),

package/cli/templates/project/src/core/publicPaths.js.tpl

@@ -5,13 +5,21 @@
 // OJO: una dirección escrita a mano desde la raíz ('/favicon.svg', '/version.json') funciona en la raíz y se rompe detrás del
 // proxy: se arma con publicUrlOf.
 //
+// El prefijo también puede llegar al SERVIR la página, sin volver a construir: si la página trae <base href="/ventas/"> (Laravel
+// lo pone con config('app.url'), un proxy con su ruta), manda ese (documentBasePath). Para eso se construye con ASSET_URL=./
+// (archivos relativos a la página). Sin <base>, todo sigue como arriba.
+//
 // Funciones puras, no renderizan: function (regla de la casa).
 
+import {documentBasePath} from '@stackcraftmx/calcita';
+
 // en las pruebas de node no hay import.meta.env (es de Vite): ahí, la raíz
 const APP_BASE_URL = import.meta.env?.BASE_URL ?? '/';
+// el prefijo que puso el servidor en <base href> ('' en la raíz), o null si la página no trae <base>
+const SERVED_BASE_PATH = documentBasePath();
 
 /** El prefijo como lo pide el router: '/ventas' (sin la diagonal del final) o '/'. */
-export const ROUTER_BASENAME = APP_BASE_URL.replace(/\/$/, '') || '/';
+export const ROUTER_BASENAME = (SERVED_BASE_PATH ?? APP_BASE_URL.replace(/\/$/, '')) || '/';
 
 /**
  * La dirección de un archivo de public/ con el prefijo: 'favicon.svg' → '/ventas/favicon.svg'.
@@ -20,5 +28,5 @@ export const ROUTER_BASENAME = APP_BASE_URL.replace(/\/$/, '') || '/';
  * @returns {string}
  */
 export function publicUrlOf(path) {
-    return `${APP_BASE_URL}${path}`;
+    return SERVED_BASE_PATH === null ? `${APP_BASE_URL}${path}` : `${SERVED_BASE_PATH}/${path}`;
 }

package/cli/templates/project/src/modules/auth/SignInPage.test.jsx.tpl

@@ -0,0 +1,20 @@
+// La prueba de pantalla de entrar: sin sesión, la app manda a «Iniciar sesión» y regresa a donde iba al entrar. Entra con
+// el botón de la cuenta de ejemplo (la demostración): la prueba nunca escribe una contraseña.
+//
+//     pnpm test
+import {screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+
+import {openScreen} from '@/testing/openScreen.jsx';
+
+describe('entrar', () => {
+    it('sin sesión pide entrar y después abre la pantalla que se pidió', async () => {
+        const {user, router} = await openScreen('/', {signedIn: false});
+        expect(await screen.findByRole('heading', {name: 'Iniciar sesión'})).toBeTruthy();
+
+        await user.click(screen.getByRole('button', {name: 'Entrar con la cuenta de ejemplo'}));
+
+        expect(await screen.findByRole('heading', {name: 'Bienvenida'})).toBeTruthy();
+        expect(router.state.location.pathname).toBe('/');
+    });
+});

package/cli/templates/project/src/modules/home/HomePage.test.jsx.tpl

@@ -0,0 +1,16 @@
+// La prueba de pantalla del inicio: la app completa abre en «/» y enseña la bienvenida con sus primeros pasos. Es el ejemplo
+// para las demás: abrir la pantalla, buscar lo que ve la persona por su papel y su nombre, y picar como ella.
+//
+//     pnpm test
+import {screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+
+import {openScreen} from '@/testing/openScreen.jsx';
+
+describe('el inicio', () => {
+    it('enseña la bienvenida y cómo seguir con el CLI', async () => {
+        await openScreen('/');
+        expect(await screen.findByRole('heading', {name: 'Bienvenida'})).toBeTruthy();
+        expect(screen.getByText('pnpm exec calcita make:module orders')).toBeTruthy();
+    });
+});

package/cli/templates/project/src/testing/browserGaps.js.tpl

@@ -0,0 +1,70 @@
+// Lo que jsdom (el navegador de mentira de las pruebas) no trae y la app sí usa.
+//
+// Cada hueco se llena con lo mínimo para que la pantalla se dibuje. Ninguna prueba depende de que esto haga algo de
+// verdad: jsdom no mide ni pinta, así que tamaños, scroll y medidas de pantalla no se prueban aquí (eso es de un navegador
+// de verdad, con Playwright).
+//
+// Funciones puras, no renderizan: function (regla de la casa).
+
+/**
+ * Los archivos que la pantalla mandó guardar (una descarga), en orden: {fileName, href}. jsdom no sabe descargar; aquí se
+ * anota el nombre para que la prueba revise qué se habría guardado.
+ */
+export const savedFiles = [];
+
+/** Observador de tamaño o de vista que nunca avisa: en jsdom todo mide 0 y no cambia. */
+class SilentObserver {
+    observe() {}
+
+    unobserve() {}
+
+    disconnect() {}
+
+    takeRecords() {
+        return [];
+    }
+}
+
+/**
+ * Consulta de medios que nunca coincide: la pantalla se dibuja como en escritorio y en modo claro.
+ *
+ * @param {string} media la consulta, p. ej. '(prefers-color-scheme: dark)'
+ * @returns {MediaQueryList}
+ */
+function neverMatchingMediaQuery(media) {
+    return {
+        matches: false,
+        media,
+        onchange: null,
+        addEventListener() {},
+        removeEventListener() {},
+        addListener() {},
+        removeListener() {},
+        dispatchEvent() {
+            return false;
+        },
+    };
+}
+
+/** Llena los huecos de jsdom. */
+export function fillBrowserGaps() {
+    window.ResizeObserver ??= SilentObserver;
+    window.IntersectionObserver ??= SilentObserver;
+    window.matchMedia ??= neverMatchingMediaQuery;
+    // ir arriba al cambiar de pantalla y llevar a la vista lo elegido
+    window.scrollTo = () => {};
+    window.HTMLElement.prototype.scrollTo ??= function scrollTo() {};
+    window.HTMLElement.prototype.scrollIntoView ??= function scrollIntoView() {};
+    // descargas y vistas previas de archivos: una dirección de mentira
+    window.URL.createObjectURL ??= () => 'blob:prueba';
+    window.URL.revokeObjectURL ??= () => {};
+    // la liga de descarga se anota en savedFiles en lugar de navegar (jsdom no navega y lo diría con un error)
+    const followLink = window.HTMLAnchorElement.prototype.click;
+    window.HTMLAnchorElement.prototype.click = function click() {
+        if (this.hasAttribute('download')) {
+            savedFiles.push({fileName: this.getAttribute('download'), href: this.href});
+            return;
+        }
+        followLink.call(this);
+    };
+}

package/cli/templates/project/src/testing/openScreen.jsx.tpl

@@ -0,0 +1,58 @@
+// Abre una pantalla como la abre una persona: la app COMPLETA (sus rutas, el marco, la sesión, el menú y los avisos) en una
+// dirección, con el servidor de mentira contestando (src/fakeServer; sin VITE_API_URL).
+//
+//     const {user} = await openScreen('/orders');
+//     await screen.findByRole('heading', {name: 'Pedidos'});
+//     await user.click(screen.getByRole('button', {name: 'Guardar'}));
+//
+// Por qué la app completa y no el componente suelto: la prueba pasa por lo mismo que la persona (permisos, menú, textos y
+// avisos) y no hay un segundo armado de proveedores que se desfase del de la app.
+//
+// OJO: para esperar a que algo desaparezca, waitForElementToBeRemoved; nunca un waitFor que compare con null: en cada intento
+// imprime la página entera y con la app completa se acaba la memoria.
+import {render} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {RouterProvider, createMemoryRouter} from 'react-router';
+import CssBaseline from '@mui/material/CssBaseline';
+import {ThemeProvider} from '@mui/material/styles';
+
+import {appRoutes} from '@/app/appRouter.jsx';
+import {appTheme} from '@/app/appTheme.js';
+//#if auth
+import {DEMO_SESSION_STORAGE_KEY, DEMO_USER} from '@/core/accountConnector.js';
+//#endif
+
+//#if auth
+/**
+ * Abre la app en una dirección.
+ *
+ * @param {string} path la dirección de la pantalla, con su query (p. ej. '/orders?status=pending')
+ * @param {{signedIn?: boolean}} [options] signedIn: entra con la persona de la demostración sin pasar por la pantalla de
+ *     entrar (por omisión, sí); con false se ve la app como alguien sin sesión
+ * @returns {Promise<{user: object, router: object}>} la persona que da clics y escribe, y el router (para revisar a dónde fue)
+ */
+export async function openScreen(path, {signedIn = true} = {}) {
+    if (signedIn) {
+        // la demostración recuerda la sesión en este navegador con el id de la persona
+        window.localStorage.setItem(DEMO_SESSION_STORAGE_KEY, DEMO_USER.id);
+    }
+//#endif
+//#if !auth
+/**
+ * Abre la app en una dirección.
+ *
+ * @param {string} path la dirección de la pantalla, con su query (p. ej. '/orders?status=pending')
+ * @returns {Promise<{user: object, router: object}>} la persona que da clics y escribe, y el router (para revisar a dónde fue)
+ */
+export async function openScreen(path) {
+//#endif
+    const router = createMemoryRouter(appRoutes, {initialEntries: [path]});
+    const user = userEvent.setup();
+    render(
+        <ThemeProvider theme={appTheme}>
+            <CssBaseline />
+            <RouterProvider router={router} />
+        </ThemeProvider>,
+    );
+    return {user, router};
+}

package/cli/templates/project/src/testing/setup.js.tpl

@@ -0,0 +1,25 @@
+// Lo que necesita cada prueba de pantalla antes de empezar (vite.config.js, test.setupFiles).
+//
+// - Llena lo que jsdom (el navegador de mentira de las pruebas) no trae y la app usa (browserGaps.js).
+// - Los mensajes de yup como llaves de texto, igual que main.jsx: así salen en el idioma activo.
+// - Al terminar cada prueba borra lo que dibujó y lo que guardó el navegador: sin esto, la siguiente prueba vería la sesión,
+//   el modo oscuro o los filtros recordados de la anterior.
+import {afterEach} from 'vitest';
+import {cleanup, configure} from '@testing-library/react';
+import {buildYupLocale} from '@stackcraftmx/calcita/forms';
+
+import {fillBrowserGaps, savedFiles} from '@/testing/browserGaps.js';
+
+fillBrowserGaps();
+buildYupLocale();
+
+// findBy… espera hasta 5 s: una pantalla completa (rutas lazy, servidor de mentira con su demora) tarda más que el segundo
+// de fábrica
+configure({asyncUtilTimeout: 5000});
+
+afterEach(() => {
+    cleanup();
+    savedFiles.length = 0;
+    window.localStorage.clear();
+    window.sessionStorage.clear();
+});