@zaaxch/tailframe 0.1.1 → 1.0.0

package/bin/tailframe.mjs

@@ -14,8 +14,9 @@ function usage() {
 	console.error("  service schematics: module <name> <VerbNoun> [--no-http], use-case <module> <VerbNoun>,");
 	console.error("    http <module> <VerbNoun>, port <module> <Name>, adapter <module> <PortName> --db <technology>,");
 	console.error("    identifiers <module> <NameId...>, integration <provider>");
-	console.error("  ui schematics: module <name> --api|--view <Name>|--component <Name>|--store <name>|--composable <name>,");
-	console.error("    api <module>, view <module> <Name>, component <module> <Name>, store <module> <name>, composable <module> <name>");
+	console.error("  ui schematics: module <name> --api|--view <Name>|--component <Name>|--store <name>|--composable <name>|--public <name>|--public-component <Name>,");
+	console.error("    api <module>, view <module> <Name>, component <module> <Name>, store <module> <name>, composable <module> <name>,");
+	console.error("    public <module> <name>, public-component <module> <Name>, app-store auth, app-store theme --storage-key <key>, app-component ThemeToggle");
 	process.exit(2);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zaaxch/tailframe",
-	"version": "0.1.1",
+	"version": "1.0.0",
 	"description": "Tailframe architecture toolkit: validates the Tailframe structure, import-boundary, and file-convention contracts. The package version is the contract version.",
 	"type": "module",
 	"bin": {

package/src/architecture.mjs

@@ -4,6 +4,22 @@ import path from "node:path";
 
 
 const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".vue"]);
