@chill-sharp/create-app 1.1.12

package/README.md

@@ -0,0 +1,12 @@
+# Create ChillSharp App
+
+Creates a ready-to-run Angular application shell backed by the published ChillSharp npm packages.
+
+```bash
+npm create @chill-sharp/app my-app
+cd my-app
+npm install
+npm start
+```
+
+The generator copies the client-owned application shell and configures it to use `@chill-sharp/ts-client`, `@chill-sharp/ng-client`, and `@chill-sharp/ui-core` from npm.

package/bin/create-chill-sharp-app.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+import { copyFileSync, cpSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const packageDirectory = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const templateDirectory = path.join(packageDirectory, 'template');
+const packageManifest = JSON.parse(readFileSync(path.join(packageDirectory, 'package.json'), 'utf8'));
+const [projectName] = process.argv.slice(2).filter((argument) => !argument.startsWith('-'));
+
+if (!projectName || process.argv.includes('--help') || process.argv.includes('-h')) {
+  printUsage();
+  process.exit(projectName ? 0 : 1);
+}
+
+if (!/^[a-z0-9][a-z0-9-]*$/.test(projectName)) {
+  console.error('Project names must use lowercase letters, digits, and hyphens only.');
+  process.exit(1);
+}
+
+const destination = path.resolve(process.cwd(), projectName);
+if (existsSync(destination)) {
+  console.error(`Cannot create '${projectName}': '${destination}' already exists.`);
+  process.exit(1);
+}
+
+cpSync(templateDirectory, destination, { recursive: true });
+
+const generatedManifestPath = path.join(destination, 'package.json');
+const generatedManifest = JSON.parse(readFileSync(generatedManifestPath, 'utf8'));
+generatedManifest.name = projectName;
+generatedManifest.private = true;
+generatedManifest.description = 'Angular application powered by ChillSharp UI.';
+generatedManifest.dependencies = {
+  ...generatedManifest.dependencies,
+  '@chill-sharp/ng-client': `^${packageManifest.version}`,
+  '@chill-sharp/ts-client': `^${packageManifest.version}`,
+  '@chill-sharp/ui-core': `^${packageManifest.version}`
+};
+writeFileSync(generatedManifestPath, `${JSON.stringify(generatedManifest, null, 2)}\n`);
+
+rmSync(path.join(destination, 'package-lock.json'), { force: true });
+rmSync(path.join(destination, 'upgrade.ps1'), { force: true });
+rmSync(path.join(destination, 'upgrade.sh'), { force: true });
+rmSync(path.join(destination, 'publish-to-shared-folder.ps1'), { force: true });
+copyFileSync(path.join(destination, 'gitignore'), path.join(destination, '.gitignore'));
+rmSync(path.join(destination, 'gitignore'), { force: true });
+writeFileSync(path.join(destination, 'README.md'), `# ${projectName}\n\nAngular application shell powered by ChillSharp UI.\n\n## Get started\n\n\`\`\`bash\nnpm install\nnpm start\n\`\`\`\n\nThe application uses published ChillSharp packages from npm. Update the shared UI explicitly with:\n\n\`\`\`bash\nnpm install @chill-sharp/ui-core@latest\n\`\`\`\n\nConfigure the API and client URLs in \`public/env.js\` and \`public/runtime-config.js\`.\n`);
+writeFileSync(path.join(destination, 'HOW_TO_BUILD.md'), `# Build ${projectName}\n\n\`\`\`bash\nnpm install\nnpm run build\n\`\`\`\n\nThe ChillSharp dependencies are restored from npm; no local package archives are required.\n`);
+
+console.log(`Created ${projectName}.`);
+console.log('Next steps:');
+console.log(`  cd ${projectName}`);
+console.log('  npm install');
+console.log('  npm start');
+
+function printUsage() {
+  console.log('Usage: npm create @chill-sharp/app <project-name>');
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@chill-sharp/create-app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/e-500/chill-sharp.git",
+    "directory": "extra/chill-sharp-create-app"
+  },
+  "version": "1.1.12",
+  "description": "Create an Angular application powered by ChillSharp UI.",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "bin": {
+    "create-chill-sharp-app": "./bin/create-chill-sharp-app.mjs"
+  },
+  "scripts": {
+    "build": "node --check bin/create-chill-sharp-app.mjs"
+  },
+  "files": [
+    "bin",
+    "template",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "chillsharp",
+    "angular",
+    "starter",
+    "generator"
+  ],
+  "author": "Andrea Piovesan",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/.agents/skills/chillsharp-current-user-preferences/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: chillsharp-current-user-preferences
+description: Configure, expose, and consume ChillSharp.Auth's cached current-user culture, time zone, date-format, number-format, and theme preferences in server logic and UI clients.
+---
+
+# ChillSharp Current User Preferences
+
+Use this skill when a ChillSharp feature needs the authenticated user's display culture, time zone, date format, or number format. It covers server-side lifecycle hooks and UI/client consumption of the authoritative `AuthUser` preferences. Do not use it for browser-only preferences unrelated to `AuthUser`.
+
+## Model
+
+`ChillUserPreferences` is an immutable snapshot with `DisplayCultureName`, `DisplayTimeZone`, `DisplayDateFormat`, `DisplayNumberFormat`, and `PreferredTheme`. The backend stores `PreferredTheme` as an opaque string. In UI Core, unauthenticated users follow browser `prefers-color-scheme`; clients register extra themes with `provideChillSharpUiCore({ additionalThemes: ['theme-name'] })`. Entity hooks read the snapshot synchronously through:
+
+```csharp
+var preferences = context.GetCurrentUserPreferences();
+```
+
+Never load `AuthUser` from an `OnCreate`, `OnUpdate`, or other lifecycle hook merely to obtain these values.
+
+## Auth integration
+
+`AddChillAuthApi` registers `IChillAuthUserPreferencesAccessor` and the singleton `IChillAuthUserPreferencesCache`. Login and token refresh warm the snapshot; `ChillAuthService` refreshes it after an `AuthUser` save and removes it for deleted or renamed external identities.
+
+For a custom host DbContext, inject the scoped accessor and implement the two `IChillContext` methods below. Keep the accessor optional only when the context must also be constructible outside DI, such as for migrations or tests.
+
+```csharp
+private readonly IChillAuthUserPreferencesAccessor? _userPreferencesAccessor;
+
+public ChillUserPreferences GetCurrentUserPreferences() =>
+    _userPreferencesAccessor?.Current ?? ChillUserPreferences.Empty;
+
+public string GetDefaultUserCultureName()
+{
+    var cultureName = GetCurrentUserPreferences().DisplayCultureName;
+    return string.IsNullOrWhiteSpace(cultureName) ? GetPrimaryCultureName() : cultureName;
+}
+```
+
+The accessor is cache-only: when there is no authenticated principal or no warmed snapshot, it returns `ChillUserPreferences.Empty`. Do not add a fallback database query to lifecycle hooks.
+
+## API and client use
+
+The authenticated endpoint `GET /api/chill-auth/current-user-preferences` returns the same `ChillUserPreferences` snapshot as JSON:
+
+```json
+{
+  "displayCultureName": "it-IT",
+  "displayTimeZone": "Europe/Rome",
+  "displayDateFormat": "dd/MM/yyyy",
+  "displayNumberFormat": "N2"
+}
+```
+
+Use this endpoint after authentication and when restoring a session; do not infer the active display culture or time zone from the browser, operating system, token claims, or auth-management user endpoints. The C#, Python, TypeScript, Angular, Vue, and React clients expose it as `GetCurrentUserPreferences`, `get_current_user_preferences`, or `getCurrentUserPreferences`; the Vue and React packages also provide `useCurrentUserPreferences`.
+
+In Angular UI Core, inject `ChillService` and read its `userPreferences` signal (or its `displayCultureName`, `displayTimeZone`, `displayDateFormat`, and `displayNumberFormat` projections). Use these values to select UI language, format and parse dates and numbers, and convert UTC timestamps. Treat all fields as optional and choose an explicit fallback only when needed.
+
+## Entity use
+
+Use `DisplayTimeZone` as an IANA zone identifier only after validating it with the application's time-zone policy. Treat all fields as optional and provide an explicit fallback where one is required.
+
+```csharp
+public override void OnUpdate(IChillContext context)
+{
+    var timeZone = context.GetCurrentUserPreferences().DisplayTimeZone;
+    // Apply application-specific behavior only when timeZone is available.
+}
+```
+
+For full setup and cache behavior, read [CurrentUserPreferences.md](../../../doc/CurrentUserPreferences.md).

package/template/.agents/skills/chillsharp-ui-template/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: chillsharp-ui-template
+description: Build and customize Angular ChillSharp client projects from the UI template, including plugins, overrides, i18n, permissions, and runtime configuration.
+---
+
+# ChillSharp UI Client Template
+
+Use this skill for work in `chill-sharp-ui-template` or a client repository created from it.
+
+The template owns runtime configuration, branding, routes, client plugins, and overrides. Shared controls, data access, schema rendering, auth, i18n primitives, and permission evaluation belong in `@chill-sharp/ui-core` and the ChillSharp client packages. Do not copy or patch shared package internals.
+
+Keep `provideClientTemplateProviders()` in the app provider chain. Register feature routes in `src/app/core/plugins/register-client-plugins.ts`; register deliberate provider replacements in `src/app/core/overrides/register-client-overrides.ts`. Use public package APIs only.
+
+Treat backend schema as the source of entity/property metadata rather than duplicating it in Angular. Use runtime API configuration from `public/env.js`. Request localized text with an explicit culture and preserve backend fallback behavior. UI permission checks can hide or disable operations, but the protected backend is the enforcement boundary.
+
+Permission-sensitive features must account for `Module -> Entity -> Property`: entity `Query/Create/Update/Delete` is separate from property `See/Modify`. Never infer write access from a visible field.
+
+Add plugins under the client-owned plugin folder, register providers through the override/provider points, keep tenant/feature flags/branding in runtime config, add focused tests, and run `npm run build` after registration changes. This `.agents/skills` directory travels with the template into client repositories.

package/template/.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*.{ts,js,json,md,scss,html}]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

