@nutin/cli 2.1.0 → 3.0.0

package/templates/base/tools/builder/core/seo/html-substitutions.js.hbs

@@ -7,90 +7,120 @@ export function escape(str) {
     .replace(/'/g, ''');
 }
 
+// Replacements go through functions: a replacement *string* would expand `$&`, `$'`
+// etc. found in a title/description, copying raw page HTML into the tag.
+// `replacement` receives the match's capture groups.
 export function upsertInHead(html, pattern, replacement, fullTag) {
   if (pattern.test(html)) {
-    return html.replace(pattern, replacement);
+    return html.replace(pattern, (_match, ...groups) => replacement(...groups));
   }
-  return html.replace('</head>', `\n    ${fullTag}\n  </head>`);
+  return insertBeforeHeadEnd(html, fullTag);
 }
 
-export function applySubstitutions(template, lang, title, description, pageUrl, ogImage) {
+function insertBeforeHeadEnd(html, tag) {
+  return html.replace('</head>', () => `\n    ${tag}\n  </head>`);
+}
+
+export function applySubstitutions(template, lang, title, description, pageUrl, ogImage, hreflangLinks = []) {
   let html = template;
 
   // lang attribute on <html>
   if (/(<html[^>]*\slang=)["'][^"']*["']/.test(html)) {
-    html = html.replace(/(<html[^>]*\slang=)["'][^"']*["']/, `$1"${lang}"`);
+    html = html.replace(/(<html[^>]*\slang=)["'][^"']*["']/, (_m, start) => `${start}"${escape(lang)}"`);
   } else {
-    html = html.replace(/<html/, `<html lang="${lang}"`);
+    html = html.replace(/<html/, () => `<html lang="${escape(lang)}"`);
   }
 
   // <title>
   html = upsertInHead(html,
     /(<title>)[^<]*(<\/title>)/,
-    `$1${escape(title)}$2`,
+    (start, end) => `${start}${escape(title)}${end}`,
     `<title>${escape(title)}</title>`
   );
 
   // <meta name="description"> — replace all occurrences, or insert one
   const descPattern = /(<meta\s+name=["']description["']\s+content=)["'][^"']*["']/;
   if (descPattern.test(html)) {
-    html = html.replace(/(<meta\s+name=["']description["']\s+content=)["'][^"']*["']/g, `$1"${escape(description)}"`);
+    html = html.replace(/(<meta\s+name=["']description["']\s+content=)["'][^"']*["']/g, (_m, start) => `${start}"${escape(description)}"`);
   } else {
-    html = html.replace('</head>', `\n    <meta name="description" content="${escape(description)}" />\n  </head>`);
+    html = insertBeforeHeadEnd(html, `<meta name="description" content="${escape(description)}" />`);
   }
 
   // <link rel="canonical">
   html = upsertInHead(html,
     /(<link\s+rel=["']canonical["']\s+href=)["'][^"']*["']/,
-    `$1"${pageUrl}/"`,
-    `<link rel="canonical" href="${pageUrl}/" />`
+    (start) => `${start}"${escape(pageUrl)}/"`,
+    `<link rel="canonical" href="${escape(pageUrl)}/" />`
   );
 
   // og:url
   html = upsertInHead(html,
     /(<meta\s+property=["']og:url["']\s+content=)["'][^"']*["']/,
-    `$1"${pageUrl}/"`,
-    `<meta property="og:url" content="${pageUrl}/" />`
+    (start) => `${start}"${escape(pageUrl)}/"`,
+    `<meta property="og:url" content="${escape(pageUrl)}/" />`
   );
 
+  // hreflang alternates — one per active language plus x-default, so crawlers see
+  // these URLs as language variants of the same page rather than duplicate content
+  if (hreflangLinks.length > 0) {
+    const altTags = hreflangLinks
+      .map(({ hreflang, href }) => `<link rel="alternate" hreflang="${escape(hreflang)}" href="${escape(href)}" />`)
+      .join('\n    ');
+    html = insertBeforeHeadEnd(html, altTags);
+  }
+
   // og:title
   html = upsertInHead(html,
     /(<meta\s+property=["']og:title["']\s+content=)["'][^"']*["']/,
-    `$1"${escape(title)}"`,
+    (start) => `${start}"${escape(title)}"`,
     `<meta property="og:title" content="${escape(title)}" />`
   );
 
   // og:description
   html = upsertInHead(html,
     /(<meta\s+property=["']og:description["']\s+content=)["'][^"']*["']/,
-    `$1"${escape(description)}"`,
+    (start) => `${start}"${escape(description)}"`,
     `<meta property="og:description" content="${escape(description)}" />`
   );
 
   // twitter:title
   html = upsertInHead(html,
     /(<meta\s+name=["']twitter:title["']\s+content=)["'][^"']*["']/,
-    `$1"${escape(title)}"`,
+    (start) => `${start}"${escape(title)}"`,
     `<meta name="twitter:title" content="${escape(title)}" />`
   );
 
   // twitter:description
   html = upsertInHead(html,
     /(<meta\s+name=["']twitter:description["']\s+content=)["'][^"']*["']/,
-    `$1"${escape(description)}"`,
+    (start) => `${start}"${escape(description)}"`,
     `<meta name="twitter:description" content="${escape(description)}" />`
   );
 
+  // og:type
+  html = upsertInHead(html,
+    /(<meta\s+property=["']og:type["']\s+content=)["'][^"']*["']/,
+    (start) => `${start}"website"`,
+    `<meta property="og:type" content="website" />`
+  );
+
+  // twitter:card — required for Twitter/X to render an image card at all
+  html = upsertInHead(html,
+    /(<meta\s+name=["']twitter:card["']\s+content=)["'][^"']*["']/,
+    (start) => `${start}"summary_large_image"`,
+    `<meta name="twitter:card" content="summary_large_image" />`
+  );
+
   // og:image + twitter:image — only when explicitly provided in route config
   if (ogImage) {
     html = upsertInHead(html,
       /(<meta\s+property=["']og:image["']\s+content=)["'][^"']*["']/,
-      `$1"${escape(ogImage)}"`,
+      (start) => `${start}"${escape(ogImage)}"`,
       `<meta property="og:image" content="${escape(ogImage)}" />`
     );
     html = upsertInHead(html,
       /(<meta\s+name=["']twitter:image["']\s+content=)["'][^"']*["']/,
-      `$1"${escape(ogImage)}"`,
+      (start) => `${start}"${escape(ogImage)}"`,
       `<meta name="twitter:image" content="${escape(ogImage)}" />`
     );
   }

package/templates/base/tools/builder/core/seo/html-substitutions.test.js.hbs

@@ -0,0 +1,45 @@
+import { applySubstitutions, upsertInHead } from './html-substitutions.js';
+
+const TEMPLATE = '<html lang="en"><head><title>x</title><meta name="description" content="d"></head><body></body></html>';
+
+describe('applySubstitutions', () => {
+  it('applySubstitutions sets title, description, canonical and og tags', () => {
+    const html = applySubstitutions(TEMPLATE, 'fr', 'Home', 'Welcome', 'https://site.test/fr', '/og.png');
+    expect(html).toContain('<html lang="fr">');
+    expect(html).toContain('<title>Home</title>');
+    expect(html).toContain('<meta name="description" content="Welcome">');
+    expect(html).toContain('<link rel="canonical" href="https://site.test/fr/" />');
+    expect(html).toContain('<meta property="og:image" content="/og.png" />');
+  });
+
+  it('applySubstitutions keeps $ replacement patterns in values literal', () => {
+    const title = "Only $' left, $` and $& and $1";
+    const html = applySubstitutions(TEMPLATE, 'en', title, 'Save $$ now', 'https://site.test', '');
+    expect(html).toContain("<title>Only $&#39; left, $` and $&amp; and $1</title>");
+    expect(html).toContain('<meta name="description" content="Save $$ now">');
+    expect(html).toContain('<meta property="og:title" content="Only $&#39; left, $` and $&amp; and $1" />');
+    expect(html.match(/<html/g).length).toBe(1);
+  });
+
+  it('applySubstitutions escapes markup in title, description and URLs', () => {
+    const html = applySubstitutions(TEMPLATE, 'en', '<b>"T"</b>', 'a & b', 'https://site.test/?a=1&b=2', '', [
+      { hreflang: 'en', href: 'https://site.test/en?x="y"' },
+    ]);
+    expect(html).toContain('<title>&lt;b&gt;&quot;T&quot;&lt;/b&gt;</title>');
+    expect(html).toContain('content="a &amp; b"');
+    expect(html).toContain('href="https://site.test/?a=1&amp;b=2/"');
+    expect(html).toContain('href="https://site.test/en?x=&quot;y&quot;"');
+  });
+
+  it('applySubstitutions inserts missing tags before </head>', () => {
+    const html = applySubstitutions('<html><head></head><body></body></html>', 'en', 'T $&', 'D', 'https://site.test', '');
+    expect(html).toContain('<html lang="en">');
+    expect(html).toContain('<title>T $&amp;</title>');
+    expect(html).toContain('<meta name="description" content="D" />');
+  });
+
+  it('upsertInHead passes capture groups to the replacement function', () => {
+    const html = upsertInHead('<head><title>a</title></head>', /(<title>)[^<]*(<\/title>)/, (start, end) => `${start}$'${end}`, '');
+    expect(html).toBe("<head><title>$'</title></head>");
+  });
+});

package/templates/base/tools/builder/core/seo/route-output.js.hbs

@@ -6,6 +6,19 @@ import { applySubstitutions } from './html-substitutions.js';
 import { getAppRoutePaths } from './ssr/ssr-render.js';
 import { builderConfig } from '../../builder.config.js';
 
+const APP_CONTAINER = /(<([a-zA-Z][\w-]*)\b[^>]*\sid=["']app["'][^>]*>)[\s\S]*?<\/\2>/;
+
+// The concrete URL path a seo.json route is prerendered at: `outputPath` when given,
+// otherwise `path` with each `:param` filled from `mockParams` (an unset optional
+// `:param?` segment is dropped). '/' maps to '' so it can be appended to baseUrl.
+export function routeSuffixOf(route) {
+  const resolved = route.outputPath ?? route.path.replace(/\/:([^/?]+)\??/g, (_match, name) => {
+    const value = route.mockParams?.[name];
+    return value === undefined || value === '' ? '' : `/${encodeURIComponent(value)}`;
+  });
+  return resolved === '/' || resolved === '' ? '' : resolved.replace(/\/$/, '');
+}
+
 export function segmentsOf(routeSuffix) {
   return routeSuffix ? routeSuffix.split('/').filter(Boolean) : [];
 }
@@ -29,17 +42,20 @@ export function validateMockParams(route) {
   }
 }
 
-export async function writeRouteHtml({ template, lang, title, description, pageUrl, ogImage, body, outputSegments, routePath }) {
-  let html = applySubstitutions(template, lang, title, description, pageUrl, ogImage);
+export async function writeRouteHtml({ template, lang, title, description, pageUrl, ogImage, body, outputSegments, routePath, hreflangLinks }) {
+  let html = applySubstitutions(template, lang, title, description, pageUrl, ogImage, hreflangLinks);
 
   if (html === template) {
     errorExit(`Failed to apply any changes for ${routePath} (lang "${lang}") — index.html may be missing a </head> tag`, 'generate-seo-html');
   }
 
-  html = html.replace(
-    /<main\s+id=["']app["'][^>]*>[\s\S]*?<\/main>/,
-    `<main id="app">\n${body}\n  </main>`
-  );
+  // Any element can be the #app mount (validate-html.js only checks for id="app"), and
+  // its opening tag is kept as authored. The replacement goes through a function so `$&`,
+  // `$'`… in the rendered markup stay literal.
+  if (!APP_CONTAINER.test(html)) {
+    errorExit(`index.html has no closed id="app" container to render ${routePath} into`, 'generate-seo-html');
+  }
+  html = html.replace(APP_CONTAINER, (_match, openTag, tagName) => `${openTag}\n${body}\n  </${tagName}>`);
 
   const outputDir = path.join(PATHS.tempSource, ...outputSegments);
   const outputPath = path.join(outputDir, 'index.html');
@@ -48,9 +64,11 @@ export async function writeRouteHtml({ template, lang, title, description, pageU
   fs.writeFileSync(outputPath, html, 'utf-8');
 }
 
-export async function warnForRoutesMissingSeoConfig(bundleUrl, seoRoutes, defaultLanguage, baseUrl) {
+// `optOutPaths`: app route patterns deliberately without SEO pages (e.g. a Markdown source
+// with "seo: false").
+export async function warnForRoutesMissingSeoConfig(bundleUrl, seoRoutes, defaultLanguage, baseUrl, optOutPaths = []) {
   const appRoutePaths = await getAppRoutePaths(bundleUrl, defaultLanguage, baseUrl);
-  const seoRoutePaths = new Set(seoRoutes.map((route) => route.path));
+  const seoRoutePaths = new Set([...seoRoutes.map((route) => route.path), ...optOutPaths]);
 
   for (const path of appRoutePaths) {
     if (seoRoutePaths.has(path)) continue;

package/templates/base/tools/builder/core/seo/route-output.test.js.hbs

@@ -0,0 +1,31 @@
+import { routeSuffixOf, segmentsOf } from './route-output.js';
+
+describe('routeSuffixOf', () => {
+  it('maps "/" to an empty suffix and keeps static paths as-is', () => {
+    expect(routeSuffixOf({ path: '/' })).toBe('');
+    expect(routeSuffixOf({ path: '/about' })).toBe('/about');
+  });
+
+  it('fills dynamic segments from mockParams', () => {
+    expect(routeSuffixOf({ path: '/blog/:slug', mockParams: { slug: 'hello-world' } })).toBe('/blog/hello-world');
+  });
+
+  it('drops an unset optional segment', () => {
+    expect(routeSuffixOf({ path: '/docs/:page?' })).toBe('/docs');
+  });
+
+  it('encodes param values', () => {
+    expect(routeSuffixOf({ path: '/tags/:tag', mockParams: { tag: 'a b' } })).toBe('/tags/a%20b');
+  });
+
+  it('prefers an explicit outputPath', () => {
+    expect(routeSuffixOf({ path: '/demo/:page?', outputPath: '/demo/overlays/', mockParams: { page: 'x' } })).toBe('/demo/overlays');
+  });
+});
+
+describe('segmentsOf', () => {
+  it('splits a suffix into directory segments', () => {
+    expect(segmentsOf('/blog/hello-world')).toEqual(['blog', 'hello-world']);
+    expect(segmentsOf('')).toEqual([]);
+  });
+});

package/templates/base/tools/builder/core/seo/seo-routes.js.hbs

@@ -0,0 +1,29 @@
+{{#if markdown}}
+import { markdownSeoRoutes, markdownSeoOptOutPaths } from '../markdown/markdown-seo-routes.js';
+{{/if}}
+import { routeSuffixOf } from './route-output.js';
+
+// Appends generated routes to config/seo.json's, skipping any whose output URL a
+// seo.json entry already covers: a hand-written entry always wins.
+export function mergeSeoRoutes(configRoutes, generatedRoutes) {
+  const covered = new Set(configRoutes.map(routeSuffixOf));
+  return [...configRoutes, ...generatedRoutes.filter((route) => !covered.has(routeSuffixOf(route)))];
+}
+
+// Every route to prerender: config/seo.json's, plus those generated by features.
+export function resolveSeoRoutes(seoConfig) {
+  let routes = seoConfig.routes ?? [];
+{{#if markdown}}
+  routes = mergeSeoRoutes(routes, markdownSeoRoutes());
+{{/if}}
+  return routes;
+}
+
+// App route patterns deliberately left without SEO pages: no "missing seo.json entry" warning.
+export function resolveSeoOptOutPaths() {
+  let paths = [];
+{{#if markdown}}
+  paths = [...paths, ...markdownSeoOptOutPaths()];
+{{/if}}
+  return paths;
+}

package/templates/base/tools/builder/core/seo/seo-routes.test.js.hbs

@@ -0,0 +1,21 @@
+import { mergeSeoRoutes } from './seo-routes.js';
+
+describe('mergeSeoRoutes', () => {
+  it('appends generated routes after the seo.json ones', () => {
+    const merged = mergeSeoRoutes([{ path: '/' }], [{ path: '/docs/:slug?', mockParams: { slug: 'intro' } }]);
+
+    expect(merged.map((route) => route.path)).toEqual(['/', '/docs/:slug?']);
+  });
+
+  it('keeps the seo.json entry when both produce the same URL', () => {
+    const fromConfig = { path: '/docs/:slug?', mockParams: { slug: 'intro' }, title: 'Hand-written' };
+    const generated = [
+      { path: '/docs/:slug?', mockParams: { slug: 'intro' }, title: 'Generated' },
+      { path: '/docs/:slug?', mockParams: { slug: 'next' }, title: 'Next' },
+    ];
+
+    const merged = mergeSeoRoutes([fromConfig], generated);
+
+    expect(merged.map((route) => route.title)).toEqual(['Hand-written', 'Next']);
+  });
+});

package/templates/base/tools/builder/core/seo/ssr/ssr-bundle.js.hbs

@@ -4,14 +4,15 @@ import path from 'path';
 import { pathToFileURL } from 'url';
 import { PATHS } from '../../app/paths.js';
 import { builderConfig } from '../../../builder.config.js';
+import { sharedDefine } from '../../prod-bundle/bundle-options.js';
 
 const SSR_DIR = path.join(PATHS.temp, '.ssr');
-const ENTRY_FILE = path.join(PATHS.tempApp, '__ssr-entry.ts');
+const ENTRY_FILE = path.join(PATHS.tempApp, '__ssr-entry.{{#if (eq lang "js")}}js{{else}}ts{{/if}}');
 const OUT_FILE = path.join(SSR_DIR, 'ssr-bundle.mjs');
 
 const ENTRY_CONTENT = `export { appRoutes } from './routes.js';
-export { I18nService, Service, registerPipes } from '../core/index.js';
-export { RouteGuardsManager } from '../core/services/router/helpers/route-guard-manager.helper.js';
+export { I18nService, Service, SecurityHelper, registerPipes } from '../core/index.js';
+export * as RouteGuardsManager from '../core/services/router/helpers/route-guard-manager.helper.js';
 `;
 
 /**
@@ -28,16 +29,14 @@ export async function buildSsrBundle() {
       ...builderConfig.esbuild,
       platform: 'node',
       format: 'esm',
-      target: ['node22'],
+      target: ['node24'],
       minify: false,
       drop: [],
       legalComments: 'none',
       loader: {
         '.json': 'json',
       },
-      define: {
-        'process.env.NODE_ENV': '"production"',
-      },
+      define: sharedDefine({ ...builderConfig, isProd: true }),
       entryPoints: [ENTRY_FILE],
       outfile: OUT_FILE,
       keepNames: true,

package/templates/base/tools/builder/core/seo/ssr/ssr-polyfills.js.hbs

@@ -3,7 +3,7 @@ import path from 'path';
 
 /**
  * Installs the minimum browser globals the framework's own base classes touch
- * unconditionally (Service's `beforeunload` listener, I18n's `navigator`/`window.location`
+ * unconditionally (the Router's `popstate` listener, I18n's `navigator`/`window.location`
  * reads), plus a couple of cheap defensive stubs (matchMedia) for common patterns
  * downstream projects add (e.g. dark-mode toggles).
  *
@@ -52,7 +52,7 @@ function createMemoryStorage() {
   };
 }
 
-export function installGlobals(window, { lang, mockFetch = {}, localesDir } = {}) {
+export function installGlobals(window, { lang, mockFetch = {}, localesDir, staticDir } = {}) {
   for (const key of Object.getOwnPropertyNames(window)) {
     setGlobal(globalThis, key, window[key]);
   }
@@ -90,7 +90,7 @@ export function installGlobals(window, { lang, mockFetch = {}, localesDir } = {}
 
   const fetchShim = (input) => {
     const url = typeof input === 'string' ? input : input?.url;
-    const promise = resolveFetch(url, { mockFetch, localesDir });
+    const promise = resolveFetch(url, { mockFetch, localesDir, staticDir });
     trackedFetches.push(promise);
     return promise;
   };
@@ -100,7 +100,7 @@ export function installGlobals(window, { lang, mockFetch = {}, localesDir } = {}
   return { trackedFetches };
 }
 
-async function resolveFetch(url, { mockFetch, localesDir }) {
+export async function resolveFetch(url, { mockFetch = {}, localesDir, staticDir } = {}) {
   if (Object.prototype.hasOwnProperty.call(mockFetch, url)) {
     return jsonResponse(mockFetch[url]);
   }
@@ -116,12 +116,41 @@ async function resolveFetch(url, { mockFetch, localesDir }) {
     return jsonResponse({});
   }
 
+  const staticFile = resolveStaticFile(url, staticDir);
+  if (staticFile) {
+    const text = fs.readFileSync(staticFile, 'utf-8');
+    return staticFile.endsWith('.json') ? jsonResponse(JSON.parse(text)) : textResponse(text);
+  }
+
   throw new Error(
     `Unexpected fetch("${url}") during SSR — no "mockFetch" entry for this endpoint and it isn't a ` +
-    `/locales/*.json request. Add a "mockFetch" entry for this route in config/seo.json if this is intentional.`
+    `/locales/*.json request or a file built into dist. Add a "mockFetch" entry for this route in config/seo.json if this is intentional.`
   );
 }
 
+// A root-relative URL naming a file the build already wrote (e.g. /generated/<id>.json,
+// fetched by the markdown feature's route guards). Paths escaping staticDir don't count.
+function resolveStaticFile(url, staticDir) {
+  if (!staticDir || typeof url !== 'string' || !url.startsWith('/')) return null;
+  const root = path.resolve(staticDir);
+  try {
+    const filePath = path.resolve(root, '.' + decodeURIComponent(url.split(/[?#]/)[0]));
+    if (!filePath.startsWith(root + path.sep)) return null;
+    return fs.statSync(filePath).isFile() ? filePath : null;
+  } catch {
+    return null;
+  }
+}
+
+function textResponse(body) {
+  return {
+    ok: true,
+    status: 200,
+    json: async () => JSON.parse(body),
+    text: async () => body,
+  };
+}
+
 function jsonResponse(body) {
   return {
     ok: true,

package/templates/base/tools/builder/core/seo/ssr/ssr-polyfills.test.js.hbs

@@ -0,0 +1,48 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { resolveFetch } from './ssr-polyfills.js';
+
+describe('resolveFetch (SSR fetch shim)', () => {
+  let staticDir;
+
+  beforeEach(() => {
+    staticDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nutin-ssr-fetch-'));
+    fs.mkdirSync(path.join(staticDir, 'generated'));
+    fs.writeFileSync(path.join(staticDir, 'generated', 'docs.json'), '{"pages":{"a":1}}');
+    fs.writeFileSync(path.join(staticDir, 'notes.txt'), 'plain text');
+  });
+
+  afterEach(() => {
+    fs.rmSync(staticDir, { recursive: true, force: true });
+  });
+
+  it('serves a mockFetch entry first', async () => {
+    const response = await resolveFetch('/generated/docs.json', { mockFetch: { '/generated/docs.json': { mocked: true } }, staticDir });
+
+    expect(await response.json()).toEqual({ mocked: true });
+  });
+
+  it('serves a file the build wrote, parsed as JSON for .json', async () => {
+    const response = await resolveFetch('/generated/docs.json?v=1', { staticDir });
+
+    expect(response.ok).toBeTruthy();
+    expect(await response.json()).toEqual({ pages: { a: 1 } });
+  });
+
+  it('serves other built files as text', async () => {
+    const response = await resolveFetch('/notes.txt', { staticDir });
+
+    expect(await response.text()).toBe('plain text');
+  });
+
+  it('refuses paths escaping the build folder', async () => {
+    await expect(() => resolveFetch('/../../etc/hosts', { staticDir })).toThrow('Unexpected fetch');
+    await expect(() => resolveFetch('/%2e%2e/%2e%2e/etc/hosts', { staticDir })).toThrow('Unexpected fetch');
+  });
+
+  it('still throws for an unknown endpoint', async () => {
+    await expect(() => resolveFetch('/api/users', { staticDir })).toThrow('Unexpected fetch');
+    await expect(() => resolveFetch('https://api.test/users', { staticDir })).toThrow('Unexpected fetch');
+  });
+});

package/templates/base/tools/builder/core/seo/ssr/ssr-render.js.hbs

@@ -15,24 +15,28 @@ export async function getAppRoutePaths(bundleUrl, lang, pageUrl) {
   // window.location.pathname, so a location-less window crashes as soon as the
   // bundle's module-load side effects instantiate I18n.getInstance().
   const { window } = parseHTML('<!doctype html><html><body></body></html>', { location: new URL(pageUrl) });
-  installGlobals(window, { lang });
+  installGlobals(window, { lang, localesDir: path.join(PATHS.tempSource, 'locales') });
   const bundle = await import(`${bundleUrl}?ssr=routes-check`);
   return Object.keys(bundle.appRoutes);
 }
 
 /**
- * Renders one (route, lang) pair by instantiating the real View via appRoutes and calling
- * .render(), returning the resulting real markup. Fresh linkedom window + cache-busted
+ * Renders one (route, lang) pair by running the route's guards, then instantiating the real
+ * View via appRoutes and calling .render(). Returns `{ html }`, or `{ blocked, redirectTo }`
+ * when a guard refuses the route. Fresh linkedom window + cache-busted
  * dynamic import per call, so no singleton state (I18nService, etc.) leaks between renders.
  */
 export async function renderRoute({ bundleUrl, appRoutesKey, mockParams, mockFetch, lang, pageUrl, i18nEnabled }) {
   // Passing a real URL instance as `location` gives `.pathname`/`.href`
   // which is what I18n's getLocaleFromUrl() actually reads.
-  const { window } = parseHTML('<!doctype html><html><body></body></html>', { location: new URL(pageUrl) });
+  // <main id="app"> mirrors index.html's real mount target — View defaults to mounting
+  // there (view.ts), so the rendered tree is attached to `document` as in the browser.
+  const { window } = parseHTML('<!doctype html><html><body><main id="app"></main></body></html>', { location: new URL(pageUrl) });
   const { trackedFetches } = installGlobals(window, {
     lang,
     mockFetch: mockFetch ?? {},
     localesDir: path.join(PATHS.tempSource, 'locales'),
+    staticDir: PATHS.tempSource,
   });
 
   let Service;
@@ -41,7 +45,7 @@ export async function renderRoute({ bundleUrl, appRoutesKey, mockParams, mockFet
   try {
     const bundle = await import(`${bundleUrl}?ssr=${renderIndex++}`);
     ({ Service } = bundle);
-    const { appRoutes, I18nService, RouteGuardsManager, registerPipes } = bundle;
+    const { appRoutes, I18nService, RouteGuardsManager, SecurityHelper, registerPipes } = bundle;
 
     const routeConfig = appRoutes[appRoutesKey];
     if (!routeConfig) {
@@ -55,8 +59,17 @@ export async function renderRoute({ bundleUrl, appRoutesKey, mockParams, mockFet
 
     if (i18nEnabled) await I18nService.setCurrentLanguage(lang);
 
-    const viewConstructor = RouteGuardsManager.getViewConstructor(routeConfig);
-    const view = viewConstructor();
+    // The route's guards run as they would for an anonymous first visit (empty storage,
+    // no session): a blocked or redirected route must not ship as public static HTML.
+    // Running them in this bundle instance also keeps what loader guards fetched (e.g.
+    // a Markdown manifest) available to the view rendered below.
+    const guardResult = await RouteGuardsManager.processRouteGuards(routeConfig, pageUrl, mockParams ?? {});
+    if (!guardResult.allowed) {
+      return { blocked: true, redirectTo: guardResult.redirectTo };
+    }
+
+    // A lazy route's factory returns a Promise (its import() is inlined in this bundle).
+    const view = await guardResult.viewConstructor();
     constructorName = view.constructor.name;
 
     if (mockParams) view.setRouteParams(mockParams);
@@ -66,7 +79,11 @@ export async function renderRoute({ bundleUrl, appRoutesKey, mockParams, mockFet
     await Promise.all(trackedFetches);
     await Promise.resolve();
 
-    return element.outerHTML;
+    // Nothing binds a prerendered page (the app re-renders it on load): Nutin's binding
+    // attributes (data-event, data-i18n, ...) are dropped, on the DOM so text is untouched.
+    SecurityHelper.stripBindingsFrom(element);
+
+    return { html: element.outerHTML };
   } catch (err) {
     throw new Error(
       `[ssr] Failed to render route "${appRoutesKey}" (lang "${lang}", view "${constructorName}"): ${err.message}${hintForError(err)}`,
@@ -88,7 +105,7 @@ function hintForError(err) {
     return (
       `\n  Hint: this usually means the component tree touches an unguarded browser global ` +
       `(e.g. "window", "navigator", "matchMedia") that isn't polyfilled for SSR — see ` +
-      `tools/builder/core/ssr/ssr-polyfills.js.`
+      `tools/builder/core/seo/ssr/ssr-polyfills.js.`
     );
   }
   return '';

package/templates/base/tools/builder/core/styles/sass.js.hbs

@@ -1,7 +1,7 @@
 import * as sass from 'sass';
 import * as fs from 'fs';
 import path from 'path';
-import { getFilesRecursive, print, errorExit } from '../../../utils/index.js';
+import { getFilesRecursive, errorExit } from '../../../utils/index.js';
 import { PATHS } from '../app/paths.js';
 import { builderConfig } from '../../builder.config.js';
 
@@ -13,24 +13,26 @@ const scssOrigins = builderConfig.sass.paths;
 const scssPath = (origin) => path.join(stylesPath, origin);
 const stylesInput = scssOrigins.map(origin => scssPath(origin));
 const pathsToLoad = [ ...stylesInput ];
+// resolves `@use "pkg:<package>/<subpath>"` through node_modules (package exports)
+const importers = [ new sass.NodePackageImporter() ];
 
 try {
   const mainResult = await sass.compileAsync(path.join(stylesPath, 'main.scss'), {
     loadPaths: [ ...pathsToLoad ],
+    importers,
     style: 'compressed'
   });
   fs.writeFileSync(stylesOutput, mainResult.css);
 
   // features styles
   const appInput = path.join(PATHS.source, 'app');
-  const appStyles = [
-    ...getFilesRecursive(path.join(appInput, 'components'), 'scss'),
-    ...getFilesRecursive(path.join(appInput, 'views'), 'scss')
-  ];
+  // Partials (_name.scss) only exist to be @use'd — compiling them standalone would duplicate their CSS.
+  const appStyles = getFilesRecursive(appInput, 'scss').filter((file) => !path.basename(file).startsWith('_'));
 
   for (const style of appStyles) {
     const result = await sass.compileAsync(style, {
       loadPaths: [ ...pathsToLoad ],
+      importers,
       style: 'compressed'
     })
     fs.appendFileSync(stylesOutput, result.css);