tova 0.7.0 → 0.9.4

package/bin/tova.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env bun
 
-import { resolve, basename, dirname, join, relative } from 'path';
+import { resolve, basename, dirname, join, relative, sep, extname } from 'path';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, copyFileSync, rmSync, chmodSync, renameSync, watch as fsWatch } from 'fs';
 import { spawn } from 'child_process';
 import { createHash as _cryptoHash } from 'crypto';
+import { createRequire as _createRequire } from 'module';
 import { Lexer } from '../src/lexer/lexer.js';
 import { Parser } from '../src/parser/parser.js';
 import { Analyzer } from '../src/analyzer/analyzer.js';
@@ -14,9 +15,10 @@ import { richError, formatDiagnostics, DiagnosticFormatter, formatSummary } from
 import { getExplanation, lookupCode } from '../src/diagnostics/error-codes.js';
 import { getFullStdlib, buildSelectiveStdlib, BUILTIN_NAMES, PROPAGATE, NATIVE_INIT } from '../src/stdlib/inline.js';
 import { Formatter } from '../src/formatter/formatter.js';
-import { REACTIVITY_SOURCE, RPC_SOURCE, ROUTER_SOURCE } from '../src/runtime/embedded.js';
+import { REACTIVITY_SOURCE, RPC_SOURCE, ROUTER_SOURCE, DEVTOOLS_SOURCE, SSR_SOURCE, TESTING_SOURCE } from '../src/runtime/embedded.js';
 import '../src/runtime/string-proto.js';
 import '../src/runtime/array-proto.js';
+import { generateSecurityScorecard } from '../src/diagnostics/security-scorecard.js';
 import { resolveConfig } from '../src/config/resolve.js';
 import { writePackageJson } from '../src/config/package-json.js';
 import { addToSection, removeFromSection } from '../src/config/edit-toml.js';
@@ -52,10 +54,10 @@ Commands:
   check [dir]      Type-check .tova files without generating code
   clean            Delete .tova-out build artifacts
   dev              Start development server with live reload
-  new <name>       Create a new Tova project (--template fullstack|api|script|library|blank)
-  install          Install npm dependencies from tova.toml
-  add <pkg>        Add an npm dependency (--dev for dev dependency)
-  remove <pkg>     Remove an npm dependency
+  new <name>       Create a new Tova project (--template fullstack|spa|site|api|script|library|blank)
+  install          Install dependencies from tova.toml
+  add <pkg>        Add a dependency (npm:pkg for npm, github.com/user/repo for Tova)
+  remove <pkg>     Remove a dependency
   repl             Start interactive Tova REPL
   lsp              Start Language Server Protocol server
   fmt <file>      Format a .tova file (--check to verify only)
@@ -70,6 +72,8 @@ Commands:
   info             Show Tova version, Bun version, project config, and installed dependencies
   doctor           Check your development environment
   completions <sh> Generate shell completions (bash, zsh, fish)
+  deploy <env>     Deploy to a server (--plan, --rollback, --logs, --status)
+  env <env> <cmd>  Manage secrets (list, set KEY=value)
   explain <code>   Show detailed explanation for an error/warning code (e.g., tova explain E202)
 
 Options:
@@ -81,7 +85,9 @@ Options:
   --verbose        Show detailed output during compilation
   --quiet          Suppress non-error output
   --debug          Show verbose error output
+  --static         Pre-render routes to static HTML files (used with --production)
   --strict         Enable strict type checking