package/template/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm run test -- --browsers=ChromeHeadless

package/template/.github/workflows/deploy.yml

@@ -0,0 +1,36 @@
+name: Deploy
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: client-ui-build
+          path: dist/chill-sharp-ui-template
+
+      - name: Deploy placeholder
+        run: echo "Replace this step with the target hosting deployment command."

package/template/angular.json

@@ -0,0 +1,131 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "chill-sharp-ui-template": {
+      "projectType": "application",
+      "schematics": {
+        "@schematics/angular:component": {
+          "style": "scss"
+        }
+      },
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular-devkit/build-angular:application",
+          "options": {
+            "outputPath": "dist/chill-sharp-ui-template",
+            "index": "src/index.html",
+            "browser": "src/main.ts",
+            "polyfills": [
+              "zone.js"
+            ],
+            "tsConfig": "tsconfig.app.json",
+            "inlineStyleLanguage": "scss",
+            "assets": [
+              {
+                "glob": "*.js",
+                "input": "node_modules/@chill-sharp/ui-core/service-worker",
+                "output": "/"
+              },
+              {
+                "glob": "**/*",
+                "input": "public"
+              },
+              {
+                "glob": "**/*",
+                "input": "src/assets",
+                "output": "assets"
+              }
+            ],
+            "styles": [
+              "src/styles.scss"
+            ],
+            "scripts": []
+          },
+          "configurations": {
+            "production": {
+              "fileReplacements": [
+                {
+                  "replace": "src/environments/environment.ts",
+                  "with": "src/environments/environment.prod.ts"
+                }
+              ],
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "500kB",
+                  "maximumError": "1.5MB"
+                },
+                {
+                  "type": "anyComponentStyle",
+                  "maximumWarning": "14kB",
+                  "maximumError": "20kB"
+                }
+              ],
+              "outputHashing": "all"
+            },
+            "development": {
+              "optimization": false,
+              "extractLicenses": false,
+              "sourceMap": true
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "@angular-devkit/build-angular:dev-server",
+          "options": {
+            "port": 6202
+          },
+          "configurations": {
+            "production": {
+              "buildTarget": "chill-sharp-ui-template:build:production"
+            },
+            "development": {
+              "buildTarget": "chill-sharp-ui-template:build:development"
+            }
+          },
+          "defaultConfiguration": "development"
+        },
+        "extract-i18n": {
+          "builder": "@angular-devkit/build-angular:extract-i18n"
+        },
+        "test": {
+          "builder": "@angular-devkit/build-angular:karma",
+          "options": {
+            "polyfills": [
+              "zone.js",
+              "zone.js/testing"
+            ],
+            "tsConfig": "tsconfig.spec.json",
+            "inlineStyleLanguage": "scss",
+            "assets": [
+              {
+                "glob": "*.js",
+                "input": "node_modules/@chill-sharp/ui-core/service-worker",
+                "output": "/"
+              },
+              {
+                "glob": "**/*",
+                "input": "public"
+              },
+              {
+                "glob": "**/*",
+                "input": "src/assets",
+                "output": "assets"
+              }
+            ],
+            "styles": [
+              "src/styles.scss"
+            ],
+            "scripts": []
+          }
+        }
+      }
+    }
+  }
+}

