@podosoft/podokit 0.11.2 → 0.12.0

package/dist/locale.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeLocaleCode = normalizeLocaleCode;
+exports.listLocales = listLocales;
+exports.validateLocale = validateLocale;
+exports.addLocale = addLocale;
+exports.setLocaleEnabled = setLocaleEnabled;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const WEB_I18N = (0, node_path_1.join)("apps", "web", "src", "lib", "i18n");
+function definitionsDir(projectRoot) {
+    return (0, node_path_1.join)(projectRoot, WEB_I18N, "locales");
+}
+function catalogsDir(projectRoot) {
+    return (0, node_path_1.join)(projectRoot, WEB_I18N, "catalogs");
+}
+function appCatalogDir(projectRoot) {
+    return (0, node_path_1.join)(catalogsDir(projectRoot), "app");
+}
+function normalizeLocaleCode(value) {
+    try {
+        const normalized = Intl.getCanonicalLocales(value)[0];
+        if (!normalized)
+            throw new Error("missing locale");
+        return normalized;
+    }
+    catch {
+        throw new Error(`Invalid locale code "${value}". Use a BCP 47 language tag such as en, ko, or pt-BR.`);
+    }
+}
+function readJson(path) {
+    const value = JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Expected a JSON object: ${path}`);
+    }
+    return value;
+}
+function readDefinition(path) {
+    const value = readJson(path);
+    const code = typeof value.code === "string" ? normalizeLocaleCode(value.code) : "";
+    const name = typeof value.name === "string" ? value.name.trim() : "";
+    const direction = value.direction;
+    const enabled = value.enabled;
+    if (!code || !name || (direction !== "ltr" && direction !== "rtl") || typeof enabled !== "boolean") {
+        throw new Error(`Invalid locale definition: ${path}`);
+    }
+    if (`${code}.json` !== (0, node_path_1.basename)(path)) {
+        throw new Error(`Locale definition filename must match its canonical code: ${code}.json`);
+    }
+    return { code, name, direction, enabled };
+}
+function listLocales(projectRoot) {
+    const dir = definitionsDir(projectRoot);
+    if (!(0, node_fs_1.existsSync)(dir))
+        throw new Error("This project does not contain PodoKit JSON locale definitions.");
+    return (0, node_fs_1.readdirSync)(dir)
+        .filter((name) => name.endsWith(".json"))
+        .map((name) => readDefinition((0, node_path_1.join)(dir, name)))
+        .sort((left, right) => left.code.localeCompare(right.code));
+}
+function merge(target, source) {
+    const result = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        const previous = result[key];
+        if (previous && typeof previous === "object" && !Array.isArray(previous) &&
+            value && typeof value === "object" && !Array.isArray(value)) {
+            result[key] = merge(previous, value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function composedCatalog(projectRoot, code) {
+    const root = catalogsDir(projectRoot);
+    if (!(0, node_fs_1.existsSync)(root))
+        return {};
+    const sources = (0, node_fs_1.readdirSync)(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort((left, right) => {
+        const leftApp = left === "app" ? 1 : 0;
+        const rightApp = right === "app" ? 1 : 0;
+        return leftApp - rightApp || left.localeCompare(right);
+    });
+    let catalog = {};
+    for (const source of sources) {
+        const path = (0, node_path_1.join)(root, source, `${code}.json`);
+        if ((0, node_fs_1.existsSync)(path))
+            catalog = merge(catalog, readJson(path));
+    }
+    return catalog;
+}
+function flatten(value, prefix = "", out = new Map()) {
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            out.set(prefix, value);
+        for (const [index, child] of value.entries()) {
+            flatten(child, `${prefix}[${index}]`, out);
+        }
+    }
+    else if (value && typeof value === "object") {
+        for (const [key, child] of Object.entries(value)) {
+            flatten(child, prefix ? `${prefix}.${key}` : key, out);
+        }
+    }
+    else {
+        out.set(prefix, value);
+    }
+    return out;
+}
+function placeholders(value) {
+    if (typeof value !== "string")
+        return [];
+    return [...value.matchAll(/\{(\w+)\}/g)].map((match) => match[1] ?? "").sort();
+}
+function validateLocale(projectRoot, rawCode) {
+    const code = normalizeLocaleCode(rawCode);
+    const definitionPath = (0, node_path_1.join)(definitionsDir(projectRoot), `${code}.json`);
+    if (!(0, node_fs_1.existsSync)(definitionPath))
+        throw new Error(`Locale ${code} has not been added.`);
+    const definition = readDefinition(definitionPath);
+    const base = new Map([...flatten(composedCatalog(projectRoot, "en"))].filter(([, value]) => value !== ""));
+    const selected = flatten(composedCatalog(projectRoot, code));
+    const missing = [];
+    for (const [key, baseValue] of base) {
+        if (!selected.has(key) || selected.get(key) === "") {
+            missing.push(key);
+            continue;
+        }
+        const selectedValue = selected.get(key);
+        const baseKind = Array.isArray(baseValue) ? "array" : typeof baseValue;
+        const selectedKind = Array.isArray(selectedValue) ? "array" : typeof selectedValue;
+        if (baseKind !== selectedKind)
+            throw new Error(`${code}:${key} must be ${baseKind}, received ${selectedKind}`);
+        if (placeholders(baseValue).join(",") !== placeholders(selectedValue).join(",")) {
+            throw new Error(`${code}:${key} must preserve placeholders ${placeholders(baseValue).join(", ")}`);
+        }
+    }
+    const total = base.size;
+    const translated = total - missing.length;
+    return {
+        definition,
+        translated,
+        total,
+        percent: total === 0 ? 100 : Math.round((translated / total) * 100),
+        missing,
+    };
+}
+function defaultLocaleName(code) {
+    try {
+        return new Intl.DisplayNames([code], { type: "language" }).of(code) ?? code;
+    }
+    catch {
+        return code;
+    }
+}
+function addLocale(projectRoot, rawCode, options = {}) {
+    const code = normalizeLocaleCode(rawCode);
+    const definitionPath = (0, node_path_1.join)(definitionsDir(projectRoot), `${code}.json`);
+    const catalogPath = (0, node_path_1.join)(appCatalogDir(projectRoot), `${code}.json`);
+    if ((0, node_fs_1.existsSync)(definitionPath) || (0, node_fs_1.existsSync)(catalogPath))
+        throw new Error(`Locale ${code} already exists.`);
+    const definition = {
+        code,
+        name: options.name?.trim() || defaultLocaleName(code),
+        direction: options.direction ?? "ltr",
+        enabled: false,
+    };
+    (0, node_fs_1.mkdirSync)(definitionsDir(projectRoot), { recursive: true });
+    (0, node_fs_1.mkdirSync)(appCatalogDir(projectRoot), { recursive: true });
+    (0, node_fs_1.writeFileSync)(definitionPath, `${JSON.stringify(definition, null, 2)}\n`);
+    (0, node_fs_1.writeFileSync)(catalogPath, "{}\n");
+    return definition;
+}
+function setLocaleEnabled(projectRoot, rawCode, enabled) {
+    const coverage = validateLocale(projectRoot, rawCode);
+    if (!enabled && coverage.definition.code === "en")
+        throw new Error("The PodoKit English fallback cannot be deactivated.");
+    const definition = { ...coverage.definition, enabled };
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(definitionsDir(projectRoot), `${definition.code}.json`), `${JSON.stringify(definition, null, 2)}\n`);
+    return { ...coverage, definition };
+}

package/dist/lockfile.js

@@ -45,6 +45,9 @@ const WALK_IGNORE = new Set([
 exports.DEFAULT_OWNED_GLOBS = [
     "apps/web/src/routes/**",
     "apps/web/src/lib/components/ui/**",
+    // Locale definitions and app messages are application-owned extension points.
+    "apps/web/src/lib/i18n/locales/**",
+    "apps/web/src/lib/i18n/catalogs/app/**",
     // Owned Nest DI extension slot — override providers here; update never touches it.
     "apps/api/src/app.extensions.ts",
     // AI agent guidance — yours to customize; update never touches it.
@@ -62,6 +65,7 @@ exports.DEFAULT_OWNED_GLOBS = [
     ".devcontainer/**",
     ".env.docker",
     "infra/traefik/**",
+    ".podokit/dev.json",
 ];
 const TEXT_EXT = /\.(json|md|ts|tsx|js|mjs|cjs|css|html|yml|yaml|txt|env|svelte|gitignore|example)$/i;
 function podokitDir(projectRoot) {

package/dist/templates/fullstack-nest-svelte/README.md

@@ -8,10 +8,49 @@ Full-stack TypeScript starter generated with [PodoKit](https://github.com/podoso
 
 ## Getting started
 
+### Recommended: containerized development
+
 ```bash
 {{packageManager}} install
 cp .env.example .env
+npx @podosoft/podokit dev watch
+```
+
+Open the URL printed by the command; a new project defaults to
+**http://{{projectName}}.localhost**. The committed `.podokit/dev.json` is the
+source of truth if you change the hostname. The first running PodoKit project starts
+one user-level Traefik gateway on `127.0.0.1:80`; additional projects reuse it and
+route by that hostname. Even a single app uses
+the same topology, with one route and no project-specific host port.
+
+Run lifecycle and container commands from a second terminal:
+
+```bash
+npx @podosoft/podokit dev url
+npx @podosoft/podokit dev ps
+npx @podosoft/podokit dev logs
+npx @podosoft/podokit dev exec api npm run migration:run -w {{projectName}}-api
+npx @podosoft/podokit dev down
+```
+
+If installed modules require extra services, use their profiles on the initial
+watch command instead:
 
+```bash
+npx @podosoft/podokit dev watch \
+  --profile cache --profile storage --profile queue
+```
+
+Pass the same profile flags to other lifecycle commands when applicable. `dev down`
+removes this project's stack and route. If it is the final registered
+project, it also removes the shared gateway and network. Source changes are synced
+through Compose Watch, including Vite HMR on the same portless browser origin.
+
+### Alternative: host processes
+
+Use this loop when you want only the web and API processes on the host:
+
+```bash
 # start local PostgreSQL + Redis
 docker compose -f infra/docker/docker-compose.yml up -d
 
@@ -35,6 +74,9 @@ generate and run a migration:
 Want a worked example? Generate the `todo` template instead:
 `npx @podosoft/podokit create my-app --template todo`.
 
+For multi-project routing, container profiles, migrations, and OAuth over a
+stable HTTPS tunnel, see the PodoKit [development guide](https://github.com/podosoft-dev/podokit/blob/main/docs/development.md).
+
 ## Deploy
 
 Docker Compose in `infra/docker`; example k3s manifests in `infra/k3s`

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/i18n/README.md

@@ -1,7 +1,9 @@
-# i18n
+# Localization
 
-Locales use [typesafe-i18n](https://github.com/ivanhofer/typesafe-i18n).
+Locale definitions live in `locales/<code>.json`. Product copy and intentional
+module overrides live in the app-owned `catalogs/app/<code>.json` files.
 
-- `en.ts` is the base locale; `ko.ts` mirrors its shape.
-- Run `npx typesafe-i18n` to generate the typed runtime and Svelte store,
-  then use `$LL.appTitle()` in components. Add keys to every locale.
+The admin-dashboard module installs the composed JSON message runtime and its
+complete English and Korean catalogs. Use `podo locale add`, `validate`, and
+`activate` to extend it. See the generated `$podokit-add-locale` skill for the
+complete workflow.

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/i18n/catalogs/app/en.json

@@ -0,0 +1 @@
+{}

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/i18n/catalogs/app/ko.json

@@ -0,0 +1 @@
+{}

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/i18n/locales/en.json

@@ -0,0 +1,6 @@
+{
+  "code": "en",
+  "name": "English",
+  "direction": "ltr",
+  "enabled": true
+}

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/i18n/locales/ko.json

@@ -0,0 +1,6 @@
+{
+  "code": "ko",
+  "name": "한국어",
+  "direction": "ltr",
+  "enabled": true
+}

package/dist/templates/fullstack-nest-svelte/apps/web/vite.config.ts

@@ -2,15 +2,10 @@ import { sveltekit } from "@sveltejs/kit/vite";
 import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "vite";
 
-// Inside the dev container (compose.dev.yaml sets VITE_DOCKER=1): bind to all
-// interfaces, allow the Traefik hostname, and route HMR's WebSocket back through
-// Traefik. The browser reaches the app at Traefik's published host port, so the
-// HMR client must target that same port — otherwise the ws connects to :80,
-// fails, and Vite silently falls back to a full page reload on every change
-// (which wipes in-progress form input). compose.dev.yaml injects
-// VITE_HMR_CLIENT_PORT to match the published Traefik port (default 80).
+// Inside the dev container, bind to all interfaces and accept local gateway or
+// HTTPS tunnel hostnames. Vite derives HMR's protocol, host, and port from the
+// browser origin so the same configuration works for both entry points.
 const inDocker = process.env.VITE_DOCKER === "1";
-const hmrClientPort = Number(process.env.VITE_HMR_CLIENT_PORT) || 80;
 
 export default defineConfig({
   plugins: [tailwindcss(), sveltekit()],
@@ -19,7 +14,6 @@ export default defineConfig({
         host: true,
         port: 5001,
         allowedHosts: true,
-        hmr: { clientPort: hmrClientPort },
       }
     : undefined,
 });

package/dist/templates/fullstack-nest-svelte/compose.dev.yaml

@@ -1,13 +1,11 @@
 # Containerized development environment.
 #
-#   docker compose -f compose.dev.yaml watch                       # core stack
-#   docker compose -f compose.dev.yaml --profile cache \
-#     --profile storage --profile queue watch                     # with modules
+#   podo dev watch                                                # core stack
+#   podo dev watch --profile cache --profile storage \
+#     --profile queue                                             # with modules
 #
-# Only Traefik binds a host port (default 80). The app is at http://app.localhost.
-# Set TRAEFIK_PORT to publish on another port (e.g. TRAEFIK_PORT=8001) so several
-# containerized stacks can run at once without colliding — the web container reads
-# the same value as VITE_HMR_CLIENT_PORT so Vite HMR follows automatically.
+# A user-level PodoKit gateway owns loopback :80 and routes each *.localhost host
+# to this stack. The legacy per-project Traefik service is opt-in only.
 # api/postgres/redis/minio have NO published ports — they talk by service name
 # on the internal network, so this stack never collides with other projects.
 #
@@ -24,6 +22,7 @@ name: {{projectName}}-dev
 
 services:
   traefik:
+    profiles: [podokit-legacy-proxy]
     image: traefik:v3.5
     command:
       - --providers.file.filename=/etc/traefik/dynamic.yml
@@ -52,10 +51,6 @@ services:
       # getClientAddress() tied to the visitor instead of the proxy container.
       - ADDRESS_HEADER=x-forwarded-for
       - XFF_DEPTH=1
-      # Match Traefik's published port so HMR's WebSocket targets the right port
-      # (default 80). Without this, HMR connects to :80 and a non-80 stack falls
-      # back to a full page reload on every edit.
-      - VITE_HMR_CLIENT_PORT=${TRAEFIK_PORT:-80}
     depends_on: [api]
     networks: [podokit]
     develop:

package/dist/templates/fullstack-nest-svelte/dot-claude/skills/podokit-add-locale/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: podokit-add-locale
+description: Add, translate, validate, activate, or troubleshoot a JSON locale in a PodoKit-generated SvelteKit app. Use when a user asks to add a language, split or edit locale JSON, check translation coverage or placeholders, configure fallback behavior, or verify locale changes through Vite HMR.
+---
+
+# PodoKit Add Locale
+
+Add languages through the PodoKit locale commands and the app-owned JSON catalog. Keep module catalogs managed so `podo update` can continue to update them.
+
+## Workflow
+
+1. Inspect the existing locale state.
+
+   ```sh
+   podo locale list
+   ```
+
+2. Add a canonical BCP 47 language tag. Set `--direction rtl` only for right-to-left languages.
+
+   ```sh
+   podo locale add pt-BR --name "Português (Brasil)"
+   ```
+
+3. Read [references/catalog-format.md](references/catalog-format.md), then translate the new app-owned file at `apps/web/src/lib/i18n/catalogs/app/<locale>.json`.
+
+4. Validate key coverage, JSON value types, and interpolation placeholders.
+
+   ```sh
+   podo locale validate pt-BR
+   ```
+
+5. Activate the locale. Partial catalogs are permitted because runtime fallback fills missing keys, but report the coverage percentage to the user.
+
+   ```sh
+   podo locale activate pt-BR
+   ```
+
+6. Run the app with its documented container-based development command. Verify the language switch, one complete key, one fallback key, and locale persistence. Editing an existing JSON file must update through Vite HMR without restarting the container. Adding a new locale file may trigger an automatic full-page reload.
+
+## Rules
+
+- Treat `en` as the stable final fallback and never deactivate it.
+- Preserve placeholders exactly. For example, translate `Hello {name}` without renaming or removing `{name}`.
+- Put product-specific copy only in `catalogs/app/`. Do not edit `catalogs/admin-dashboard/` or other module catalogs directly.
+- Keep locale definition filenames identical to their canonical codes, including case such as `pt-BR.json`.
+- Do not activate a locale definition before its JSON parses and `podo locale validate` succeeds.
+- Do not use the UI message catalogs for user-authored records. Dynamic content needs locale-aware records and a separate publication/fallback policy.
+- When deactivating a locale, preserve its files so it can be reactivated without losing translations.
+
+## Fallback And Site Default
+
+The message runtime resolves missing keys in this order: selected locale, configured site default, then English. The site default is an administrator choice, not a build-time constant. Changing it must not delete or rewrite catalogs.
+
+If a requested language is unsupported or inactive, resolve it to the configured site default. Keep localized URL and SEO behavior in the consuming app; the catalogs provide translated strings but do not define routing policy.
+
+## Completion Checklist
+
+- `podo locale validate` succeeds for every active locale.
+- The new locale definition is active and has the intended display name and direction.
+- App-owned JSON contains the new product copy; managed module catalogs remain untouched.
+- Development edits update without a container restart.
+- Automated tests cover selection, fallback, placeholders, and at least one incomplete catalog.
+- User-facing locale setup or routing documentation is updated when behavior changes.

package/dist/templates/fullstack-nest-svelte/dot-claude/skills/podokit-add-locale/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PodoKit Locale Setup"
+  short_description: "Add and validate JSON locale catalogs safely"
+  default_prompt: "Use $podokit-add-locale to add, validate, activate, and test a new JSON locale in this PodoKit app."

package/dist/templates/fullstack-nest-svelte/dot-claude/skills/podokit-add-locale/references/catalog-format.md

@@ -0,0 +1,49 @@
+# JSON Catalog Format
+
+## Directory Layout
+
+```text
+apps/web/src/lib/i18n/
+├── locales/
+│   ├── en.json
+│   ├── ko.json
+│   └── pt-BR.json
+└── catalogs/
+    ├── admin-dashboard/  # PodoKit-managed module messages
+    ├── blog/             # module-managed messages when installed
+    └── app/              # app-owned product messages and overrides
+```
+
+Each locale definition has this shape:
+
+```json
+{
+  "code": "pt-BR",
+  "name": "Português (Brasil)",
+  "direction": "ltr",
+  "enabled": false
+}
+```
+
+`code` must be a canonical BCP 47 tag and must match the filename. `direction` is `ltr` or `rtl`. Newly added locales stay inactive until explicitly activated.
+
+## Catalog Composition
+
+Catalogs are nested JSON objects with strings at their leaves:
+
+```json
+{
+  "common": {
+    "save": "Save",
+    "welcome": "Welcome, {name}"
+  }
+}
+```
+
+The runtime lazily loads every `catalogs/*/<locale>.json` file. Module catalogs are merged first in stable name order; the `app` catalog is merged last, so the consuming app may intentionally override module copy without modifying managed files.
+
+English defines the complete key and value-type contract. Other locales may omit keys, but translated values must retain the English type and all `{placeholder}` names. JSON objects and arrays are supported; executable expressions are not.
+
+## Development Reloading
+
+Catalog imports use Vite's `import.meta.glob`. Changes to an existing JSON dependency participate in Vite HMR and must appear without restarting the development container. A new file changes the glob membership and may cause Vite to reload the page automatically. If neither occurs, confirm that the app source directory, including `apps/web/src`, is mounted or synced by the development compose configuration.

package/dist/templates/fullstack-nest-svelte/dot-env.docker

@@ -6,11 +6,11 @@ POSTGRES_USER=podokit
 POSTGRES_PASSWORD=podokit
 POSTGRES_DB=podokit
 BACKEND_INTERNAL_URL=http://api:5002
-CORS_ORIGIN=http://app.localhost
+CORS_ORIGIN=http://{{projectName}}.localhost,http://localhost
 REDIS_HOST=redis
 REDIS_PORT=6379
 BETTER_AUTH_SECRET=change-me-in-container-min-32-characters
-BETTER_AUTH_URL=http://app.localhost
+BETTER_AUTH_URL=http://{{projectName}}.localhost
 ADMIN_EMAILS=admin@example.com
 AUDIT_LOG_ENABLED=true
 RATE_LIMIT_TTL=60

package/dist/templates/fullstack-nest-svelte/dot-gitignore

@@ -18,3 +18,6 @@ test-results/
 
 # local performance reports
 output/lighthouse/
+
+# podo dev generated compose overlay
+.podokit/runtime/

package/dist/templates/fullstack-nest-svelte/dot-podokit/dev.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "hostname": "{{projectName}}.localhost"
+}

package/dist/templates/fullstack-nest-svelte/tests/README.md

@@ -9,7 +9,13 @@ npm run test:e2e:ui      # pages (chromium)
 npm run test:e2e:report  # open the HTML report
 ```
 
-The suite runs against a live stack (web on `E2E_BASE_URL`, default
-`http://localhost:5001`, proxying `/api/*` to the API). Start PostgreSQL, run the
-auth migration, and start the API + web first. Files ending in `*.api.spec.ts` run
-in the request-only `api` project; `*.ui.spec.ts` run in the chromium `ui` project.
+The suite runs against a live stack (web on `E2E_BASE_URL`, proxying `/api/*` to
+the API). With the recommended containerized loop, start `podo dev watch` and run:
+
+```bash
+E2E_BASE_URL=http://{{projectName}}.localhost npm run test:e2e
+```
+
+The default `http://localhost:5001` is for the alternative `npm run dev`
+host-process loop. Files ending in `*.api.spec.ts` run in the request-only `api`
+project; `*.ui.spec.ts` run in the chromium `ui` project.

package/dist/templates/modules/admin-dashboard/files/apps/api/src/site-settings/site-settings.controller.ts

@@ -31,6 +31,7 @@ const ICON_TYPES = new Set(["image/svg+xml", "image/png", "image/x-icon", "image
 // preset a slug, and overrides a JSON map of hex colors under known token keys.
 const HEX = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
 const PRESET = /^[a-z0-9-]{1,32}$/;
+const LOCALE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
 const THEME_TOKEN_KEYS = new Set([
   "background",
   "card",
@@ -46,6 +47,14 @@ const THEME_TOKEN_KEYS = new Set([
 /** Validate/normalize a single theme setting value. Empty string clears it. */
 function validateThemeValue(key: string, value: string): string {
   if (value === "") return "";
+  if (key === "locale") {
+    if (!LOCALE.test(value)) throw new BadRequestException("locale must be a valid BCP 47 language tag");
+    try {
+      return Intl.getCanonicalLocales(value)[0] ?? value;
+    } catch {
+      throw new BadRequestException("locale must be a valid BCP 47 language tag");
+    }
+  }
   if (key === "brandColor") {
     if (!HEX.test(value)) throw new BadRequestException("brandColor must be a hex color");
     return value;

package/dist/templates/modules/admin-dashboard/files/apps/web/src/hooks.server.ts

@@ -35,7 +35,11 @@ export const handle: Handle = async ({ event, resolve }) => {
     event.locals.session = null;
   }
   const response = await resolve(event, {
-    transformPageChunk: ({ html }) => html.replace('lang="en"', `lang="${event.locals.locale}"`),
+    transformPageChunk: ({ html }) =>
+      html.replace(
+        /(<html\b[^>]*?\slang=)(["'])[^"']*\2/i,
+        `$1"${event.locals.locale}"`,
+      ),
   });
   return applySearchIndexingHeaders(response, event.url.pathname);
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/auth-errors.ts

@@ -0,0 +1,3 @@
+/** Stable registration-policy errors used by Better Auth callbacks before the
+ *  shared API client is necessarily upgraded in an existing generated app. */
+export const PUBLIC_SIGNUP_DISABLED = "PUBLIC_SIGNUP_DISABLED" as const;

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/auth-redirect.ts

@@ -0,0 +1,27 @@
+const AUTH_PATHS = new Set(["/login", "/signup", "/forgot-password", "/reset-password"]);
+
+/** Accept only same-site absolute paths and keep authentication redirects from
+ *  becoming open redirects or loops back into an auth screen. */
+export function safeAuthRedirect(value: string | null | undefined, fallback = "/"): string {
+  if (!value || !value.startsWith("/") || value.startsWith("//") || value.includes("\\")) {
+    return fallback;
+  }
+  try {
+    const parsed = new URL(value, "http://podokit.local");
+    if (parsed.origin !== "http://podokit.local" || AUTH_PATHS.has(parsed.pathname)) return fallback;
+    return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+  } catch {
+    return fallback;
+  }
+}
+
+/** Current same-site path, suitable for a login return target. */
+export function currentPath(url: URL): string {
+  return safeAuthRedirect(`${url.pathname}${url.search}${url.hash}`);
+}
+
+/** Add a validated return target to an authentication-page link. */
+export function withAuthRedirect(authPath: "/login" | "/signup", target: string): string {
+  const params = new URLSearchParams({ redirect: safeAuthRedirect(target) });
+  return `${authPath}?${params.toString()}`;
+}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/account-menu.svelte

@@ -1,5 +1,7 @@
 <script lang="ts">
   import { goto } from "$app/navigation";
+  import { page } from "$app/state";
+  import { currentPath, withAuthRedirect } from "$lib/auth-redirect";
   import { Button } from "$lib/components/ui/button";
   import * as DropdownMenu from "$lib/components/ui/dropdown-menu";
   import LayoutDashboardIcon from "@lucide/svelte/icons/layout-dashboard";
@@ -12,16 +14,19 @@
 
   let { user }: { user: SessionUser | null } = $props();
   const i18n = getI18n();
+  const loginHref = $derived(withAuthRedirect("/login", currentPath(page.url)));
 
   async function signOut(): Promise<void> {
+    const returnTo = currentPath(page.url);
     await api.auth.signOut();
-    await goto("/login", { invalidateAll: true });
+    await goto(returnTo, { invalidateAll: true });
   }
 </script>
 
 {#if user}
   <DropdownMenu.Root>
     <DropdownMenu.Trigger
+      data-testid="account-menu"
       class="hover:bg-muted focus-visible:border-ring focus-visible:ring-ring/50 inline-flex size-8 items-center justify-center rounded-full outline-none focus-visible:ring-3"
       aria-label={i18n.t.nav.account}
     >
@@ -38,9 +43,9 @@
         <DropdownMenu.Item onSelect={() => goto("/admin")}><LayoutDashboardIcon class="mr-2 size-4" /> {i18n.t.common.appName}</DropdownMenu.Item>
       {/if}
       <DropdownMenu.Separator />
-      <DropdownMenu.Item onSelect={signOut}><LogOutIcon class="mr-2 size-4" /> {i18n.t.nav.signOut}</DropdownMenu.Item>
+      <DropdownMenu.Item data-testid="sign-out" onSelect={signOut}><LogOutIcon class="mr-2 size-4" /> {i18n.t.nav.signOut}</DropdownMenu.Item>
     </DropdownMenu.Content>
   </DropdownMenu.Root>
 {:else}
-  <Button href="/login" variant="ghost">{i18n.t.auth.signIn}</Button>
+  <Button data-testid="sign-in-link" href={loginHref} variant="ghost">{i18n.t.auth.signIn}</Button>
 {/if}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/sidebar-user-menu.svelte

@@ -15,7 +15,7 @@
 
   async function signOut(): Promise<void> {
     await api.auth.signOut();
-    await goto("/login", { invalidateAll: true });
+    await goto("/", { invalidateAll: true });
   }
 </script>