dh-remixer-sdk 0.0.45 → 0.0.46-4dc2bca

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dh-remixer-sdk",
-  "version": "0.0.45",
+  "version": "0.0.46-4dc2bca",
   "type": "module",
   "files": [
     "templates",

package/scripts/ssg-helmet/extract-routes.mjs

@@ -23,13 +23,13 @@ const strVal = (v) => {
   return null;
 };
 
-const walk = (n, f) => {
+const walk = (n, f, parent) => {
   if (!n || typeof n !== "object") return;
-  f(n);
+  f(n, parent);
   for (const k in n) {
     const v = n[k];
-    if (Array.isArray(v)) v.forEach((x) => walk(x, f));
-    else if (v && typeof v.type === "string") walk(v, f);
+    if (Array.isArray(v)) v.forEach((x) => walk(x, f, n));
+    else if (v && typeof v.type === "string") walk(v, f, n);
   }
 };
 
@@ -76,6 +76,275 @@ const parseSource = (src, filePath = "routes.tsx") => {
 const calleeName = (callee) =>
   callee?.type === "Identifier" ? callee.name : callee?.type === "MemberExpression" ? callee.property?.name : null;
 
+const ROUTER_SOURCES = new Set(["react-router", "react-router-dom"]);
+const SINGLE_PAGE_PACKAGES = new Set(["react", "react-helmet-async", "lucide-react"]);
+const SINGLE_PAGE_REACT_APIS = new Set([
+  "Fragment", "StrictMode", "createContext", "useContext", "useState", "useReducer",
+  "useEffect", "useLayoutEffect", "useInsertionEffect", "useMemo", "useCallback", "useRef",
+  "useId", "useTransition", "useDeferredValue", "useDebugValue", "useSyncExternalStore",
+]);
+const OPAQUE_RENDER_PROPS = new Set([
+  "ref", "dangerouslySetInnerHTML", "srcDoc", "script", "noscript", "htmlAttributes", "bodyAttributes",
+]);
+const OPAQUE_ELEMENTS = new Set(["script", "iframe", "object", "embed", "html", "body"]);
+const PATH_STATE_NAMES = new Set([
+  "window", "document", "globalThis", "self", "top", "parent", "frames",
+  "location", "history", "navigation", "pathname", "hash", "require", "eval", "Function",
+  "constructor", "__proto__", "createElement", "cloneElement",
+]);
+const GLOBAL_NAMES = new Set([
+  "undefined", "NaN", "Infinity", "Array", "Object", "String", "Number", "Boolean",
+  "Math", "JSON", "Date", "Intl", "Map", "Set", "RegExp", "Error", "console",
+]);
+const isFunction = (node) =>
+  ["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"].includes(node?.type);
+const isJsx = (node) => ["JSXElement", "JSXFragment"].includes(node?.type);
+const definesComponent = (node) => isFunction(node) || ["ClassDeclaration", "ClassExpression"].includes(node?.type);
+const importedName = (specifier) =>
+  specifier.type === "ImportDefaultSpecifier" ? "default" : specifier.imported?.name ?? "*";
+
+const bindPattern = (node, bindings) => {
+  if (!node) return;
+  if (node.type === "Identifier") bindings.add(node);
+  else if (node.type === "RestElement") bindPattern(node.argument, bindings);
+  else if (node.type === "AssignmentPattern") bindPattern(node.left, bindings);
+  else if (node.type === "ArrayPattern") node.elements.forEach((element) => bindPattern(element, bindings));
+  else if (node.type === "ObjectPattern") {
+    node.properties.forEach((property) => bindPattern(property.value ?? property.argument, bindings));
+  }
+};
+
+const functionReturn = (node) => {
+  if (!isFunction(node) || node.async || node.generator || node.params.length) return null;
+  if (node.body.type !== "BlockStatement") return node.body;
+  const last = node.body.body.at(-1);
+  let returns = 0;
+  const visit = (child) => {
+    if (!child || typeof child !== "object" || isFunction(child)) return;
+    if (child.type === "ReturnStatement") returns += 1;
+    for (const value of Object.values(child)) {
+      if (Array.isArray(value)) value.forEach(visit);
+      else if (value && typeof value.type === "string") visit(value);
+    }
+  };
+  visit(node.body);
+  return returns === 1 && last?.type === "ReturnStatement" ? last.argument : null;
+};
+
+const isNullLocationHelper = (ast, component) => {
+  const returned = functionReturn(component);
+  if (returned?.type !== "Literal" || returned.value !== null || component.body.type !== "BlockStatement") return false;
+  if (ast.body.some((node) =>
+    !["ImportDeclaration", "ExportDefaultDeclaration", "FunctionDeclaration"].includes(node.type))) return false;
+  if (ast.body.filter((node) => node.type === "FunctionDeclaration").some((node) => node !== component)) return false;
+  const imports = ast.body.filter((node) => node.type === "ImportDeclaration");
+  if (!imports.some((node) => ROUTER_SOURCES.has(node.source.value) &&
+    node.specifiers.some((specifier) => specifier.imported?.name === "useLocation"))) return false;
+  if (imports.some((node) => node.source.value !== "react" && !ROUTER_SOURCES.has(node.source.value))) return false;
+  if (imports.some((node) => node.specifiers.some((specifier) =>
+    specifier.type !== "ImportSpecifier" || specifier.local.name !== specifier.imported.name ||
+    !(node.source.value === "react" && specifier.imported.name === "useEffect" ||
+      ROUTER_SOURCES.has(node.source.value) && specifier.imported.name === "useLocation")))) return false;
+
+  const isCall = (node, name) =>
+    node?.type === "CallExpression" && node.callee.type === "Identifier" && node.callee.name === name;
+  const isLocation = (node) => isCall(node, "useLocation") && node.arguments.length === 0;
+  const isScroll = (node) => node?.type === "CallExpression" && node.callee.type === "MemberExpression" &&
+    !node.callee.computed && node.callee.object.name === "window" && node.callee.property.name === "scrollTo" &&
+    node.arguments.length === 2 &&
+    node.arguments.every((argument) => argument.type === "Literal" && typeof argument.value === "number");
+  const locations = new Set();
+  const pathnames = new Set();
+  for (const statement of component.body.body.slice(0, -1)) {
+    if (statement.type === "VariableDeclaration" && statement.declarations.length === 1) {
+      const { id, init } = statement.declarations[0];
+      if (!isLocation(init)) return false;
+      if (id.type === "Identifier") locations.add(id.name);
+      else if (id.type === "ObjectPattern" && id.properties.length === 1 &&
+        id.properties[0].type === "Property" && id.properties[0].key.name === "pathname" &&
+        id.properties[0].value.type === "Identifier") pathnames.add(id.properties[0].value.name);
+      else return false;
+      continue;
+    }
+    if (statement.type !== "ExpressionStatement") return false;
+    const expression = statement.expression;
+    if (isLocation(expression)) continue;
+    if (!isCall(expression, "useEffect") || expression.arguments.length !== 2 ||
+      !imports.some((node) => node.source.value === "react" && node.specifiers.some((specifier) => specifier.imported?.name === "useEffect"))) return false;
+    const [effect, dependencies] = expression.arguments;
+    if (!isFunction(effect) || effect.params.length || effect.async || effect.generator) return false;
+    const effects = effect.body.type === "BlockStatement"
+      ? effect.body.body
+      : [{ type: "ExpressionStatement", expression: effect.body }];
+    if (!effects.length || effects.some((entry) =>
+      entry.type !== "ExpressionStatement" || !isScroll(entry.expression))) return false;
+    if (dependencies.type !== "ArrayExpression" || dependencies.elements.some((entry) =>
+      !(entry?.type === "Identifier" && (locations.has(entry.name) || pathnames.has(entry.name)) ||
+        entry?.type === "MemberExpression" && !entry.computed && locations.has(entry.object.name) && entry.property.name === "pathname"))) return false;
+  }
+  return true;
+};
+
+export function singlePageFromSource(src, filePath, trusted = false) {
+  const ast = parseSource(src, filePath);
+  if (!ast || !ast.body.length) return { eligible: false, app: false, imports: [], exports: [], components: [] };
+
+  const declarations = new Map();
+  const bindings = new Set();
+  const imports = [];
+  const exportValues = new Map();
+  const elements = new Set();
+  const writes = new Set();
+  walk(ast, (node) => {
+    if (node.type === "JSXOpeningElement" && node.name.type === "JSXIdentifier" && !/^[a-z]/.test(node.name.name)) {
+      elements.add(node.name.name);
+    }
+    if (["AssignmentExpression", "ForInStatement", "ForOfStatement"].includes(node.type)) bindPattern(node.left, writes);
+    if (node.type === "UpdateExpression") bindPattern(node.argument, writes);
+  });
+  const written = new Set([...writes].map((node) => node.name));
+  const local = (name) => !written.has(name) && declarations.get(name);
+  for (const node of ast.body) {
+    const declaration = node.declaration ?? node;
+    if (declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") {
+      if (declaration.id) declarations.set(declaration.id.name, declaration);
+    }
+    if (declaration.type === "VariableDeclaration") {
+      for (const entry of declaration.declarations) {
+        if (entry.id.type === "Identifier") declarations.set(entry.id.name, entry.init);
+      }
+    }
+    if (node.type === "ImportDeclaration") {
+      imports.push({
+        source: node.source.value,
+        names: node.specifiers.map(importedName),
+        elements: node.specifiers.filter((specifier) => elements.has(specifier.local.name)).map(importedName),
+      });
+      node.specifiers.forEach((specifier) => declarations.set(specifier.local.name, specifier));
+    }
+    if (node.type === "ExportDefaultDeclaration") exportValues.set("default", declaration.id ?? declaration);
+    if (node.type === "ExportNamedDeclaration") {
+      if (declaration.id) exportValues.set(declaration.id.name, declaration.id);
+      if (declaration.type === "VariableDeclaration") {
+        for (const entry of declaration.declarations) if (entry.id.type === "Identifier") exportValues.set(entry.id.name, entry.id);
+      }
+      for (const specifier of node.specifiers) exportValues.set(specifier.exported.name, specifier.local);
+    }
+  }
+  const exportNames = [...exportValues.keys()];
+  const components = [...exportValues]
+    .filter(([, value]) => definesComponent(value.type === "Identifier" ? local(value.name) : value))
+    .map(([name]) => name);
+  const exported = ast.body.find((node) => node.type === "ExportDefaultDeclaration")?.declaration;
+  const component = exported?.type === "Identifier" ? declarations.get(exported.name) : exported;
+  const app = isJsx(functionReturn(component));
+  if (trusted || isNullLocationHelper(ast, component)) {
+    return { eligible: true, app, imports, exports: exportNames, components };
+  }
+
+  let eligible = true;
+  const routerBindings = new Set();
+  const reactBindings = new Set();
+  for (const node of ast.body.filter((entry) => entry.type === "ImportDeclaration")) {
+    const source = node.source.value;
+    if (source === "react") {
+      if (node.specifiers.some((specifier) => specifier.type === "ImportSpecifier" &&
+        !SINGLE_PAGE_REACT_APIS.has(specifier.imported.name))) eligible = false;
+      node.specifiers.filter((specifier) => specifier.type !== "ImportSpecifier")
+        .forEach((specifier) => reactBindings.add(specifier.local.name));
+    }
+    if (source.startsWith(".") || source.startsWith("@/")) {
+      if (node.specifiers.some((specifier) => specifier.type === "ImportNamespaceSpecifier")) eligible = false;
+    } else if (ROUTER_SOURCES.has(source)) {
+      if (!node.specifiers.length || node.specifiers.some((specifier) =>
+        specifier.type !== "ImportSpecifier" || specifier.imported.name !== "BrowserRouter" || specifier.local.name !== "BrowserRouter")) eligible = false;
+      else routerBindings.add("BrowserRouter");
+    } else if (!SINGLE_PAGE_PACKAGES.has(source)) eligible = false;
+  }
+  const parents = new Map();
+  const scopes = new Map();
+  walk(ast, (node, parent) => parents.set(node, parent));
+  const scopeFor = (node, hoisted = false) => {
+    while (node && node !== ast && !isFunction(node) &&
+      (hoisted || !["BlockStatement", "CatchClause", "ForStatement", "ForOfStatement", "ForInStatement", "SwitchStatement"].includes(node.type))) {
+      node = parents.get(node);
+    }
+    return node ?? ast;
+  };
+  const declare = (pattern, scope) => {
+    const declared = new Set();
+    bindPattern(pattern, declared);
+    if (!scopes.has(scope)) scopes.set(scope, new Set());
+    for (const binding of declared) {
+      bindings.add(binding);
+      scopes.get(scope).add(binding.name);
+    }
+  };
+  walk(ast, (node, parent) => {
+    if (node.type === "VariableDeclarator") declare(node.id, scopeFor(parent, parent.kind === "var"));
+    if (isFunction(node)) {
+      if (node.id) declare(node.id, node.type === "FunctionDeclaration" ? scopeFor(parent) : node);
+      node.params.forEach((parameter) => declare(parameter, node));
+    }
+    if (node.type === "ClassDeclaration" && node.id) declare(node.id, scopeFor(parent));
+    if (node.type === "CatchClause") declare(node.param, node);
+    if (node.type === "ImportDeclaration") node.specifiers.forEach((specifier) => declare(specifier.local, ast));
+  });
+  const scopeOf = (node) => {
+    let current = node;
+    while (current && !scopes.get(current)?.has(node.name)) current = parents.get(current);
+    return current;
+  };
+  walk(ast, (node, parent) => {
+    if (["ImportExpression", "ThisExpression", "MetaProperty", "ExportAllDeclaration"].includes(node.type)) eligible = false;
+    if (node.type === "ExportNamedDeclaration" && node.source) eligible = false;
+    if (node.type === "MemberExpression" && node.computed &&
+      (node.property.type !== "Literal" || PATH_STATE_NAMES.has(node.property.value))) eligible = false;
+    if (node.type === "Property") {
+      const name = node.key.type === "Identifier" && !node.computed ? node.key.name : node.key.value;
+      if (node.computed && node.key.type !== "Literal" ||
+        PATH_STATE_NAMES.has(name) || OPAQUE_RENDER_PROPS.has(name)) eligible = false;
+    }
+    if (node.type === "JSXSpreadAttribute") eligible = false;
+    if (node.type === "JSXAttribute") {
+      const name = attrName(node);
+      if (OPAQUE_RENDER_PROPS.has(name)) eligible = false;
+      if (/^on[A-Z]/.test(name)) {
+        const handler = node.value?.expression;
+        if (!isFunction(handler) || handler.params.length) eligible = false;
+      }
+    }
+    if (node.type === "Identifier") {
+      if (PATH_STATE_NAMES.has(node.name)) eligible = false;
+      if (reactBindings.has(node.name) &&
+        !["ImportDefaultSpecifier", "ImportNamespaceSpecifier"].includes(parent?.type) &&
+        !(parent?.type === "MemberExpression" && parent.object === node && !parent.computed &&
+          SINGLE_PAGE_REACT_APIS.has(parent.property.name))) eligible = false;
+      const property = parent?.type === "MemberExpression" && parent.property === node && !parent.computed ||
+        parent?.type === "Property" && parent.key === node && !parent.computed && !parent.shorthand;
+      const specifier = ["ImportSpecifier", "ExportSpecifier"].includes(parent?.type);
+      if (!property && !specifier && !bindings.has(node) &&
+        !scopeOf(node) && !GLOBAL_NAMES.has(node.name)) eligible = false;
+      if (routerBindings.has(node.name) && !specifier) eligible = false;
+    }
+    if (node.type === "JSXOpeningElement") {
+      const name = node.name;
+      if (name.type === "JSXMemberExpression") {
+        if (name.object.type !== "JSXIdentifier" || !reactBindings.has(name.object.name) ||
+          !["Fragment", "StrictMode"].includes(name.property.name)) eligible = false;
+      } else if (name.type !== "JSXIdentifier") eligible = false;
+      else if (OPAQUE_ELEMENTS.has(name.name.toLowerCase())) eligible = false;
+      else if (name.name === "BrowserRouter") {
+        if (!routerBindings.has(name.name) || node.attributes.length) eligible = false;
+      } else if (name.name === "Route" || name.name === "Routes" ||
+        NON_PATH_ROUTERS.has(name.name) || PATH_ROUTERS.has(name.name)) eligible = false;
+      else if (!/^[a-z]/.test(name.name) && (scopeOf(name) !== ast || !definesComponent(local(name.name)) &&
+        !["ImportSpecifier", "ImportDefaultSpecifier"].includes(local(name.name)?.type))) eligible = false;
+    }
+  });
+  return { eligible, app, imports, exports: exportNames, components };
+}
+
 export function routeTableFromSource(src, filePath) {
   const ast = parseSource(src, filePath);
   if (!ast) return { patterns: [], routeCount: 0, complete: false, notFoundCatchAll: false };

package/scripts/ssg-helmet/route-patterns.mjs

@@ -1,35 +1,88 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { hasRouter } from "./has-router.mjs";
-import { routeTableFromSource } from "./extract-routes.mjs";
+import { routeTableFromSource, singlePageFromSource } from "./extract-routes.mjs";
 
 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "out", ".next", "public"]);
 const SOURCE_FILE_RE = /\.(?:tsx|jsx|ts|js|mjs)$/;
 const DECLARATION_FILE_RE = /\.d\.ts$/;
 const CATCH_ALL_PATTERN = "/*";
+const TEMPLATE_HELPERS = ["components/routing/ScrollTopRouting.tsx", "components/seo/SEOHead.tsx"];
 
-async function sourceFiles(dir) {
-  const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+async function sourceFiles(dir, scan) {
+  const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => {
+    scan.readable = false;
+    return [];
+  });
   const nested = await Promise.all(
     entries.map(async (entry) => {
       const fullPath = path.join(dir, entry.name);
-      if (entry.isDirectory()) return SKIP_DIRS.has(entry.name) ? [] : sourceFiles(fullPath);
+      if (SKIP_DIRS.has(entry.name)) return [];
+      if (entry.isDirectory()) return sourceFiles(fullPath, scan);
       const isSource = SOURCE_FILE_RE.test(entry.name) && !DECLARATION_FILE_RE.test(entry.name);
+      if (entry.isSymbolicLink()) scan.readable = false;
       return entry.isFile() && isSource ? [fullPath] : [];
     }),
   );
   return nested.flat();
 }
 
+async function canonicalSources() {
+  const templates = new URL("../../templates/", import.meta.url);
+  const filemap = await fs.readFile(new URL("base/filemap.json", templates), "utf8").then(JSON.parse).catch(() => ({}));
+  const sources = await Promise.all([
+    ...Object.entries(filemap).map(([source, target]) => [`base/${source}`, target]),
+    ...TEMPLATE_HELPERS.map((target) => [`landing-page/${target}`, target]),
+  ]
+    .filter(([, target]) => SOURCE_FILE_RE.test(target))
+    .map(async ([source, target]) => [target, await fs.readFile(new URL(source, templates), "utf8").catch(() => null)]));
+  return new Map(sources);
+}
+
+async function importsResolved(files, sourceDir) {
+  const extensions = ["", ".tsx", ".jsx", ".ts", ".js", ".mjs", "/index.tsx", "/index.jsx", "/index.ts", "/index.js", "/index.mjs"];
+  for (const [file, analysis] of files) {
+    for (const { source, names, elements } of analysis.imports) {
+      if (!source.startsWith(".") && !source.startsWith("@/")) continue;
+      const base = source.startsWith("@/")
+        ? path.resolve(sourceDir, source.slice(2))
+        : path.resolve(path.dirname(file), source);
+      const relative = path.relative(sourceDir, base);
+      if (relative.startsWith("..") || path.isAbsolute(relative)) return false;
+      const resolved = extensions.map((extension) => files.get(`${base}${extension}`)).find(Boolean);
+      if (resolved) {
+        if (names.some((name) => !resolved.exports.includes(name)) ||
+          elements.some((name) => !resolved.components.includes(name))) return false;
+      } else {
+        if (elements.length || !/\.(?:css|json|svg|png|jpe?g|gif|webp|woff2?)$/.test(base)) return false;
+        if (!await fs.stat(base).then((stat) => stat.isFile()).catch(() => false)) return false;
+      }
+    }
+  }
+  return true;
+}
+
 export async function collectRouteTable(sourceDir) {
+  if (typeof sourceDir !== "string" || !sourceDir) {
+    return { routerFound: false, complete: false, hasCatchAll: false, patterns: ["/"] };
+  }
   let routerFound = false;
   let complete = true;
   let routeCount = 0;
   let notFoundCatchAll = false;
   const declared = new Set();
+  const scan = { readable: true };
+  const sources = new Map();
+  const canonical = await canonicalSources();
+  sourceDir = path.resolve(sourceDir);
 
-  for (const file of (await sourceFiles(sourceDir)).sort()) {
-    const src = await fs.readFile(file, "utf8").catch(() => "");
+  for (const file of (await sourceFiles(sourceDir, scan)).sort()) {
+    const src = await fs.readFile(file, "utf8").catch(() => {
+      scan.readable = false;
+      return "";
+    });
+    const trusted = canonical.get(path.relative(sourceDir, file).split(path.sep).join("/")) === src;
+    sources.set(file, singlePageFromSource(src, file, trusted));
     if (!hasRouter(src)) continue;
     routerFound = true;
 
@@ -40,9 +93,14 @@ export async function collectRouteTable(sourceDir) {
     for (const pattern of table.patterns) declared.add(pattern);
   }
 
+  const apps = [...sources].filter(([file]) => /^App\.(?:tsx|jsx|ts|js|mjs)$/.test(path.basename(file)));
+  const rootOnly = scan.readable && sources.size > 0 && routeCount === 0 &&
+    apps.length === 1 && apps[0][1].app && [...sources.values()].every((source) => source.eligible) &&
+    await importsResolved(sources, sourceDir);
+
   return {
     routerFound,
-    complete: routerFound && complete && routeCount > 0 && notFoundCatchAll,
+    complete: (routerFound && complete && routeCount > 0 && notFoundCatchAll) || rootOnly,
     hasCatchAll: declared.has(CATCH_ALL_PATTERN),
     patterns: [...new Set(["/", ...declared])]
       .filter((pattern) => pattern !== CATCH_ALL_PATTERN)

package/scripts/ssg-helmet/route-patterns.test.mjs

@@ -1,4 +1,5 @@
-import { test } from "node:test";
+import { test, mock } from "node:test";
+import fsPromises from "node:fs/promises";
 import assert from "node:assert/strict";
 import fs from "node:fs";
 import os from "node:os";
@@ -73,7 +74,7 @@ test("routes declared in a second router file are part of the table", async () =
   assert.deepEqual(table.patterns, ["/", "/blog/:slug"]);
 });
 
-test("a single-page site with only a router import gets an incomplete table with its home", async () => {
+test("a single-page site with an incidental null-rendering location helper is complete", async () => {
   const table = await collectRouteTable(
     siteWith({
       "App.tsx": `export default function App() { return <main />; }`,
@@ -81,13 +82,13 @@ test("a single-page site with only a router import gets an incomplete table with
     }),
   );
 
-  assert.deepEqual(table, { routerFound: true, complete: false, hasCatchAll: false, patterns: ["/"] });
+  assert.deepEqual(table, { routerFound: true, complete: true, hasCatchAll: false, patterns: ["/"] });
 });
 
-test("a site without any router has no table", async () => {
+test("a plain default-exported App is complete without claiming a router or catch-all", async () => {
   const table = await collectRouteTable(siteWith({ "App.tsx": `export default () => <main />;` }));
 
-  assert.equal(table.routerFound, false);
+  assert.deepEqual(table, { routerFound: false, complete: true, hasCatchAll: false, patterns: ["/"] });
 });
 
 test("splat routes are never prerendered as a page", async () => {
@@ -186,3 +187,359 @@ test("a router file that does not parse makes the table incomplete", async () =>
 
   assert.equal(table.complete, false);
 });
+
+const SINGLE_PAGE = `export default function App() { return <main>Home</main>; }`;
+
+for (const source of [
+  SINGLE_PAGE,
+  `const App = () => <main />; export default App;`,
+  `import { BrowserRouter } from "react-router-dom"; export default () => <BrowserRouter><main /></BrowserRouter>;`,
+]) {
+  test(`a supported root-only App is complete: ${source}`, async () => {
+    const table = await collectRouteTable(siteWith({ "App.tsx": source }));
+    assert.deepEqual(table, {
+      routerFound: source.includes("react-router-dom"),
+      complete: true,
+      hasCatchAll: false,
+      patterns: ["/"],
+    });
+  });
+}
+
+test("a resolved local component and a null scroll helper remain root-only", async () => {
+  const table = await collectRouteTable(siteWith({
+    "App.tsx": `import Home from "./Home"; export default () => <Home />;`,
+    "Home.tsx": `export default () => <main>Home</main>;`,
+    "Scroll.tsx": `import { useEffect } from "react";
+import { useLocation } from "react-router-dom";
+export default function Scroll() {
+  const { pathname } = useLocation();
+  useEffect(() => { window.scrollTo(0, 0); }, [pathname]);
+  return null;
+}`,
+  }));
+  assert.equal(table.complete, true);
+});
+
+test("Helmet title, meta and link props remain root-only", async () => {
+  const table = await collectRouteTable(siteWith({
+    "App.tsx": `import { Helmet, HelmetProvider } from "react-helmet-async";
+export default function App() {
+  return <HelmetProvider><main><Helmet title="Home" meta={[{ name: "description", content: "Welcome" }]} link={[{ rel: "canonical", href: "https://one-page.example/" }]} /><h1>Home</h1></main></HelmetProvider>;
+}`,
+  }));
+  assert.deepEqual(table, { routerFound: false, complete: true, hasCatchAll: false, patterns: ["/"] });
+});
+
+test("a public dispatcher loaded through Helmet cannot certify a root-only table", async (t) => {
+  const dir = siteWith({
+    "App.tsx": `import { Helmet } from "react-helmet-async";
+export default function App() {
+  return <main><Helmet script={[{ src: "/dispatcher.js", async: true }]} /><h1>Home</h1></main>;
+}`,
+    "public/dispatcher.js": `if (location.pathname === "/about") document.querySelector("main").innerHTML = "<h1>About</h1>";`,
+  });
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+  assert.deepEqual(await collectRouteTable(dir), {
+    routerFound: false, complete: false, hasCatchAll: false, patterns: ["/"],
+  });
+});
+
+test("Helmet title and meta children with imported components remain root-only", async () => {
+  const table = await collectRouteTable(siteWith({
+    "App.tsx": `import { Helmet } from "react-helmet-async";
+import { Hero } from "./Hero";
+import Footer from "./Footer";
+export default function App() {
+  return <main><Helmet><title>Home</title><meta name="description" content="Welcome" /></Helmet><Hero /><Footer /></main>;
+}`,
+    "Hero.tsx": `export function Hero() { return <h1>Home</h1>; }`,
+    "Footer.tsx": `const Footer = () => <footer />; export default Footer;`,
+  }));
+  assert.deepEqual(table, { routerFound: false, complete: true, hasCatchAll: false, patterns: ["/"] });
+});
+
+for (const [label, files] of [
+  ["named string", {
+    "App.tsx": `import { Helmet } from "react-helmet-async"; import { Body } from "./tags"; export default () => <main><Helmet><Body onload='if (location.pathname === "/about") document.body.textContent = "About";' /></Helmet></main>;`,
+    "tags.ts": `export const Body = "body";`,
+  }],
+  ["default string", {
+    "App.tsx": `import Script from "./Script"; export default () => <main><Script async src="/dispatcher.js" /></main>;`,
+    "Script.ts": `export default "script";`,
+  }],
+  ["reassigned export", {
+    "App.tsx": `import { Page } from "./Page"; export default () => <main><Page async src="/dispatcher.js" /></main>;`,
+    "Page.tsx": `export let Page = () => <main />; export const swap = () => { Page = "script"; };`,
+  }],
+  ["JSON value", {
+    "App.tsx": `import Script from "./tag.json"; export default () => <main><Script async src="/dispatcher.js" /></main>;`,
+    "tag.json": `"script"`,
+  }],
+]) {
+  test(`an imported non-component element type cannot certify a root-only table: ${label}`, async () => {
+    assert.equal((await collectRouteTable(siteWith(files))).complete, false);
+  });
+}
+
+const UNSUPPORTED_SINGLE_PAGES = [
+  ["empty Routes", `import { Routes } from "react-router-dom"; export default () => <Routes />;`],
+  ["aliased Routes", `import { Routes as R } from "react-router-dom"; export default () => <R />;`],
+  ["namespace router", `import * as RR from "react-router-dom"; export default () => <RR.BrowserRouter><main /></RR.BrowserRouter>;`],
+  ["aliased BrowserRouter", `import { BrowserRouter as B } from "react-router-dom"; export default () => <B><main /></B>;`],
+  ["indirect BrowserRouter", `import { BrowserRouter } from "react-router-dom"; const B = BrowserRouter; export default () => <B><main /></B>;`],
+  ["computed router", `import * as RR from "react-router-dom"; const B = RR["BrowserRouter"]; export default () => <B />;`],
+  ["useRoutes", `import { useRoutes } from "react-router-dom"; export default function App() { return useRoutes([]); }`],
+  ["aliased data router", `import { createBrowserRouter as make } from "react-router-dom"; const r = make([]); export default () => <main />;`],
+  ["wouter", `import { Router } from "wouter"; export default () => <Router><main /></Router>;`],
+  ["tanstack", `import { RouterProvider } from "@tanstack/react-router"; export default () => <RouterProvider />;`],
+  ["unknown external dispatcher", `import Page from "custom-pages"; export default () => <Page />;`],
+  ["basename", `import { BrowserRouter } from "react-router-dom"; export default () => <BrowserRouter basename="/shop"><main /></BrowserRouter>;`],
+  ["spread router", `import { BrowserRouter } from "react-router-dom"; const config = {}; export default () => <BrowserRouter {...config}><main /></BrowserRouter>;`],
+  ["pathname rendering", `export default () => window.location.pathname === "/" ? <main /> : <aside />;`],
+  ["DOM ref URL rendering", `import { useState } from "react"; export default function App() { const [page, setPage] = useState("Home"); return <main ref={node => { if (node) setPage(node.baseURI.endsWith("/about") ? "About" : "Home"); }}>{page}</main>; }`],
+  ["computed DOM ref URL rendering", `import { useState } from "react"; export default function App() { const [page, setPage] = useState("Home"); return <main ref={node => { if (node) setPage(node["base" + "URI"].endsWith("/about") ? "About" : "Home"); }}>{page}</main>; }`],
+  ["DOM event URL rendering", `import { useState } from "react"; export default function App() { const [page, setPage] = useState("Home"); return <main onClick={event => setPage(event.target.baseURI.endsWith("/about") ? "About" : "Home")}>{page}</main>; }`],
+  ["computed DOM event URL rendering", `import { useState } from "react"; export default function App() { const [page, setPage] = useState("Home"); return <main onClick={event => setPage(event.target["base" + "URI"].endsWith("/about") ? "About" : "Home")}>{page}</main>; }`],
+  ["spread DOM callbacks", `import { useState } from "react"; export default function App() { const [page, setPage] = useState("Home"); const props = { ref: node => node && setPage(node.baseURI) }; return <main {...props}>{page}</main>; }`],
+  ["opaque HTML", `export default () => <main dangerouslySetInnerHTML={{ __html: html }} />; const html = "<img onerror='alert(location.pathname)'>";`],
+  ["opaque script", `export default () => <main><script src="/dispatcher.js" /></main>;`],
+  ["aliased Helmet script", `import { Helmet as Head } from "react-helmet-async"; export default () => <main><Head script={[{ src: "/dispatcher.js", async: true }]} /></main>;`],
+  ["inline Helmet script", `import { Helmet } from "react-helmet-async"; export default () => <main><Helmet script={[{ innerHTML: 'if (location.pathname === "/about") document.body.textContent = "About";' }]} /></main>;`],
+  ["Helmet noscript HTML", `import { Helmet } from "react-helmet-async"; export default () => <main><Helmet noscript={[{ innerHTML: '<img src="/missing" onerror="alert(location.pathname)">' }]} /></main>;`],
+  ["Helmet body event attributes", `import { Helmet } from "react-helmet-async"; export default () => <main><Helmet bodyAttributes={{ onload: 'if (location.pathname === "/about") document.body.textContent = "About";' }} /></main>;`],
+  ["Helmet HTML event attributes", `import { Helmet } from "react-helmet-async"; export default () => <main><Helmet htmlAttributes={{ onload: 'if (location.pathname === "/about") document.body.textContent = "About";' }} /></main>;`],
+  ["Helmet body event child", `import { Helmet } from "react-helmet-async"; export default () => <main><Helmet><body onload='if (location.pathname === "/about") document.body.textContent = "About";' /></Helmet></main>;`],
+  ["Helmet HTML event child", `import { Helmet } from "react-helmet-async"; export default () => <main><Helmet><html onclick='if (location.pathname === "/about") document.body.textContent = "About";' /></Helmet></main>;`],
+  ["mixed-case opaque element", `export default () => <main><sCript src="/dispatcher.js" /></main>;`],
+  ["string element alias", `import { Helmet } from "react-helmet-async"; const Body = "body"; export default () => <main><Helmet><Body onload='if (location.pathname === "/about") document.body.textContent = "About";' /></Helmet></main>;`],
+  ["lowercase-free element alias", `const _script = "script"; export default () => <main><_script async src="/dispatcher.js" /></main>;`],
+  ["reassigned component", `let Page = () => <main />; Page = "script"; export default () => <main><Page async src="/dispatcher.js" /></main>;`],
+  ["shadowed component", `const Page = () => <main />; export default function App() { const Page = "script"; return <main><Page async src="/dispatcher.js" /></main>; }`],
+  ["quoted element-constructor destructuring", `import React, { useState } from "react"; const { "createElement": h } = React; export default function App() { const [page, setPage] = useState("Home"); return <main>{h("div", { ref: node => { if (node) setPage(node.baseURI.endsWith("/about") ? "About" : "Home"); } }, page)}</main>; }`],
+  ["computed element-constructor destructuring", `import React, { useState } from "react"; const key = "createElement"; const { [key]: h } = React; export default function App() { const [page, setPage] = useState("Home"); return <main>{h("div", { ref: node => node && setPage(node.baseURI) }, page)}</main>; }`],
+  ["reflected element constructor", `import React from "react"; const h = Object.getOwnPropertyDescriptor(React, "createElement").value; export default () => <main>{h("script", { src: "/dispatcher.js" })}</main>;`],
+  ["indirect element construction", `import { createElement as element } from "react"; export default () => <main>{element("div", { ref: node => node && node.baseURI })}</main>;`],
+  ["computed location", `const p = globalThis["location"]["pathname"]; export default () => <main>{p}</main>;`],
+  ["location destructuring", `const { location: current } = window; export default () => <main>{current.pathname}</main>;`],
+  ["rendering location hook", `import { useLocation } from "react-router-dom"; export default function App() { const p = useLocation(); return <main>{p.pathname}</main>; }`],
+  ["dynamic import", `import { lazy } from "react"; const Page = lazy(() => import("./Page")); export default () => <Page />;`],
+  ["require", `const Page = require("./Page"); export default () => <Page />;`],
+  ["unresolved default", `export default App;`],
+  ["unresolved JSX", `export default () => <Home />;`],
+  ["unresolved expression", `export default () => <main>{missing}</main>;`],
+  ["binding in a different scope", `function helper() { const missing = "other"; return missing; } export default () => <main>{missing}</main>;`],
+  ["aliased location hook", `import { useLocation as loc } from "react-router-dom"; export default function App() { const p = loc(); return <main>{p.pathname}</main>; }`],
+  ["null helper with a rendering effect", `import { useEffect } from "react"; import { useLocation } from "react-router-dom"; export default function App() { const { pathname } = useLocation(); useEffect(() => { document.body.innerHTML = pathname; }, [pathname]); return null; }`],
+  ["unresolved import", `import Home from "./missing"; export default () => <Home />;`],
+  ["unresolved named import", `import { Home } from "./Home"; export default () => <Home />;`],
+  ["non-rendering App", `export default function App() { return null; }`],
+  ["empty App", ``],
+  ["unparseable App", `export default () => <main;`],
+];
+
+for (const [label, source] of UNSUPPORTED_SINGLE_PAGES) {
+  test(`unsupported single-page analysis fails open: ${label}`, async () => {
+    const table = await collectRouteTable(siteWith({
+      "App.tsx": source,
+      "Home.tsx": `export const Other = () => <main />;`,
+      "Page.tsx": `export default () => <main />;`,
+    }));
+    assert.equal(table.complete, false);
+  });
+}
+
+test("missing source and files without an App cannot prove root-only completeness", async () => {
+  const dir = siteWith({});
+  for (const source of [undefined, null, "", dir, path.join(dir, "missing"), siteWith({ "Home.tsx": SINGLE_PAGE })]) {
+    assert.equal((await collectRouteTable(source)).complete, false);
+  }
+});
+
+for (const file of ["A.tsx", "Z.tsx", "lib/remixer/custom.tsx", "lib/custom.tsx"]) {
+  test(`an unsupported second application source vetoes root-only completeness: ${file}`, async () => {
+    for (const source of [
+      `import { useRoutes as routes } from "react-router-dom"; export const page = routes([]);`,
+      `export const Page = () => window.location.pathname === "/other" ? <aside /> : <main />;`,
+      `export const broken = <main;`,
+    ]) {
+      const table = await collectRouteTable(siteWith({ "App.tsx": SINGLE_PAGE, [file]: source }));
+      assert.equal(table.complete, false);
+    }
+  });
+}
+
+test("an unreadable application source cannot prove root-only completeness", async () => {
+  const dir = siteWith({ "App.tsx": SINGLE_PAGE, "Other.tsx": `export const other = 1;` });
+  const readFile = fsPromises.readFile.bind(fsPromises);
+  const mocked = mock.method(fsPromises, "readFile", async (file, ...args) => {
+    if (file === path.join(dir, "Other.tsx")) throw new Error("unreadable fixture");
+    return readFile(file, ...args);
+  });
+  try {
+    assert.equal((await collectRouteTable(dir)).complete, false);
+  } finally {
+    mocked.mock.restore();
+  }
+});
+
+const canonicalScaffold = () => {
+  const base = new URL("../../templates/base/", import.meta.url);
+  const filemap = JSON.parse(fs.readFileSync(new URL("filemap.json", base), "utf8"));
+  return {
+    ...Object.fromEntries(Object.entries(filemap)
+      .filter(([, target]) => /\.(?:ts|tsx)$/.test(target))
+      .map(([source, target]) => [target, fs.readFileSync(new URL(source, base), "utf8")])),
+    "App.tsx": SINGLE_PAGE,
+    "tailwind.config.ts": `export default {};`,
+    "fonts.ts": `export const GOOGLE_FONTS_URL = "https://fonts.googleapis.com/css2?family=Inter";`,
+    "index.css": "",
+  };
+};
+
+test("the byte-identical filemapped SDK bootstrap and SEO observer do not veto a single page", async () => {
+  const table = await collectRouteTable(siteWith(canonicalScaffold()));
+  assert.deepEqual(table, { routerFound: false, complete: true, hasCatchAll: false, patterns: ["/"] });
+});
+
+test("a modified canonical SEO helper that dispatches page content vetoes a single page", async () => {
+  const files = canonicalScaffold();
+  files["lib/remixer/seo.tsx"] = `export const RemixerSeo = () => window.location.pathname === "/other" ? <aside /> : <main />;`;
+  assert.equal((await collectRouteTable(siteWith(files))).complete, false);
+});
+
+test("a canonical filename or directory alone does not exempt a dispatcher", async () => {
+  for (const file of ["index.tsx", "lib/remixer/seo.tsx", "lib/remixer/custom.tsx", "lib/custom.tsx"]) {
+    const files = canonicalScaffold();
+    files[file] = `export const Dispatch = () => location.pathname === "/other" ? <aside /> : <main />;`;
+    assert.equal((await collectRouteTable(siteWith(files))).complete, false);
+  }
+});
+
+const LANDING_PAGE_HELPERS = ["components/routing/ScrollTopRouting.tsx", "components/seo/SEOHead.tsx"];
+const LANDING_PAGE_APP = `import { BrowserRouter } from "react-router-dom";
+import ScrollTopRouting from "@/components/routing/ScrollTopRouting";
+import Home from "@/pages/Home";
+
+export default function App() {
+  return (
+    <BrowserRouter>
+      <ScrollTopRouting />
+      <Home />
+    </BrowserRouter>
+  );
+}`;
+const DISPATCHER = `\nexport const Dispatch = () => location.pathname === "/other" ? <aside /> : <main />;\n`;
+
+const landingPageScaffold = (app = LANDING_PAGE_APP) => ({
+  ...canonicalScaffold(),
+  ...Object.fromEntries(LANDING_PAGE_HELPERS.map((file) =>
+    [file, fs.readFileSync(new URL(`../../templates/landing-page/${file}`, import.meta.url), "utf8")])),
+  "App.tsx": app,
+  "pages/Home.tsx": `import SEOHead from "@/components/seo/SEOHead";
+
+export default function Home() {
+  return (
+    <>
+      <SEOHead titleKey="Home" descriptionKey="Welcome to our one-page site." />
+      <main><h1>Home</h1></main>
+    </>
+  );
+}`,
+  "assets/images.json": "{}\n",
+});
+
+for (const [label, app] of [
+  ["a BrowserRouter App rendering Home", LANDING_PAGE_APP],
+  ["the bare template App", `import React from "react";\n\nconst App: React.FC = () => {\n  return <main />;\n};\n\nexport default App;\n`],
+]) {
+  test(`the byte-identical landing-page scroll and SEO helpers do not veto a single page: ${label}`, async () => {
+    const table = await collectRouteTable(siteWith(landingPageScaffold(app)));
+    assert.deepEqual(table, { routerFound: true, complete: true, hasCatchAll: false, patterns: ["/"] });
+  });
+}
+
+for (const [label, edit] of [
+  ...LANDING_PAGE_HELPERS.map((file) => [`modified ${file}`, (files) => { files[file] += DISPATCHER; }]),
+  ["SEO helper bytes at another path", (files) => {
+    files["components/seo/Head.tsx"] = files["components/seo/SEOHead.tsx"];
+    delete files["components/seo/SEOHead.tsx"];
+    files["pages/Home.tsx"] = files["pages/Home.tsx"].replace("components/seo/SEOHead", "components/seo/Head");
+  }],
+  ["SEO helper without its images manifest", (files) => { delete files["assets/images.json"]; }],
+]) {
+  test(`landing-page helpers are trusted only as the canonical file at the canonical path: ${label}`, async () => {
+    const files = landingPageScaffold();
+    edit(files);
+    assert.equal((await collectRouteTable(siteWith(files))).complete, false);
+  });
+}
+
+test("an unreadable source directory cannot prove root-only completeness", async () => {
+  const dir = siteWith({ "App.tsx": SINGLE_PAGE, "components/Other.tsx": `export const other = 1;` });
+  const readdir = fsPromises.readdir.bind(fsPromises);
+  const mocked = mock.method(fsPromises, "readdir", async (file, ...args) => {
+    if (file === path.join(dir, "components")) throw new Error("unreadable fixture");
+    return readdir(file, ...args);
+  });
+  try {
+    assert.equal((await collectRouteTable(dir)).complete, false);
+  } finally {
+    mocked.mock.restore();
+  }
+});
+
+test("a split-file data router vetoes a plain App even when its API is aliased", async () => {
+  const table = await collectRouteTable(siteWith({
+    "App.tsx": SINGLE_PAGE,
+    "router.ts": `import { createBrowserRouter as create } from "react-router-dom"; export const router = create([{ path: "/other" }]);`,
+  }));
+  assert.equal(table.complete, false);
+});
+
+test("a literal JSX route cannot become complete through the root-only branch", async () => {
+  const table = await collectRouteTable(siteWith({
+    "App.tsx": `import { BrowserRouter } from "react-router-dom"; export default () => <BrowserRouter><main /></BrowserRouter>;`,
+    "routes.tsx": `import { Route } from "react-router-dom"; export const Other = () => <Route path="/other" element={<aside />} />;`,
+  }));
+  assert.equal(table.complete, false);
+  assert.deepEqual(table.patterns, ["/", "/other"]);
+});
+
+test("a null arrow location helper fails open without throwing", async () => {
+  const table = await collectRouteTable(siteWith({
+    "App.tsx": SINGLE_PAGE,
+    "Helper.jsx": `import { useLocation } from "react-router-dom"; export default () => null;`,
+  }));
+  assert.equal(table.complete, false);
+});
+
+test("a zero-argument local-state event handler remains path-independent", async () => {
+  const table = await collectRouteTable(siteWith({
+    "App.tsx": `import { useState } from "react";
+export default function App() {
+  const [open, setOpen] = useState(false);
+  return <main><button onClick={() => setOpen(!open)}>Menu</button>{open ? <nav>Contact</nav> : null}</main>;
+}`,
+  }));
+  assert.deepEqual(table, { routerFound: false, complete: true, hasCatchAll: false, patterns: ["/"] });
+});
+
+test("ignored dependency directories remain ignored when symlinked", async () => {
+  const dir = siteWith({ "App.tsx": SINGLE_PAGE });
+  const dependency = siteWith({ "router.tsx": `export const Page = () => location.pathname;` });
+  fs.symlinkSync(dependency, path.join(dir, "node_modules"), "dir");
+  assert.equal((await collectRouteTable(dir)).complete, true);
+});
+
+test("direct React namespace hooks and fragments remain supported", async () => {
+  const table = await collectRouteTable(siteWith({
+    "App.tsx": `import React from "react";
+export default function App() {
+  const [open, setOpen] = React.useState(false);
+  return <React.Fragment><button onClick={() => setOpen(!open)}>Menu</button>{open ? <nav>Contact</nav> : null}</React.Fragment>;
+}`,
+  }));
+  assert.equal(table.complete, true);
+});

package/scripts/ssg-helmet/site-files.mjs

@@ -92,7 +92,7 @@ export async function writeIndexNowKeyFile(settings = SEO_SETTINGS) {
 }
 
 export async function writeRoutesJson(routeTable) {
-  if (routeTable?.routerFound) {
+  if (routeTable?.routerFound || routeTable?.complete === true) {
     await writeJsonFile("_routes.json", {
       complete: routeTable.complete === true,
       patterns: routeTable.patterns,

package/scripts/ssg-helmet/site-files.test.mjs

@@ -17,6 +17,7 @@ const {
   writeIndexNowKeyFile,
   writeRedirectsJson,
   writeRoutesJson,
+  writeSiteFiles,
 } = await import("./site-files.mjs");
 
 const { createRunClock } = await import("./run-clock.mjs");
@@ -52,15 +53,47 @@ test("_redirects.json is a bare array and is not written without redirects", asy
   assert.deepEqual(JSON.parse(readBuild("_redirects.json")), [{ from: "/drinks", to: "/menu" }]);
 });
 
-test("_routes.json carries the declared patterns only when a router was found", async () => {
-  await writeRoutesJson({ routerFound: false, hasCatchAll: false, patterns: ["/"] });
-  assert.equal(existsInBuild("_routes.json"), false);
+test("_routes.json carries declared router patterns and serializes completeness as strict true only", async () => {
+  const patterns = ["/", "/about", "/product/:id", "/blog/*"];
+  for (const complete of [true, false, undefined, "true", 1, [], {}]) {
+    await writeRoutesJson({ routerFound: true, complete, hasCatchAll: true, patterns });
+    assert.deepEqual(JSON.parse(readBuild("_routes.json")), { complete: complete === true, patterns });
+  }
+});
+
+test("_routes.json is written for a complete root-only table without a router", async () => {
+  fs.rmSync(path.join(BUILD_DIR, "_routes.json"), { force: true });
 
-  await writeRoutesJson({ routerFound: true, complete: true, hasCatchAll: true, patterns: ["/", "/about", "/product/:id", "/blog/*"] });
-  assert.deepEqual(JSON.parse(readBuild("_routes.json")), { complete: true, patterns: ["/", "/about", "/product/:id", "/blog/*"] });
+  await writeRoutesJson({ routerFound: false, complete: true, hasCatchAll: false, patterns: ["/"] });
 
-  await writeRoutesJson({ routerFound: true, complete: false, hasCatchAll: false, patterns: ["/"] });
-  assert.deepEqual(JSON.parse(readBuild("_routes.json")), { complete: false, patterns: ["/"] });
+  assert.deepEqual(JSON.parse(readBuild("_routes.json")), { complete: true, patterns: ["/"] });
+});
+
+test("_routes.json skips absent, unknown and incomplete tables without a router", async () => {
+  for (const routeTable of [
+    undefined,
+    null,
+    {},
+    { patterns: ["/"] },
+    { routerFound: false, hasCatchAll: false, patterns: ["/"] },
+    { routerFound: false, complete: false, hasCatchAll: false, patterns: ["/"] },
+  ]) {
+    fs.rmSync(path.join(BUILD_DIR, "_routes.json"), { force: true });
+
+    await writeRoutesJson(routeTable);
+
+    assert.equal(existsInBuild("_routes.json"), false);
+  }
+});
+
+test("truthy non-boolean completeness never authorizes a manifest without a router", async () => {
+  for (const complete of ["true", 1, [], {}]) {
+    fs.rmSync(path.join(BUILD_DIR, "_routes.json"), { force: true });
+
+    await writeRoutesJson({ routerFound: false, complete, hasCatchAll: false, patterns: ["/"] });
+
+    assert.equal(existsInBuild("_routes.json"), false);
+  }
 });
 
 test("without a prerendered not-found page a plain noindex page is written at the root", async () => {
@@ -167,3 +200,179 @@ test("without a catch-all the plain page is written and nothing is prerendered",
   assert.deepEqual(rendered, []);
   assert.match(readBuild("404.html"), /<h1>Page not found<\/h1>/);
 });
+
+const ROOT_ONLY_HOME = `<!doctype html><html lang="en"><head><title>Home</title>
+<script type="module" src="/assets/home.js"></script></head>
+<body><div id="root"><main><h1>Home</h1><p>Welcome to our one-page site.</p><a href="#contact">Contact</a></main></div></body></html>`;
+const ROOT_ONLY_APP = `export default function App() {
+  return <main><h1>Home</h1><p>Welcome to our one-page site.</p><a href="#contact">Contact</a></main>;
+}`;
+
+function landingPageSources() {
+  const templates = new URL("../../templates/", import.meta.url);
+  const read = (file) => fs.readFileSync(new URL(file, templates), "utf8");
+  const filemap = JSON.parse(read("base/filemap.json"));
+  return {
+    ...Object.fromEntries(Object.entries(filemap)
+      .filter(([, target]) => /\.(?:ts|tsx)$/.test(target))
+      .map(([source, target]) => [target, read(`base/${source}`)])),
+    "components/routing/ScrollTopRouting.tsx": read("landing-page/components/routing/ScrollTopRouting.tsx"),
+    "components/seo/SEOHead.tsx": read("landing-page/components/seo/SEOHead.tsx"),
+    "App.tsx": `import { BrowserRouter } from "react-router-dom";
+import ScrollTopRouting from "@/components/routing/ScrollTopRouting";
+import Home from "@/pages/Home";
+
+export default function App() {
+  return (
+    <BrowserRouter>
+      <ScrollTopRouting />
+      <Home />
+    </BrowserRouter>
+  );
+}`,
+    "pages/Home.tsx": `import SEOHead from "@/components/seo/SEOHead";
+
+export default function Home() {
+  return (
+    <>
+      <SEOHead titleKey="Home" descriptionKey="Welcome to our one-page site." />
+      <main><h1>Home</h1><p>Welcome to our one-page site.</p><a href="/#contact">Contact</a></main>
+    </>
+  );
+}`,
+    "assets/images.json": "{}\n",
+    "tailwind.config.ts": `export default {};`,
+    "fonts.ts": `export const GOOGLE_FONTS_URL = "https://fonts.googleapis.com/css2?family=Inter";`,
+    "index.css": "",
+  };
+}
+
+const ROOT_ONLY_SOURCES = [
+  {
+    name: "a plain default App",
+    files: { "App.tsx": ROOT_ONLY_APP },
+    routerFound: false,
+  },
+  {
+    name: "an incidental null location helper",
+    files: {
+      "App.tsx": `import { BrowserRouter } from "react-router-dom";
+import ScrollTopRouting from "./components/ScrollTopRouting";
+export default function App() {
+  return <BrowserRouter><ScrollTopRouting /><main><h1>Home</h1><p>Welcome to our one-page site.</p><a href="#contact">Contact</a></main></BrowserRouter>;
+}`,
+      "components/ScrollTopRouting.tsx": `import { useEffect } from "react";
+import { useLocation } from "react-router-dom";
+export default function ScrollTopRouting() {
+  const { pathname } = useLocation();
+  useEffect(() => { window.scrollTo(0, 0); }, [pathname]);
+  return null;
+}`,
+    },
+    routerFound: true,
+  },
+  {
+    name: "a BrowserRouter wrapper without route declarations",
+    files: {
+      "App.tsx": `import { BrowserRouter } from "react-router-dom";
+export default function App() {
+  return <BrowserRouter><main><h1>Home</h1><p>Welcome to our one-page site.</p><a href="#contact">Contact</a></main></BrowserRouter>;
+}`,
+    },
+    routerFound: true,
+  },
+  {
+    name: "the default landing-page template with its scroll and SEO helpers",
+    files: landingPageSources(),
+    routerFound: true,
+  },
+];
+
+async function writeCollectedSiteFiles(t, files, settings = SWITCHED_ON) {
+  const { collectRouteTable } = await import("./route-patterns.mjs");
+  const sourceDir = fs.mkdtempSync(path.join(os.tmpdir(), "site-files-source-"));
+  t.after(() => fs.rmSync(sourceDir, { recursive: true, force: true }));
+  for (const [file, content] of Object.entries(files)) {
+    const target = path.join(sourceDir, file);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, "utf8");
+  }
+  fs.rmSync(BUILD_DIR, { recursive: true, force: true });
+  fs.mkdirSync(BUILD_DIR, { recursive: true });
+  fs.writeFileSync(path.join(BUILD_DIR, "index.html"), ROOT_ONLY_HOME, "utf8");
+
+  const routeTable = await collectRouteTable(sourceDir);
+  const rendered = [];
+  await writeSiteFiles({ sitemapRoutes: ["/"], routeTable }, settings);
+  await writeNotFoundPageInTime(
+    { routeTable, prerender: async (route) => (rendered.push(route), ROOT_ONLY_HOME), clock: clockAt(0) },
+    settings,
+  );
+  return { routeTable, rendered };
+}
+
+for (const { name, files, routerFound } of ROOT_ONLY_SOURCES) {
+  test(`collector-to-artifacts: ${name} gets a complete root manifest and a plain 404 without changing Home`, async (t) => {
+    const { routeTable, rendered } = await writeCollectedSiteFiles(t, files);
+
+    assert.deepEqual(routeTable, { routerFound, complete: true, hasCatchAll: false, patterns: ["/"] });
+    assert.deepEqual(JSON.parse(readBuild("_routes.json")), { complete: true, patterns: ["/"] });
+    assert.match(readBuild("404.html"), /<meta name="robots" content="noindex" \/>/);
+    assert.match(readBuild("404.html"), /<title>Page not found \| Home<\/title>/);
+    assert.match(readBuild("404.html"), /<h1>Page not found<\/h1>/);
+    assert.match(readBuild("404.html"), /<a href="\/">Go to the home page<\/a>/);
+    assert.doesNotMatch(readBuild("404.html"), /<script|<h1>Home<\/h1>/i);
+    assert.equal(readBuild("index.html"), ROOT_ONLY_HOME);
+    assert.deepEqual(rendered, []);
+    assert.equal(existsInBuild(`${NOT_FOUND_PROBE_ROUTE.slice(1)}/index.html`), false);
+  });
+}
+
+test("collector-to-artifacts: unsupported pathname-driven rendering stays non-authoritative", async (t) => {
+  const { routeTable, rendered } = await writeCollectedSiteFiles(t, {
+    "App.tsx": `export default function App() {
+  return window.location.pathname === "/about" ? <main><h1>About</h1></main> : <main><h1>Home</h1></main>;
+}`,
+  });
+
+  assert.equal(routeTable.complete, false);
+  assert.equal(existsInBuild("_routes.json"), false);
+  assert.match(readBuild("404.html"), /<h1>Page not found<\/h1>/);
+  assert.doesNotMatch(readBuild("404.html"), /<script/i);
+  assert.equal(readBuild("index.html"), ROOT_ONLY_HOME);
+  assert.deepEqual(rendered, []);
+});
+
+for (const [form, helmet] of [
+  ["script prop", `<Helmet script={[{ src: "/dispatcher.js", async: true }]} />`],
+  ["body event child", `<Helmet><body onload='if (location.pathname === "/about") document.querySelector("main").innerHTML = "<h1>About</h1>";' /></Helmet>`],
+]) for (const routerFound of [false, true]) {
+  test(`collector-to-artifacts: an executable Helmet ${form} stays non-authoritative (routerFound: ${routerFound})`, async (t) => {
+    const { routeTable, rendered } = await writeCollectedSiteFiles(t, {
+      "App.tsx": `import { Helmet } from "react-helmet-async";
+${routerFound ? 'import { BrowserRouter } from "react-router-dom";' : ""}
+export default function App() {
+  return ${routerFound ? "<BrowserRouter>" : ""}<main>${helmet}<h1>Home</h1></main>${routerFound ? "</BrowserRouter>" : ""};
+}`,
+      "public/dispatcher.js": `if (location.pathname === "/about") document.querySelector("main").innerHTML = "<h1>About</h1>";`,
+    });
+
+    assert.deepEqual(routeTable, { routerFound, complete: false, hasCatchAll: false, patterns: ["/"] });
+    if (routerFound) assert.deepEqual(JSON.parse(readBuild("_routes.json")), { complete: false, patterns: ["/"] });
+    else assert.equal(existsInBuild("_routes.json"), false);
+    assert.equal(readBuild("index.html"), ROOT_ONLY_HOME);
+    assert.deepEqual(rendered, []);
+  });
+}
+
+test("collector-to-artifacts: SEO not switched on skips the root-only manifest and 404", async (t) => {
+  for (const settings of [{}, { siteUrl: "https://one-page.example-cdn.com", private: true }]) {
+    const { routeTable, rendered } = await writeCollectedSiteFiles(t, { "App.tsx": ROOT_ONLY_APP }, settings);
+
+    assert.equal(routeTable.complete, true);
+    assert.equal(existsInBuild("_routes.json"), false);
+    assert.equal(existsInBuild("404.html"), false);
+    assert.equal(readBuild("index.html"), ROOT_ONLY_HOME);
+    assert.deepEqual(rendered, []);
+  }
+});

package/templates/landing-page/components/routing/ScrollTopRouting.tsx

@@ -0,0 +1,29 @@
+import { useEffect } from "react";
+import { useLocation } from "react-router-dom";
+
+/**
+ * ScrollTopRouting component
+ * Automatically scrolls to top of page when route changes
+ * Must be placed inside Router component (BrowserRouter/HashRouter)
+ * before the Routes component
+ */
+function ScrollTopRouting() {
+  const { pathname, hash } = useLocation();
+
+  useEffect(() => {
+    if (hash) {
+      const id = hash.replace("#", "");
+      const el = document.getElementById(id);
+      if (el) {
+        setTimeout(() => el.scrollIntoView({ behavior: "smooth" }), 80);
+      }
+    } else {
+      window.scrollTo({ top: 0, left: 0, behavior: "instant" });
+    }
+  }, [pathname, hash]);
+
+  return null;
+}
+
+export default ScrollTopRouting;
+

package/templates/landing-page/components/seo/SEOHead.tsx

@@ -0,0 +1,111 @@
+import { useLayoutEffect } from "react";
+import { Helmet } from "react-helmet-async";
+import images from "@/assets/images.json";
+
+interface SEOHeadProps {
+  titleKey?: string;
+  descriptionKey?: string;
+  ogImage?: string;
+  ogImageKey?: string;
+  noindex?: boolean;
+}
+
+const SEOHEAD_MARK = { "data-seohead": "" };
+const CANONICAL_TAG = 'link[rel="canonical"]';
+const OG_URL_TAG = 'meta[property="og:url"]';
+const OG_SITE_NAME_TAG = 'meta[property="og:site_name"]';
+const STATIC_URL_TAGS = new Set(
+  typeof document === "undefined" ? [] : Array.from(document.head.querySelectorAll(`${CANONICAL_TAG}, ${OG_URL_TAG}`)),
+);
+
+function normalizePath(pathname: string) {
+  return pathname.replace(/\/+$/, "") || "/";
+}
+
+function currentPageUrl() {
+  if (typeof window === "undefined" || (window as Window & { __PRERENDER__?: boolean }).__PRERENDER__) {
+    return undefined;
+  }
+  return `${window.location.origin}${normalizePath(window.location.pathname)}`;
+}
+
+function foreignHeadTags(selector: string) {
+  if (typeof document === "undefined") {
+    return [];
+  }
+  return Array.from(document.head.querySelectorAll(`${selector}:not([data-seohead])`));
+}
+
+function foreignTagMatchesPage(selector: string, urlAttribute: string) {
+  const url = foreignHeadTags(selector)[0]?.getAttribute(urlAttribute);
+  if (!url) {
+    return false;
+  }
+  try {
+    return normalizePath(new URL(url, window.location.href).pathname) === normalizePath(window.location.pathname);
+  } catch {
+    return false;
+  }
+}
+
+function removeStaticTags(selector: string) {
+  foreignHeadTags(selector)
+    .filter((tag) => STATIC_URL_TAGS.has(tag))
+    .forEach((tag) => tag.remove());
+}
+
+// Canonical <head> for every page. Render exactly one <SEOHead /> per page
+// inside pages/*.tsx; no raw <Helmet> anywhere else. Pulls og:image from
+// assets/images.json by default so social sharing works without extra wiring.
+//
+// titleKey / descriptionKey take the DISPLAY VALUE: literal text on a
+// monolingual/inline site, or a pre-translated value (t('…')) when the project
+// externalizes text. The legacy prop names are kept on purpose — existing
+// projects ship a SEOHead with the same names (translating internally, where
+// t() falls back to the given string), so one prompt directive stays correct
+// for every project. No useLanguage() here: this component must not depend on
+// LanguageProvider.
+export function SEOHead({
+  titleKey = "Remixer AI by DreamHost",
+  descriptionKey = "AI website builder for everyone!",
+  ogImage,
+  ogImageKey = "og_image",
+  noindex = false,
+}: SEOHeadProps) {
+  const siteTitle = import.meta.env.VITE_METADATA_TITLE as string | undefined;
+  const metaTitle = siteTitle ? `${titleKey} | ${siteTitle}` : titleKey;
+  const resolvedOg =
+    ogImage ?? (images as Record<string, string>)[ogImageKey];
+  const pageUrl = currentPageUrl();
+  const ownsCanonical = pageUrl !== undefined && !foreignTagMatchesPage(CANONICAL_TAG, "href");
+  const ownsOgUrl = pageUrl !== undefined && !foreignTagMatchesPage(OG_URL_TAG, "content");
+  const ownsSiteName = Boolean(siteTitle) && foreignHeadTags(OG_SITE_NAME_TAG).length === 0;
+
+  useLayoutEffect(() => {
+    if (ownsCanonical) {
+      removeStaticTags(CANONICAL_TAG);
+    }
+    if (ownsOgUrl) {
+      removeStaticTags(OG_URL_TAG);
+    }
+  }, [ownsCanonical, ownsOgUrl, pageUrl]);
+
+  return (
+    <Helmet>
+      <title>{metaTitle}</title>
+      <meta name="description" content={descriptionKey} />
+      <meta property="og:title" content={metaTitle} />
+      <meta property="og:description" content={descriptionKey} />
+      <meta property="og:type" content="website" />
+      {resolvedOg ? <meta property="og:image" content={resolvedOg} /> : null}
+      <meta name="twitter:card" content="summary_large_image" />
+      {resolvedOg ? <meta name="twitter:image" content={resolvedOg} /> : null}
+      {ownsSiteName ? <meta property="og:site_name" content={siteTitle} {...SEOHEAD_MARK} /> : null}
+      {ownsOgUrl ? <meta property="og:url" content={pageUrl} {...SEOHEAD_MARK} /> : null}
+      {ownsCanonical ? <link rel="canonical" href={pageUrl} {...SEOHEAD_MARK} /> : null}
+      {noindex ? <meta name="robots" content="noindex" /> : null}
+    </Helmet>
+  );
+}
+
+export default SEOHead;