package/template/doc/CurrentUserPreferences.md

@@ -0,0 +1,106 @@
+# Current User Preferences
+
+Versione italiana: [Italiano](./it/CurrentUserPreferences.md)
+
+`ChillSharp.Auth` can make the authenticated user's display preferences available to entity lifecycle hooks without querying `AuthUser` during every save.
+
+The immutable `ChillUserPreferences` snapshot contains:
+
+- `DisplayCultureName`
+- `DisplayTimeZone`
+- `DisplayDateFormat`
+- `DisplayNumberFormat`
+- `PreferredTheme`
+
+## Registration And Cache Lifecycle
+
+`AddChillAuthApi<TContext>()` registers a singleton `IChillAuthUserPreferencesCache` and scoped `IChillAuthUserPreferencesAccessor`.
+
+When the user logs in or refreshes a token, ChillSharp loads the matching `AuthUser` once and warms a snapshot keyed by its `ExternalId`. The accessor only reads that in-memory snapshot during requests; it does not query the user table.
+
+`ChillAuthService` refreshes the cached snapshot after creating or updating an `AuthUser`. It invalidates a deleted user's snapshot and both the previous and new keys when `ExternalId` changes.
+
+The cache stores scalar preference values, never a tracked EF Core `AuthUser` instance.
+
+## Current User Preferences API
+
+Authenticated clients can retrieve the same snapshot used by server-side code with:
+
+```http
+GET /api/chill-auth/current-user-preferences
+Authorization: Bearer <access token>
+```
+
+The response is a `ChillUserPreferences` JSON object:
+
+```json
+{
+  "displayCultureName": "it-IT",
+  "displayTimeZone": "Europe/Rome",
+  "displayDateFormat": "dd/MM/yyyy",
+  "displayNumberFormat": "N2",
+  "preferredTheme": "cini"
+}
+```
+
+Use this endpoint after login and when restoring an authenticated UI session. It is the source of truth for the language/culture, time zone, date format, and number format used by the API client and UI; do not derive those values from the browser, operating system, token claims, or an auth-management endpoint.
+
+The C# client exposes `GetCurrentUserPreferences()`. The Python client exposes `get_current_user_preferences()`, while the TypeScript client and Angular wrapper expose `getCurrentUserPreferences()`. The Vue and React packages additionally provide `useCurrentUserPreferences()`.
+
+In the Angular UI Core package, inject `ChillService` and consume its `userPreferences` signal or the individual `displayCultureName`, `displayTimeZone`, `displayDateFormat`, `displayNumberFormat`, and `preferredTheme` projections. `PreferredTheme` is an opaque server-stored string. UI Core uses browser `prefers-color-scheme` light/dark before login; client apps add selectable themes with `provideChillSharpUiCore({ additionalThemes: ['cini'] })`.
+
+## Host DbContext
+
+`IChillContext.GetCurrentUserPreferences()` returns `ChillUserPreferences.Empty` by default. In an auth-enabled custom host context, inject `IChillAuthUserPreferencesAccessor` and delegate to it:
+
+```csharp
+using ChillSharp;
+using ChillSharp.Auth.Services;
+
+public class AppDbContext : DbContext, IChillContext, IChillAuthDbContext
+{
+    private readonly IChillAuthUserPreferencesAccessor? _userPreferencesAccessor;
+
+    public AppDbContext(
+        DbContextOptions<AppDbContext> options,
+        IChillAuthUserPreferencesAccessor? userPreferencesAccessor = null)
+        : base(options)
+    {
+        _userPreferencesAccessor = userPreferencesAccessor;
+    }
+
+    public ChillUserPreferences GetCurrentUserPreferences() =>
+        _userPreferencesAccessor?.Current ?? ChillUserPreferences.Empty;
+
+    public string GetDefaultUserCultureName()
+    {
+        var cultureName = GetCurrentUserPreferences().DisplayCultureName;
+        return string.IsNullOrWhiteSpace(cultureName)
+            ? GetPrimaryCultureName()
+            : cultureName;
+    }
+}
+```
+
+The optional constructor parameter keeps design-time creation and tests that construct the context directly compatible. A normal dependency-injection-created context receives the accessor.
+
+`ChillAuthDbContext` already implements this pattern.
+
+## Entity Lifecycle Hooks
+
+Use the snapshot directly from the supplied `IChillContext`. No database access is required in the hook.
+
+```csharp
+public override void OnUpdate(IChillContext context)
+{
+    var preferences = context.GetCurrentUserPreferences();
+    var timeZone = preferences.DisplayTimeZone;
+
+    if (!string.IsNullOrWhiteSpace(timeZone))
+    {
+        // Apply application-specific time-zone behavior.
+    }
+}
+```
+
+All values can be empty for background jobs, unauthenticated calls, or a user without a matching `AuthUser`. Treat them as optional and choose an application fallback. Validate `DisplayTimeZone` before using it as a time-zone identifier.