+const APP_STORE_FILES = ["auth.store.ts", "theme.store.ts"];
+const APP_PUBLIC_FILES = ["ThemeToggle.vue"];
+const APP_STORE_TARGETS = new Set(["src/app/stores/auth.store", "src/app/stores/theme.store"]);
+const APP_PUBLIC_TARGETS = new Set(["src/app/public/ThemeToggle"]);
+
+function withoutSourceExtension(target) {
+	return target?.replace(/\.(?:ts|tsx|vue)$/, "");
+}
+
+function isPublicAppStore(target) {
+	return APP_STORE_TARGETS.has(withoutSourceExtension(target));
+}
+
+function isPublicAppUi(target) {
+	return APP_PUBLIC_TARGETS.has(withoutSourceExtension(target));
+}
 
 export function toPosix(value) {
 	return value.split(path.sep).join("/");
@@ -47,6 +63,10 @@ function resolveInternal(relativeFile, specifier) {
 	return path.posix.normalize(path.posix.join(path.posix.dirname(relativeFile), specifier));
 }
 
+function looksLikeUnsupportedInternalAlias(specifier) {
+	return /^(?:(?:~|#|\$)\/(?:src\/)?|@(?:app|core|platform|modules)\/|(?:src\/)?(?:app|core|platform|modules)\/)/.test(specifier);
+}
+
 export function isTestFile(relative) {
 	return relative.includes("/__tests__/") || /\.(?:test|spec)\.[^.]+$/.test(relative);
 }
@@ -86,6 +106,10 @@ function validateStructure(root, kind, fail) {
 			if (!allowed.includes(name)) fail(`Unexpected architecture ${entryKind}: ${relative}/${name}`);
 		}
 	};
+	const checkOptionalEntries = (relative, entryKind, allowed) => {
+		const target = path.join(root, relative);
+		if (fs.existsSync(target) && fs.statSync(target).isDirectory()) checkEntries(relative, entryKind, allowed);
+	};
 
 	if (kind === "service") {
 		checkEntries("src", "directory", ["__tests__", "app", "core", "modules", "platform"]);
@@ -95,8 +119,12 @@ function validateStructure(root, kind, fail) {
 	} else {
 		checkEntries("src", "directory", ["app", "core", "modules", "platform"]);
 		checkEntries("src", "file", ["main.ts"]);
-		checkEntries("src/app", "directory", ["__tests__", "components", "stores", "views"]);
+		checkEntries("src/app", "directory", ["__tests__", "components", "public", "stores", "views"]);
 		checkEntries("src/core", "directory", []);
+		checkOptionalEntries("src/app/public", "directory", []);
+		checkOptionalEntries("src/app/public", "file", APP_PUBLIC_FILES);
+		checkOptionalEntries("src/app/stores", "directory", []);
+		checkOptionalEntries("src/app/stores", "file", APP_STORE_FILES);
 	}
 
 	const platform = path.join(root, "src/platform");
@@ -108,11 +136,14 @@ function validateStructure(root, kind, fail) {
 	}
 	const allowedModuleDirectories = kind === "service"
 		? ["__tests__", "domain", "http", "persistence", "use-cases"]
-		: ["__tests__", "api", "components", "composables", "routes", "stores", "types", "views"];
+		: ["__tests__", "api", "components", "composables", "public", "routes", "stores", "types", "views"];
 	for (const moduleName of listEntries(modules, "directory")) {
-		if (kind === "ui" && moduleName === "theme") fail("Application theme must live under src/app, not src/modules/theme");
+		if (kind === "ui" && ["auth", "theme"].includes(moduleName)) {
+			fail(`Application ${moduleName === "auth" ? "authentication" : "theme"} must live under src/app, not src/modules/${moduleName}`);
+		}
 		checkEntries(`src/modules/${moduleName}`, "directory", allowedModuleDirectories);
 		checkEntries(`src/modules/${moduleName}`, "file", []);
+		if (kind === "ui") checkOptionalEntries(`src/modules/${moduleName}/public`, "directory", []);
 	}
 }
 
@@ -188,7 +219,7 @@ function validateServiceImport(source, target, external, fail, graph) {
 	}
 }
 
-function validateUiImport(source, target, external, fail) {
+function validateUiImport(source, target, external, fail, graph) {
 	if (source === "src/main.ts") {
 		if (external || !target.startsWith("src/app/")) fail(`src/main.ts may import only app bootstrap code, not ${external ?? target}`);
 		return;
@@ -197,6 +228,22 @@ function validateUiImport(source, target, external, fail) {
 		if (external || !target.startsWith("src/core/")) fail(`${source} violates core purity by importing ${external ?? target}`);
 		return;
 	}
+	if (source.startsWith("src/app/stores/")) {
+		if (external || target.startsWith("src/core/") || target.startsWith("src/platform/")) return;
+		fail(`${source} is a canonical shell store and may import only framework packages, core, or platform, not ${target}`);
+		return;
+	}
+	if (source.startsWith("src/app/public/")) {
+		if (external || target.startsWith("src/core/") || target.startsWith("src/platform/") || isPublicAppStore(target)) return;
+		fail(`${source} is canonical public shell UI and may import only framework packages, core, platform, or a canonical app store, not ${target}`);
+		return;
+	}
+	if (/^src\/app\/(?:components|views)\//.test(source)) {
+		const targetModule = moduleParts(target ?? "");
+		if (!targetModule || targetModule.layer === "public") return;
+		fail(`${source} may compose a product module only through a named module public entry, not ${target}; route module views directly from src/app/router.ts`);
+		return;
+	}
 	if (source.startsWith("src/app/")) return;
 	if (source.startsWith("src/platform/")) {
 		if (external || target.startsWith("src/core/") || target.startsWith("src/platform/")) return;
@@ -205,20 +252,27 @@ function validateUiImport(source, target, external, fail) {
 	}
 	const sourceModule = moduleParts(source);
 	if (!sourceModule || external) return;
-	if (target.startsWith("src/core/") || target.startsWith("src/platform/")) return;
+	if (target.startsWith("src/core/") || target.startsWith("src/platform/") || isPublicAppStore(target) || isPublicAppUi(target)) return;
 	const targetModule = moduleParts(target);
 	if (targetModule?.module === sourceModule.module) return;
-	fail(`${source} may import only its own UI module, core, or platform, not ${target}`);
+	if (targetModule?.layer === "public" && targetModule.remainder && !targetModule.remainder.includes("/")) {
+		if (!isTestFile(source) && sourceModule.layer !== "__tests__") {
+			if (!graph.has(sourceModule.module)) graph.set(sourceModule.module, new Set());
+			graph.get(sourceModule.module).add(targetModule.module);
+		}
+		return;
+	}
+	fail(`${source} may import only its own UI module, core, platform, the canonical auth/theme app stores, ThemeToggle, or a named file directly under another module's public directory, not ${target}`);
 }
 
-function detectCycles(graph, fail) {
+function detectCycles(graph, fail, label) {
 	const visited = new Set();
 	const active = [];
 	const activeSet = new Set();
 	const visit = (moduleName) => {
 		if (activeSet.has(moduleName)) {
 			const start = active.indexOf(moduleName);
-			fail(`Cross-module use-case dependency cycle: ${[...active.slice(start), moduleName].join(" -> ")}`);
+			fail(`${label}: ${[...active.slice(start), moduleName].join(" -> ")}`);
 			return;
 		}
 		if (visited.has(moduleName)) return;
@@ -246,14 +300,18 @@ export function validateArchitecture(rootArgument, kind) {
 		const relative = toPosix(path.relative(root, absolute));
 		for (const specifier of extractImports(fs.readFileSync(absolute, "utf8"), relative)) {
 			const target = resolveInternal(relative, specifier);
+			if (!target && looksLikeUnsupportedInternalAlias(specifier)) {
+				fail(`${relative} uses unsupported internal import alias ${specifier}; use @/ or a relative import so boundaries remain enforceable`);
+				continue;
+			}
 			if (target && !target.startsWith("src/")) {
 				fail(`${relative} has a relative import outside src: ${specifier}`);
 				continue;
 			}
 			if (kind === "service") validateServiceImport(relative, target, target ? undefined : specifier, fail, graph);
-			else validateUiImport(relative, target, target ? undefined : specifier, fail);
+			else validateUiImport(relative, target, target ? undefined : specifier, fail, graph);
 		}
 	}
-	if (kind === "service") detectCycles(graph, fail);
+	detectCycles(graph, fail, kind === "service" ? "Cross-module use-case dependency cycle" : "Cross-module UI public dependency cycle");
 	return errors;
 }

package/src/conventions.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { toPosix, walk } from "./architecture.mjs";
+import { authAppStoreSource, themeAppStoreSource, themeToggleSource } from "./generate.mjs";
 
 const PASCAL = /^[A-Z][A-Za-z0-9]*$/;
 const CAMEL = /^[a-z][A-Za-z0-9]*$/;
@@ -8,6 +9,11 @@ const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const ROLES = new Set(["routes", "schemas", "api", "store", "types", "documents"]);
 const NOT_PLURAL = new Set(["status", "analysis"]);
 const BRAND_PATTERN = /\bBrand\s*<|unique symbol/;
+const ROUTE_NAMES_FILE = "src/core/RouteNames.ts";
+const ROUTE_NAMES_DECLARATION = /\b(?:enum|const|type)\s+RouteNames\b/;
+const ROUTE_NAMES_CANONICAL_DECLARATION = /\bexport\s+enum\s+RouteNames\b/;
+const ROUTE_NAMES_VALUE = /^\s*[A-Z][A-Z0-9_]*\s*=\s*["']([^"']+)["']/gm;
+const ROUTE_NAME_REFERENCE = /\bname:\s*["']([^"']+)["']/g;
 
 function parseName(fileName) {
 	if (fileName.endsWith(".d.ts")) return undefined;
@@ -59,6 +65,9 @@ export function validateConventions(rootArgument, kind) {
 			if ((relative.startsWith("src/core/") && name.extension === ".ts") && BRAND_PATTERN.test(fs.readFileSync(absolute, "utf8"))) {
 				flag("S5", relative, `${relative} defines identifier branding in core; branded IDs and the Brand helper belong in the owning module's domain/identifiers.ts`);
 			}
+			if (kind === "ui" && relative.startsWith("src/app/public/") && relative.slice("src/app/public/".length).includes("/")) {
+				flag("U6", relative, `${relative} is nested under app/public; public shell entries are named files directly under src/app/public`);
+			}
 			continue;
 		}
 
@@ -95,9 +104,83 @@ export function validateConventions(rootArgument, kind) {
 			flag("S5", relative, `${relative} declares identifier branding outside domain/identifiers.ts; each module keeps its brands, Brand helper, and boundary helpers in one domain/identifiers.ts`);
 		}
 	}
+	if (kind === "ui") {
+		validateRouteNames(root, src, flag);
+		validateCanonicalShell(root, flag);
+	}
 	return violations;
 }
 
+function normalizeGeneratedSource(source) {
+	return source.replace(/\r\n/g, "\n");
+}
+
+function validateCanonicalShell(root, flag) {
+	const authRelative = "src/app/stores/auth.store.ts";
+	const authFile = path.join(root, authRelative);
+	if (fs.existsSync(authFile) && normalizeGeneratedSource(fs.readFileSync(authFile, "utf8")) !== authAppStoreSource()) {
+		flag("U7", authRelative, `${authRelative} differs from the canonical Tailframe auth store; regenerate it instead of maintaining a project-local variant`);
+	}
+
+	const themeRelative = "src/app/stores/theme.store.ts";
+	const themeFile = path.join(root, themeRelative);
+	if (fs.existsSync(themeFile)) {
+		const source = normalizeGeneratedSource(fs.readFileSync(themeFile, "utf8"));
+		const storageKeyMatch = source.match(/useLocalStorage<Theme>\(("(?:\\.|[^"\\])*"), preferredTheme\(\)\)/);
+		let expected;
+		if (storageKeyMatch) {
+			try { expected = themeAppStoreSource(JSON.parse(storageKeyMatch[1])); } catch { /* reported below */ }
+		}
+		if (!expected || source !== expected) {
+			flag("U7", themeRelative, `${themeRelative} differs from the canonical Tailframe theme store; only its generated storage-key value may vary`);
+		}
+	}
+
+	const toggleRelative = "src/app/public/ThemeToggle.vue";
+	const toggleFile = path.join(root, toggleRelative);
+	if (fs.existsSync(toggleFile)) {
+		if (!fs.existsSync(themeFile)) flag("U7", toggleRelative, `${toggleRelative} requires ${themeRelative}`);
+		if (normalizeGeneratedSource(fs.readFileSync(toggleFile, "utf8")) !== themeToggleSource()) {
+			flag("U7", toggleRelative, `${toggleRelative} differs from the canonical Tailframe theme toggle; regenerate it instead of maintaining a project-local variant`);
+		}
+	}
+}
+
+/**
+ * Route names are the one piece of shell vocabulary a module legitimately needs, so they live in a
+ * core enum both sides may import. A module that cannot reach the enum hardcodes the string instead,
+ * and a later rename breaks navigation silently.
+ */
+function validateRouteNames(root, src, flag) {
+	const declarationFile = path.join(root, ROUTE_NAMES_FILE);
+	const declared = new Set();
+	if (!fs.existsSync(declarationFile)) {
+		flag("U5", ROUTE_NAMES_FILE, `${ROUTE_NAMES_FILE} is required; route names are one exported enum shared by the router and modules`);
+	} else {
+		const text = fs.readFileSync(declarationFile, "utf8");
+		if (!ROUTE_NAMES_CANONICAL_DECLARATION.test(text)) {
+			flag("U5", ROUTE_NAMES_FILE, `${ROUTE_NAMES_FILE} must declare export enum RouteNames`);
+		}
+		for (const match of text.matchAll(ROUTE_NAMES_VALUE)) declared.add(match[1]);
+		if (declared.size === 0) flag("U5", ROUTE_NAMES_FILE, `${ROUTE_NAMES_FILE} must declare at least one string-valued route name`);
+	}
+	for (const absolute of walk(src)) {
+		const relative = toPosix(path.relative(root, absolute));
+		if (![".ts", ".vue"].includes(path.extname(relative))) continue;
+		const text = fs.readFileSync(absolute, "utf8");
+		if (relative !== ROUTE_NAMES_FILE && ROUTE_NAMES_DECLARATION.test(text)) {
+			flag("U5", relative, `${relative} declares RouteNames outside ${ROUTE_NAMES_FILE}; route names are one core enum imported by the router and by modules`);
+		}
+		if (!relative.startsWith("src/modules/") || declared.size === 0) continue;
+		for (const match of text.matchAll(ROUTE_NAME_REFERENCE)) {
+			if (declared.has(match[1])) {
+				flag("U5", relative, `${relative} hardcodes the route name "${match[1]}"; import RouteNames from ${ROUTE_NAMES_FILE}`);
+				break;
+			}
+		}
+	}
+}
+
 function validateShared(relative, name, flag) {
 	if (name.stem === "index") return;
 	const directory = path.posix.basename(path.posix.dirname(relative));
@@ -111,6 +194,10 @@ function validateShared(relative, name, flag) {
 		else if (directory === "views" && !name.stem.endsWith("View")) flag("U2", relative, `${relative} views are named <Name>View.vue`);
 		return;
 	}
+	if (relative.startsWith("src/app/stores/") && name.extension === ".ts") {
+		flag("U3", relative, `${relative} is not a canonical app store; app/stores is closed to auth.store.ts and theme.store.ts`);
+		return;
+	}
 	if (!PASCAL.test(name.stem) && !CAMEL.test(name.stem)) {
 		flag("G1", relative, `${relative} must be named after its primary export in that export's casing (PascalCase or camelCase)`);
 	}
@@ -178,6 +265,14 @@ function validateUiFile(relative, moduleName, layer, name, flag) {
 		if (name.role !== "store") flag("U3", relative, `${relative} stores are named <name>.store.ts`);
 		return;
 	}
+	if (layer === "public") {
+		const remainder = relative.slice(`src/modules/${moduleName}/public/`.length);
+		if (remainder.includes("/")) flag("U6", relative, `${relative} is nested; module public entries are named files directly under public/`);
+		else if (name.role !== undefined || (!PASCAL.test(name.stem) && !CAMEL.test(name.stem))) {
+			flag("U6", relative, `${relative} must be a named public entry in primary-export casing, not a role-suffix file or barrel`);
+		}
+		return;
+	}
 	if (layer === "types") {
 		if (name.role !== undefined) {
 			if (name.role !== "types" || name.subject !== moduleName) flag("U3", relative, `${relative} the module types role file is ${moduleName}.types.ts`);

package/src/generate.mjs

@@ -4,6 +4,7 @@ import { loadExceptions, isExcepted } from "./exceptions.mjs";
 
 const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const PASCAL = /^[A-Z][A-Za-z0-9]*$/;
+const PRIMARY = /^(?:[A-Z][A-Za-z0-9]*|[a-z][A-Za-z0-9]*)$/;
 const NOT_PLURAL = new Set(["status", "analysis"]);
 
 export class GenerateError extends Error {}
@@ -30,6 +31,14 @@ function requireModuleName(root, name) {
 	return name;
 }
 
+function requireUiModuleName(root, name) {
+	requireModuleName(root, name);
+	if (["auth", "theme"].includes(name)) {
+		fail(`UI module "${name}" is reserved for application-shell state under src/app/stores`);
+	}
+	return name;
+}
+
 function requirePascal(value, label, forbiddenSuffixes = []) {
 	if (!value || !PASCAL.test(value)) fail(`${label} must be PascalCase, received "${value ?? ""}"`);
 	for (const suffix of forbiddenSuffixes) {
@@ -38,6 +47,11 @@ function requirePascal(value, label, forbiddenSuffixes = []) {
 	return value;
 }
 
+function requirePrimary(value, label) {
+	if (!value || !PRIMARY.test(value)) fail(`${label} must use PascalCase or camelCase primary-export naming, received "${value ?? ""}"`);
+	return value;
+}
+
 function operationName(moduleName, verbNoun) {
 	const moduleSuffix = pascal(moduleName);
 	if (verbNoun.endsWith(moduleSuffix) && verbNoun !== moduleSuffix) {
@@ -265,9 +279,11 @@ export async function get${pascal(moduleName)}() {
 	}
 	if (kindOptions.store) {
 		files[`src/modules/${moduleName}/stores/${kindOptions.store}.store.ts`] =
-`import { reactive } from "vue";
+`import { defineStore } from "pinia";
 
-export const ${camel(kindOptions.store)}Store = reactive({});
+export const use${pascal(kindOptions.store)}Store = defineStore("${moduleName}/${kindOptions.store}", () => {
+	return {};
+});
 `;
 	}
 	if (kindOptions.composable) {
@@ -275,56 +291,221 @@ export const ${camel(kindOptions.store)}Store = reactive({});
 `export function use${pascal(kindOptions.composable)}() {
 	return {};
 }
+`;
+	}
+	if (kindOptions.public) {
+		const exportName = kindOptions.public;
+		files[`src/modules/${moduleName}/public/${exportName}.ts`] = exportName[0] === exportName[0].toUpperCase()
+			? `export interface ${exportName} {}\n`
+			: `export function ${exportName}() {\n\treturn {};\n}\n`;
+	}
+	if (kindOptions.publicComponent) {
+		files[`src/modules/${moduleName}/public/${kindOptions.publicComponent}.vue`] =
+`<script setup lang="ts"></script>
+
+<template>
+	<div></div>
+</template>
 `;
 	}
 	return files;
 }
 
+export function themeAppStoreSource(storageKey) {
+	return `import { useLocalStorage } from "@vueuse/core";
+import { defineStore } from "pinia";
+import { computed } from "vue";
+
+export type Theme = "light" | "dark";
+
+const preferredTheme = (): Theme =>
+	typeof window !== "undefined" && window.matchMedia?.("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+
+export const useThemeStore = defineStore("theme", () => {
+	const theme = useLocalStorage<Theme>(${JSON.stringify(storageKey)}, preferredTheme());
+	const isDark = computed(() => theme.value === "dark");
+
+	function toggleTheme() {
+		theme.value = isDark.value ? "light" : "dark";
+	}
+
+	return { theme, isDark, toggleTheme };
+});
+`;
+}
+
+export function themeToggleSource() {
+	return `<template>
+	<button
+		type="button"
+		:aria-label="\`Switch to \${themeStore.isDark ? 'light' : 'dark'} mode\`"
+		:title="\`Switch to \${themeStore.isDark ? 'light' : 'dark'} mode\`"
+		@click="themeStore.toggleTheme"
+	>
+		<svg
+			v-if="themeStore.isDark"
+			aria-hidden="true"
+			class="size-5"
+			viewBox="0 0 24 24"
+			fill="none"
+			stroke="currentColor"
+			stroke-width="1.8"
+		>
+			<circle cx="12" cy="12" r="4" />
+			<path
+				d="M12 2v2m0 16v2M4.93 4.93l1.42 1.42m11.3 11.3 1.42 1.42M2 12h2m16 0h2M4.93 19.07l1.42-1.42m11.3-11.3 1.42-1.42"
+			/>
+		</svg>
+		<svg
+			v-else
+			aria-hidden="true"
+			class="size-5"
+			viewBox="0 0 24 24"
+			fill="none"
+			stroke="currentColor"
+			stroke-width="1.8"
+		>
+			<path d="M20.5 15.2A8.5 8.5 0 0 1 8.8 3.5a8.5 8.5 0 1 0 11.7 11.7Z" />
+		</svg>
+	</button>
+</template>
+
+<script setup lang="ts">
+import { useThemeStore } from "@/app/stores/theme.store";
+
+const themeStore = useThemeStore();
+</script>
+`;
+}
+
+export function authAppStoreSource() {
+	return `import { auth, googleProvider } from "@/platform/firebase";
+import { onIdTokenChanged, signInWithPopup, signOut, type User } from "firebase/auth";
+import { defineStore } from "pinia";
+import { ref } from "vue";
+
+export const useAuthStore = defineStore("auth", () => {
+	const firebaseUser = ref<User | null>(null);
+	const ready = ref(false);
+
+	onIdTokenChanged(auth, (user) => {
+		firebaseUser.value = user;
+		ready.value = true;
+	});
+
+	const signInWithGoogle = () => signInWithPopup(auth, googleProvider);
+	const logout = () => signOut(auth);
+	const getIdToken = () => firebaseUser.value?.getIdToken();
+
+	return { firebaseUser, ready, signInWithGoogle, logout, getIdToken };
+});
+`;
+}
+
+function appStoreFiles(name, options) {
+	if (name === "theme") {
+		const storageKey = options.get("--storage-key");
+		if (!storageKey) fail("Theme app-store generation requires --storage-key <key>");
+		return { "src/app/stores/theme.store.ts": themeAppStoreSource(storageKey) };
+	}
+	if (name === "auth") return { "src/app/stores/auth.store.ts": authAppStoreSource() };
+	fail(`App store must be one of auth or theme, received "${name ?? ""}"`);
+}
+
+function appPublicComponentFiles(name) {
+	if (name !== "ThemeToggle") {
+		fail(`Public shell component must be ThemeToggle, received "${name ?? ""}"; product UI belongs in its owning module`);
+	}
+	return {
+		"src/app/public/ThemeToggle.vue": themeToggleSource()
+	};
+}
+
 const uiSchematics = {
 	module(root, [name], options) {
-		requireModuleName(root, name);
+		requireUiModuleName(root, name);
 		const artifacts = {
 			api: options.has("--api"),
 			view: options.get("--view"),
 			component: options.get("--component"),
 			store: options.get("--store"),
-			composable: options.get("--composable")
+			composable: options.get("--composable"),
+			public: options.get("--public"),
+			publicComponent: options.get("--public-component")
 		};
 		if (artifacts.view) requirePascal(artifacts.view, "View");
 		if (artifacts.component) requirePascal(artifacts.component, "Component");
 		if (artifacts.store && !KEBAB.test(artifacts.store)) fail(`Store name must be lowercase kebab-case, received "${artifacts.store}"`);
 		if (artifacts.composable && !KEBAB.test(artifacts.composable)) fail(`Composable name must be lowercase kebab-case, received "${artifacts.composable}"`);
+		if (artifacts.public) requirePrimary(artifacts.public, "Public entry");
+		if (artifacts.publicComponent) requirePascal(artifacts.publicComponent, "Public component");
 		const files = uiArtifacts(name, artifacts);
-		if (!Object.keys(files).length) fail("A UI module needs at least one artifact: pass --api, --view <Name>, --component <Name>, --store <name>, or --composable <name> (empty layers are forbidden)");
+		if (!Object.keys(files).length) fail("A UI module needs at least one artifact: pass --api, --view <Name>, --component <Name>, --store <name>, --composable <name>, --public <name>, or --public-component <Name> (empty layers are forbidden)");
 		return [plan(files), [
 			...(artifacts.view ? [`Register the view in a route and mount it from src/app/router.ts`] : []),
 			...(artifacts.api ? [`Point ${name}.api.ts at the real RPC operation`] : []),
-			`Compose the module from src/app only; other modules must not import it`
+			...(artifacts.public ? [`Implement ${artifacts.public}.ts as one stable public capability; keep internal module paths private`] : []),
+			...(artifacts.publicComponent ? [`Implement ${artifacts.publicComponent}.vue as one stable public component backed only by this module's internals`] : []),
+			`Compose the module from src/app; sibling modules may use only named files directly under this module's public directory`
 		]];
 	},
 	api(root, [moduleName]) {
-		requireModuleName(root, moduleName);
+		requireUiModuleName(root, moduleName);
 		return [plan(uiArtifacts(moduleName, { api: true })), [`Point ${moduleName}.api.ts at the real RPC operation`]];
 	},
 	view(root, [moduleName, name]) {
-		requireModuleName(root, moduleName);
+		requireUiModuleName(root, moduleName);
 		requirePascal(name, "View");
 		return [plan(uiArtifacts(moduleName, { view: name })), [`Register the view in a route and mount it from src/app/router.ts`]];
 	},
 	component(root, [moduleName, name]) {
-		requireModuleName(root, moduleName);
+		requireUiModuleName(root, moduleName);
 		requirePascal(name, "Component");
 		return [plan(uiArtifacts(moduleName, { component: name })), [`Use the component from this module's views only`]];
 	},
 	store(root, [moduleName, name]) {
-		requireModuleName(root, moduleName);
+		requireUiModuleName(root, moduleName);
 		if (!name || !KEBAB.test(name)) fail(`Store name must be lowercase kebab-case, received "${name ?? ""}"`);
-		return [plan(uiArtifacts(moduleName, { store: name })), [`Keep the store module-private; cross-module state belongs in src/app`]];
+		return [plan(uiArtifacts(moduleName, { store: name })), [`Keep product state in this owning module; expose a deliberate facade with tailframe generate public ${moduleName} use${pascal(name)}Store only when another module needs it`]];
 	},
 	composable(root, [moduleName, name]) {
-		requireModuleName(root, moduleName);
+		requireUiModuleName(root, moduleName);
 		if (!name || !KEBAB.test(name)) fail(`Composable name must be lowercase kebab-case, received "${name ?? ""}"`);
-		return [plan(uiArtifacts(moduleName, { composable: name })), [`Use the composable from this module only`]];
+		return [plan(uiArtifacts(moduleName, { composable: name })), [`Use the composable inside this module; expose a named public facade only when another module needs it`]];
+	},
+	public(root, [moduleName, name]) {
+		requireUiModuleName(root, moduleName);
+		requirePrimary(name, "Public entry");
+		return [plan(uiArtifacts(moduleName, { public: name })), [
+			`Expose one stable capability from ${name}.ts; it may adapt this module's internal stores, composables, types, or API`,
+			`Keep UI module dependencies acyclic and import no sibling internals`
+		]];
+	},
+	"public-component"(root, [moduleName, name]) {
+		requireUiModuleName(root, moduleName);
+		requirePascal(name, "Public component");
+		return [plan(uiArtifacts(moduleName, { publicComponent: name })), [
+			`Implement ${name}.vue as one stable public component backed only by ${moduleName} internals`,
+			`Keep UI module dependencies acyclic and import no sibling internals`
+		]];
+	},
+	"app-store"(root, [name], options) {
+		if (name === "auth" && !fs.existsSync(path.join(root, "src/platform/firebase.ts"))) {
+			fail("Auth app-store generation requires src/platform/firebase.ts exporting auth and googleProvider");
+		}
+		return [plan(appStoreFiles(name, options)), [
+			`Use the generated ${name}.store.ts as emitted; do not fork its implementation per project`,
+			`Modules may import the store directly; every other app store name is forbidden`
+		]];
+	},
+	"app-component"(root, [name]) {
+		if (name === "ThemeToggle" && !fs.existsSync(path.join(root, "src/app/stores/theme.store.ts"))) {
+			fail("ThemeToggle generation requires src/app/stores/theme.store.ts; generate the theme app store first");
+		}
+		return [plan(appPublicComponentFiles(name)), [
+			`Use ThemeToggle as emitted; do not fork its implementation per project`,
+			`Keep every other reusable UI capability in its owning module`
+		]];
 	}
 };
 

package/src/new.mjs

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { GenerateError } from "./generate.mjs";
+import { authAppStoreSource, GenerateError } from "./generate.mjs";
 
 function fail(message) {
 	throw new GenerateError(message);
@@ -132,15 +132,15 @@ Use this workflow for any new domain capability or operation. Add only the layer
 1. Identify the module, requested operations, entry points, and repositories in scope. Classify every intended file with the applicable AGENTS.md placement table before writing. Do not assume full CRUD.
 2. Read the root and every applicable child \`AGENTS.md\`.
 3. Inspect the nearest working module and tests.
-4. Create architecture files only with the tailframe CLI: \`tailframe generate\` creates service modules, use cases, http files, ports, adapters, identifiers, and integrations, and UI modules, api clients, views, components, stores, and composables on canonical paths with canonical names. Hand-creating architecture files is a conformance violation; complete the printed wiring checklist after each generation.
-5. Colocate product capability behavior under \`src/modules/<module>\` in both the service and UI. Never substitute \`features\` or global \`apis\`, \`views\`, \`services\`, \`stores\`, or \`types\` directories. Theme state, its toggle, tests, the router, and the application shell always belong under UI \`src/app\`; never create \`src/modules/theme\`. Start backend modules with \`use-cases/\`, \`http/\`, and tests; add \`domain/\` or \`persistence/\` only when required. Add only the UI module directories earned by the capability.
+4. Create architecture files only with the tailframe CLI: \`tailframe generate\` creates service modules, use cases, http files, ports, adapters, identifiers, integrations, UI modules, and the closed UI shell catalog on canonical paths with canonical names. Hand-creating architecture files or editing generated shell-catalog implementations is a conformance violation; complete the printed wiring checklist after each generation.
+5. Colocate product capability behavior under \`src/modules/<module>\` in both the service and UI. Never substitute \`features\` or global \`apis\`, \`views\`, \`services\`, \`stores\`, or \`types\` directories. UI \`app/stores\` is closed to generated \`auth.store.ts\` and \`theme.store.ts\`; \`app/public\` is closed to generated \`ThemeToggle.vue\`. Never create \`src/modules/theme\` or \`src/modules/auth\`. Product records, current-user domain records, selections, filters, and workflows stay in their owning module. Start backend modules with \`use-cases/\`, \`http/\`, and tests; add \`domain/\` or \`persistence/\` only when required. Add only the UI module directories earned by the capability.
 6. Define use cases as \`execute(context, input)\`. Keep trusted \`RequestContext\` separate from client input.
 7. Put ownership, RBAC, entitlements, and domain policies in use-case or domain code, not client bodies or route metadata.
 8. Define repository contracts in the owning module and implement them in persistence adapters.
 9. For persisted capabilities, prefer branded, domain-owned string IDs at domain and repository-port boundaries; generate the module's identifier file with \`tailframe generate identifiers <module> <NameId...>\`. Keep MongoDB \`ObjectId\` conversion inside MongoDB persistence adapters, using persistence-only document types rather than \`any\` to bypass the boundary.
 10. Let HTTP routes, jobs, workers, scheduled tasks, and CLIs invoke use cases directly; do not call one entry point from another.
-11. Keep operation names, payloads, authentication, response contracts, and client types synchronized. A service module may import another only through a named file directly under the provider's use-cases directory and must keep the module dependency graph acyclic. UI modules never import one another; compose them in UI app.
-12. Add required container, route, client, navigation, worker, or process registration and focused tests.
+11. Keep operation names, payloads, authentication, response contracts, and client types synchronized. A service module may import another only through a named file directly under the provider's use-cases directory. A UI module may import another only through a named file directly under the provider's public directory. Both graphs must remain acyclic. UI modules may import only the generated auth/theme app stores and \`ThemeToggle\` from app; every other app path is private.
+12. Add required container, route, client, navigation, worker, or process registration and focused tests. Route module views directly from \`app/router.ts\`. App views and shell components consume product modules only through named module \`public/\` entries; they never import module views or other internals.
 13. Run npm run validate:architecture in every affected repository, then run focused type checks and tests. Report repositories, operations, entry points, checks, placement decisions, and gaps.
 
 Do not create empty architectural layers, speculative operations, or mandatory controllers. Do not claim behavior from static files, weaken trusted context or persistence ownership, or change unrelated background behavior.
@@ -398,7 +398,7 @@ These conventions apply to \`${svc}\`. This service is a modular monolith organi
 | Cross-entry-point technology-neutral contract | Flat \`src/core\` |
 | Root executable | Bootstrap of matching \`src/app\` assembly only |
 
-Product vocabulary stays in the module that owns its meaning; never move it into \`core\`. A module may import another only through a named file directly under the provider's \`use-cases/\`; its domain, HTTP, persistence, ports, and tests remain private, and cross-module use-case dependencies must be acyclic.
+Product vocabulary stays in the module that owns its meaning; never move it into \`core\`. A module may import another only through a named file directly under the provider's \`use-cases/\`; its domain, HTTP, persistence, ports, and tests remain private, and cross-module use-case dependencies must be acyclic. Use \`@/\` or relative internal imports; do not add another source alias.
 
 ## Public API contract
 - Use singular RPC-shaped \`POST /api/v1/<module>.<operation>\` operations and the \`{ result: ... }\` success envelope.
@@ -469,12 +469,13 @@ add(`${ui}/.gitignore`, `node_modules/\ndist/\n.env*\n!.env.example\ncerts/\n*.l
 if (options.auth === "firebase") add(`${ui}/.env.example`, `VITE_FIREBASE_API_KEY=\nVITE_FIREBASE_AUTH_DOMAIN=\nVITE_FIREBASE_PROJECT_ID=\nVITE_FIREBASE_APP_ID=\n`);
 add(`${ui}/src/core/rpc.ts`, `export interface RpcResponse<T> { result: T; }\nexport interface RpcError { error: { message: string; code?: string }; }`);
 if (options.auth === "firebase") {
-	add(`${ui}/src/platform/firebase.ts`, `import { initializeApp } from "firebase/app";\nexport const firebaseApp = initializeApp({ apiKey: import.meta.env.VITE_FIREBASE_API_KEY, authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN, projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID, appId: import.meta.env.VITE_FIREBASE_APP_ID });`);
-	add(`${ui}/src/app/stores/auth.ts`, `import { defineStore } from "pinia";\nimport { getAuth, onAuthStateChanged, signOut, type User } from "firebase/auth";\nimport { ref } from "vue";\nimport { firebaseApp } from "@/platform/firebase";\nexport const useAuthStore = defineStore("auth", () => { const firebaseUser = ref<User|null>(null); const ready = ref(false); const auth = getAuth(firebaseApp); onAuthStateChanged(auth, user => { firebaseUser.value = user; ready.value = true; }); const getIdToken = () => firebaseUser.value?.getIdToken(); const logout = () => signOut(auth); return { firebaseUser, ready, getIdToken, logout }; });`);
+	add(`${ui}/src/platform/firebase.ts`, `import { initializeApp } from "firebase/app";\nimport { getAuth, GoogleAuthProvider } from "firebase/auth";\n\nconst firebaseApp = initializeApp({\n\tapiKey: import.meta.env.VITE_FIREBASE_API_KEY,\n\tauthDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,\n\tprojectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,\n\tappId: import.meta.env.VITE_FIREBASE_APP_ID\n});\n\nexport const auth = getAuth(firebaseApp);\nexport const googleProvider = new GoogleAuthProvider();`);
+	add(`${ui}/src/app/stores/auth.store.ts`, authAppStoreSource());
 }
-add(`${ui}/src/app/router.ts`, `import { createRouter, createWebHistory } from "vue-router";\nexport enum RouteNames { HOME = "Home" }\nexport default createRouter({ history: createWebHistory(), routes: [{ path: "/", name: RouteNames.HOME, component: () => import("@/app/views/HomeView.vue") }] });`);
+add(`${ui}/src/core/RouteNames.ts`, `/** Route vocabulary shared by the router and by modules. Modules never import the router itself. */\nexport enum RouteNames {\n\tHOME = "Home"\n}\n`);
+add(`${ui}/src/app/router.ts`, `import { createRouter, createWebHistory } from "vue-router";\nimport { RouteNames } from "@/core/RouteNames";\nexport default createRouter({ history: createWebHistory(), routes: [{ path: "/", name: RouteNames.HOME, component: () => import("@/app/views/HomeView.vue") }] });`);
 add(`${ui}/src/platform/http.ts`, `import axios from "axios";\nexport const http = axios.create({ baseURL: \`\${window.location.origin}/api/v1\`, headers: { "Content-Type": "application/json" } });`);
-if (options.auth === "firebase") add(`${ui}/src/app/configureHttp.ts`, `import type { Pinia } from "pinia";\nimport router, { RouteNames } from "@/app/router";\nimport { useAuthStore } from "@/app/stores/auth";\nimport { http } from "@/platform/http";\nexport function configureHttp(pinia: Pinia) {\n\tconst auth = useAuthStore(pinia);\n\thttp.interceptors.request.use(async config => { const token = await auth.getIdToken(); if (token) config.headers.Authorization = \`Bearer \${token}\`; return config; });\n\thttp.interceptors.response.use(response => response, async error => { if (error?.response?.status === 401) { await auth.logout(); await router.push({ name: RouteNames.HOME }); } return Promise.reject(error); });\n}\n`);
+if (options.auth === "firebase") add(`${ui}/src/app/configureHttp.ts`, `import type { Pinia } from "pinia";\nimport router from "@/app/router";\nimport { RouteNames } from "@/core/RouteNames";\nimport { useAuthStore } from "@/app/stores/auth.store";\nimport { http } from "@/platform/http";\nexport function configureHttp(pinia: Pinia) {\n\tconst auth = useAuthStore(pinia);\n\thttp.interceptors.request.use(async config => { const token = await auth.getIdToken(); if (token) config.headers.Authorization = \`Bearer \${token}\`; return config; });\n\thttp.interceptors.response.use(response => response, async error => { if (error?.response?.status === 401) { await auth.logout(); await router.push({ name: RouteNames.HOME }); } return Promise.reject(error); });\n}\n`);
 add(`${ui}/src/modules/health/api/health.api.ts`, `import { http } from "@/platform/http";\nimport type { RpcResponse } from "@/core/rpc";\nexport async function getHealth() { return (await http.post<RpcResponse<{ status: string }>>("health.get")).data.result; }`);
 add(`${ui}/src/app/views/HomeView.vue`, `<template><main class="mx-auto flex min-h-screen max-w-5xl flex-col justify-center gap-4 px-6 py-16"><p class="font-bold uppercase tracking-[0.12em] text-emerald-800">Project foundation</p><h1 class="m-0 text-5xl font-bold sm:text-7xl">${title}</h1><p>The product domain is intentionally undefined.</p></main></template>`);
 add(`${ui}/src/app/App.vue`, `<template><RouterView /></template><script setup lang="ts">import { RouterView } from "vue-router";</script>`);
@@ -488,26 +489,30 @@ add(`${ui}/AGENTS.md`, `# ${title} UI guidance
 These conventions apply to \`${ui}/src\`. Inspect the nearest working module before adding files.
 
 ## Architecture vocabulary
-- Use \`src/app\` for Vue bootstrap, the application shell, routing, global styles, and truly application-wide state.
+- Use \`src/app\` for Vue bootstrap, the application shell, routing, global styles, and the closed Tailframe auth/theme catalog.
 - Use \`src/core\` only for small technology-neutral client contracts.
 - Use \`src/platform\` for Axios, Firebase, browser APIs, and other technical adapters.
 - Use \`src/modules/<module>\` for every product capability. Never substitute \`src/features\` or global \`apis\`, \`views\`, \`services\`, \`stores\`, or \`types\` directories.
-- These are the only UI architecture roots. Keep \`src/core\` flat. Shared capability code belongs to the module that owns it; reusable application-shell presentation belongs under \`src/app\`, whose optional directories are limited to \`components\`, \`stores\`, \`views\`, and \`__tests__\`.
-- Keep application-wide theme state at \`src/app/stores/theme.store.ts\`, its toggle at \`src/app/components/ThemeToggle.vue\`, and its tests under \`src/app/__tests__\`. Never create \`src/modules/theme\`.
+- These are the only UI architecture roots. Keep \`src/core\` flat. Shared capability code belongs to the module that owns it. \`src/app/stores\` is closed to generated \`auth.store.ts\` and \`theme.store.ts\`; \`src/app/public\` is closed to generated \`ThemeToggle.vue\`. Do not edit their implementations; only the generated theme storage key varies. Internal shell components remain private under \`src/app/components\`.
+- Never create \`src/modules/theme\` or \`src/modules/auth\`. Product records, current-user domain records, selections, filters, workflows, and module API calls always belong to the owning product module.
 
 ## Change placement
 | Change | Canonical owner |
 | --- | --- |
 | Capability API, component, composable, state, type, or view | \`src/modules/<module>\` |
+| Capability intentionally consumed by another module | Named file directly under provider \`src/modules/<module>/public\` |
 | Axios, Firebase, browser, or vendor mechanism | \`src/platform\` |
-| Shell, router, global state/theme, or cross-capability composition | \`src/app\` |
+| Firebase identity/readiness or theme preference | Generated \`src/app/stores/auth.store.ts\` or \`theme.store.ts\` |
+| Canonical theme control consumed by modules | Generated \`src/app/public/ThemeToggle.vue\` |
+| Any other state or reusable presentation | Owning \`src/modules/<module>\` |
+| Shell, router, global styles, or cross-capability composition | \`src/app\` |
 | Technology-neutral client contract | Flat \`src/core\` |
 | Root executable | Bootstrap of \`src/app\` only |
 
-UI modules never import one another. Compose capabilities in \`src/app\`; platform code never imports app or module code.
+UI modules may import a sibling only through a named file directly under the provider's \`public/\` directory; keep the graph acyclic. From app, modules may import only generated \`auth.store.ts\`, \`theme.store.ts\`, and \`ThemeToggle.vue\`; every other app path is private. App views and shell components consume modules only through named module \`public/\` entries; route module views directly from \`app/router.ts\`. Use \`@/\` or relative internal imports; do not add another source alias. Platform imports neither app nor modules.
 
 ## Module shape
-Under \`src/modules/<module>\`, add only needed \`api/\`, \`components/\`, \`composables/\`, \`routes/\`, \`stores/\`, \`types/\`, \`views/\`, and \`__tests__/\` directories. Do not invent alternative layer names or generate speculative CRUD. Create module files only with \`tailframe generate\`.
+Under \`src/modules/<module>\`, add only needed \`api/\`, \`components/\`, \`composables/\`, \`public/\`, \`routes/\`, \`stores/\`, \`types/\`, \`views/\`, and \`__tests__/\` directories. Public entries are named direct files, never nested directories or barrels. Do not invent alternative layer names or generate speculative CRUD. Create module and public shell files only with \`tailframe generate\`.
 
 ## API contract
 - Use the shared Axios client and singular \`POST <module>.<operation>\` calls.
@@ -519,6 +524,7 @@ Use named routes.${options.auth === "firebase" ? " Preserve Firebase authenticat
 
 ## State management
 Keep local state local. Use Pinia only for state shared across routes or unrelated components.
+Keep all product state in the owning module. The auth/theme stores and ThemeToggle are Tailframe-owned generated sources shared byte-for-byte across projects apart from the explicit theme storage key.
 
 ## UI behavior
 Reuse Vue, PrimeVue, Tailwind, loading, error, and accessibility conventions. Provide explicit loading, empty, error, and authorization states.

package/src/validate.mjs

@@ -2,6 +2,8 @@ import { validateArchitecture } from "./architecture.mjs";
 import { validateConventions } from "./conventions.mjs";
 import { isExcepted, loadExceptions } from "./exceptions.mjs";
 
+const NON_EXCEPTABLE_RULES = new Set(["U5", "U6", "U7"]);
+
 export function runValidate(root, kind) {
 	const structural = validateArchitecture(root, kind);
 	if (structural.some((error) => error.startsWith("Architecture root") || error.startsWith("Architecture kind"))) {
@@ -9,7 +11,7 @@ export function runValidate(root, kind) {
 	}
 	const exceptions = loadExceptions(root);
 	const conventions = validateConventions(root, kind)
-		.filter((violation) => !isExcepted(violation.path, exceptions))
+		.filter((violation) => NON_EXCEPTABLE_RULES.has(violation.rule) || !isExcepted(violation.path, exceptions))
 		.map((violation) => `${violation.rule}: ${violation.message}`);
 	return [...structural, ...conventions];
 }