+  --strict-security Promote security warnings to errors
 `;
 
 async function main() {
@@ -100,14 +106,15 @@ async function main() {
   const command = args[0];
 
   const isStrict = args.includes('--strict');
+  const isStrictSecurity = args.includes('--strict-security');
   switch (command) {
     case 'run': {
-      const runArgs = args.filter(a => a !== '--strict');
+      const runArgs = args.filter(a => a !== '--strict' && a !== '--strict-security');
       const filePath = runArgs[1];
       const restArgs = runArgs.slice(2);
       const ddIdx = restArgs.indexOf('--');
       const scriptArgs = ddIdx !== -1 ? restArgs.slice(ddIdx + 1) : restArgs;
-      await runFile(filePath, { strict: isStrict, scriptArgs });
+      await runFile(filePath, { strict: isStrict, strictSecurity: isStrictSecurity, scriptArgs });
       break;
     }
     case 'build':
@@ -143,6 +150,74 @@ async function main() {
     case 'remove':
       await removeDep(args[1]);
       break;
+    case 'update': {
+      const updatePkg = args[1] || null;
+      const updateConfig = resolveConfig(process.cwd());
+      const updateDeps = updatePkg
+        ? { [updatePkg]: updateConfig.dependencies?.[updatePkg] || '*' }
+        : updateConfig.dependencies || {};
+
+      if (Object.keys(updateDeps).length === 0) {
+        console.log('  No Tova dependencies to update.');
+        break;
+      }
+
+      console.log('  Checking for updates...');
+      // Delete lock file to force fresh resolution
+      const lockPath = join(process.cwd(), 'tova.lock');
+      if (existsSync(lockPath)) {
+        rmSync(lockPath);
+      }
+      await installDeps();
+      break;
+    }
+    case 'cache': {
+      const subCmd = args[1] || 'list';
+      const { getCacheDir } = await import('../src/config/module-cache.js');
+      const cacheDir = getCacheDir();
+
+      if (subCmd === 'path') {
+        console.log(cacheDir);
+      } else if (subCmd === 'list') {
+        console.log(`  Cache: ${cacheDir}\n`);
+        if (existsSync(cacheDir)) {
+          try {
+            const hosts = readdirSync(cacheDir).filter(h => !h.startsWith('.'));
+            let found = false;
+            for (const host of hosts) {
+              const hostPath = join(cacheDir, host);
+              if (!statSync(hostPath).isDirectory()) continue;
+              const owners = readdirSync(hostPath);
+              for (const owner of owners) {
+                const ownerPath = join(hostPath, owner);
+                if (!statSync(ownerPath).isDirectory()) continue;
+                const repos = readdirSync(ownerPath);
+                for (const repo of repos) {
+                  const repoPath = join(ownerPath, repo);
+                  if (!statSync(repoPath).isDirectory()) continue;
+                  const versions = readdirSync(repoPath).filter(v => v.startsWith('v'));
+                  console.log(`  ${host}/${owner}/${repo}: ${versions.join(', ') || '(empty)'}`);
+                  found = true;
+                }
+              }
+            }
+            if (!found) console.log('  (empty)');
+          } catch { console.log('  (empty)'); }
+        } else {
+          console.log('  (empty)');
+        }
+      } else if (subCmd === 'clean') {
+        if (existsSync(cacheDir)) {
+          rmSync(cacheDir, { recursive: true, force: true });
+        }
+        console.log('  Cache cleared.');
+      } else {
+        console.error(`  Unknown cache subcommand: ${subCmd}`);
+        console.error('  Usage: tova cache [list|path|clean]');
+        process.exit(1);
+      }
+      break;
+    }
     case 'fmt':
       formatFile(args.slice(1));
       break;
@@ -173,6 +248,9 @@ async function main() {
     case 'migrate:status':
       await migrateStatus(args.slice(1));
       break;
+    case 'deploy':
+      await deployCommand(args.slice(1));
+      break;
     case 'explain': {
       const code = args[1];
       if (!code) {
@@ -207,10 +285,10 @@ async function main() {
       break;
     default:
       if (command.endsWith('.tova')) {
-        const directArgs = args.filter(a => a !== '--strict').slice(1);
+        const directArgs = args.filter(a => a !== '--strict' && a !== '--strict-security').slice(1);
         const ddIdx = directArgs.indexOf('--');
         const scriptArgs = ddIdx !== -1 ? directArgs.slice(ddIdx + 1) : directArgs;
-        await runFile(command, { strict: isStrict, scriptArgs });
+        await runFile(command, { strict: isStrict, strictSecurity: isStrictSecurity, scriptArgs });
       } else {
         console.error(`Unknown command: ${command}`);
         console.log(HELP);
@@ -228,7 +306,7 @@ function compileTova(source, filename, options = {}) {
   const parser = new Parser(tokens, filename);
   const ast = parser.parse();
 
-  const analyzer = new Analyzer(ast, filename, { strict: options.strict || false });
+  const analyzer = new Analyzer(ast, filename, { strict: options.strict || false, strictSecurity: options.strictSecurity || false });
   // Pre-define extra names in the analyzer scope (used by REPL for cross-line persistence)
   if (options.knownNames) {
     for (const name of options.knownNames) {
@@ -546,6 +624,22 @@ function findTovaFiles(dir) {
   return files;
 }
 
+// ─── Deploy ──────────────────────────────────────────────────
+
+async function deployCommand(args) {
+  const { parseDeployArgs } = await import('../src/deploy/deploy.js');
+  const deployArgs = parseDeployArgs(args);
+
+  if (!deployArgs.envName && !deployArgs.list) {
+    console.error(color.red('Error: deploy requires an environment name (e.g., tova deploy prod)'));
+    process.exit(1);
+  }
+
+  // For now, just parse and build — full SSH deployment is wired in integration
+  console.log(color.cyan('Deploy feature is being implemented...'));
+  console.log('Parsed args:', deployArgs);
+}
+
 // ─── Run ────────────────────────────────────────────────────
 
 async function runFile(filePath, options = {}) {
@@ -595,11 +689,12 @@ async function runFile(filePath, options = {}) {
     }
     const hasTovaImports = tovaImportPaths.length > 0;
 
-    const output = compileTova(source, filePath, { strict: options.strict });
+    const output = compileTova(source, filePath, { strict: options.strict, strictSecurity: options.strictSecurity });
 
     // Execute the generated JavaScript (with stdlib)
     const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
     const stdlib = getRunStdlib();
+    const __tova_require = _createRequire(import.meta.url);
 
     // CLI mode: execute the cli code directly
     if (output.isCli) {
@@ -608,8 +703,8 @@ async function runFile(filePath, options = {}) {
       // Override process.argv for cli dispatch
       const scriptArgs = options.scriptArgs || [];
       code = `process.argv = ["node", ${JSON.stringify(resolved)}, ...${JSON.stringify(scriptArgs)}];\n` + code;
-      const fn = new AsyncFunction('__tova_args', '__tova_filename', '__tova_dirname', code);
-      await fn(scriptArgs, resolved, dirname(resolved));
+      const fn = new AsyncFunction('__tova_args', '__tova_filename', '__tova_dirname', 'require', code);
+      await fn(scriptArgs, resolved, dirname(resolved), __tova_require);
       return;
     }
 
@@ -644,8 +739,8 @@ async function runFile(filePath, options = {}) {
     if (/\bfunction\s+main\s*\(/.test(code)) {
       code += '\nconst __tova_exit = await main(__tova_args); if (typeof __tova_exit === "number") process.exitCode = __tova_exit;\n';
     }
-    const fn = new AsyncFunction('__tova_args', '__tova_filename', '__tova_dirname', code);
-    await fn(scriptArgs, resolved, dirname(resolved));
+    const fn = new AsyncFunction('__tova_args', '__tova_filename', '__tova_dirname', 'require', code);
+    await fn(scriptArgs, resolved, dirname(resolved), __tova_require);
   } catch (err) {
     console.error(richError(source, err, filePath));
     if (process.argv.includes('--debug') || process.env.DEBUG) {
@@ -655,12 +750,217 @@ async function runFile(filePath, options = {}) {
   }
 }
 
+// ─── Import Path Fixup ──────────────────────────────────────
+
+function fixImportPaths(code, outputFilePath, outDir, srcDir) {
+  const relPath = relative(outDir, outputFilePath);
+  const depth = dirname(relPath).split(sep).filter(p => p && p !== '.').length;
+
+  // Fix runtime imports: './runtime/X.js' → correct relative path based on depth
+  if (depth > 0) {
+    const prefix = '../'.repeat(depth);
+    for (const runtimeFile of ['reactivity.js', 'rpc.js', 'router.js', 'devtools.js', 'ssr.js', 'testing.js']) {
+      code = code.split("'./runtime/" + runtimeFile + "'").join("'" + prefix + "runtime/" + runtimeFile + "'");
+      code = code.split('"./runtime/' + runtimeFile + '"').join('"' + prefix + 'runtime/' + runtimeFile + '"');
+    }
+  }
+
+  // Add .js extension to relative imports that don't have one
+  code = code.replace(
+    /from\s+(['"])(\.[^'"]+)\1/g,
+    (match, quote, path) => {
+      if (path.endsWith('.js')) return match;
+      return 'from ' + quote + path + '.js' + quote;
+    }
+  );
+
+  // Inject missing router imports
+  code = injectRouterImport(code, depth);
+
+  // Fix duplicate identifiers between reactivity and router imports (e.g. 'lazy')
+  const reactivityMatch = code.match(/^import\s+\{([^}]+)\}\s+from\s+['"][^'"]*runtime\/reactivity[^'"]*['"]/m);
+  const routerMatch = code.match(/^(import\s+\{)([^}]+)(\}\s+from\s+['"][^'"]*runtime\/router[^'"]*['"])/m);
+  if (reactivityMatch && routerMatch) {
+    const reactivityNames = new Set(reactivityMatch[1].split(',').map(s => s.trim()));
+    const routerNames = routerMatch[2].split(',').map(s => s.trim());
+    const deduped = routerNames.filter(n => !reactivityNames.has(n));
+    if (deduped.length < routerNames.length) {
+      if (deduped.length === 0) {
+        // Remove the entire router import line if nothing left
+        code = code.replace(/^import\s+\{[^}]*\}\s+from\s+['"][^'"]*runtime\/router[^'"]*['"];?\s*\n?/m, '');
+      } else {
+        code = code.replace(routerMatch[0], routerMatch[1] + ' ' + deduped.join(', ') + ' ' + routerMatch[3]);
+      }
+    }
+  }
+
+  // Fix CodeBlock/code prop template literal interpolation: the compiler treats {identifier}
+  // inside string attributes as interpolation, generating `${identifier}` in template literals.
+  // For code example strings, these should be literal braces. Revert them.
+  code = code.replace(/code:\s*`([\s\S]*?)`/g, (match, content) => {
+    if (!content.includes('${')) return match;
+    const fixed = content.replace(/\$\{(\w+)\}/g, '{ $1 }');
+    // Convert template literal to regular string with escaped quotes and newlines
+    return 'code: "' + fixed.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n') + '"';
+  });
+
+  // File-based routing: inject routes if src/pages/ exists and no manual routes defined
+  if (srcDir && !(/\b(defineRoutes|createRouter)\s*\(/.test(code))) {
+    const fileRoutes = generateFileBasedRoutes(srcDir);
+    if (fileRoutes) {
+      // Convert Tova-style imports to JS imports with .js extensions
+      const jsRoutes = fileRoutes
+        .replace(/from\s+"([^"]+)"/g, (m, p) => 'from "' + p + '.js"');
+      // Inject before the last closing function or at the end
+      code = code + '\n// ── File-Based Routes (auto-generated from src/pages/) ──\n' + jsRoutes + '\n';
+    }
+  }
+
+  return code;
+}
+
+function injectRouterImport(code, depth) {
+  const routerFuncs = ['createRouter', 'lazy', 'resetRouter', 'getPath', 'navigate',
+                       'getCurrentRoute', 'getParams', 'getQuery', 'getMeta', 'getRouter',
+                       'defineRoutes', 'onRouteChange', 'Router', 'Link', 'Outlet', 'Redirect',
+                       'beforeNavigate', 'afterNavigate'];
+  const hasRouterImport = /runtime\/router/.test(code);
+  if (hasRouterImport) return code;
+
+  // Strip import lines before checking for router function usage to avoid false positives
+  const codeWithoutImports = code.replace(/^import\s+\{[^}]*\}\s+from\s+['"][^'"]*['"];?\s*$/gm, '');
+  const usedFuncs = routerFuncs.filter(fn => new RegExp('\\b' + fn + '\\b').test(codeWithoutImports));
+  if (usedFuncs.length === 0) return code;
+
+  const routerPath = depth === 0
+    ? './runtime/router.js'
+    : '../'.repeat(depth) + 'runtime/router.js';
+
+  const importLine = "import { " + usedFuncs.join(', ') + " } from '" + routerPath + "';\n";
+
+  // Insert after first import line, or at the start
+  const firstImportEnd = code.indexOf(';\n');
+  if (firstImportEnd !== -1 && code.trimStart().startsWith('import ')) {
+    return code.slice(0, firstImportEnd + 2) + importLine + code.slice(firstImportEnd + 2);
+  }
+  return importLine + code;
+}
+
+// ─── File-Based Routing ──────────────────────────────────────
+
+function generateFileBasedRoutes(srcDir) {
+  const pagesDir = join(srcDir, 'pages');
+  if (!existsSync(pagesDir) || !statSync(pagesDir).isDirectory()) return null;
+
+  // Scan pages directory recursively
+  const routes = [];
+  let hasLayout = false;
+  let has404 = false;
+
+  function scanDir(dir, prefix) {
+    const entries = readdirSync(dir).sort();
+    for (const entry of entries) {
+      const fullPath = join(dir, entry);
+      const stat = statSync(fullPath);
+
+      if (stat.isDirectory()) {
+        // Check for layout in subdirectory
+        const subLayout = join(fullPath, '_layout.tova');
+        if (existsSync(subLayout)) {
+          const childRoutes = [];
+          scanDir(fullPath, prefix + '/' + entry);
+          // Layout routes handled via nested children
+          continue;
+        }
+        scanDir(fullPath, prefix + '/' + entry);
+        continue;
+      }
+
+      if (!entry.endsWith('.tova')) continue;
+      const name = entry.replace('.tova', '');
+
+      // Skip layout files (handled separately)
+      if (name === '_layout') {
+        if (prefix === '') hasLayout = true;
+        continue;
+      }
+
+      // 404 page
+      if (name === '404') {
+        has404 = true;
+        const relImport = './pages' + (prefix ? prefix + '/' : '/') + name;
+        routes.push({ path: '404', importPath: relImport, componentName: 'NotFoundPage__auto' });
+        continue;
+      }
+
+      // Determine route path
+      let routePath;
+      if (name === 'index') {
+        routePath = prefix || '/';
+      } else if (name.startsWith('[...') && name.endsWith(']')) {
+        // Catch-all: [...slug] → *
+        routePath = prefix + '/*';
+      } else if (name.startsWith('[[') && name.endsWith(']]')) {
+        // Optional param: [[id]] → /:id?
+        const paramName = name.slice(2, -2);
+        routePath = prefix + '/:' + paramName + '?';
+      } else if (name.startsWith('[') && name.endsWith(']')) {
+        // Dynamic param: [id] → /:id
+        const paramName = name.slice(1, -1);
+        routePath = prefix + '/:' + paramName;
+      } else {
+        routePath = prefix + '/' + name;
+      }
+
+      const relImport = './pages' + (prefix ? prefix + '/' : '/') + name;
+      // Generate safe component name from path
+      const safeName = name
+        .replace(/\[\.\.\.(\w+)\]/, 'CatchAll_$1')
+        .replace(/\[\[(\w+)\]\]/, 'Optional_$1')
+        .replace(/\[(\w+)\]/, 'Param_$1')
+        .replace(/[^a-zA-Z0-9_]/g, '_');
+      const componentName = '__Page_' + (prefix ? prefix.slice(1).replace(/\//g, '_') + '_' : '') + safeName;
+
+      routes.push({ path: routePath, importPath: relImport, componentName });
+    }
+  }
+
+  scanDir(pagesDir, '');
+
+  if (routes.length === 0) return null;
+
+  // Generate import statements and route map
+  const imports = routes.map(r =>
+    'import { Page as ' + r.componentName + ' } from "' + r.importPath + '"'
+  ).join('\n');
+
+  const routeEntries = routes.map(r =>
+    '    "' + r.path + '": ' + r.componentName + ','
+  ).join('\n');
+
+  // Check for root layout
+  let layoutImport = '';
+  let layoutWrap = '';
+  if (hasLayout) {
+    layoutImport = '\nimport { Layout as __RootLayout } from "./pages/_layout"';
+    // With layout, wrap routes as children
+    // For now, just generate flat routes — layout support can be added later
+  }
+
+  const generated = imports + layoutImport + '\n\n' +
+    'defineRoutes({\n' + routeEntries + '\n})';
+
+  return generated;
+}
+
 // ─── Build ──────────────────────────────────────────────────
 
 async function buildProject(args) {
   const config = resolveConfig(process.cwd());
   const isProduction = args.includes('--production');
+  const isStatic = args.includes('--static');
   const buildStrict = args.includes('--strict');
+  const buildStrictSecurity = args.includes('--strict-security');
   const isVerbose = args.includes('--verbose');
   const isQuiet = args.includes('--quiet');
   const isWatch = args.includes('--watch');
@@ -678,7 +978,7 @@ async function buildProject(args) {
 
   // Production build uses a separate optimized pipeline
   if (isProduction) {
-    return await productionBuild(srcDir, outDir);
+    return await productionBuild(srcDir, outDir, isStatic);
   }
 
   const tovaFiles = findFiles(srcDir, '.tova');
@@ -695,6 +995,9 @@ async function buildProject(args) {
   writeFileSync(join(runtimeDest, 'reactivity.js'), REACTIVITY_SOURCE);
   writeFileSync(join(runtimeDest, 'rpc.js'), RPC_SOURCE);
   writeFileSync(join(runtimeDest, 'router.js'), ROUTER_SOURCE);
+  writeFileSync(join(runtimeDest, 'devtools.js'), DEVTOOLS_SOURCE);
+  writeFileSync(join(runtimeDest, 'ssr.js'), SSR_SOURCE);
+  writeFileSync(join(runtimeDest, 'testing.js'), TESTING_SOURCE);
 
   if (!isQuiet) console.log(`\n  Building ${tovaFiles.length} file(s)...\n`);
 
@@ -710,6 +1013,7 @@ async function buildProject(args) {
 
   // Group files by directory for multi-file merging
   const dirGroups = groupFilesByDirectory(tovaFiles);
+  let _scorecardData = null; // Collect security info for scorecard
 
   for (const [dir, files] of dirGroups) {
     const dirName = basename(dir) === '.' ? 'app' : basename(dir);
@@ -746,10 +1050,13 @@ async function buildProject(args) {
         }
       }
 
-      const result = mergeDirectory(dir, srcDir, { strict: buildStrict });
+      const result = mergeDirectory(dir, srcDir, { strict: buildStrict, strictSecurity: buildStrictSecurity });
       if (!result) continue;
 
-      const { output, single } = result;
+      const { output, single, warnings: buildWarnings, securityConfig, hasServer, hasEdge } = result;
+      if ((hasServer || hasEdge) && !_scorecardData) {
+        _scorecardData = { securityConfig, warnings: buildWarnings || [], hasServer, hasEdge };
+      }
       // Preserve relative directory structure in output (e.g., src/lib/math.tova → lib/math.js)
       const outBaseName = single
         ? relative(srcDir, files[0]).replace(/\.tova$/, '').replace(/\\/g, '/')
@@ -803,7 +1110,7 @@ async function buildProject(args) {
       else if (output.isModule) {
         if (output.shared && output.shared.trim()) {
           const modulePath = join(outDir, `${outBaseName}.js`);
-          writeFileSync(modulePath, generateSourceMap(output.shared, modulePath));
+          writeFileSync(modulePath, fixImportPaths(generateSourceMap(output.shared, modulePath), modulePath, outDir));
           if (!isQuiet) console.log(`  ✓ ${relLabel} → ${relative('.', modulePath)}${timing}`);
         }
         // Update incremental build cache
@@ -822,28 +1129,30 @@ async function buildProject(args) {
         // Write shared
         if (output.shared && output.shared.trim()) {
           const sharedPath = join(outDir, `${outBaseName}.shared.js`);
-          writeFileSync(sharedPath, generateSourceMap(output.shared, sharedPath));
+          writeFileSync(sharedPath, fixImportPaths(generateSourceMap(output.shared, sharedPath), sharedPath, outDir));
           if (!isQuiet) console.log(`  ✓ ${relLabel} → ${relative('.', sharedPath)}${timing}`);
         }
 
         // Write default server
         if (output.server) {
           const serverPath = join(outDir, `${outBaseName}.server.js`);
-          writeFileSync(serverPath, generateSourceMap(output.server, serverPath));
+          writeFileSync(serverPath, fixImportPaths(generateSourceMap(output.server, serverPath), serverPath, outDir));
           if (!isQuiet) console.log(`  ✓ ${relLabel} → ${relative('.', serverPath)}${timing}`);
         }
 
         // Write default browser
         if (output.browser) {
           const browserPath = join(outDir, `${outBaseName}.browser.js`);
-          writeFileSync(browserPath, generateSourceMap(output.browser, browserPath));
+          // Pass srcDir for file-based routing injection (only for root-level browser output)
+          const browserSrcDir = (relDir === '.' || relDir === '') ? srcDir : undefined;
+          writeFileSync(browserPath, fixImportPaths(generateSourceMap(output.browser, browserPath), browserPath, outDir, browserSrcDir));
           if (!isQuiet) console.log(`  ✓ ${relLabel} → ${relative('.', browserPath)}${timing}`);
         }
 
         // Write default edge
         if (output.edge) {
           const edgePath = join(outDir, `${outBaseName}.edge.js`);
-          writeFileSync(edgePath, generateSourceMap(output.edge, edgePath));
+          writeFileSync(edgePath, fixImportPaths(generateSourceMap(output.edge, edgePath), edgePath, outDir));
           if (!isQuiet) console.log(`  ✓ ${relLabel} → ${relative('.', edgePath)} [edge]${timing}`);
         }
 
@@ -852,7 +1161,7 @@ async function buildProject(args) {
           for (const [name, code] of Object.entries(output.servers)) {
             if (name === 'default') continue;
             const path = join(outDir, `${outBaseName}.server.${name}.js`);
-            writeFileSync(path, code);
+            writeFileSync(path, fixImportPaths(code, path, outDir));
             if (!isQuiet) console.log(`  ✓ ${relLabel} → ${relative('.', path)} [server:${name}]${timing}`);
           }
         }
@@ -862,7 +1171,7 @@ async function buildProject(args) {
           for (const [name, code] of Object.entries(output.edges)) {
             if (name === 'default') continue;
             const path = join(outDir, `${outBaseName}.edge.${name}.js`);
-            writeFileSync(path, code);
+            writeFileSync(path, fixImportPaths(code, path, outDir));
             if (!isQuiet) console.log(`  ✓ ${relLabel} → ${relative('.', path)} [edge:${name}]${timing}`);
           }
         }
@@ -872,7 +1181,7 @@ async function buildProject(args) {
           for (const [name, code] of Object.entries(output.browsers)) {
             if (name === 'default') continue;
             const path = join(outDir, `${outBaseName}.browser.${name}.js`);
-            writeFileSync(path, code);
+            writeFileSync(path, fixImportPaths(code, path, outDir));
             if (!isQuiet) console.log(`  ✓ ${relLabel} → ${relative('.', path)} [browser:${name}]${timing}`);
           }
         }
@@ -912,6 +1221,18 @@ async function buildProject(args) {
     const cachedStr = skippedCount > 0 ? ` (${skippedCount} cached)` : '';
     console.log(`\n  Build complete. ${dirCount - errorCount}/${dirCount} directory group(s) succeeded${cachedStr}${timingStr}.\n`);
   }
+
+  // Security scorecard (shown with --verbose or --strict-security, suppressed with --quiet)
+  if ((isVerbose || buildStrictSecurity) && !isQuiet && _scorecardData) {
+    const scorecard = generateSecurityScorecard(
+      _scorecardData.securityConfig,
+      _scorecardData.warnings,
+      _scorecardData.hasServer,
+      _scorecardData.hasEdge
+    );
+    if (scorecard) console.log(scorecard.format());
+  }
+
   if (errorCount > 0) process.exit(1);
 
   // Watch mode for build command
@@ -938,6 +1259,7 @@ async function buildProject(args) {
 
 async function checkProject(args) {
   const checkStrict = args.includes('--strict');
+  const checkStrictSecurity = args.includes('--strict-security');
   const isVerbose = args.includes('--verbose');
   const isQuiet = args.includes('--quiet');
 
@@ -980,6 +1302,8 @@ async function checkProject(args) {
   let totalErrors = 0;
   let totalWarnings = 0;
   const seenCodes = new Set();
+  let _checkScorecardData = null;
+  const _allCheckWarnings = [];
 
   for (const file of tovaFiles) {
     const relPath = relative(srcDir, file);
@@ -990,13 +1314,39 @@ async function checkProject(args) {
       const tokens = lexer.tokenize();
       const parser = new Parser(tokens, file);
       const ast = parser.parse();
-      const analyzer = new Analyzer(ast, file, { strict: checkStrict, tolerant: true });
+      const analyzer = new Analyzer(ast, file, { strict: checkStrict, strictSecurity: checkStrictSecurity, tolerant: true });
       const result = analyzer.analyze();
 
       const errors = result.errors || [];
       const warnings = result.warnings || [];
       totalErrors += errors.length;
       totalWarnings += warnings.length;
+      _allCheckWarnings.push(...warnings);
+
+      // Collect security info for scorecard
+      if (!_checkScorecardData) {
+        const hasServer = ast.body.some(n => n.type === 'ServerBlock');
+        const hasEdge = ast.body.some(n => n.type === 'EdgeBlock');
+        if (hasServer || hasEdge) {
+          const secNode = ast.body.find(n => n.type === 'SecurityBlock');
+          let secCfg = null;
+          if (secNode) {
+            secCfg = {};
+            for (const child of secNode.body || []) {
+              if (child.type === 'AuthDeclaration') secCfg.auth = { authType: child.authType || 'jwt', storage: child.config?.storage?.value };
+              else if (child.type === 'CsrfDeclaration') secCfg.csrf = { enabled: child.config?.enabled?.value !== false };
+              else if (child.type === 'RateLimitDeclaration') secCfg.rateLimit = { max: child.config?.max?.value };
+              else if (child.type === 'CspDeclaration') secCfg.csp = { default_src: true };
+              else if (child.type === 'CorsDeclaration') {
+                const origins = child.config?.origins;
+                secCfg.cors = { origins: origins ? (origins.elements || []).map(e => e.value) : [] };
+              }
+              else if (child.type === 'AuditDeclaration') secCfg.audit = { events: ['auth'] };
+            }
+          }
+          _checkScorecardData = { securityConfig: secCfg, hasServer, hasEdge };
+        }
+      }
 
       if (errors.length > 0 || warnings.length > 0) {
         const formatter = new DiagnosticFormatter(source, file);
@@ -1025,6 +1375,17 @@ async function checkProject(args) {
     }
   }
 
+  // Security scorecard (shown with --verbose or --strict-security, suppressed with --quiet)
+  if ((isVerbose || checkStrictSecurity) && !isQuiet && _checkScorecardData) {
+    const scorecard = generateSecurityScorecard(
+      _checkScorecardData.securityConfig,
+      _allCheckWarnings,
+      _checkScorecardData.hasServer,
+      _checkScorecardData.hasEdge
+    );
+    if (scorecard) console.log(scorecard.format());
+  }
+
   if (!isQuiet) {
     console.log(`\n  ${tovaFiles.length} file${tovaFiles.length === 1 ? '' : 's'} checked, ${formatSummary(totalErrors, totalWarnings)}`);
     // Show explain hint for encountered error codes
@@ -1061,6 +1422,7 @@ async function devServer(args) {
   const explicitPort = args.find((_, i, a) => a[i - 1] === '--port');
   const basePort = parseInt(explicitPort || config.dev.port || '3000');
   const buildStrict = args.includes('--strict');
+  const buildStrictSecurity = args.includes('--strict-security');
 
   const tovaFiles = findFiles(srcDir, '.tova');
   if (tovaFiles.length === 0) {
@@ -1104,6 +1466,9 @@ async function devServer(args) {
   writeFileSync(join(runtimeDest, 'reactivity.js'), REACTIVITY_SOURCE);
   writeFileSync(join(runtimeDest, 'rpc.js'), RPC_SOURCE);
   writeFileSync(join(runtimeDest, 'router.js'), ROUTER_SOURCE);
+  writeFileSync(join(runtimeDest, 'devtools.js'), DEVTOOLS_SOURCE);
+  writeFileSync(join(runtimeDest, 'ssr.js'), SSR_SOURCE);
+  writeFileSync(join(runtimeDest, 'testing.js'), TESTING_SOURCE);
 
   const serverFiles = [];
   let hasClient = false;
@@ -1119,25 +1484,40 @@ async function devServer(args) {
 
   // Pass 1: Merge each directory, write shared/client outputs, collect clientHTML
   const dirResults = [];
+  const allSharedParts = [];
+  let browserCode = '';
   for (const [dir, files] of dirGroups) {
     const dirName = basename(dir) === '.' ? 'app' : basename(dir);
     try {
-      const result = mergeDirectory(dir, srcDir, { strict: buildStrict });
+      const result = mergeDirectory(dir, srcDir, { strict: buildStrict, strictSecurity: buildStrictSecurity });
       if (!result) continue;
 
       const { output, single } = result;
-      const outBaseName = single ? basename(files[0], '.tova') : dirName;
+      const relDir = relative(srcDir, dir);
+      const outBaseName = single
+        ? relative(srcDir, files[0]).replace(/\.tova$/, '').replace(/\\/g, '/')
+        : (relDir === '.' ? dirName : relDir + '/' + dirName);
       dirResults.push({ dir, output, outBaseName, single, files });
 
+      // Ensure output subdirectory exists for nested paths
+      const outSubDir = dirname(join(outDir, outBaseName));
+      if (outSubDir !== outDir) mkdirSync(outSubDir, { recursive: true });
+
       if (output.shared && output.shared.trim()) {
-        writeFileSync(join(outDir, `${outBaseName}.shared.js`), output.shared);
+        // Use .js (not .shared.js) for module files to match build output
+        const ext = (output.isModule || (!output.browser && !output.server)) ? '.js' : '.shared.js';
+        const sp = join(outDir, `${outBaseName}${ext}`);
+        const fixedShared = fixImportPaths(output.shared, sp, outDir);
+        writeFileSync(sp, fixedShared);
+        allSharedParts.push(fixedShared);
       }
 
       if (output.browser) {
         const p = join(outDir, `${outBaseName}.browser.js`);
-        writeFileSync(p, output.browser);
-        clientHTML = await generateDevHTML(output.browser, srcDir, actualReloadPort);
-        writeFileSync(join(outDir, 'index.html'), clientHTML);
+        const browserSrcDir = (relative(srcDir, dir) === '.' || relative(srcDir, dir) === '') ? srcDir : undefined;
+        const fixedBrowser = fixImportPaths(output.browser, p, outDir, browserSrcDir);
+        writeFileSync(p, fixedBrowser);
+        browserCode = fixedBrowser;
         hasClient = true;
       }
     } catch (err) {
@@ -1145,6 +1525,16 @@ async function devServer(args) {
     }
   }
 
+  // Generate dev HTML with all shared code prepended to browser code
+  // Skip if the project has its own index.html (uses import maps or custom module loading)
+  const hasCustomIndex = existsSync(join(process.cwd(), 'index.html'));
+  if (hasClient && !hasCustomIndex) {
+    const allSharedCode = allSharedParts.join('\n').replace(/^export /gm, '');
+    const fullClientCode = allSharedCode ? allSharedCode + '\n' + browserCode : browserCode;
+    clientHTML = await generateDevHTML(fullClientCode, srcDir, actualReloadPort);
+    writeFileSync(join(outDir, 'index.html'), clientHTML);
+  }
+
   // Pass 2: Write server files with clientHTML injected
   for (const { output, outBaseName } of dirResults) {
     if (output.server) {
@@ -1216,6 +1606,75 @@ async function devServer(args) {
     console.log(`  ✓ Client: ${relative('.', outDir)}/index.html`);
   }
 
+  // If no server blocks were found but we have a client, start a static file server
+  if (processes.length === 0 && hasClient) {
+    const mimeTypes = {
+      '.html': 'text/html',
+      '.js': 'application/javascript',
+      '.mjs': 'application/javascript',
+      '.css': 'text/css',
+      '.json': 'application/json',
+      '.png': 'image/png',
+      '.jpg': 'image/jpeg',
+      '.gif': 'image/gif',
+      '.svg': 'image/svg+xml',
+      '.ico': 'image/x-icon',
+      '.woff': 'font/woff',
+      '.woff2': 'font/woff2',
+      '.map': 'application/json',
+    };
+
+    const staticServer = Bun.serve({
+      port: basePort,
+      async fetch(req) {
+        const url = new URL(req.url);
+        let pathname = url.pathname;
+
+        // Try to serve the file directly from outDir, srcDir, or project root
+        const tryPaths = [
+          join(outDir, pathname),
+          join(srcDir, pathname),
+          join(process.cwd(), pathname),
+        ];
+
+        for (const filePath of tryPaths) {
+          if (existsSync(filePath) && statSync(filePath).isFile()) {
+            const ext = extname(filePath);
+            const contentType = mimeTypes[ext] || 'application/octet-stream';
+            const content = readFileSync(filePath);
+            return new Response(content, {
+              headers: {
+                'Content-Type': contentType,
+                'Cache-Control': 'no-cache',
+                'Access-Control-Allow-Origin': '*',
+              },
+            });
+          }
+        }
+
+        // SPA fallback: serve index.html for non-file routes
+        const indexPath = join(outDir, 'index.html');
+        if (existsSync(indexPath)) {
+          return new Response(readFileSync(indexPath), {
+            headers: { 'Content-Type': 'text/html', 'Cache-Control': 'no-cache' },
+          });
+        }
+
+        const rootIndex = join(process.cwd(), 'index.html');
+        if (existsSync(rootIndex)) {
+          return new Response(readFileSync(rootIndex), {
+            headers: { 'Content-Type': 'text/html', 'Cache-Control': 'no-cache' },
+          });
+        }
+
+        return new Response('Not Found', { status: 404 });
+      },
+    });
+
+    console.log(`\n  Static file server running:`);
+    console.log(`    → http://localhost:${basePort}`);
+  }
+
   function handleReloadFetch(req) {
       const url = new URL(req.url);
       if (url.pathname === '/__tova_reload') {
@@ -1269,22 +1728,39 @@ async function devServer(args) {
       // Merge each directory group, collect client HTML
       const rebuildDirGroups = groupFilesByDirectory(currentFiles);
       let rebuildClientHTML = '';
+      const rebuildSharedParts = [];
+      let rebuildBrowserCode = '';
+      let rebuildHasClient = false;
 
       for (const [dir, files] of rebuildDirGroups) {
         const dirName = basename(dir) === '.' ? 'app' : basename(dir);
-        const result = mergeDirectory(dir, srcDir, { strict: buildStrict });
+        const result = mergeDirectory(dir, srcDir, { strict: buildStrict, strictSecurity: buildStrictSecurity });
         if (!result) continue;
 
         const { output, single } = result;
-        const outBaseName = single ? basename(files[0], '.tova') : dirName;
+        const relDir = relative(srcDir, dir);
+        const outBaseName = single
+          ? relative(srcDir, files[0]).replace(/\.tova$/, '').replace(/\\/g, '/')
+          : (relDir === '.' ? dirName : relDir + '/' + dirName);
+
+        // Ensure output subdirectory exists for nested paths
+        const outSubDir = dirname(join(outDir, outBaseName));
+        if (outSubDir !== outDir) mkdirSync(outSubDir, { recursive: true });
 
         if (output.shared && output.shared.trim()) {
-          writeFileSync(join(outDir, `${outBaseName}.shared.js`), output.shared);
+          const ext = (output.isModule || (!output.browser && !output.server)) ? '.js' : '.shared.js';
+          const sp = join(outDir, `${outBaseName}${ext}`);
+          const fixedShared = fixImportPaths(output.shared, sp, outDir);
+          writeFileSync(sp, fixedShared);
+          rebuildSharedParts.push(fixedShared);
         }
         if (output.browser) {
-          writeFileSync(join(outDir, `${outBaseName}.browser.js`), output.browser);
-          rebuildClientHTML = await generateDevHTML(output.browser, srcDir, actualReloadPort);
-          writeFileSync(join(outDir, 'index.html'), rebuildClientHTML);
+          const p = join(outDir, `${outBaseName}.browser.js`);
+          const browserSrcDir = (relative(srcDir, dir) === '.' || relative(srcDir, dir) === '') ? srcDir : undefined;
+          const fixedBrowser = fixImportPaths(output.browser, p, outDir, browserSrcDir);
+          writeFileSync(p, fixedBrowser);
+          rebuildBrowserCode = fixedBrowser;
+          rebuildHasClient = true;
         }
         if (output.server) {
           let serverCode = output.server;
@@ -1292,7 +1768,7 @@ async function devServer(args) {
             serverCode = `const __clientHTML = ${JSON.stringify(rebuildClientHTML)};\n` + serverCode;
           }
           const p = join(outDir, `${outBaseName}.server.js`);
-          writeFileSync(p, serverCode);
+          writeFileSync(p, fixImportPaths(serverCode, p, outDir));
           newServerFiles.push(p);
         }
         if (output.multiBlock && output.servers) {
@@ -1304,6 +1780,14 @@ async function devServer(args) {
           }
         }
       }
+
+      // Generate dev HTML with all shared code prepended to browser code
+      if (rebuildHasClient) {
+        const rebuildAllShared = rebuildSharedParts.join('\n').replace(/^export /gm, '');
+        const rebuildFullClient = rebuildAllShared ? rebuildAllShared + '\n' + rebuildBrowserCode : rebuildBrowserCode;
+        rebuildClientHTML = await generateDevHTML(rebuildFullClient, srcDir, actualReloadPort);
+        writeFileSync(join(outDir, 'index.html'), rebuildClientHTML);
+      }
     } catch (err) {
       console.error(`  ✗ Rebuild failed: ${err.message}`);
       return; // Keep old processes running
@@ -1421,6 +1905,10 @@ ${bundled}
   const inlineReactivity = REACTIVITY_SOURCE.replace(/^export /gm, '');
   const inlineRpc = RPC_SOURCE.replace(/^export /gm, '');
 
+  // Detect if client code uses routing (defineRoutes, Router, getPath, navigate, etc.)
+  const usesRouter = /\b(createRouter|lazy|resetRouter|defineRoutes|Router|getPath|getQuery|getParams|getCurrentRoute|getMeta|getRouter|navigate|onRouteChange|beforeNavigate|afterNavigate|Outlet|Link|Redirect)\b/.test(clientCode);
+  const inlineRouter = usesRouter ? ROUTER_SOURCE.replace(/^export /gm, '').replace(/^\s*import\s+(?:\{[^}]*\}|[\w$]+|\*\s+as\s+[\w$]+)\s+from\s+['"][^'"]+['"];?\s*$/gm, '') : '';
+
   // Strip all import lines from client code (we inline the runtime instead)
   const inlineClient = clientCode
     .replace(/^\s*import\s+(?:\{[^}]*\}|[\w$]+|\*\s+as\s+[\w$]+)\s+from\s+['"][^'"]+['"];?\s*$/gm, '')
@@ -1471,6 +1959,8 @@ ${inlineReactivity}
 // ── Tova Runtime: RPC ──
 ${inlineRpc}
 
+${usesRouter ? '// ── Tova Runtime: Router ──\n' + inlineRouter : ''}
+
 // ── App ──
 ${inlineClient}
   </script>${liveReloadScript}
@@ -1485,11 +1975,12 @@ ${inlineClient}
 const PROJECT_TEMPLATES = {
   fullstack: {
     label: 'Full-stack app',
-    description: 'server + client + shared blocks',
+    description: 'server + browser + shared blocks',
     tomlDescription: 'A full-stack Tova application',
     entry: 'src',
     file: 'src/app.tova',
     content: name => `// ${name} — Built with Tova
+// Full-stack app: server RPC + client-side routing
 
 shared {
   type Message {
@@ -1506,7 +1997,7 @@ server {
   route GET "/api/message" => get_message
 }
 
-client {
+browser {
   state message = ""
   state timestamp = ""
   state refreshing = false
@@ -1525,6 +2016,23 @@ client {
     refreshing = false
   }
 
+  // ─── Navigation ─────────────────────────────────────────
+  component NavBar {
+    <nav class="border-b border-gray-100 bg-white/80 backdrop-blur-sm sticky top-0 z-10">
+      <div class="max-w-5xl mx-auto px-6 py-4 flex items-center justify-between">
+        <Link href="/" class="flex items-center gap-2 no-underline">
+          <div class="w-8 h-8 bg-gradient-to-br from-indigo-500 to-purple-600 rounded-lg"></div>
+          <span class="font-bold text-gray-900 text-lg">"${name}"</span>
+        </Link>
+        <div class="flex items-center gap-6">
+          <Link href="/" exactActiveClass="text-indigo-600 font-semibold" class="text-sm font-medium transition-colors text-gray-500 hover:text-gray-900 no-underline">"Home"</Link>
+          <Link href="/about" activeClass="text-indigo-600 font-semibold" class="text-sm font-medium transition-colors text-gray-500 hover:text-gray-900 no-underline">"About"</Link>
+        </div>
+      </div>
+    </nav>
+  }
+
+  // ─── Pages ──────────────────────────────────────────────
   component FeatureCard(icon, title, description) {
     <div class="group relative bg-white rounded-2xl p-6 shadow-sm border border-gray-100 hover:shadow-lg hover:border-indigo-100 transition-all duration-300">
       <div class="w-10 h-10 bg-indigo-50 rounded-xl flex items-center justify-center text-lg mb-4 group-hover:bg-indigo-100 transition-colors">
@@ -1535,72 +2043,416 @@ client {
     </div>
   }
 
+  component HomePage {
+    <main class="max-w-5xl mx-auto px-6">
+      <div class="py-20 text-center">
+        <div class="inline-flex items-center gap-2 bg-indigo-50 text-indigo-700 text-sm font-medium px-4 py-1.5 rounded-full mb-6">
+          <span class="w-1.5 h-1.5 bg-indigo-500 rounded-full"></span>
+          "Powered by Tova"
+        </div>
+        <h1 class="text-5xl font-bold text-gray-900 tracking-tight mb-4">"Welcome to " <span class="bg-gradient-to-r from-indigo-600 to-purple-600 bg-clip-text text-transparent">"${name}"</span></h1>
+        <p class="text-xl text-gray-500 max-w-2xl mx-auto mb-10">"A modern full-stack app. Edit " <code class="text-sm bg-gray-100 text-indigo-600 px-2 py-1 rounded-md font-mono">"src/app.tova"</code> " to get started."</p>
+
+        <div class="inline-flex items-center gap-3 bg-white border border-gray-200 rounded-2xl p-2 shadow-sm">
+          <div class="bg-gradient-to-r from-indigo-500 to-purple-500 text-white px-5 py-2.5 rounded-xl font-medium">
+            "{message}"
+          </div>
+          <button
+            on:click={handle_refresh}
+            class="px-4 py-2.5 text-gray-500 hover:text-indigo-600 hover:bg-indigo-50 rounded-xl transition-all font-medium text-sm"
+          >
+            if refreshing {
+              "..."
+            } else {
+              "Refresh"
+            }
+          </button>
+        </div>
+        if timestamp != "" {
+          <p class="text-xs text-gray-400 mt-3">"Last fetched at " "{timestamp}"</p>
+        }
+      </div>
+
+      <div class="grid grid-cols-1 md:grid-cols-3 gap-5 pb-20">
+        <FeatureCard
+          icon="\u2699"
+          title="Full-Stack"
+          description="Server and client in one file. Shared types, RPC calls, and reactive UI — all type-safe."
+        />
+        <FeatureCard
+          icon="\u26A1"
+          title="Fast Refresh"
+          description="Edit your code and see changes instantly. The dev server recompiles on save."
+        />
+        <FeatureCard
+          icon="\uD83C\uDFA8"
+          title="Tailwind Built-in"
+          description="Style with utility classes out of the box. No config or build step needed."
+        />
+      </div>
+    </main>
+  }
+
+  component AboutPage {
+    <main class="max-w-5xl mx-auto px-6 py-12">
+      <h2 class="text-3xl font-bold text-gray-900 mb-6">"About"</h2>
+      <div class="bg-white rounded-xl border border-gray-200 p-8 space-y-4">
+        <p class="text-gray-600 leading-relaxed">"${name} is a full-stack application built with Tova — a modern language that compiles to JavaScript."</p>
+        <p class="text-gray-600 leading-relaxed">"It uses shared types between server and browser, server-side RPC, and client-side routing."</p>
+      </div>
+      <div class="mt-8">
+        <Link href="/" class="text-indigo-600 hover:text-indigo-700 font-medium no-underline">"\u2190 Back to home"</Link>
+      </div>
+    </main>
+  }
+
+  component NotFoundPage {
+    <div class="max-w-5xl mx-auto px-6 py-16 text-center">
+      <h1 class="text-6xl font-bold text-gray-200 mb-4">"404"</h1>
+      <p class="text-lg text-gray-500 mb-6">"Page not found"</p>
+      <Link href="/" class="text-indigo-600 hover:text-indigo-700 font-medium no-underline">"Go home"</Link>
+    </div>
+  }
+
+  // ─── Router setup ─────────────────────────────────────────
+  createRouter({
+    routes: {
+      "/": HomePage,
+      "/about": { component: AboutPage, meta: { title: "About" } },
+      "404": NotFoundPage,
+    },
+    scroll: "auto",
+  })
+
   component App {
     <div class="min-h-screen bg-gradient-to-br from-slate-50 via-white to-indigo-50">
-      <nav class="border-b border-gray-100 bg-white/80 backdrop-blur-sm sticky top-0 z-10">
-        <div class="max-w-5xl mx-auto px-6 py-4 flex items-center justify-between">
-          <div class="flex items-center gap-2">
-            <div class="w-8 h-8 bg-gradient-to-br from-indigo-500 to-purple-600 rounded-lg"></div>
-            <span class="font-bold text-gray-900 text-lg">"${name}"</span>
+      <NavBar />
+      <Router />
+      <div class="border-t border-gray-100 py-8 text-center">
+        <p class="text-sm text-gray-400">"Built with " <a href="https://github.com/tova-lang/tova-lang" class="text-indigo-500 hover:text-indigo-600 transition-colors">"Tova"</a></p>
+      </div>
+    </div>
+  }
+}
+`,
+    nextSteps: name => `    cd ${name}\n    tova dev`,
+  },
+  spa: {
+    label: 'Single-page app',
+    description: 'browser-only app with routing',
+    tomlDescription: 'A Tova single-page application',
+    entry: 'src',
+    file: 'src/app.tova',
+    content: name => `// ${name} — Built with Tova
+// Demonstrates: createRouter, Link, Router, Outlet, navigate(),
+// dynamic :param routes, nested routes, route meta, 404 handling
+
+browser {
+  // ─── Navigation bar with active link highlighting ─────────
+  component NavBar {
+    <nav class="bg-white border-b border-gray-100 sticky top-0 z-10">
+      <div class="max-w-5xl mx-auto px-6 py-4 flex items-center justify-between">
+        <Link href="/" class="flex items-center gap-2 no-underline">
+          <div class="w-8 h-8 bg-gradient-to-br from-indigo-500 to-purple-600 rounded-lg"></div>
+          <span class="font-bold text-gray-900 text-lg">"${name}"</span>
+        </Link>
+        <div class="flex items-center gap-6">
+          <Link href="/" exactActiveClass="text-indigo-600 font-semibold" class="text-sm font-medium transition-colors text-gray-500 hover:text-gray-900">"Home"</Link>
+          <Link href="/users" activeClass="text-indigo-600 font-semibold" class="text-sm font-medium transition-colors text-gray-500 hover:text-gray-900">"Users"</Link>
+          <Link href="/settings" activeClass="text-indigo-600 font-semibold" class="text-sm font-medium transition-colors text-gray-500 hover:text-gray-900">"Settings"</Link>
+        </div>
+      </div>
+    </nav>
+  }
+
+  // ─── Home page ────────────────────────────────────────────
+  component HomePage {
+    <div class="max-w-5xl mx-auto px-6 py-16 text-center">
+      <div class="inline-flex items-center gap-2 bg-indigo-50 text-indigo-700 text-sm font-medium px-4 py-1.5 rounded-full mb-6">
+        <span class="w-1.5 h-1.5 bg-indigo-500 rounded-full"></span>
+        "Tova Router"
+      </div>
+      <h1 class="text-4xl font-bold text-gray-900 mb-4">"Welcome to " <span class="text-indigo-600">"${name}"</span></h1>
+      <p class="text-lg text-gray-500 mb-8">"A single-page app with client-side routing. Click around to explore."</p>
+      <div class="flex items-center justify-center gap-4">
+        <Link href="/users" class="inline-block bg-indigo-600 text-white px-6 py-3 rounded-lg font-medium hover:bg-indigo-700 transition-colors no-underline">"Browse Users"</Link>
+        <Link href="/settings/profile" class="inline-block bg-white text-gray-700 border border-gray-200 px-6 py-3 rounded-lg font-medium hover:bg-gray-50 transition-colors no-underline">"Settings"</Link>
+      </div>
+    </div>
+  }
+
+  // ─── Users list (demonstrates programmatic navigation) ────
+  fn go_to_user(uid) {
+    navigate("/users/{uid}")
+  }
+
+  component UsersPage {
+    <div class="max-w-5xl mx-auto px-6 py-12">
+      <h2 class="text-2xl font-bold text-gray-900 mb-6">"Users"</h2>
+      <div class="bg-white rounded-xl border border-gray-200 divide-y divide-gray-100">
+        <div class="flex items-center justify-between p-4 hover:bg-gray-50 cursor-pointer transition-colors" on:click={fn() go_to_user("1")}>
+          <div class="flex items-center gap-3">
+            <div class="w-9 h-9 bg-indigo-100 text-indigo-600 rounded-full flex items-center justify-center font-semibold text-sm">"A"</div>
+            <div>
+              <p class="font-medium text-gray-900">"alice"</p>
+              <p class="text-xs text-gray-500">"Admin"</p>
+            </div>
+          </div>
+          <span class="text-gray-400 text-sm">"View \u2192"</span>
+        </div>
+        <div class="flex items-center justify-between p-4 hover:bg-gray-50 cursor-pointer transition-colors" on:click={fn() go_to_user("2")}>
+          <div class="flex items-center gap-3">
+            <div class="w-9 h-9 bg-green-100 text-green-600 rounded-full flex items-center justify-center font-semibold text-sm">"B"</div>
+            <div>
+              <p class="font-medium text-gray-900">"bob"</p>
+              <p class="text-xs text-gray-500">"Editor"</p>
+            </div>
           </div>
-          <div class="flex items-center gap-4">
-            <a href="https://github.com/tova-lang/tova-lang" class="text-sm text-gray-500 hover:text-gray-900 transition-colors">"Docs"</a>
-            <a href="https://github.com/tova-lang/tova-lang" class="text-sm bg-gray-900 text-white px-4 py-2 rounded-lg hover:bg-gray-800 transition-colors">"GitHub"</a>
+          <span class="text-gray-400 text-sm">"View \u2192"</span>
+        </div>
+        <div class="flex items-center justify-between p-4 hover:bg-gray-50 cursor-pointer transition-colors" on:click={fn() go_to_user("3")}>
+          <div class="flex items-center gap-3">
+            <div class="w-9 h-9 bg-purple-100 text-purple-600 rounded-full flex items-center justify-center font-semibold text-sm">"C"</div>
+            <div>
+              <p class="font-medium text-gray-900">"charlie"</p>
+              <p class="text-xs text-gray-500">"Viewer"</p>
+            </div>
           </div>
+          <span class="text-gray-400 text-sm">"View \u2192"</span>
         </div>
-      </nav>
+      </div>
+    </div>
+  }
 
-      <main class="max-w-5xl mx-auto px-6">
-        <div class="py-20 text-center">
-          <div class="inline-flex items-center gap-2 bg-indigo-50 text-indigo-700 text-sm font-medium px-4 py-1.5 rounded-full mb-6">
-            <span class="w-1.5 h-1.5 bg-indigo-500 rounded-full"></span>
-            "Powered by Tova"
+  // ─── User detail (demonstrates :id dynamic route param) ───
+  component UserPage(id) {
+    <div class="max-w-5xl mx-auto px-6 py-12">
+      <button on:click={fn() navigate("/users")} class="text-sm text-indigo-600 hover:text-indigo-700 mb-6 inline-flex items-center gap-1 cursor-pointer bg-transparent border-0">
+        "\u2190 Back to users"
+      </button>
+      <div class="bg-white rounded-xl border border-gray-200 p-8">
+        <div class="flex items-center gap-4 mb-6">
+          <div class="w-14 h-14 bg-indigo-100 text-indigo-600 rounded-full flex items-center justify-center font-bold text-xl">
+            "#{id}"
+          </div>
+          <div>
+            <h2 class="text-2xl font-bold text-gray-900">"User {id}"</h2>
+            <span class="text-sm text-gray-500">"Dynamic route parameter: " <code class="bg-gray-100 text-indigo-600 px-1.5 py-0.5 rounded text-xs">":id = {id}"</code></span>
           </div>
-          <h1 class="text-5xl font-bold text-gray-900 tracking-tight mb-4">"Welcome to " <span class="bg-gradient-to-r from-indigo-600 to-purple-600 bg-clip-text text-transparent">"${name}"</span></h1>
-          <p class="text-xl text-gray-500 max-w-2xl mx-auto mb-10">"A modern full-stack app. Edit " <code class="text-sm bg-gray-100 text-indigo-600 px-2 py-1 rounded-md font-mono">"src/app.tova"</code> " to get started."</p>
+        </div>
+        <p class="text-gray-600">"This page receives " <code class="bg-gray-100 text-indigo-600 px-1.5 py-0.5 rounded text-xs">"id"</code> " from the route " <code class="bg-gray-100 text-indigo-600 px-1.5 py-0.5 rounded text-xs">"/users/:id"</code> " pattern."</p>
+      </div>
+    </div>
+  }
 
-          <div class="inline-flex items-center gap-3 bg-white border border-gray-200 rounded-2xl p-2 shadow-sm">
-            <div class="bg-gradient-to-r from-indigo-500 to-purple-500 text-white px-5 py-2.5 rounded-xl font-medium">
-              "{message}"
-            </div>
-            <button
-              on:click={handle_refresh}
-              class="px-4 py-2.5 text-gray-500 hover:text-indigo-600 hover:bg-indigo-50 rounded-xl transition-all font-medium text-sm"
-            >
-              if refreshing {
-                "..."
-              } else {
-                "Refresh"
-              }
-            </button>
+  // ─── Settings layout with nested routes + Outlet ──────────
+  component SettingsLayout {
+    <div class="max-w-5xl mx-auto px-6 py-12">
+      <h2 class="text-2xl font-bold text-gray-900 mb-6">"Settings"</h2>
+      <div class="flex gap-8">
+        <aside class="w-48 flex-shrink-0">
+          <div class="flex flex-col gap-1">
+            <Link href="/settings/profile" activeClass="bg-indigo-50 text-indigo-700" class="block px-3 py-2 rounded-lg text-sm font-medium text-gray-600 hover:bg-gray-50 no-underline transition-colors">"Profile"</Link>
+            <Link href="/settings/account" activeClass="bg-indigo-50 text-indigo-700" class="block px-3 py-2 rounded-lg text-sm font-medium text-gray-600 hover:bg-gray-50 no-underline transition-colors">"Account"</Link>
           </div>
-          if timestamp != "" {
-            <p class="text-xs text-gray-400 mt-3">"Last fetched at " "{timestamp}"</p>
-          }
+        </aside>
+        <div class="flex-1 min-w-0">
+          <Outlet />
         </div>
+      </div>
+    </div>
+  }
 
-        <div class="grid grid-cols-1 md:grid-cols-3 gap-5 pb-20">
-          <FeatureCard
-            icon="&#9881;"
-            title="Full-Stack"
-            description="Server and client in one file. Shared types, RPC calls, and reactive UI — all type-safe."
-          />
-          <FeatureCard
-            icon="&#9889;"
-            title="Fast Refresh"
-            description="Edit your code and see changes instantly. The dev server recompiles on save."
-          />
-          <FeatureCard
-            icon="&#127912;"
-            title="Tailwind Built-in"
-            description="Style with utility classes out of the box. No config or build step needed."
-          />
+  component ProfileSettings {
+    <div class="bg-white rounded-xl border border-gray-200 p-6">
+      <h3 class="text-lg font-semibold text-gray-900 mb-4">"Profile Settings"</h3>
+      <p class="text-gray-600 mb-4">"This is a nested child route rendered via " <code class="bg-gray-100 text-indigo-600 px-1.5 py-0.5 rounded text-xs">"Outlet"</code> " inside SettingsLayout."</p>
+      <div class="space-y-4">
+        <div>
+          <label class="block text-sm font-medium text-gray-700 mb-1">"Display Name"</label>
+          <div class="w-full border border-gray-300 rounded-lg px-3 py-2 text-sm text-gray-900">"Alice"</div>
+        </div>
+        <div>
+          <label class="block text-sm font-medium text-gray-700 mb-1">"Bio"</label>
+          <div class="w-full border border-gray-300 rounded-lg px-3 py-2 text-sm text-gray-500">"Tova developer"</div>
         </div>
+      </div>
+    </div>
+  }
 
-        <div class="border-t border-gray-100 py-8 text-center">
-          <p class="text-sm text-gray-400">"Built with " <a href="https://github.com/tova-lang/tova-lang" class="text-indigo-500 hover:text-indigo-600 transition-colors">"Tova"</a></p>
+  component AccountSettings {
+    <div class="bg-white rounded-xl border border-gray-200 p-6">
+      <h3 class="text-lg font-semibold text-gray-900 mb-4">"Account Settings"</h3>
+      <p class="text-gray-600 mb-4">"Another nested child of " <code class="bg-gray-100 text-indigo-600 px-1.5 py-0.5 rounded text-xs">"/settings"</code> "."</p>
+      <div class="space-y-4">
+        <div>
+          <label class="block text-sm font-medium text-gray-700 mb-1">"Email"</label>
+          <div class="w-full border border-gray-300 rounded-lg px-3 py-2 text-sm text-gray-900">"alice@example.com"</div>
         </div>
+        <div class="pt-4 border-t border-gray-100">
+          <button class="text-sm text-red-600 hover:text-red-700 font-medium cursor-pointer bg-transparent border-0">"Delete Account"</button>
+        </div>
+      </div>
+    </div>
+  }
+
+  // ─── 404 page ─────────────────────────────────────────────
+  component NotFoundPage {
+    <div class="max-w-5xl mx-auto px-6 py-16 text-center">
+      <h1 class="text-6xl font-bold text-gray-200 mb-4">"404"</h1>
+      <p class="text-lg text-gray-500 mb-6">"Page not found"</p>
+      <Link href="/" class="text-indigo-600 hover:text-indigo-700 font-medium no-underline">"Go home"</Link>
+    </div>
+  }
+
+  // ─── Router setup ─────────────────────────────────────────
+  createRouter({
+    routes: {
+      "/": HomePage,
+      "/users": { component: UsersPage, meta: { title: "Users" } },
+      "/users/:id": { component: UserPage, meta: { title: "User Detail" } },
+      "/settings": {
+        component: SettingsLayout,
+        children: {
+          "/profile": { component: ProfileSettings, meta: { title: "Profile" } },
+          "/account": { component: AccountSettings, meta: { title: "Account" } },
+        },
+      },
+      "404": NotFoundPage,
+    },
+    scroll: "auto",
+  })
+
+  // ─── Update document title from route meta ────────────────
+  afterNavigate(fn(current) {
+    if current.meta != undefined {
+      if current.meta.title != undefined {
+        document.title = "{current.meta.title} | ${name}"
+      }
+    }
+  })
+
+  component App {
+    <div class="min-h-screen bg-gray-50">
+      <NavBar />
+      <Router />
+    </div>
+  }
+}
+`,
+    nextSteps: name => `    cd ${name}\n    tova dev`,
+  },
+  site: {
+    label: 'Static site',
+    description: 'docs or marketing site with pages',
+    tomlDescription: 'A Tova static site',
+    entry: 'src',
+    file: 'src/app.tova',
+    extraFiles: [
+      {
+        path: 'src/pages/home.tova',
+        content: name => `pub component HomePage {
+  <div class="max-w-4xl mx-auto px-6 py-16">
+    <h1 class="text-4xl font-bold text-gray-900 mb-4">"Welcome to ${name}"</h1>
+    <p class="text-lg text-gray-600 mb-8">"A static site built with Tova. Fast, simple, and easy to deploy anywhere."</p>
+    <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
+      <div class="bg-white rounded-xl border border-gray-200 p-6">
+        <h3 class="font-semibold text-gray-900 mb-2">"Fast by default"</h3>
+        <p class="text-gray-500 text-sm">"Client-side routing for smooth, instant navigation between pages."</p>
+      </div>
+      <div class="bg-white rounded-xl border border-gray-200 p-6">
+        <h3 class="font-semibold text-gray-900 mb-2">"Deploy anywhere"</h3>
+        <p class="text-gray-500 text-sm">"GitHub Pages, Netlify, Vercel, Firebase — works with any static host."</p>
+      </div>
+    </div>
+  </div>
+}
+`,
+      },
+      {
+        path: 'src/pages/docs.tova',
+        content: name => `pub component DocsPage {
+  <div class="max-w-4xl mx-auto px-6 py-12">
+    <h1 class="text-3xl font-bold text-gray-900 mb-6">"Documentation"</h1>
+    <div class="prose">
+      <h2 class="text-xl font-semibold text-gray-900 mt-8 mb-3">"Getting Started"</h2>
+      <p class="text-gray-600 mb-4">"Add your documentation content here. Each page is a Tova component with its own route."</p>
+      <h2 class="text-xl font-semibold text-gray-900 mt-8 mb-3">"Adding Pages"</h2>
+      <p class="text-gray-600 mb-4">"Create a new file in " <code class="bg-gray-100 text-indigo-600 px-1.5 py-0.5 rounded text-sm">"src/pages/"</code> " and add a route in " <code class="bg-gray-100 text-indigo-600 px-1.5 py-0.5 rounded text-sm">"src/app.tova"</code> "."</p>
+    </div>
+  </div>
+}
+`,
+      },
+      {
+        path: 'src/pages/about.tova',
+        content: name => `pub component AboutPage {
+  <div class="max-w-4xl mx-auto px-6 py-12">
+    <h1 class="text-3xl font-bold text-gray-900 mb-6">"About"</h1>
+    <p class="text-gray-600">"This site was built with Tova — a modern programming language that compiles to JavaScript."</p>
+  </div>
+}
+`,
+      },
+    ],
+    content: name => `// ${name} — Built with Tova
+import { HomePage } from "./pages/home"
+import { DocsPage } from "./pages/docs"
+import { AboutPage } from "./pages/about"
+
+browser {
+  component SiteNav {
+    <header class="bg-white border-b border-gray-100 sticky top-0 z-10">
+      <div class="max-w-5xl mx-auto px-6 py-4 flex items-center justify-between">
+        <Link href="/" class="flex items-center gap-2 no-underline">
+          <div class="w-7 h-7 bg-gradient-to-br from-indigo-500 to-purple-600 rounded-lg"></div>
+          <span class="font-bold text-gray-900">"${name}"</span>
+        </Link>
+        <nav class="flex items-center gap-6">
+          <Link href="/" exactActiveClass="text-indigo-600 font-semibold" class="text-sm font-medium transition-colors no-underline text-gray-500 hover:text-gray-900">"Home"</Link>
+          <Link href="/docs" activeClass="text-indigo-600 font-semibold" class="text-sm font-medium transition-colors no-underline text-gray-500 hover:text-gray-900">"Docs"</Link>
+          <Link href="/about" activeClass="text-indigo-600 font-semibold" class="text-sm font-medium transition-colors no-underline text-gray-500 hover:text-gray-900">"About"</Link>
+        </nav>
+      </div>
+    </header>
+  }
+
+  component NotFoundPage {
+    <div class="max-w-4xl mx-auto px-6 py-16 text-center">
+      <h1 class="text-6xl font-bold text-gray-200 mb-4">"404"</h1>
+      <p class="text-lg text-gray-500 mb-6">"Page not found"</p>
+      <Link href="/" class="text-indigo-600 hover:text-indigo-700 font-medium no-underline">"Go home"</Link>
+    </div>
+  }
+
+  createRouter({
+    routes: {
+      "/": HomePage,
+      "/docs": { component: DocsPage, meta: { title: "Documentation" } },
+      "/about": { component: AboutPage, meta: { title: "About" } },
+      "404": NotFoundPage,
+    },
+    scroll: "auto",
+  })
+
+  // Update document title from route meta
+  afterNavigate(fn(current) {
+    if current.meta != undefined {
+      if current.meta.title != undefined {
+        document.title = "{current.meta.title} | ${name}"
+      }
+    }
+  })
+
+  component App {
+    <div class="min-h-screen bg-gray-50">
+      <SiteNav />
+      <main>
+        <Router />
       </main>
+      <footer class="border-t border-gray-100 py-8 text-center">
+        <p class="text-sm text-gray-400">"Built with Tova"</p>
+      </footer>
     </div>
   }
 }
@@ -1644,12 +2496,20 @@ print("Hello, {name}!")
     tomlDescription: 'A Tova library',
     entry: 'src',
     noEntry: true,
+    isPackage: true,
     file: 'src/lib.tova',
     content: name => `// ${name} — A Tova library
+//
+// Usage:
+//   import { greet } from "github.com/yourname/${name}"
 
 pub fn greet(name: String) -> String {
   "Hello, {name}!"
 }
+
+pub fn version() -> String {
+  "0.1.0"
+}
 `,
     nextSteps: name => `    cd ${name}\n    tova build`,
   },
@@ -1664,7 +2524,7 @@ pub fn greet(name: String) -> String {
   },
 };
 
-const TEMPLATE_ORDER = ['fullstack', 'api', 'script', 'library', 'blank'];
+const TEMPLATE_ORDER = ['fullstack', 'spa', 'site', 'api', 'script', 'library', 'blank'];
 
 async function newProject(rawArgs) {
   const name = rawArgs.find(a => !a.startsWith('-'));
@@ -1681,11 +2541,12 @@ async function newProject(rawArgs) {
 
   if (!name) {
     console.error(color.red('Error: No project name specified'));
-    console.error('Usage: tova new <project-name> [--template fullstack|api|script|library|blank]');
+    console.error('Usage: tova new <project-name> [--template fullstack|spa|site|api|script|library|blank]');
     process.exit(1);
   }
 
   const projectDir = resolve(name);
+  const projectName = basename(projectDir);
   if (existsSync(projectDir)) {
     console.error(color.red(`Error: Directory '${name}' already exists`));
     process.exit(1);
@@ -1737,24 +2598,49 @@ async function newProject(rawArgs) {
   const createdFiles = [];
 
   // tova.toml
-  const tomlConfig = {
-    project: {
-      name,
-      version: '0.1.0',
-      description: template.tomlDescription,
-    },
-    build: {
-      output: '.tova-out',
-    },
-  };
-  if (!template.noEntry) {
-    tomlConfig.project.entry = template.entry;
-  }
-  if (templateName === 'fullstack' || templateName === 'api') {
-    tomlConfig.dev = { port: 3000 };
-    tomlConfig.npm = {};
+  let tomlContent;
+  if (template.isPackage) {
+    // Library packages use [package] section per package management design
+    tomlContent = [
+      '[package]',
+      `name = "github.com/yourname/${projectName}"`,
+      `version = "0.1.0"`,
+      `description = "${template.tomlDescription}"`,
+      `license = "MIT"`,
+      `exports = ["greet", "version"]`,
+      '',
+      '[build]',
+      'output = ".tova-out"',
+      '',
+      '[dependencies]',
+      '',
+      '[npm]',
+      '',
+    ].join('\n') + '\n';
+  } else {
+    const tomlConfig = {
+      project: {
+        name: projectName,
+        version: '0.1.0',
+        description: template.tomlDescription,
+      },
+      build: {
+        output: '.tova-out',
+      },
+    };
+    if (!template.noEntry) {
+      tomlConfig.project.entry = template.entry;
+    }
+    if (templateName === 'fullstack' || templateName === 'api' || templateName === 'spa' || templateName === 'site') {
+      tomlConfig.dev = { port: 3000 };
+      tomlConfig.npm = {};
+    }
+    if (templateName === 'spa' || templateName === 'site') {
+      tomlConfig.deploy = { base: '/' };
+    }
+    tomlContent = stringifyTOML(tomlConfig);
   }
-  writeFileSync(join(projectDir, 'tova.toml'), stringifyTOML(tomlConfig));
+  writeFileSync(join(projectDir, 'tova.toml'), tomlContent);
   createdFiles.push('tova.toml');
 
   // .gitignore
@@ -1770,12 +2656,22 @@ bun.lock
 
   // Template source file
   if (template.file && template.content) {
-    writeFileSync(join(projectDir, template.file), template.content(name));
+    writeFileSync(join(projectDir, template.file), template.content(projectName));
     createdFiles.push(template.file);
   }
 
+  // Extra files (e.g., page components for site template)
+  if (template.extraFiles) {
+    for (const extra of template.extraFiles) {
+      const extraPath = join(projectDir, extra.path);
+      mkdirSync(dirname(extraPath), { recursive: true });
+      writeFileSync(extraPath, extra.content(projectName));
+      createdFiles.push(extra.path);
+    }
+  }
+
   // README
-  writeFileSync(join(projectDir, 'README.md'), `# ${name}
+  let readmeContent = `# ${projectName}
 
 Built with [Tova](https://github.com/tova-lang/tova-lang) — a modern full-stack language.
 
@@ -1784,7 +2680,34 @@ Built with [Tova](https://github.com/tova-lang/tova-lang) — a modern full-stac
 \`\`\`bash
 ${template.nextSteps(name).trim()}
 \`\`\`
-`);
+`;
+  if (template.isPackage) {
+    readmeContent += `
+## Usage
+
+\`\`\`tova
+import { greet } from "github.com/yourname/${projectName}"
+
+print(greet("world"))
+\`\`\`
+
+## Publishing
+
+Tag a release and push — no registry needed:
+
+\`\`\`bash
+git tag v0.1.0
+git push origin v0.1.0
+\`\`\`
+
+Others can then add your package:
+
+\`\`\`bash
+tova add github.com/yourname/${projectName}
+\`\`\`
+`;
+  }
+  writeFileSync(join(projectDir, 'README.md'), readmeContent);
   createdFiles.push('README.md');
 
   // Print created files
@@ -1875,7 +2798,7 @@ server {
   route GET "/api/message" => get_message
 }
 
-client {
+browser {
   state message = ""
 
   effect {
@@ -1912,6 +2835,70 @@ async function installDeps() {
     return;
   }
 
+  // Resolve Tova module dependencies (if any)
+  const tovaDeps = config.dependencies || {};
+  const { isTovModule: _isTovMod, expandBlessedPackage: _expandBlessed } = await import('../src/config/module-path.js');
+
+  // Expand blessed package shorthands (e.g., tova/data → github.com/tova-lang/data)
+  const expandedTovaDeps = {};
+  for (const [k, v] of Object.entries(tovaDeps)) {
+    const expanded = _expandBlessed(k);
+    expandedTovaDeps[expanded || k] = v;
+  }
+
+  const tovModuleKeys = Object.keys(expandedTovaDeps).filter(k => _isTovMod(k));
+
+  if (tovModuleKeys.length > 0) {
+    const { resolveDependencies } = await import('../src/config/resolver.js');
+    const { listRemoteTags, fetchModule, getCommitSha } = await import('../src/config/git-resolver.js');
+    const { isVersionCached, getModuleCachePath } = await import('../src/config/module-cache.js');
+    const { readLockFile, writeLockFile } = await import('../src/config/lock-file.js');
+
+    console.log('  Resolving Tova dependencies...');
+
+    const lock = readLockFile(cwd);
+    const tovaModuleDeps = {};
+    for (const k of tovModuleKeys) {
+      tovaModuleDeps[k] = expandedTovaDeps[k];
+    }
+
+    try {
+      const { resolved, npmDeps } = await resolveDependencies(tovaModuleDeps, {
+        getAvailableVersions: async (mod) => {
+          if (lock?.modules?.[mod]) return [lock.modules[mod].version];
+          const tags = await listRemoteTags(mod);
+          return tags.map(t => t.version);
+        },
+        getModuleConfig: async (mod, version) => {
+          if (!isVersionCached(mod, version)) {
+            console.log(`  Fetching ${mod}@v${version}...`);
+            await fetchModule(mod, version);
+          }
+          const modPath = getModuleCachePath(mod, version);
+          try {
+            return resolveConfig(modPath);
+          } catch { return null; }
+        },
+        getVersionSha: async (mod, version) => {
+          if (lock?.modules?.[mod]?.sha) return lock.modules[mod].sha;
+          return await getCommitSha(mod, version);
+        },
+      });
+
+      writeLockFile(cwd, resolved, npmDeps);
+      console.log(`  Resolved ${Object.keys(resolved).length} Tova module(s)`);
+
+      // Merge transitive npm deps into config for package.json generation
+      if (Object.keys(npmDeps).length > 0) {
+        if (!config.npm) config.npm = {};
+        if (!config.npm.prod) config.npm.prod = {};
+        Object.assign(config.npm.prod, npmDeps);
+      }
+    } catch (err) {
+      console.error(`  Failed to resolve Tova dependencies: ${err.message}`);
+    }
+  }
+
   // Generate shadow package.json from tova.toml
   const wrote = writePackageJson(config, cwd);
   if (wrote) {
@@ -1920,7 +2907,9 @@ async function installDeps() {
     const code = await new Promise(res => proc.on('close', res));
     process.exit(code);
   } else {
-    console.log('  No npm dependencies in tova.toml. Nothing to install.\n');
+    if (tovModuleKeys.length === 0) {
+      console.log('  No npm dependencies in tova.toml. Nothing to install.\n');
+    }
   }
 }
 
@@ -1985,21 +2974,60 @@ async function addDep(args) {
     await installDeps();
   } else {
     // Tova native dependency
-    let name = actualPkg;
-    let source = actualPkg;
+    const { isTovModule: isTovMod, expandBlessedPackage } = await import('../src/config/module-path.js');
+
+    // Parse potential @version suffix
+    let pkgName = actualPkg;
+    let versionConstraint = null;
+    if (pkgName.includes('@') && !pkgName.startsWith('@')) {
+      const atIdx = pkgName.lastIndexOf('@');
+      versionConstraint = pkgName.slice(atIdx + 1);
+      pkgName = pkgName.slice(0, atIdx);
+    }
+
+    // Expand blessed package shorthand: tova/data → github.com/tova-lang/data
+    const expandedPkg = expandBlessedPackage(pkgName);
+    const resolvedPkg = expandedPkg || pkgName;
+
+    if (isTovMod(pkgName)) {
+      // Tova module: fetch tags, pick version, add to [dependencies]
+      const { listRemoteTags, pickLatestTag } = await import('../src/config/git-resolver.js');
+      try {
+        const tags = await listRemoteTags(resolvedPkg);
+        if (tags.length === 0) {
+          console.error(`  No version tags found for ${resolvedPkg}`);
+          process.exit(1);
+        }
+        if (!versionConstraint) {
+          const latest = pickLatestTag(tags);
+          versionConstraint = `^${latest.version}`;
+        }
+        addToSection(tomlPath, 'dependencies', `"${resolvedPkg}"`, versionConstraint);
+        console.log(`  Added ${resolvedPkg}@${versionConstraint} to [dependencies] in tova.toml`);
+        await installDeps();
+      } catch (err) {
+        console.error(`  Failed to add ${pkgName}: ${err.message}`);
+        process.exit(1);
+      }
+      return;
+    }
+
+    // Local path or generic dependency
+    let name = pkgName;
+    let source = pkgName;
 
     // Detect source type
-    if (actualPkg.startsWith('file:') || actualPkg.startsWith('./') || actualPkg.startsWith('../') || actualPkg.startsWith('/')) {
+    if (pkgName.startsWith('file:') || pkgName.startsWith('./') || pkgName.startsWith('../') || pkgName.startsWith('/')) {
       // Local path dependency
-      source = actualPkg.startsWith('file:') ? actualPkg : `file:${actualPkg}`;
-      name = basename(actualPkg.replace(/^file:/, ''));
-    } else if (actualPkg.startsWith('git:') || actualPkg.includes('github.com/') || actualPkg.includes('.git')) {
+      source = pkgName.startsWith('file:') ? pkgName : `file:${pkgName}`;
+      name = basename(pkgName.replace(/^file:/, ''));
+    } else if (pkgName.startsWith('git:') || pkgName.includes('.git')) {
       // Git dependency
-      source = actualPkg.startsWith('git:') ? actualPkg : `git:${actualPkg}`;
-      name = basename(actualPkg.replace(/\.git$/, '').replace(/^git:/, ''));
+      source = pkgName.startsWith('git:') ? pkgName : `git:${pkgName}`;
+      name = basename(pkgName.replace(/\.git$/, '').replace(/^git:/, ''));
     } else {
       // Tova registry package (future: for now, just store the name)
-      source = `*`;
+      source = versionConstraint || `*`;
     }
 
     addToSection(tomlPath, 'dependencies', name, source);
@@ -2828,6 +3856,26 @@ async function startRepl() {
         const declaredInCode = new Set();
         for (const m of code.matchAll(/\bfunction\s+([a-zA-Z_]\w*)/g)) { declaredInCode.add(m[1]); userDefinedNames.add(m[1]); }
         for (const m of code.matchAll(/\bconst\s+([a-zA-Z_]\w*)/g)) { declaredInCode.add(m[1]); userDefinedNames.add(m[1]); }
+        // Extract destructured names: const { a, b } = ... or const [ a, b ] = ...
+        for (const m of code.matchAll(/\bconst\s+\{\s*([^}]+)\}/g)) {
+          for (const part of m[1].split(',')) {
+            const trimmed = part.trim();
+            if (!trimmed) continue;
+            // Handle renaming: "key: alias" or "key: alias = default" — extract the alias
+            const colonMatch = trimmed.match(/^\w+\s*:\s*([a-zA-Z_]\w*)/);
+            const name = colonMatch ? colonMatch[1] : trimmed.match(/^([a-zA-Z_]\w*)/)?.[1];
+            if (name) { declaredInCode.add(name); userDefinedNames.add(name); }
+          }
+        }
+        for (const m of code.matchAll(/\bconst\s+\[\s*([^\]]+)\]/g)) {
+          for (const part of m[1].split(',')) {
+            const trimmed = part.trim();
+            if (!trimmed) continue;
+            const name = trimmed.startsWith('...') ? trimmed.slice(3).trim() : trimmed;
+            const id = name.match(/^([a-zA-Z_]\w*)/)?.[1];
+            if (id) { declaredInCode.add(id); userDefinedNames.add(id); }
+          }
+        }
         for (const m of code.matchAll(/\blet\s+([a-zA-Z_]\w*)/g)) {
           declaredInCode.add(m[1]);
           userDefinedNames.add(m[1]);
@@ -3124,7 +4172,11 @@ async function binaryBuild(srcDir, outputName, outDir) {
 
 // ─── Production Build ────────────────────────────────────────
 
-async function productionBuild(srcDir, outDir) {
+async function productionBuild(srcDir, outDir, isStatic = false) {
+  const config = resolveConfig(process.cwd());
+  const basePath = config.deploy?.base || '/';
+  const base = basePath.endsWith('/') ? basePath : basePath + '/';
+
   const tovaFiles = findFiles(srcDir, '.tova');
   if (tovaFiles.length === 0) {
     console.error('No .tova files found');
@@ -3169,6 +4221,9 @@ async function productionBuild(srcDir, outDir) {
     const serverPath = join(outDir, `server.${hash}.js`);
     writeFileSync(serverPath, serverBundle);
     console.log(`  server.${hash}.js`);
+
+    // Write stable server.js entrypoint for Docker/deployment
+    writeFileSync(join(outDir, 'server.js'), `import "./server.${hash}.js";\n`);
   }
 
   // Write script bundle for plain scripts (no server/client blocks)
@@ -3196,7 +4251,9 @@ async function productionBuild(srcDir, outDir) {
       // No npm imports — inline runtime, strip all imports
       const reactivityCode = REACTIVITY_SOURCE.replace(/^export /gm, '');
       const rpcCode = RPC_SOURCE.replace(/^export /gm, '');
-      clientBundle = reactivityCode + '\n' + rpcCode + '\n' + allSharedCode + '\n' +
+      const usesRouter = /\b(defineRoutes|Router|getPath|getQuery|getParams|getCurrentRoute|navigate|onRouteChange|beforeNavigate|afterNavigate|Outlet|Link|Redirect)\b/.test(allClientCode);
+      const routerCode = usesRouter ? ROUTER_SOURCE.replace(/^export /gm, '').replace(/^\s*import\s+(?:\{[^}]*\}|[\w$]+|\*\s+as\s+[\w$]+)\s+from\s+['"][^'"]+['"];?\s*$/gm, '') : '';
+      clientBundle = reactivityCode + '\n' + rpcCode + '\n' + (routerCode ? routerCode + '\n' : '') + allSharedCode + '\n' +
         allClientCode.replace(/^\s*import\s+(?:\{[^}]*\}|[\w$]+|\*\s+as\s+[\w$]+)\s+from\s+['"][^'"]+['"];?\s*$/gm, '').trim();
     }
 
@@ -3207,14 +4264,19 @@ async function productionBuild(srcDir, outDir) {
 
     // Generate production HTML
     const scriptTag = useModule
-      ? `<script type="module" src="client.${hash}.js"></script>`
-      : `<script src="client.${hash}.js"></script>`;
+      ? `<script type="module" src="${base}.tova-out/client.${hash}.js"></script>`
+      : `<script src="${base}.tova-out/client.${hash}.js"></script>`;
     const html = `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Tova App</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: system-ui, -apple-system, sans-serif; }
+  </style>
 </head>
 <body>
   <div id="app"></div>
@@ -3223,6 +4285,12 @@ async function productionBuild(srcDir, outDir) {
 </html>`;
     writeFileSync(join(outDir, 'index.html'), html);
     console.log(`  index.html`);
+
+    // SPA fallback files for various static hosts
+    writeFileSync(join(outDir, '404.html'), html);
+    console.log(`  404.html (GitHub Pages SPA fallback)`);
+    writeFileSync(join(outDir, '200.html'), html);
+    console.log(`  200.html (Surge SPA fallback)`);
   }
 
   // Minify all JS bundles using Bun's built-in transpiler
@@ -3259,13 +4327,64 @@ async function productionBuild(srcDir, outDir) {
     }
   }
 
+  // Rewrite min entrypoints to import minified hashed files
+  for (const f of ['server.min.js', 'script.min.js']) {
+    const minEntry = join(outDir, f);
+    try {
+      const content = readFileSync(minEntry, 'utf-8');
+      const rewritten = content.replace(/\.js(["'])/g, '.min.js$1');
+      writeFileSync(minEntry, rewritten);
+    } catch {}
+  }
+
   if (minified === 0 && jsFiles.length > 0) {
     console.log('  (minification skipped — Bun.build unavailable)');
   }
 
+  // Static generation: pre-render each route to its own HTML file
+  if (isStatic && allClientCode.trim()) {
+    console.log(`\n  Static generation...\n`);
+
+    const routePaths = extractRoutePaths(allClientCode);
+    if (routePaths.length > 0) {
+      // Read the generated index.html to use as the shell for all routes
+      const shellHtml = readFileSync(join(outDir, 'index.html'), 'utf-8');
+      for (const routePath of routePaths) {
+        const htmlPath = routePath === '/'
+          ? join(outDir, 'index.html')
+          : join(outDir, routePath.replace(/^\//, ''), 'index.html');
+
+        mkdirSync(dirname(htmlPath), { recursive: true });
+        writeFileSync(htmlPath, shellHtml);
+        const relPath = relative(outDir, htmlPath);
+        console.log(`  ${relPath}`);
+      }
+      console.log(`\n  Pre-rendered ${routePaths.length} route(s)`);
+    }
+  }
+
   console.log(`\n  Production build complete.\n`);
 }
 
+function extractRoutePaths(code) {
+  // Support both defineRoutes({...}) and createRouter({ routes: {...} })
+  let match = code.match(/defineRoutes\s*\(\s*\{([^}]+)\}\s*\)/);
+  if (!match) {
+    match = code.match(/routes\s*:\s*\{([^}]+)\}/);
+  }
+  if (!match) return [];
+
+  const paths = [];
+  const entries = match[1].matchAll(/"([^"]+)"\s*:/g);
+  for (const entry of entries) {
+    const path = entry[1];
+    if (path === '404' || path === '*') continue;
+    if (path.includes(':')) continue;
+    paths.push(path);
+  }
+  return paths;
+}
+
 // Fallback JS minifier — string/regex-aware, no AST required
 function _simpleMinify(code) {
   // Phase 1: Strip comments while respecting strings and regexes
@@ -3739,6 +4858,10 @@ function collectExports(ast, filename) {
       allNames.add(node.name);
       if (node.isPublic) publicExports.add(node.name);
     }
+    if (node.type === 'ComponentDeclaration') {
+      allNames.add(node.name);
+      if (node.isPublic) publicExports.add(node.name);
+    }
     if (node.type === 'ImplDeclaration') { /* impl doesn't export a name */ }
   }
 
@@ -3780,8 +4903,24 @@ function compileWithImports(source, filename, srcDir) {
     // Collect this module's exports for validation
     collectExports(ast, filename);
 
-    // Resolve .tova imports first
+    // Resolve imports: tova: prefix, @/ prefix, then .tova files
     for (const node of ast.body) {
+      // Resolve tova: prefix imports to runtime modules
+      if ((node.type === 'ImportDeclaration' || node.type === 'ImportDefault' || node.type === 'ImportWildcard') && node.source.startsWith('tova:')) {
+        node.source = './runtime/' + node.source.slice(5) + '.js';
+        continue;
+      }
+      // Resolve @/ prefix imports to project root
+      if ((node.type === 'ImportDeclaration' || node.type === 'ImportDefault' || node.type === 'ImportWildcard') && node.source.startsWith('@/')) {
+        const relPath = node.source.slice(2);
+        let resolved = resolve(srcDir, relPath);
+        if (!resolved.endsWith('.tova')) resolved += '.tova';
+        const fromDir = dirname(filename);
+        let rel = relative(fromDir, resolved);
+        if (!rel.startsWith('.')) rel = './' + rel;
+        node.source = rel;
+        // Fall through to .tova import handling below
+      }
       if (node.type === 'ImportDeclaration' && node.source.endsWith('.tova')) {
         const importPath = resolve(dirname(filename), node.source);
         trackDependency(filename, importPath);
@@ -3998,8 +5137,22 @@ function mergeDirectory(dir, srcDir, options = {}) {
     // Collect exports for cross-file import validation
     collectExports(ast, file);
 
-    // Resolve cross-directory .tova imports (same logic as compileWithImports)
+    // Resolve imports: tova: prefix, @/ prefix, then cross-directory .tova
     for (const node of ast.body) {
+      if ((node.type === 'ImportDeclaration' || node.type === 'ImportDefault' || node.type === 'ImportWildcard') && node.source.startsWith('tova:')) {
+        node.source = './runtime/' + node.source.slice(5) + '.js';
+        continue;
+      }
+      if ((node.type === 'ImportDeclaration' || node.type === 'ImportDefault' || node.type === 'ImportWildcard') && node.source.startsWith('@/')) {
+        const relPath = node.source.slice(2);
+        let resolved = resolve(srcDir, relPath);
+        if (!resolved.endsWith('.tova')) resolved += '.tova';
+        const fromDir = dirname(file);
+        let rel = relative(fromDir, resolved);
+        if (!rel.startsWith('.')) rel = './' + rel;
+        node.source = rel;
+        // Fall through to .tova import handling below
+      }
       if ((node.type === 'ImportDeclaration' || node.type === 'ImportDefault' || node.type === 'ImportWildcard') && node.source.endsWith('.tova')) {
         const importPath = resolve(dirname(file), node.source);
         // Only process imports from OTHER directories (same-dir files are merged)
@@ -4075,7 +5228,7 @@ function mergeDirectory(dir, srcDir, options = {}) {
   const mergedAST = new Program(mergedBody);
 
   // Run analyzer on merged AST
-  const analyzer = new Analyzer(mergedAST, dir);
+  const analyzer = new Analyzer(mergedAST, dir, { strict: options.strict, strictSecurity: options.strictSecurity });
   const { warnings } = analyzer.analyze();
 
   if (warnings.length > 0) {
@@ -4096,7 +5249,27 @@ function mergeDirectory(dir, srcDir, options = {}) {
   output._sourceContents = sourceContents;
   output._sourceFiles = tovaFiles;
 
-  return { output, files: tovaFiles, single: false };
+  // Extract security info for scorecard
+  const hasServer = mergedBody.some(n => n.type === 'ServerBlock');
+  const hasEdge = mergedBody.some(n => n.type === 'EdgeBlock');
+  const securityNode = mergedBody.find(n => n.type === 'SecurityBlock');
+  let securityConfig = null;
+  if (securityNode) {
+    securityConfig = {};
+    for (const child of securityNode.body || []) {
+      if (child.type === 'AuthDeclaration') securityConfig.auth = { authType: child.authType || 'jwt', storage: child.config?.storage?.value };
+      else if (child.type === 'CsrfDeclaration') securityConfig.csrf = { enabled: child.config?.enabled?.value !== false };
+      else if (child.type === 'RateLimitDeclaration') securityConfig.rateLimit = { max: child.config?.max?.value };
+      else if (child.type === 'CspDeclaration') securityConfig.csp = { default_src: true };
+      else if (child.type === 'CorsDeclaration') {
+        const origins = child.config?.origins;
+        securityConfig.cors = { origins: origins ? (origins.elements || []).map(e => e.value) : [] };
+      }
+      else if (child.type === 'AuditDeclaration') securityConfig.audit = { events: ['auth'] };
+    }
+  }
+
+  return { output, files: tovaFiles, single: false, warnings, securityConfig, hasServer, hasEdge };
 }
 
 // Group .tova files by their parent directory
@@ -4269,7 +5442,7 @@ function completionsCommand(shell) {
     'migrate:create', 'migrate:up', 'migrate:down', 'migrate:reset', 'migrate:fresh', 'migrate:status',
   ];
 
-  const globalFlags = ['--help', '--version', '--output', '--production', '--watch', '--verbose', '--quiet', '--debug', '--strict'];
+  const globalFlags = ['--help', '--version', '--output', '--production', '--watch', '--verbose', '--quiet', '--debug', '--strict', '--strict-security'];
 
   switch (shell) {
     case 'bash': {
@@ -4292,7 +5465,7 @@ _tova() {
       return 0
       ;;
     --template)
-      COMPREPLY=( $(compgen -W "fullstack api script library blank" -- "\${cur}") )
+      COMPREPLY=( $(compgen -W "fullstack spa site api script library blank" -- "\${cur}") )
       return 0
       ;;
     completions)
@@ -4340,7 +5513,7 @@ ${commands.map(c => `    '${c}:${c} command'`).join('\n')}
       case $words[1] in
         new)
           _arguments \\
-            '--template[Project template]:template:(fullstack api script library blank)' \\
+            '--template[Project template]:template:(fullstack spa site api script library blank)' \\
             '*:name:'
           ;;
         run|build|check|fmt|doc)
@@ -4432,7 +5605,7 @@ _tova "$@"
       script += `complete -c tova -l debug -d 'Debug output'\n`;
       script += `complete -c tova -l strict -d 'Strict type checking'\n`;
       script += `\n# Template completions for 'new'\n`;
-      script += `complete -c tova -n '__fish_seen_subcommand_from new' -l template -d 'Project template' -xa 'fullstack api script library blank'\n`;
+      script += `complete -c tova -n '__fish_seen_subcommand_from new' -l template -d 'Project template' -xa 'fullstack spa site api script library blank'\n`;
       script += `\n# Shell completions for 'completions'\n`;
       script += `complete -c tova -n '__fish_seen_subcommand_from completions' -xa 'bash zsh fish'\n`;