package/template/doc/it/CurrentUserPreferences.md

@@ -0,0 +1,106 @@
+# Preferenze Dell'Utente Corrente
+
+English version: [English](../CurrentUserPreferences.md)
+
+`ChillSharp.Auth` puo rendere disponibili agli hook del ciclo di vita delle entita le preferenze di visualizzazione dell'utente autenticato senza interrogare `AuthUser` a ogni salvataggio.
+
+Lo snapshot immutabile `ChillUserPreferences` contiene:
+
+- `DisplayCultureName`
+- `DisplayTimeZone`
+- `DisplayDateFormat`
+- `DisplayNumberFormat`
+- `PreferredTheme`
+
+## Registrazione E Ciclo Di Vita Della Cache
+
+`AddChillAuthApi<TContext>()` registra il singleton `IChillAuthUserPreferencesCache` e lo scoped `IChillAuthUserPreferencesAccessor`.
+
+Quando l'utente esegue il login o rinnova un token, ChillSharp carica una volta l'`AuthUser` corrispondente e inizializza uno snapshot associato al suo `ExternalId`. L'accessor legge solo quello snapshot in memoria durante le richieste; non interroga la tabella utenti.
+
+`ChillAuthService` aggiorna lo snapshot in cache dopo la creazione o l'aggiornamento di un `AuthUser`. Invalida lo snapshot di un utente eliminato ed entrambe le chiavi, precedente e nuova, quando cambia `ExternalId`.
+
+La cache memorizza valori scalari delle preferenze, mai un'istanza EF Core tracciata di `AuthUser`.
+
+## API delle preferenze dell'utente corrente
+
+I client autenticati possono recuperare lo stesso snapshot utilizzato dal codice server con:
+
+```http
+GET /api/chill-auth/current-user-preferences
+Authorization: Bearer <access token>
+```
+
+La risposta e un oggetto JSON `ChillUserPreferences`:
+
+```json
+{
+  "displayCultureName": "it-IT",
+  "displayTimeZone": "Europe/Rome",
+  "displayDateFormat": "dd/MM/yyyy",
+  "displayNumberFormat": "N2",
+  "preferredTheme": "cini"
+}
+```
+
+Usa questo endpoint dopo il login e durante il ripristino di una sessione UI autenticata. E la fonte autorevole per lingua/cultura, fuso orario, formato data e formato numerico usati dal client API e dalla UI; non ricavare tali valori dal browser, dal sistema operativo, dalle claim del token o da un endpoint di gestione dell'autenticazione.
+
+Il client C# espone `GetCurrentUserPreferences()`. Il client Python espone `get_current_user_preferences()`, mentre il client TypeScript e il wrapper Angular espongono `getCurrentUserPreferences()`. I pacchetti Vue e React forniscono inoltre `useCurrentUserPreferences()`.
+
+Nel pacchetto Angular UI Core, inietta `ChillService` e usa il signal `userPreferences` oppure le singole proiezioni `displayCultureName`, `displayTimeZone`, `displayDateFormat`, `displayNumberFormat` e `preferredTheme`. `PreferredTheme` e una stringa opaca salvata dal server. UI Core usa `prefers-color-scheme` del browser prima del login; le app client aggiungono temi selezionabili con `provideChillSharpUiCore({ additionalThemes: ['cini'] })`.
+
+## DbContext Host
+
+Per impostazione predefinita `IChillContext.GetCurrentUserPreferences()` restituisce `ChillUserPreferences.Empty`. In un contesto host personalizzato con auth abilitata, inietta `IChillAuthUserPreferencesAccessor` e delega a esso:
+
+```csharp
+using ChillSharp;
+using ChillSharp.Auth.Services;
+
+public class AppDbContext : DbContext, IChillContext, IChillAuthDbContext
+{
+    private readonly IChillAuthUserPreferencesAccessor? _userPreferencesAccessor;
+
+    public AppDbContext(
+        DbContextOptions<AppDbContext> options,
+        IChillAuthUserPreferencesAccessor? userPreferencesAccessor = null)
+        : base(options)
+    {
+        _userPreferencesAccessor = userPreferencesAccessor;
+    }
+
+    public ChillUserPreferences GetCurrentUserPreferences() =>
+        _userPreferencesAccessor?.Current ?? ChillUserPreferences.Empty;
+
+    public string GetDefaultUserCultureName()
+    {
+        var cultureName = GetCurrentUserPreferences().DisplayCultureName;
+        return string.IsNullOrWhiteSpace(cultureName)
+            ? GetPrimaryCultureName()
+            : cultureName;
+    }
+}
+```
+
+Il parametro opzionale del costruttore mantiene compatibile la creazione a design-time e i test che costruiscono direttamente il contesto. Un contesto creato normalmente dalla dependency injection riceve l'accessor.
+
+`ChillAuthDbContext` implementa gia questo schema.
+
+## Hook Del Ciclo Di Vita Delle Entita
+
+Usa lo snapshot direttamente dall'`IChillContext` fornito. Nell'hook non e necessario alcun accesso al database.
+
+```csharp
+public override void OnUpdate(IChillContext context)
+{
+    var preferences = context.GetCurrentUserPreferences();
+    var timeZone = preferences.DisplayTimeZone;
+
+    if (!string.IsNullOrWhiteSpace(timeZone))
+    {
+        // Applica il comportamento relativo al fuso orario dell'applicazione.
+    }
+}
+```
+
+Tutti i valori possono essere vuoti per job in background, chiamate non autenticate o un utente senza un `AuthUser` corrispondente. Considerali opzionali e scegli un fallback dell'applicazione. Valida `DisplayTimeZone` prima di usarlo come identificatore di fuso orario.

