@nutin/cli 2.1.0 → 3.0.0

package/templates/base/AGENTS.md.hbs

@@ -19,14 +19,19 @@ nutin.config.js   build/feature config — see below
 
 - Favor small, composable components.
 - One `View` = one route.
-- Import everything from barrel files (`core/index.js`, `components/index.js`, `views/index.js`, `services/index.js`) — do not deep-import.
+- Import framework code from the `core/index.js` barrel — do not deep-import into `core/`. App elements have no barrels: import them by file path.
+{{#if (eq lang "ts")}}
+- Framework types (`Nutin.ComponentConfig`, `Nutin.ComponentOptions`, `Nutin.CatalogConfig`, `Nutin.Template`, `Nutin.Routes`, `Nutin.RouteGuard`, `Nutin.RequestConfig`, …) live in the global `Nutin` namespace declared in `core/internals.d.ts` — use them without importing. App events extend it in `src/app/globals.d.ts` (`declare namespace Nutin { interface AppEventMap { … } }`).
+{{/if}}
+- `src/app/` layout is free; `components/`, `views/`, `services/` is the default suggestion.
 
 ## Commands
 
-- Serve: `{{packageManager}} run serve` (build + serve), `{{packageManager}} run serve:only` (no rebuild), `{{packageManager}} run dev` (watch mode).
-- Build: `{{packageManager}} run build` (dev) or `{{packageManager}} run build:prod` (production).
-- Generate: `{{packageManager}} run generate ELEMENT ELEMENT_NAME` (`ELEMENT` = `component`/`view`/`service`, supports nested paths, updates the nearest `index.ts` barrel).
-- Test: `{{packageManager}} run testin-nutin` (build + run), `{{packageManager}} run testin-nutin:only` (no rebuild), `{{packageManager}} run testin-nutin:watch`.
+- Serve: `{{packageManager}} run serve` (build + serve), `{{packageManager}} run serve:prod` (prod build + serve), `{{packageManager}} run serve:only` (no rebuild), `{{packageManager}} run dev` (watch mode, reloads the page after each rebuild). Port defaults to 9090; override with `-- --port <n>` or `PORT=<n>`.
+- Build: `{{packageManager}} run build` (dev) or `{{packageManager}} run build:prod` (production). Opt-in dependencies (Tailwind, `markdown`) are only installed automatically in an interactive terminal; elsewhere pass `-- -y` (or set `NUTIN_ASSUME_YES`).
+- Generate: `{{packageManager}} run generate ELEMENT ELEMENT_NAME` (`ELEMENT` = `component`/`view`/`service`; `ELEMENT_NAME` may be a nested path, generated in `src/app/<path>/`; fails if that folder already exists and isn't empty).
+- Test: `{{packageManager}} run testin-nutin` (build + run), `{{packageManager}} run testin-nutin:only` (no rebuild), `{{packageManager}} run testin-nutin:watch`, `{{packageManager}} run testin-nutin:coverage`, `{{packageManager}} run testin-nutin:verbose`.
+- Update Nutin: `nutin-update` refuses to run unless the project is committed (no changes, no untracked files; `--allow-dirty` skips the check). Files edited here that also changed upstream are merged three-way; overlapping edits get `diff3` conflict markers, and the project won't build, nor will `nutin-update` run again, until they're resolved (listed in `.nutin-meta.json`'s `unmergedFiles` and `NUTIN-UPDATE-REPORT.md`).
 
 ## Base classes
 
@@ -37,15 +42,16 @@ BaseComponent<T>     — render/destroy engine, data-* parsing, children
 └── View              — one per route; mounted/unmounted by the Router
 ```
 
-- `render()`: `onBeforeRender()` → sanitize + set `innerHTML` → mount children (`data-component`/`data-catalog`) → parse `data-i18n`/`data-pipe` → bind `data-event` listeners → `onAfterRender()`. Runs in full on every `render()` call — no virtual DOM/diffing.
+- `render()`: `onBeforeRender()` → sanitize the template and insert the resulting nodes (`SecurityHelper.sanitizeToFragment()`, never assigned to `innerHTML`) → mount children (`data-component`/`data-catalog`) → parse `data-i18n`/`data-pipe` → bind `data-event` listeners → `onAfterRender()`. Runs in full on every `render()` call — no virtual DOM/diffing; only children with `keep`/`keepBy` are kept (see "Children components").
 - `destroy()`: unbinds events, unsubscribes bus listeners, destroys children, removes the element.
-- `Service`: direct `new` throws — always use `MyService.getInstance()` (or the exported const). Auto-binds all methods to the instance. `registerCleanup(fn)` for teardown; `Service.destroyAll()` runs on `beforeunload`.
-- Overridable hooks (all no-op by default): `onBeforeRender`, `onAfterRender`, `onBeforeDestroy`, `onAfterDestroy`, `generateTemplate()`, `registerChildren()`. `View` adds router-only `onEnter()`/`onExit()`.
+- `Service`: direct `new` throws — always use `MyService.getInstance()` (or the exported const). Auto-binds all methods to the instance. `registerCleanup(fn)` callbacks run on `dispose()`, `MyService.destroy()` and `Service.destroyAll()` (tests, SSR) — nothing is torn down on page unload.
+- Overridable hooks (all no-op by default): `onBeforeRender`, `onAfterRender`, `onBeforeDestroy`, `onAfterDestroy`, `onKept`, `generateTemplate()`, `registerChildren()`. `View` adds router-only `onEnter()`/`onExit()`.
 
 ## Children components
 
-- Override `registerChildren(): ComponentConfig[]` to declare children — matched against `[data-component="selector"]` elements in the rendered template. ComponentConfig: `{ selector: 'my-selector', factory: (el) => new MyComponent(el, {...} )}`.
-- For repeated lists, use the inherited `createCatalogComponents({ items, elementName, selector, component })` inside `registerChildren()` instead of hand-writing one entry per item — targets `[data-catalog="selector"]`.
+- Override `registerChildren(): Nutin.ComponentConfig[]` to declare children — matched against `[data-component="selector"]` elements in the rendered template. ComponentConfig: `{ selector: 'my-selector', factory: (el) => new MyComponent(el, {...} ), keep?: string | number }`.
+- Children are destroyed and recreated on every parent render unless they have a `keep` value: with the same value on the next render, the child is kept as-is (factory not called, not re-rendered, DOM state preserved) and only its `onKept()` hook runs. Put in `keep` whatever should force a recreate.
+- For repeated lists, use the inherited `createCatalogComponents({ items, elementName, selector, component })` inside `registerChildren()` instead of hand-writing one entry per item — targets `[data-catalog="selector"]`. Add `keepBy: (item, index) => id` to keep items whose id is unchanged and whose item is shallow-equal; without it the catalog is rebuilt every render.
 
 ## `data-*` attributes
 
@@ -62,7 +68,7 @@ BaseComponent<T>     — render/destroy engine, data-* parsing, children
 
 ## DOM events binding
 
-Handlers are (re-)bound on every `render()`, not at build time. Always use private methods prefixed with underscore:
+Handlers are (re-)bound on every `render()`, not at build time. Always use private methods prefixed with underscore{{#if (eq lang "ts")}} (`protected` for a handler a subclass's template uses){{/if}}:
 
 ```html
 <div data-event="event:_myFunction:@value,@id">
@@ -71,17 +77,21 @@ Handlers are (re-)bound on every `render()`, not at build time. Always use priva
 private _myFunction(value: string, id: string) { doStuff() }
 ```
 
-Tokens: `@value`, `@id`, `@class`, `@textContent`, `@event`, `@target`, `@attr:name`, `@dataset:key`, plus string/number literals.
+{{#if (eq lang "ts")}}The build type-checks each handler name written in a template against the class: a missing one fails `tsc` at the template line, and handlers count as used for `noUnusedLocals` (on in this project). Names built with `${}` aren't checked. {{/if}}At runtime, a missing handler binds nothing and logs a `console.warn` in development.
+
+Tokens: `@value`, `@id`, `@class`, `@textContent`, `@event`, `@target`, `@attr:name`, `@dataset:key`, plus string/number literals (quoted literals may contain commas). Token values are raw (not HTML-escaped): escaping happens when they are rendered through an `html` template.
+
+Only defaults that leave the page are cancelled: link clicks (`<a href>`, unless modified, e.g. ctrl+click), form `submit` and submit-button clicks inside a form. Other events keep their default (typing, checking a box); take `@event` and call `preventDefault()` yourself if needed. A component only binds its own `data-event`/`data-bind`/`data-i18n` elements, not those inside nested child components.
 
 ## Core services
 
-- `AppEventBus` — `subscribe`/`once`/`emit`/`off`. Inside a component, prefer `this.listen(event, cb)` (auto-unsubscribes on `destroy()`) or `this.listenToRenderEvents([event1, event2, ...])` (re-runs `this.render()` whenever any of the given events fire) over calling the bus directly. Typed facades — each `on*` subscriber returns a closure you call directly to unsubscribe (`const off = Navigation.onNavigate(cb); ...; off();`), no need to keep the original callback reference around for `off()`:
+- `AppEventBus` — `subscribe`/`once`/`emit`/`off`.{{#if (eq lang "ts")}} Declare app events in `src/app/globals.d.ts`'s `Nutin.AppEventMap`: `emit()` requires the declared payload, and an event declared `undefined` takes none.{{/if}} Inside a component, prefer `this.listen(event, cb)` (auto-unsubscribes on `destroy()`) or `this.listenToRenderEvents([event1, event2, ...])` (re-runs `this.render()` whenever any of the given events fire) over calling the bus directly. Typed facades — each `on*` subscriber returns a closure you call directly to unsubscribe (`const off = Navigation.onNavigate(cb); ...; off();`), no need to keep the original callback reference around for `off()`:
   - `Navigation` — `navigateTo(path)`/`onNavigate`, `reload()`/`onReload`.
   - `Lifecycle` — `viewMount(viewName)`/`onViewMount`, `viewUnmount(viewName)`/`onViewUnmount`, plus generic `beforeRender`/`afterRender`/`beforeDestroy`/`afterDestroy`.
-- `AppRouter(routes)` — call once in `main.ts`; routes support `:param`/`:param?` and per-route guards.
+- `AppRouter(routes)` — call once in `main.ts` (optional: without it, mount components into any element with `new X(el).render()`; the build then skips the `routes` and `#app` checks, unless `generateSEOFiles` is on; a mount target that isn't found logs a `console.error` in development; testin-nutin's framework tests still mount into `#app`, see "Testing"); routes support `:param`/`:param?`, per-route guards, and lazy views: a factory returning `import('./views/x/x.view.js').then((m) => new m.XView())` loads the view on first visit (import it by its own file, not through a barrel{{#if (eq lang "ts")}}; factory type: global `Nutin.ViewFactory`{{/if}}). Keep `/` and `/404` eager. After each in-app navigation (not the first load or `Navigation.reload()`), focus moves to the view's `<h1>`, else the `<h1>` in `<main>`, else the view element, with `document.title` announced in a polite live region in that last case only (a focused heading is read by screen readers). Give each view an `<h1>`. `document.title` comes from `View.documentTitle()` if overridden, else `config/seo.json`'s title (with `generateSEOFiles`), the `<viewName>.title` translation, then `viewName`.
 - `registerGlobals({ before?, after? })` — each entry is `{ component, id }` (a bare class, constructed internally); mounts them outside `<main id="app">` (`before`/`after` control placement relative to it), stamping each root element with `id`. `hideGlobals(ids)`/`revealGlobals(ids)` (same module) toggle visibility by those ids from any component or view. Call once in `main.ts`.
-- `AppHttpClient` — `get/post/put/patch/delete<T>(endpoint, data?, config?)`; non-OK responses throw `HttpError`.
-- `I18nService` — `translate(key, fallback?)`, `setCurrentLanguage(lang)`; language list comes from `config/languages.json`.
+- `AppHttpClient` — `get/post/put/patch/delete<T>(endpoint, data?, config?)`; non-OK responses throw `HttpError`. Relative endpoints resolve against the page origin; a subclass with a base URL rejects endpoints leaving it. Build paths from values with ``path`/users/${id}` `` (encoded `/` and `\` in paths are rejected unless the API is in the `trustedAPIs` option). FormData/Blob bodies are sent as-is; 204 → `undefined`.
+- `I18nService` — `translate(key, fallback?)`, `setCurrentLanguage(lang)`; language list comes from `config/languages.json`. `initI18n()` (same module) loads the translations when `i18n` is enabled and does nothing otherwise; `main.ts` awaits it before starting the app. With `i18n: false`, prod builds drop the i18n code unless app code references `I18nService`.
 - `AppPipeRegistry` — `register(name, fn)` / `apply(name, value, args)`; backs `data-pipe`.
 
 ## Styling
@@ -91,40 +101,27 @@ Tokens: `@value`, `@id`, `@class`, `@textContent`, `@event`, `@target`, `@attr:n
 
 ## Pipes
 
-```
-// currency
-AppPipeRegistry.register('currency');
-    
-// date
-AppPipeRegistry.register('date');
-
-// number (toFixed)
-AppPipeRegistry.register('number');
-
-// string pipes
-AppPipeRegistry.register('uppercase');
-AppPipeRegistry.register('lowercase');    
-AppPipeRegistry.register('capitalize');
-AppPipeRegistry.register('capitalizeAll');
-AppPipeRegistry.register('truncate');
-    
-// utility pipes
-AppPipeRegistry.register('default');
-AppPipeRegistry.register('json');
-```
+Built-in pipes, registered by `registerPipes()` in `main.ts` (args in `data-pipe="name:arg1,arg2"`):
+
+- `currency:currency,locale` (defaults `USD`, `en-US`), `date:locale,format,time` (defaults browser language, `long`), `number:decimals` (`toFixed`, default `0`)
+- `uppercase`, `lowercase`, `capitalize`, `capitalizeAll`, `truncate:length,suffix` (defaults `50`, `...`)
+- `default:fallback`, `json`
+
+Add your own with `AppPipeRegistry.register(name, (value, ...args) => string)`; args arrive as strings.
 
 ## Configuration
 
 ### `nutin.config.js`
 
 Central options/tools config (see the inline comments for details):
-- `i18n`, `tailwind`, `generateSEO`, `dockerPorts` — top-level feature toggles (`dockerPorts` only applies once the docker feature is added).
+- `i18n`, `tailwind`, `generateSEOFiles` — top-level feature toggles.
+- `dockerPorts`, `markdownSources` — options of the `docker`/`markdown` features, only present once added with `nutin-add <feature>`.
 - `builder.{sass.paths, esbuild}` — build pipeline behavior.
 - `testinNutin.{includeFramework, includeTools, includeApp, jsdomOptions}` — test discovery/environment.
 
 ### `config/seo.json`
 
-Consumed by builder (production only) to generate static HTML per route. Unused if `nutin.config.js -> generateSEO` is disabled.
+Consumed by builder (production only) to generate static HTML per route. Unused if `nutin.config.js -> generateSEOFiles` is disabled. Dynamic routes (`/blog/:slug`) are written at their real URL from `mockParams` (or `outputPath`). Route guards run first, as an anonymous visitor: a route they block or redirect isn't prerendered nor listed in `sitemap.xml`.
 
 ### `config/languages.json`
 
@@ -132,17 +129,22 @@ Consumed by i18nService and builder. Unused if i18n is disabled.
 
 ## Security
 
-`SecurityHelper.sanitizeTemplate()` runs on every `render()` before `innerHTML` is set — `trustLevel` (`'strict' | 'normal' | 'trusted'`, default `'normal'`) controls how much is stripped (`<script>`/inline handlers always; `<iframe>`/`javascript:`/`data:` under `strict` only). Use `SecurityHelper.escapeHtml()` when manually interpolating strings into templates.
+Write every template with the `html` tag (`import { html, raw } from` core): `templateFn = (task) => html\`<li>${task.name}</li>\``. Every `${}` is HTML-escaped, whatever the data's source (input, HTTP, localStorage). Nested `html` results are inserted as-is, and arrays are inserted item by item (no `.join('')`). For lists, use `createCatalogComponents()` (see "Children components") rather than mapping items to markup in the template: each item becomes a child component with its own events and state, kept across renders with `keepBy`. Unquoted attribute values (`title=${x}`) are quoted automatically. A plain value in tag position (`<input ${x}>`) is filtered like `raw()` there: plain attributes stay, handlers, bindings and script URLs are dropped. Wrap HTML you want rendered in `raw()`: it's parsed in place at render (works inside `<svg>`/`<table>`) and loses Nutin's binding attributes (`data-event`, `data-component`, `data-catalog`, `data-bind`, `data-i18n`, `data-pipe*`). `trustedRaw()` keeps them, for markup you wrote yourself (e.g. compiled Markdown). An untagged template literal escapes nothing, and the build warns about each one containing `${}`.
+
+Every `render()` also sanitizes the template (`SecurityHelper.sanitizeToFragment()`) and inserts the resulting nodes directly — never re-parsed from a string. `trustLevel` (`'strict' | 'normal' | 'trusted'`, default `'normal'`) controls how much is stripped (`<script>`/`<style>`/`<link>`/`<base>`/`<meta>`, inline handlers, `srcdoc`, `javascript:` URLs, `data:` frames and SVG `<animate>`/`<set>` targeting URL attributes from `normal` up; `<iframe>`/`<object>`/`<embed>` and all `data:` URLs under `strict` only). Don't interpolate data into `data-event` args or `style`: use `data-x="${v}"` + `@dataset:x`. URL attributes (`href`, `src`, `action`, …) whose interpolated value makes them a `javascript:` URL get `about:invalid#nutin-blocked` instead, at every trust level. It is a second layer for `raw()` content, not a substitute for `html`.
 
 ## Testing (testin-nutin)
 
-Nutin's own hand-built test runner + jsdom - not Jest. `describe`/`it` only (**no `test()` alias**), `beforeAll`/`beforeEach`/`afterEach`/`afterAll` (one of each per suite, no stacking - inside `describe` statement, not top-level). All globals — no imports needed in test files.
+Nutin's own hand-built test runner + jsdom - not Jest. Tests are plain JavaScript (`*.test.js` importing the compiled `#root/dist/...` output){{#if (eq lang "ts")}}, so they aren't type-checked{{/if}}. `describe`/`it` only (**no `test()` alias**), `beforeAll`/`beforeEach`/`afterEach`/`afterAll` (one of each per suite, no stacking - anywhere inside the `describe` statement, not top-level). `it.todo(name)` lists a pending test. All globals — no imports needed in test files.
 
 - Matchers: `toBe`, `toEqual`, `toContain`, `toBeTruthy`/`toBeFalsy`, `toBeDefined`/`toBeUndefined`, `toBeInstanceOf`, `toHaveBeenCalled`/`toHaveBeenCalledWith`, `toBeLessThan`/`toBeGreaterThan`, `toThrow` — each has a `.not` counterpart.
 - `spyOn(obj, 'method')` returns `.calls`/`.callCount`/`.lastCall`, `.andCallFake(fn)`/`.andReturn(v)`, `.restore()` — unlike mocks, calls pass through by default.
 - `tools/testin-nutin/mocks/` has ready-made `MockEventBus`/`MockHttpClient`/`MockI18n`/`MockRouter` for constructor injection.
-- `useFakeTimers()`/`useRealTimers()`/`advanceTimersByTime(ms)`/`runAllTimers()` for time-dependent code.
+- `useFakeTimers()`/`useRealTimers()`/`advanceTimersByTime(ms)`/`runAllTimers()` for time-dependent code; `flushPromises()` for pending promises.
+- `silenceConsole(method | methods, fn)` runs `fn` with those `console` methods muted (sync or async). Use it in any test that triggers an expected warning/error.
+- `$(selector)`/`$$(selector)` — `document.querySelector`/`querySelectorAll` (as an array).
 - Test discovery/scope controlled by `nutin.config.js`'s `testinNutin.includeApp`/`includeFramework`.
+- Tests run against the built `dist/src/index.html`, and the framework tests (`includeFramework`) mount into its `#app` element. An app without the router that has no `#app` keeps an empty `<div id="app"></div>` in `src/index.html` (not `hidden`: focus tests need it focusable), or sets `includeFramework: false`.
 
 ## Nutin
 
@@ -165,4 +167,4 @@ When modifying Nutin `core/` files:
 
 ## Documentation
 
-[Nutin Documentation](https://github.com/LoisKOUNINEF/nutin/tree/main/docs)
+[Nutin Documentation](https://www.nutin.dev/docs)

package/templates/base/GETTING_STARTED.md.hbs

@@ -15,7 +15,7 @@
 
 ```
 src/
-  app/
+  app/    -- suggested layout: organize src/app however you like
     components/
     services/
     views/
@@ -27,23 +27,33 @@ src/
 
 tools/    -- build, development, generator and testing
 
-nutin.config.js   -- features and configuration
+nutin.config.js   -- options and configuration
 ```
 
+* Views **orchestrate application flow**
+* Components **encapsulate UI behavior**
+* Services **handle application concerns** through shared instances
+
 ### Imports
 
-Imports use **relative paths** and end with `.js` extension.
+- Imports use **relative paths** and end with `.js` extension.
 
 ```js
 import { Foo } from 'relative/path/to/foo.js';
 ```
 
+- Use Nutin's code barrel file (`src/core/index.js`) to import Nutin's modules.
+{{#if (eq lang "ts")}}
+- Nutin's types (`Nutin.ComponentConfig`, `Nutin.Routes`, `Nutin.Template`, …) live in the global `Nutin` namespace declared in `src/core/internals.d.ts`: no import needed.
+{{/if}}
+
 ## How do I run my app?
 
 ```bash
 # Development
 {{packageManager}} run serve # build and serve
 {{packageManager}} run dev   # build and serve with live reload
+{{packageManager}} run dev -- --port 3000 # serve on another port (default 9090; PORT=3000 also works)
 
 # Build
 {{packageManager}} run build      # build the application
@@ -52,16 +62,14 @@ import { Foo } from 'relative/path/to/foo.js';
 
 ## How do I generate components, views and services?
 
-Generated elements are automatically exported from the corresponding barrel file:
-`src/app/<components|views|services>/index.ts`.
-
+Elements are generated in `src/app/<path>/`, so you choose the project structure. The generator stops if the target folder already exists and isn't empty.
 
 ```bash
-{{packageManager}} run generate <component|view|service> ELEMENT_NAME
+{{packageManager}} run generate <component|view|service> PATH/TO/ELEMENT_NAME
 
 # Examples
-{{packageManager}} run generate component my-component # Target dir: src/app/components/my-component/
-{{packageManager}} run generate component path/to/my-component/ # Target dir: src/app/components/path/to/my-component/
+{{packageManager}} run generate component components/hello-world # generates src/app/components/hello-world/hello-world.component.ts|html|scss
+{{packageManager}} run generate view user/dashboard # generates src/app/user/dashboard/dashboard.view.ts|html|scss
 ```
 
 ## What does a typical component look like?
@@ -75,8 +83,8 @@ components/
 ```
 
 ```ts
-// The builder injects the component's .html template here.
-const templateFn = (product: Product) => `__TEMPLATE_PLACEHOLDER__`;
+// The component's .html template is injected here.
+const templateFn = (product: Product) => html`__TEMPLATE_PLACEHOLDER__`;
 
 export class ProductCardComponent extends Component {
   private _product: Product;
@@ -87,7 +95,7 @@ export class ProductCardComponent extends Component {
   }
 
   // Declares children mounted into the data-component / data-catalog placeholders below.
-  public registerChildren(): ComponentConfig[] {
+  public registerChildren(): Nutin.ComponentConfig[] {
     // Single child, matched to <div data-component="product-details">
     const detailsComponent = {
       selector: `product-details`,
@@ -120,7 +128,8 @@ export class ProductCardComponent extends Component {
 
 ```html
 <div
-  data-event="click:_goToProductPage:${product.id}"
+  data-product-id="${product.id}"
+  data-event="click:_goToProductPage:@dataset:productId"
   class="product-card"
 >
   <h2 class="product-card__name">${product.name}</h2>
@@ -147,12 +156,12 @@ Defining both an inline template and an external `.html` file, or neither, fails
 
 ### Main file
 
-`nutin.config.js` - Main Nutin configuration and tool options. See the inline comments for details.
+`nutin.config.js` - Main Nutin configuration and tool options. See the inline comments and [How do I configure Nutin?](https://www.nutin.dev/docs/options-and-features/configure-nutin) for details.
+
+This is where you can:
 
-- `tailwind`, `i18n`, `generateSEOFiles` — top-level features, `false` by default. 
-See [Options and features](https://github.com/LoisKOUNINEF/nutin/tree/main/docs/OPTIONS_AND_FEATURES.md).
-- `builder.*` — controls build behavior.
-- `testinNutin.*` — controls Nutin's built-in testing toolkit.
+- Toggle options ([Tailwind CSS](https://www.nutin.dev/docs/options-and-features/use-tailwind-css), [i18n](https://www.nutin.dev/docs/options-and-features/use-i18n), [SEO file generation](https://www.nutin.dev/docs/options-and-features/use-seo-file-generation)). 
+- Configure the builder and the built-in testing toolkit.
 
 ### Specialized files
 
@@ -171,7 +180,7 @@ See [Options and features](https://github.com/LoisKOUNINEF/nutin/tree/main/docs/
 
 You can use any testing tool you prefer for application code.
 
-This project includes [testin-nutin](https://github.com/LoisKOUNINEF/nutin/tree/main/docs/TESTING.md), Nutin's lightweight testing toolkit. Nutin itself is tested exclusively with it, and the tests are included in the generated project so you can:
+This project includes [testin-nutin](https://www.nutin.dev/docs/testing), Nutin's small testing toolkit. Nutin itself is tested exclusively with it, and the tests are included in the generated project so you can:
 - use them as executable documentation;
 - run and modify Nutin's tests when modifying its code.
 
@@ -187,13 +196,13 @@ testinNutin: {
   includeApp: true,
 }
 ```
-*Note:* TestinNutin files use root imports.
+*Note:* TestinNutin files are plain JavaScript and use root imports{{#if (eq lang "ts")}}: they test the compiled output, so they aren't type-checked{{/if}}.
 ```js
 import { MyModule } from '#root/dist/src/path/to/my-module.js';
 ```
 
 ## Go further
 
-- [Repository documentation](https://github.com/LoisKOUNINEF/nutin/tree/main/docs/API.md)
-- [First app tutorial](https://www.nutin.org/tutorial)
-- [Nutin website](https://www.nutin.org)
+- [Documentation](https://www.nutin.dev/docs)
+- [First app tutorial](https://www.nutin.dev/tutorial)
+- [Nutin website](https://www.nutin.dev)

package/templates/base/README.md.hbs

@@ -2,13 +2,16 @@
 
 ## Development
 
-- `{{packageManager}} run serve` — build and serve
-- `{{packageManager}} run dev` — build and serve with live reload
+Requires Node.js 24 or later.
+
+- `{{packageManager}} run serve`: build and serve
+- `{{packageManager}} run dev`: build and serve with live reload
+- Both serve on port 9090 by default. Pass `-- --port 3000` (or set `PORT=3000`) to change it
 
 ## Build
 
-- `{{packageManager}} run build` — build the application
-- `{{packageManager}} run build:prod` — build the application for production
+- `{{packageManager}} run build`: build the application
+- `{{packageManager}} run build:prod`: build the application for production
 
 ## Getting started
 

package/templates/base/nutin.config.js.hbs

@@ -16,7 +16,7 @@ export default {
       bundle: true,
       minify: true,
       sourcemap: false,
-      target: ['es2015'],
+      target: ['es2020'],
       drop: ['console', 'debugger'],
     },
   },

package/templates/base/src/app/globals.d.ts.hbs

@@ -1,4 +1,7 @@
-declare interface AppEventMap {
+declare namespace Nutin {
+  interface AppEventMap {
     // Add app-specific event types here
-    // 'event': { /* payload? */ }
-};
+    // 'task-saved': { taskId: number };  // emit('task-saved', { taskId }) — payload required
+    // 'tasks-cleared': undefined;        // emit('tasks-cleared') — no payload
+  }
+}

package/templates/base/src/app/guards.ts.hbs

@@ -1,10 +1,8 @@
-import { RouteGuard } from "../core/index.js";
-
 export const Guards = {
   /**
    * Basic example
    */
-  requireAuth: (redirectTo: string = '/login'): RouteGuard => {
+  requireAuth: (redirectTo: string = '/login'): Nutin.RouteGuard => {
     return () => {
       const isAuthenticated = !!localStorage.getItem('user_token');
       return isAuthenticated || redirectTo;

package/templates/base/src/app/main.ts.hbs

@@ -1,5 +1,4 @@
-import nutinConfig from '../../nutin.config.js';
-import { AppRouter, Service, I18nService, registerPipes } from '../core/index.js';
+import { AppRouter, initI18n, registerPipes } from '../core/index.js';
 import { appRoutes } from './routes.js';
 
 class App {
@@ -10,12 +9,6 @@ class App {
 }
 
 document.addEventListener('DOMContentLoaded', async () => {
-  if (nutinConfig.i18n) {
-    await I18nService.initTranslations();
-  }
+  await initI18n();
   new App();
 });
-
-window.addEventListener('beforeunload', async () => {
-  await Service.destroyAll();
-});

package/templates/base/src/app/routes.ts.hbs

@@ -1,7 +1,13 @@
-import { Routes } from '../core/index.js';
-import { HomeView, NotFoundView } from './views/index.js';
+import { HomeView } from './views/home/home.view.js';
+import { NotFoundView } from './views/not-found/not-found.view.js';
+{{#if markdown}}
+import { markdownRoutes } from './markdown/markdown-routes.js';
+{{/if}}
 
-export const appRoutes: Routes = {
+export const appRoutes: Nutin.Routes = {
   '/': () => new HomeView(),
+{{#if markdown}}
+  ...markdownRoutes(),
+{{/if}}
   '/404': () => new NotFoundView(),
 }

package/templates/base/src/app/views/home/home.view.html.hbs

@@ -3,5 +3,5 @@
   <span style="font-style:italic;font-size:clamp(.6875rem,2vw,1rem);">nutin v{{version}}</span>
   <img src="/assets/images/logo-trans.avif" width=250 height=250 alt="nutin's logo. A frame opened on the top left through which a plant grows.">
   <div style="color:#C56648;font-size:clamp(1.125rem,4vw,1.5rem);">Happy Coding 🎉</div>
-  <div style="font-size:clamp(.75rem,2vw,1rem);font-style:italic;position:fixed;bottom:0;">so lightweight it's <span style="font-weight:bold;">nutin</span>.</div>
+  <div style="font-size:clamp(.75rem,2vw,1rem);font-style:italic;position:fixed;bottom:0;padding-bottom:.2rem;">it's <span style="font-weight:bold;"><a style="text-decoration:none;color:#6C8359;" href="https://nutin.dev">nutin</a></span>.</div>
 </div>

package/templates/base/src/app/views/home/home.view.ts.hbs

@@ -1,6 +1,6 @@
-import { View } from '../../../core/index.js';
+import { View, html } from '../../../core/index.js';
 
-const template = `__TEMPLATE_PLACEHOLDER__`;
+const template = html`__TEMPLATE_PLACEHOLDER__`;
 
 export class HomeView extends View {
   constructor() {

package/templates/base/src/app/views/not-found/not-found.view.ts.hbs

@@ -1,6 +1,6 @@
-import { Navigation, View } from '../../../core/index.js';
+import { Navigation, View, html } from '../../../core/index.js';
 
-const template = `__TEMPLATE_PLACEHOLDER__`;
+const template = html`__TEMPLATE_PLACEHOLDER__`;
 
 export class NotFoundView extends View {
   constructor() {