@nutin/cli 2.1.1 → 3.0.0

package/lib/src/update-app/json-drift.mjs

@@ -0,0 +1,54 @@
+import path from 'path';
+import * as fsExtra from 'fs-extra';
+import { JsonManager } from '../create-app/json-manager.mjs';
+
+const fs = fsExtra.default;
+
+// package.json and tsconfig.json aren't rendered from templates (JsonManager writes them
+// once, at creation), so the template diff never sees them. They're compared with what
+// this CLI would generate instead, and only reported.
+// Only the entries nutin generates are compared; anything the user added is ignored.
+const PACKAGE_JSON_SECTIONS = ['scripts', 'devDependencies'];
+
+function same(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function compareEntries(file, section, yours = {}, generated = {}) {
+  return Object.entries(generated)
+    .filter(([key, value]) => !same(yours[key], value))
+    .map(([key, value]) => ({ file, key: section ? `${section}.${key}` : key, yours: yours[key], nutin: value }));
+}
+
+async function readJsonIfExists(filePath) {
+  if (!(await fs.pathExists(filePath))) return null;
+  try {
+    return await fs.readJSON(filePath);
+  } catch {
+    return null;
+  }
+}
+
+export async function findJsonDrift(projectPath, context) {
+  const jsonManager = new JsonManager();
+  const drift = [];
+
+  const packageJson = await readJsonIfExists(path.join(projectPath, 'package.json'));
+  if (packageJson) {
+    const generated = jsonManager.buildPackageJson(context);
+    for (const section of PACKAGE_JSON_SECTIONS) {
+      drift.push(...compareEntries('package.json', section, packageJson[section], generated[section]));
+    }
+  }
+
+  if (context.lang !== 'js') {
+    const tsconfig = await readJsonIfExists(path.join(projectPath, 'tsconfig.json'));
+    if (tsconfig) {
+      const generated = jsonManager.buildTsconfigJson();
+      drift.push(...compareEntries('tsconfig.json', 'compilerOptions', tsconfig.compilerOptions, generated.compilerOptions));
+      drift.push(...compareEntries('tsconfig.json', null, { include: tsconfig.include, exclude: tsconfig.exclude }, { include: generated.include, exclude: generated.exclude }));
+    }
+  }
+
+  return drift;
+}

package/lib/src/update-app/project-updater.mjs

@@ -8,12 +8,16 @@ import { fetchOldTemplates } from './fetch-old-templates.mjs';
 import { parseVersion, compareVersions } from './version-compare.mjs';
 import { bootstrapProjectMeta } from '../common/meta-bootstrap-prompt.mjs';
 import { printUpdateSummary } from './update-summary-printer.mjs';
-import { writeConflictReport } from './conflict-report-writer.mjs';
+import { writeUpdateReport, REPORT_FILE_NAME } from './conflict-report-writer.mjs';
+import { mergeFile, hasConflictMarkers, CONFLICT_MARKER } from './three-way-merge.mjs';
+import { isGitAvailable, getWorkingTreeStatus } from '../common/git.mjs';
 import { UpdateContextBuilder } from './update-context-builder.mjs';
 import { TemplateDiffer } from './template-differ.mjs';
+import { findJsonDrift } from './json-drift.mjs';
 
 const fs = fsExtra.default;
-const REPORT_FILE_NAME = 'NUTIN-UPDATE-REPORT.md';
+
+const UNDO_COMMAND = 'git checkout -- . && git clean -fd';
 
 export class ProjectUpdater {
   constructor() {
@@ -22,8 +26,12 @@ export class ProjectUpdater {
   }
 
   async updateProject(projectPath, options = {}) {
-    const { yes = false, from } = options;
+    const { yes = false, from, allowDirty = false } = options;
+    // Read before anything here writes .nutin-meta.json (bootstrap, resolved conflicts), so only your
+    // own changes count. Enforced right before the first file write.
+    const gitStatus = allowDirty ? null : await getWorkingTreeStatus(projectPath);
     const meta = await this.resolveMeta(projectPath);
+    await this.assertNoConflictMarkers(projectPath, meta);
 
     if (this.isUpToDate(meta)) {
       print.boldSuccess(`✅ Already up to date (nutin v${packageVersion}).`);
@@ -37,7 +45,7 @@ export class ProjectUpdater {
 
     try {
       const changeSet = await this.computeChangeSet(projectPath, meta, oldTemplatesRoot);
-      await this.applyChangeSet(projectPath, meta, changeSet, { yes });
+      await this.applyChangeSet(projectPath, meta, changeSet, { yes, gitStatus });
     } finally {
       await cleanup();
     }
@@ -62,6 +70,28 @@ export class ProjectUpdater {
     }
   }
 
+  // Files the last update left with conflict markers (meta.unmergedFiles): nothing is updated until
+  // they're resolved, so a merge never runs on top of markers and a re-run still reports them.
+  async assertNoConflictMarkers(projectPath, meta) {
+    const unmerged = meta.unmergedFiles ?? [];
+    if (unmerged.length === 0) return;
+
+    const stillMarked = [];
+    for (const relPath of unmerged) {
+      if (await hasConflictMarkers(path.join(projectPath, relPath))) stillMarked.push(relPath);
+    }
+    if (stillMarked.length > 0) {
+      throw new Error(
+        `${stillMarked.length} file(s) still have conflict markers from the last update — the project won't build until ` +
+        `they're resolved. Search for "${CONFLICT_MARKER}", merge, then run nutin-update again:\n` +
+        stillMarked.map((relPath) => `  - ${relPath}`).join('\n'),
+      );
+    }
+
+    await updateProjectMeta(projectPath, { unmergedFiles: [] });
+    print.info('Conflict markers from the last update are resolved.');
+  }
+
   isUpToDate(meta) {
     return compareVersions(meta.version, packageVersion) === 0;
   }
@@ -84,12 +114,13 @@ export class ProjectUpdater {
 
   async computeChangeSet(projectPath, meta, oldTemplatesRoot) {
     const { oldContext, newContext } = await this.contextBuilder.buildContexts(projectPath, meta);
-    return this.differ.diff(projectPath, oldTemplatesRoot, oldContext, newContext);
+    const changeSet = await this.differ.diff(projectPath, oldTemplatesRoot, oldContext, newContext);
+    return { ...changeSet, jsonDrift: await findJsonDrift(projectPath, newContext) };
   }
 
-  async applyChangeSet(projectPath, meta, changeSet, { yes }) {
-    const { toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated } = changeSet;
-    printUpdateSummary({ toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated });
+  async applyChangeSet(projectPath, meta, changeSet, { yes, gitStatus = null }) {
+    const { toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated, jsonDrift } = changeSet;
+    printUpdateSummary({ toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated, jsonDrift });
 
     if (toUpdate.length === 0 && toAdd.length === 0 && conflicts.length === 0) {
       print.boldSuccess('\n✅ Nothing to update.');
@@ -97,18 +128,32 @@ export class ProjectUpdater {
       return;
     }
 
-    if (!yes && (toUpdate.length > 0 || toAdd.length > 0)) {
+    // Binary files can't be merged: they're kept as they are and listed in the report.
+    const toMerge = conflicts.filter(({ newEntry, actualContent }) => !newEntry.isBinary && !Buffer.isBuffer(actualContent));
+    const binaryConflicts = conflicts.filter((conflict) => !toMerge.includes(conflict));
+
+    if (gitStatus) this.assertPristine(gitStatus);
+
+    if (toMerge.length > 0 && !(await isGitAvailable())) {
+      throw new Error(
+        `nutin-update needs git to merge the ${toMerge.length} file(s) you edited, but git was not found. ` +
+        'Install git and run nutin-update again. No files were changed.',
+      );
+    }
+
+    if (!yes && (toUpdate.length > 0 || toAdd.length > 0 || toMerge.length > 0)) {
       if (!process.stdin.isTTY) {
         print.warn('\n⚠️ Non-interactive shell detected — skipping the confirmation prompt.');
         print.boldInfo('Re-run with --yes to apply these updates automatically. No files were changed.');
         return;
       }
 
+      const merges = toMerge.length > 0 ? ` and merge ${toMerge.length} file(s) you edited` : '';
       const { proceed } = await inquirer.prompt([
         {
           type: 'confirm',
           name: 'proceed',
-          message: `\nApply ${toUpdate.length + toAdd.length} safe file update(s)?`,
+          message: `\nApply ${toUpdate.length + toAdd.length} file update(s)${merges}?`,
           default: true,
         },
       ]);
@@ -124,15 +169,79 @@ export class ProjectUpdater {
       await fs.writeFile(outputPath, newEntry.content);
     }
 
-    if (conflicts.length > 0) {
-      await writeConflictReport(projectPath, conflicts, meta.version, packageVersion);
-      print.boldError(`\n⚠️  ${conflicts.length} file(s) you modified need manual attention — see ${REPORT_FILE_NAME}`);
+    const { merged, conflicted } = await this.mergeEditedFiles(projectPath, meta, toMerge);
+
+    if (merged.length > 0 || conflicted.length > 0 || binaryConflicts.length > 0) {
+      await writeUpdateReport(projectPath, { merged, conflicted, binaryConflicts }, meta.version, packageVersion);
     }
 
-    await updateProjectMeta(projectPath, { version: packageVersion });
+    await updateProjectMeta(projectPath, {
+      version: packageVersion,
+      unmergedFiles: conflicted.map(({ relPath }) => relPath),
+    });
+
+    if (merged.length > 0) {
+      print.info(`\n${merged.length} file(s) you edited were merged with the new version — review them (listed in ${REPORT_FILE_NAME}).`);
+    }
+    if (binaryConflicts.length > 0) {
+      print.boldError(`\n⚠️  ${binaryConflicts.length} binary file(s) you modified were left as they are — see ${REPORT_FILE_NAME}`);
+    }
+    if (conflicted.length > 0) {
+      print.boldError(
+        `\n⚠️  ${conflicted.length} file(s) have conflict markers — the project won't build until they're resolved ` +
+        `(search for "${CONFLICT_MARKER}"):`,
+      );
+      conflicted.forEach(({ relPath }) => print.boldError(`    - ${relPath}`));
+    }
+    if (gitStatus) {
+      print.info(`\nTo undo this update, run from the project folder: ${UNDO_COMMAND}`);
+      print.info(`Important: this will also remove any untracked folder.`);
+    }
 
     print.boldSuccess(`\n✅ Updated to nutin v${packageVersion}.`);
   }
+
+  // The update must be undoable with git: no uncommitted changes and no untracked files in the
+  // project folder, so checkout + clean only reverts what the update wrote. --allow-dirty skips this.
+  assertPristine({ repo, gitFound, changes }) {
+    if (!gitFound) {
+      throw new Error('git was not found: nutin-update uses it to make the update undoable. Install git, or pass --allow-dirty. No files were changed.');
+    }
+    if (!repo) {
+      throw new Error(
+        'This project isn\'t in a git repository, so the update couldn\'t be undone. Run "git init" and commit, ' +
+        'or pass --allow-dirty. No files were changed.',
+      );
+    }
+    if (changes.length > 0) {
+      throw new Error(
+        'Commit or stash your changes first (untracked files included), so the update can be undone with git, ' +
+        `or pass --allow-dirty. No files were changed:\n${changes.map((line) => `    ${line}`).join('\n')}`,
+      );
+    }
+  }
+
+  // Three-way merge of each file you edited: the old nutin version is the base, so your edits and
+  // nutin's changes are both kept, and only overlapping edits get conflict markers.
+  async mergeEditedFiles(projectPath, meta, toMerge) {
+    const merged = [];
+    const conflicted = [];
+    const labels = { base: `nutin v${meta.version}`, theirs: `nutin v${packageVersion}` };
+
+    for (const { relPath, actualContent, baseContent, newEntry } of toMerge) {
+      const { content, conflictCount } = await mergeFile({
+        base: baseContent,
+        yours: actualContent,
+        theirs: newEntry.content,
+        labels,
+      });
+      await fs.writeFile(path.join(projectPath, relPath), content);
+      if (conflictCount > 0) conflicted.push({ relPath, conflictCount });
+      else merged.push({ relPath });
+    }
+
+    return { merged, conflicted };
+  }
 }
 
 export const projectUpdater = new ProjectUpdater();

package/lib/src/update-app/template-differ.mjs

@@ -11,8 +11,8 @@ function contentEquals(a, b) {
   return a === b;
 }
 
-// Paths the user is expected to hand-edit right after `create-app` — their generated
-// content is just placeholder/starter scaffolding, so nutin-update must never rewrite
+// Paths the user is expected to hand-edit right after `create-app`.
+// Their generated content is just placeholder/starter scaffolding, so nutin-update must never rewrite
 // or conflict-flag them.
 const FULLY_EXCLUDED_PATTERNS = [
   /^config\/[^/]+\.json$/,
@@ -21,7 +21,7 @@ const FULLY_EXCLUDED_PATTERNS = [
 ];
 
 // Like FULLY_EXCLUDED_PATTERNS, but only for files that already existed before this
-// update — a brand new file introduced by a newer template version should still be added.
+// update. A brand new file introduced by a newer template version should still be added.
 const ADD_ONLY_PATTERNS = [
   /^src\/styles(\/|$)/,
 ];
@@ -114,8 +114,8 @@ export class TemplateDiffer {
       if (contentEquals(actualContent, oldEntry.content)) {
         toUpdate.push({ relPath, newEntry });
       } else if (!contentEquals(actualContent, newEntry.content)) {
-        // Differs from both baselines — a real conflict.
-        conflicts.push({ relPath, actualContent, newEntry });
+        // Differs from both baselines: a real conflict, merged from the old baseline at apply time.
+        conflicts.push({ relPath, actualContent, baseContent: oldEntry.content, newEntry });
       }
     }
 

package/lib/src/update-app/three-way-merge.mjs

@@ -0,0 +1,42 @@
+import os from 'os';
+import path from 'path';
+import * as fsExtra from 'fs-extra';
+import { execFileAsync } from '../common/git.mjs';
+
+const fs = fsExtra.default;
+
+export const CONFLICT_MARKER = '<<<<<<< yours';
+
+// Merges nutin's changes (base -> theirs) into your file with `git merge-file`, which needs the git
+// binary but no repository. Overlapping edits get diff3 markers: yours, the old nutin version, the new one.
+export async function mergeFile({ base, yours, theirs, labels }) {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'nutin-merge-'));
+  try {
+    const [yoursPath, basePath, theirsPath] = ['yours', 'base', 'theirs'].map((name) => path.join(tmpDir, name));
+    await Promise.all([
+      fs.writeFile(yoursPath, yours),
+      fs.writeFile(basePath, base),
+      fs.writeFile(theirsPath, theirs),
+    ]);
+
+    const args = ['merge-file', '-p', '--diff3', '-L', 'yours', '-L', labels.base, '-L', labels.theirs, yoursPath, basePath, theirsPath];
+    try {
+      const { stdout } = await execFileAsync('git', args, { maxBuffer: 1024 * 1024 * 50 });
+      return { content: stdout, conflictCount: 0 };
+    } catch (error) {
+      // A positive exit code below 255 is the number of conflicts; anything else is a real failure.
+      if (Number.isInteger(error.code) && error.code > 0 && error.code < 255) {
+        return { content: error.stdout, conflictCount: error.code };
+      }
+      throw error;
+    }
+  } finally {
+    await fs.remove(tmpDir);
+  }
+}
+
+export async function hasConflictMarkers(filePath) {
+  if (!(await fs.pathExists(filePath))) return false;
+  const content = await fs.readFile(filePath, 'utf8');
+  return content.split('\n').some((line) => line.startsWith(CONFLICT_MARKER));
+}

package/lib/src/update-app/update-context-builder.mjs

@@ -13,6 +13,7 @@ export class UpdateContextBuilder {
     const baseContext = {
       projectName: packageJson.name,
       packageManager,
+      lang: meta.lang ?? 'ts',
       ...meta.features,
       ciCommand: getCiCommand(packageManager),
     };

package/lib/src/update-app/update-summary-printer.mjs

@@ -1,11 +1,13 @@
 import { print } from '../utils/print.mjs';
 
-export function printUpdateSummary({ toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated }) {
+const describeValue = (value) => (value === undefined ? '(missing)' : JSON.stringify(value));
+
+export function printUpdateSummary({ toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated, jsonDrift = [] }) {
   print.section('\nSummary:');
   print.info(`  ${toUpdate.length} file(s) will be updated (untouched since generation)`);
   print.info(`  ${toAdd.length} new file(s) will be added`);
   if (conflicts.length > 0) {
-    print.boldError(`  ${conflicts.length} file(s) you modified need manual attention`);
+    print.boldError(`  ${conflicts.length} file(s) you edited will be merged with the new version`);
   }
   if (noLongerGenerated.length > 0) {
     print.boldError(`  ${noLongerGenerated.length} file(s) nutin no longer generates — left in place, review manually:`);
@@ -19,4 +21,10 @@ export function printUpdateSummary({ toUpdate, toAdd, conflicts, unknown, remove
     print.section(`  ${removedByUser.length} file(s) nutin used to generate but you removed — not recreated:`);
     removedByUser.forEach(({ relPath }) => print.section(`    - ${relPath}`));
   }
+  if (jsonDrift.length > 0) {
+    print.section(`  ${jsonDrift.length} package.json/tsconfig.json value(s) differ from what this nutin version generates — never changed automatically, apply by hand if wanted:`);
+    jsonDrift.forEach(({ file, key, yours, nutin }) =>
+      print.section(`    - ${file} ${key}: yours ${describeValue(yours)}, nutin ${describeValue(nutin)}`)
+    );
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nutin/cli",
-  "version": "2.1.1",
+  "version": "3.0.0",
   "description": "The structure of a framework. The freedom of vanilla.",
   "preferGlobal": true,
   "main": "lib/index.mjs",
@@ -30,15 +30,16 @@
   "author": "Loïs Kouninef <loiskouninef@gmail.com>",
   "license": "MIT",
   "dependencies": {
-    "commander": "^9.0.0",
+    "commander": "^15.0.0",
     "diff": "^9.0.0",
-    "fs-extra": "^11.0.0",
-    "handlebars": "^4.7.8",
-    "inquirer": "^9.0.0",
-    "tar": "^7.5.22"
+    "fs-extra": "^11.4.1",
+    "handlebars": "^4.7.10",
+    "inquirer": "^14.2.3",
+    "tar": "^7.5.22",
+    "typescript": "5.9.3"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "repository": {
     "type": "git",
@@ -47,5 +48,5 @@
   "bugs": {
     "url": "https://github.com/LoisKOUNINEF/nutin/issues"
   },
-  "homepage": "www.nutin.org"
+  "homepage": "www.nutin.dev"
 }

package/templates/base/AGENTS.md.hbs

@@ -20,14 +20,18 @@ nutin.config.js   build/feature config — see below
 - Favor small, composable components.
 - One `View` = one route.
 - 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).
+- 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`.
+- 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
 
@@ -38,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
 
@@ -63,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">
@@ -72,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
@@ -92,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`
 
@@ -133,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
 
@@ -166,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)