package/template/gitignore

@@ -0,0 +1,6 @@
+/dist
+/tmp
+/out-tsc
+/coverage
+/node_modules
+/.angular

package/template/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "chill-sharp-ui-template",
+  "version": "1.1.6",
+  "private": true,
+  "description": "Template Angular shell for ChillSharp UI client applications.",
+  "scripts": {
+    "ng": "ng",
+    "start": "ng serve",
+    "build": "ng build",
+    "watch": "ng build --watch --configuration development",
+    "test": "ng test --watch=false",
+    "lint": "tsc --noEmit -p tsconfig.app.json"
+  },
+  "dependencies": {
+    "@angular/cdk": "^19.2.19",
+    "@angular/common": "^19.2.0",
+    "@angular/compiler": "^19.2.0",
+    "@angular/core": "^19.2.0",
+    "@angular/forms": "^19.2.0",
+    "@angular/platform-browser": "^19.2.0",
+    "@angular/platform-browser-dynamic": "^19.2.0",
+    "@angular/router": "^19.2.0",
+    "@chill-sharp/ng-client": "file:packages/chill-sharp-ng-client-1.1.6.tgz",
+    "@chill-sharp/ts-client": "file:packages/chill-sharp-ts-client-1.1.6.tgz",
+    "@chill-sharp/ui-core": "file:packages/chill-sharp-ui-core-1.1.6.tgz",
+    "rxjs": "~7.8.0",
+    "tslib": "^2.3.0",
+    "zone.js": "~0.15.0"
+  },
+  "devDependencies": {
+    "@angular-devkit/build-angular": "^19.2.20",
+    "@angular/cli": "^19.2.20",
+    "@angular/compiler-cli": "^19.2.20",
+    "@types/jasmine": "~5.1.0",
+    "jasmine-core": "~5.6.0",
+    "karma": "~6.4.0",
+    "karma-chrome-launcher": "~3.2.0",
+    "karma-coverage": "~2.2.0",
+    "karma-jasmine": "~5.1.0",
+    "karma-jasmine-html-reporter": "~2.1.0",
+    "typescript": "~5.7.2"
+  }
+}

package/template/public/env.js

@@ -0,0 +1,15 @@
+(function () {
+  const DEBUG_CHILLSHARP_ENV = {
+    uiUrl: 'http://localhost:6202',
+    apiUrl: 'https://localhost:6002/api'
+  };
+
+  function readEnvValue(value, fallback) {
+    return value && !/^\$\{[^}]+\}$/.test(value)
+      ? value
+      : fallback;
+  }
+
+  globalThis.CHILLSHARP_UI_URL = readEnvValue('${CHILLSHARP_UI_URL}', DEBUG_CHILLSHARP_ENV.uiUrl);
+  globalThis.CHILLSHARP_API_URL = readEnvValue('${CHILLSHARP_API_URL}', DEBUG_CHILLSHARP_ENV.apiUrl);
+}());

package/template/public/runtime-config.js

@@ -0,0 +1,10 @@
+globalThis.__clientUiTemplateRuntimeConfig__ = globalThis.__clientUiTemplateRuntimeConfig__ ?? {
+  tenantCode: 'template-client',
+  featureFlags: {
+    clientHomeEnabled: true
+  }
+};
+
+globalThis.__chillSharpUiRuntimeConfig__ = globalThis.__chillSharpUiRuntimeConfig__ ?? {
+  workspaceTaskSources: []
+};

package/template/public/sw.js

@@ -0,0 +1,8 @@
+// Shared cache behavior is upgraded with @chill-sharp/ui-core.
+self.CHILL_SHARP_SW_OPTIONS = {
+  cachePrefix: 'chill-sharp-ui',
+  cacheVersion: 'v2',
+  cacheTimeoutMs: 10 * 60 * 1000,
+  appShell: ['/', '/index.html']
+};
+importScripts('./chill-sharp-service-worker.js');

package/template/src/app/app.component.spec.ts

@@ -0,0 +1,15 @@
+import { TestBed } from '@angular/core/testing';
+import { AppComponent } from './app.component';
+
+describe('AppComponent', () => {
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [AppComponent]
+    }).compileComponents();
+  });
+
+  it('creates the shell component', () => {
+    const fixture = TestBed.createComponent(AppComponent);
+    expect(fixture.componentInstance).toBeTruthy();
+  });
+});

package/template/src/app/app.component.ts

@@ -0,0 +1,10 @@
+import { Component } from '@angular/core';
+import { ChillSharpUiRootComponent } from '@chill-sharp/ui-core';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [ChillSharpUiRootComponent],
+  template: '<chill-sharp-ui-root />'
+})
+export class AppComponent {}

package/template/src/app/app.config.ts

@@ -0,0 +1,22 @@
+import { APP_INITIALIZER, ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { provideChillSharpUiCore } from '@chill-sharp/ui-core';
+import { appRoutes } from './app.routes';
+import { CLIENT_APP_CONFIG } from '../config/app-config';
+import { provideClientTemplateProviders } from './core/providers/client-template.providers';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideZoneChangeDetection({ eventCoalescing: true }),
+    provideRouter(appRoutes),
+    ...provideChillSharpUiCore(),
+    ...provideClientTemplateProviders(),
+    {
+      provide: APP_INITIALIZER,
+      multi: true,
+      useFactory: () => () => {
+        globalThis.document.title = CLIENT_APP_CONFIG.appName;
+      }
+    }
+  ]
+};

package/template/src/app/app.routes.ts

@@ -0,0 +1,14 @@
+import { Routes } from '@angular/router';
+import { CHILL_SHARP_UI_ROUTES } from '@chill-sharp/ui-core';
+import { getClientFeatureRoutes } from './core/plugins/register-client-plugins';
+
+const coreRoutes = CHILL_SHARP_UI_ROUTES.filter((route) => route.path !== '**');
+
+export const appRoutes: Routes = [
+  ...getClientFeatureRoutes(),
+  ...coreRoutes,
+  {
+    path: '**',
+    redirectTo: 'login'
+  }
+];

package/template/src/app/core/overrides/README.md

@@ -0,0 +1,12 @@
+# Client Overrides
+
+Use this folder for client-specific provider replacements and future override registrations exposed by `@chill-sharp/ui-core`.
+
+Typical examples:
+
+- branded header providers
+- custom page title strategy
+- specialized service implementations
+- feature-flag-driven replacements
+
+`register-client-overrides.ts` returns an empty provider array by default so each client repo can opt into overrides intentionally.

package/template/src/app/core/overrides/register-client-overrides.ts

@@ -0,0 +1,5 @@
+import { Provider } from '@angular/core';
+
+export function getClientOverrideProviders(): Provider[] {
+  return [];
+}

package/template/src/app/core/plugins/README.md

@@ -0,0 +1,17 @@
+# Client Plugins
+
+Use this folder for client-owned extension registration.
+
+Typical examples:
+
+- client-only routes
+- extra menu integration when the core exposes plugin hooks
+- additional providers required by local features
+
+`register-client-plugins.ts` currently demonstrates the simplest template-owned extension: a client route.
+
+Included examples:
+
+- [`hello-plugin`](hello-plugin/README.md): route plugin that renders `Hello {{name}}` from `hello-plugin/:name`
+
+For plugin README guidance, see [`../../../../../HOW_TO_CREATE_UI_CORE_PLUGIN_README.md`](../../../../../HOW_TO_CREATE_UI_CORE_PLUGIN_README.md).

package/template/src/app/core/plugins/hello-plugin/README.md

@@ -0,0 +1,25 @@
+# Hello Plugin
+
+## Purpose
+
+This is a simple template-owned route plugin. It renders:
+
+```text
+Hello {{name}}
+```
+
+where `name` is read from the route parameter.
+
+## Registration
+
+The plugin is registered by `src/app/core/plugins/register-client-plugins.ts` at:
+
+```text
+hello-plugin/:name
+```
+
+Example URL:
+
+```text
+/hello-plugin/Manu
+```

package/template/src/app/core/plugins/hello-plugin/hello-plugin.component.ts

@@ -0,0 +1,28 @@
+import { CommonModule } from '@angular/common';
+import { Component, computed, inject } from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { ActivatedRoute } from '@angular/router';
+import { map } from 'rxjs';
+
+@Component({
+  selector: 'app-hello-plugin',
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <section class="client-template-page">
+      <p class="eyebrow">Hello Plugin</p>
+      <h1>Hello {{ name() }}</h1>
+    </section>
+  `
+})
+export class HelloPluginComponent {
+  private readonly route = inject(ActivatedRoute);
+  private readonly routeName = toSignal(this.route.paramMap.pipe(
+    map((params) => params.get('name')?.trim() ?? '')
+  ), { initialValue: '' });
+
+  protected readonly name = computed(() => {
+    const value = this.routeName();
+    return value || 'World';
+  });
+}

package/template/src/app/core/plugins/register-client-plugins.ts

@@ -0,0 +1,16 @@
+import { Routes } from '@angular/router';
+import { HelloPluginComponent } from './hello-plugin/hello-plugin.component';
+import { ClientHomeComponent } from '../../pages/client-home/client-home.component';
+
+export function getClientFeatureRoutes(): Routes {
+  return [
+    {
+      path: 'hello-plugin/:name',
+      component: HelloPluginComponent
+    },
+    {
+      path: 'client-home',
+      component: ClientHomeComponent
+    }
+  ];
+}

package/template/src/app/core/providers/client-template.providers.ts

@@ -0,0 +1,8 @@
+import { Provider } from '@angular/core';
+import { getClientOverrideProviders } from '../overrides/register-client-overrides';
+
+export function provideClientTemplateProviders(): Provider[] {
+  return [
+    ...getClientOverrideProviders()
+  ];
+}

package/template/src/app/pages/client-home/client-home.component.ts

@@ -0,0 +1,41 @@
+import { CommonModule } from '@angular/common';
+import { Component } from '@angular/core';
+import { CLIENT_APP_CONFIG } from '../../../config/app-config';
+import { readClientRuntimeConfig } from '../../../config/runtime-config';
+
+@Component({
+  selector: 'app-client-home',
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <section class="client-template-page">
+      <p class="eyebrow">Client Template</p>
+      <h1>{{ appConfig.appName }}</h1>
+      <p>
+        This is a client-owned route that lives in the template shell instead of the shared
+        <code>&#64;chill-sharp/ui-core</code> package.
+      </p>
+
+      <div class="client-template-grid">
+        <article class="client-template-card">
+          <strong>Tenant</strong>
+          <p>{{ runtimeConfig.tenantCode }}</p>
+        </article>
+
+        <article class="client-template-card">
+          <strong>API</strong>
+          <p>{{ appConfig.apiBaseUrl }}</p>
+        </article>
+
+        <article class="client-template-card">
+          <strong>Theme</strong>
+          <p>{{ appConfig.themeName }}</p>
+        </article>
+      </div>
+    </section>
+  `
+})
+export class ClientHomeComponent {
+  protected readonly appConfig = CLIENT_APP_CONFIG;
+  protected readonly runtimeConfig = readClientRuntimeConfig();
+}

package/template/src/assets/branding/logo.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 160 48" role="img" aria-labelledby="title">
+  <title>Client Template Logo</title>
+  <rect width="160" height="48" rx="12" fill="#13424d"/>
+  <circle cx="28" cy="24" r="10" fill="#f5c46b"/>
+  <path d="M52 16h54c8 0 14 6 14 14s-6 14-14 14H52z" fill="#0f6d61"/>
+  <text x="60" y="30" font-family="Segoe UI, sans-serif" font-size="15" fill="#fffdf8">Client UI</text>
+</svg>

package/template/src/config/app-config.ts

@@ -0,0 +1,17 @@
+import { environment } from '../environments/environment';
+
+export interface ClientAppConfig {
+  appName: string;
+  apiBaseUrl: string;
+  tenantCode: string;
+  themeName: string;
+  supportEmail: string;
+}
+
+export const CLIENT_APP_CONFIG: ClientAppConfig = {
+  appName: 'ChillSharp Client Template',
+  apiBaseUrl: environment.apiBaseUrl,
+  tenantCode: 'template-client',
+  themeName: 'template-default',
+  supportEmail: 'support@example.com'
+};

package/template/src/config/runtime-config.ts

@@ -0,0 +1,13 @@
+export interface ClientTemplateRuntimeConfig {
+  tenantCode: string;
+  featureFlags: Record<string, boolean>;
+}
+
+export function readClientRuntimeConfig(): ClientTemplateRuntimeConfig {
+  const runtimeConfig = globalThis.__clientUiTemplateRuntimeConfig__;
+
+  return {
+    tenantCode: runtimeConfig?.tenantCode ?? 'template-client',
+    featureFlags: runtimeConfig?.featureFlags ?? {}
+  };
+}

package/template/src/environments/environment.prod.ts

@@ -0,0 +1,4 @@
+export const environment = {
+  production: true,
+  apiBaseUrl: globalThis.CHILLSHARP_API_URL?.trim() || 'https://example.invalid/api'
+};

package/template/src/environments/environment.ts

@@ -0,0 +1,4 @@
+export const environment = {
+  production: false,
+  apiBaseUrl: globalThis.CHILLSHARP_API_URL?.trim() || 'http://localhost:6002/api'
+};

package/template/src/index.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>ChillSharp UI Template</title>
+  <base href="/">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+</head>
+<body>
+  <script src="env.js"></script>
+  <script src="runtime-config.js"></script>
+  <app-root></app-root>
+  <script>
+    if ('serviceWorker' in navigator) {
+      window.addEventListener('load', () => {
+        navigator.serviceWorker.register('/sw.js', { updateViaCache: 'none' })
+          .catch((error) => console.error('Service worker registration failed.', error));
+      });
+    }
+  </script>
+</body>
+</html>

package/template/src/main.ts

@@ -0,0 +1,6 @@
+import { bootstrapApplication } from '@angular/platform-browser';
+import { appConfig } from './app/app.config';
+import { AppComponent } from './app/app.component';
+
+bootstrapApplication(AppComponent, appConfig)
+  .catch((err) => console.error(err));

package/template/src/runtime-config.d.ts

@@ -0,0 +1,10 @@
+declare global {
+  var CHILLSHARP_API_URL: string | undefined;
+  var CHILLSHARP_UI_URL: string | undefined;
+  var __clientUiTemplateRuntimeConfig__: {
+    tenantCode?: string;
+    featureFlags?: Record<string, boolean>;
+  } | undefined;
+}
+
+export {};

package/template/src/styles.scss

@@ -0,0 +1,116 @@
+@use '@chill-sharp/ui-core/styles/core-theme.scss';
+
+:root {
+  --font-sans: "Segoe UI Variable", "Segoe UI", sans-serif;
+  --bg-top: #f6f0e8;
+  --bg-bottom: #dfeaea;
+  --accent: #0f6d61;
+  --accent-strong: #13424d;
+  --accent-soft: rgba(15, 109, 97, 0.14);
+  --surface-0: #fffdf8;
+  --surface-1: rgba(255, 253, 248, 0.84);
+  --surface-2: rgba(255, 255, 255, 0.72);
+  --surface-3: rgba(239, 246, 246, 0.9);
+  --text-main: #18313b;
+  --text-muted: #64757a;
+  --border-color: rgba(24, 49, 59, 0.13);
+  --shadow: 0 24px 60px rgba(20, 65, 77, 0.12);
+  --shadow-soft: 0 12px 30px rgba(20, 65, 77, 0.08);
+  --workspace-backdrop:
+    radial-gradient(circle at top left, rgba(15, 109, 97, 0.16), transparent 28%),
+    radial-gradient(circle at top right, rgba(188, 146, 93, 0.14), transparent 24%),
+    linear-gradient(180deg, var(--bg-top), var(--bg-bottom));
+}
+
+body::before {
+  content: '';
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  background:
+    linear-gradient(90deg, rgba(255, 255, 255, 0.12) 1px, transparent 1px),
+    linear-gradient(rgba(255, 255, 255, 0.12) 1px, transparent 1px);
+  background-size: 2rem 2rem;
+  mask-image: linear-gradient(180deg, rgba(0, 0, 0, 0.3), transparent 70%);
+  opacity: 0.28;
+}
+
+.client-template-page {
+  max-width: 64rem;
+  margin: 2.5rem auto;
+  padding: 2rem;
+  border-radius: 1.5rem;
+  border: 1px solid var(--border-color);
+  background: var(--surface-1);
+  box-shadow: var(--shadow-soft);
+  backdrop-filter: blur(16px);
+}
+
+.client-template-page h1 {
+  margin: 0;
+  font-size: clamp(2rem, 5vw, 3.4rem);
+  line-height: 0.95;
+}
+
+.client-template-page p {
+  color: var(--text-muted);
+}
+
+.client-template-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr));
+  gap: 1rem;
+  margin-top: 1.5rem;
+}
+
+.client-template-card {
+  padding: 1rem;
+  border-radius: 1rem;
+  background: var(--surface-2);
+  border: 1px solid var(--border-color);
+}
+
+// Keep the application menu dense and list-like instead of presenting every
+// entry as a separate card. These selectors intentionally override the
+// public UI-core menu classes from the client template.
+.workspace-menu__tree {
+  gap: 0.15rem;
+}
+
+.workspace-menu__tree-node,
+.workspace-menu__tree-children {
+  gap: 0.1rem;
+}
+
+.workspace-menu__tree-row {
+  gap: 0.25rem;
+}
+
+.workspace-menu__tree-main {
+  border: 0;
+  border-radius: 0.55rem;
+  background: transparent;
+  box-shadow: none;
+}
+
+.workspace-menu__tree-main.is-active {
+  border: 0;
+  background: var(--accent-soft);
+}
+
+.workspace-menu__tree-main.is-pending-expand {
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--accent) 42%, transparent);
+}
+
+.workspace-menu__tree-trigger {
+  padding: 0.5rem 0.7rem;
+}
+
+.workspace-menu__tree-expander {
+  width: 2.25rem;
+  padding: 0.45rem;
+}
+
+.workspace-menu__tree-meta {
+  padding: 0 0.7rem 0.5rem;
+}

package/template/tsconfig.app.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/app",
+    "types": []
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "src/**/*.spec.ts"
+  ]
+}

package/template/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "outDir": "./dist/out-tsc",
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "importHelpers": true,
+    "target": "ES2022",
+    "module": "preserve"
+  },
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true
+  },
+  "files": [],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/template/tsconfig.spec.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/spec",
+    "types": [
+      "jasmine"
+    ]
+  },
+  "include": [
+    "src/**/*.spec.ts",
+    "src/**/*.d.ts"
+  ]
+}