@jskit-ai/jskit-catalog 0.2.30 → 0.2.32

package/scripts/navigation.mjs

@@ -1,6 +1,19 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { blankJsComments, lineIndex, splitVue } from "./material3-source.mjs";
+import {
+  DEFAULT_IMPORT,
+  TEMPLATE_TAG,
+  VOID_TAGS,
+  balancedFrom,
+  blankHtmlComments,
+  blankJsComments,
+  enclosingObject,
+  kebab,
+  lineIndex,
+  localComponent,
+  splitVue
+} from "./material3-source.mjs";
+import { readPackageRoutes } from "./package-routes.mjs";
 
 // The navigation rules of the JSKIT Material 3 guide (#241). The shell owns Up and the per-tab trail;
 // an app declares each inner page's parent and links through JSKIT navigation, nothing more. Plain `jskit check`
@@ -13,7 +26,10 @@ const RULES = Object.freeze({
   "nav/raw-link": "forbidden-in-app-code",
   "nav/back-control": "forbidden-in-app-code",
   "nav/missing-parent": "what-an-app-declares",
-  "nav/top-level-parent": "what-an-app-declares"
+  "nav/top-level-parent": "what-an-app-declares",
+  "nav/placement-data": "what-an-app-declares",
+  "nav/missing-shell-layout": "what-an-app-declares",
+  "nav/surface-parent": "what-an-app-declares"
 });
 
 const HISTORY_CALL = /(?<![\w$.])(?:(?:window|globalThis)\s*\.\s*)?history\s*\.\s*(?:back|go|forward|pushState|replaceState)\s*\(/gu;
@@ -60,6 +76,7 @@ const MAIN_NAV_TARGET = /\btarget\s*:\s*["']shell\.(?:primary|secondary)-nav["']
 // draws its own bar renders shell-web's Up control in it.
 const SHELL_LAYOUT_IMPORT = /\bfrom\s*["'](?:@\/components\/ShellLayout|@jskit-ai\/shell-web\/client\/components\/ShellLayout)(?:\.vue)?["']/u;
 const SHELL_UP_TAG = /<\s*(?:ShellUpButton|shell-up-button)\b/u;
+const SHELL_TITLE_TAG = /<\s*(?:ShellPageTitle|shell-page-title)\b/u;
 const LOCAL_IMPORT = /\bfrom\s*["']((?:@\/|\.{1,2}\/)[^"']+)["']/gu;
 const ROUTER_VIEW_TAG = /<\s*(?:RouterView|router-view)\b/u;
 
@@ -101,12 +118,17 @@ function isPlacementLink(code, offset) {
   return Boolean(placement) && /\btarget\s*:\s*["'`][\w.-]+["'`]/u.test(placement.text) && /\bkind\s*:/u.test(placement.text);
 }
 
-// A back-named function that navigates the app; a variable, an import or an in-component step is not back logic.
+// A back-named function that navigates the app, and the import of a back component (ContextBackButton); a variable,
+// a composable's import or an in-component step is not back logic.
 function checkScriptBackNames(code, offset, report) {
   for (const match of code.matchAll(BACK_DEFINITION)) {
     if (!navigatesApp(definitionOf(code, match[1]), code)) continue;
     report("nav/back-control", offset + match.index, `${match[1]} navigates back in the app. ${UP_OWNER}; delete it and declare the page's parent.`);
   }
+  for (const match of code.matchAll(DEFAULT_IMPORT)) {
+    if (!/^[A-Z]/u.test(match[1]) || !isBackComponentName(match[1])) continue;
+    report("nav/back-control", offset + match.index, `${match[1]} is a back component. ${UP_OWNER}; remove it and declare the page's parent.`);
+  }
 }
 
 // The text of a local function's definition: function name(...) { ... }, or const name = ... to its end.
@@ -171,9 +193,13 @@ function visibleText(inner) {
   return inner.replace(/<[^>]*>/gu, " ").replace(/\{\{[\s\S]*?\}\}/gu, " ").replace(/\s+/gu, " ").trim();
 }
 
-function isBackTag(tag) {
-  const segments = tag.name.split("-");
-  return segments.includes("back") && !tag.name.startsWith("v-");
+// A back component, in either case (tags are read in kebab case): ContextBackButton, <page-back-link>, GoBack,
+// BackToList. Not Vuetify's own tags, a back office, or a back-to-top control, which scrolls the page.
+const BACK_COMPONENT = /(?:^|-)back(?:$|-(?:action|arrow|btn|button|chevron|control|icon|link|nav|navigation)(?:-|$)|-to-(?!top(?:-|$)))/u;
+
+function isBackComponentName(name) {
+  const tag = kebab(name);
+  return !tag.startsWith("v-") && BACK_COMPONENT.test(tag);
 }
 
 function looksLikeBack(tag) {
@@ -197,11 +223,12 @@ function checkBackControl(tag, report, script = "") {
     report("nav/back-control", tag.offset, "Breadcrumbs navigate back up the hierarchy. The shell's Up arrow does that; the app bar title says where the person is.");
     return;
   }
-  if (!navigatesFromControl(tag, script)) return;
-  if (isBackTag(tag)) {
+  // A back component navigates by itself, so its tag needs no link or handler to be one.
+  if (isBackComponentName(tag.name)) {
     report("nav/back-control", tag.offset, `<${tag.name}> is a back control. ${UP_OWNER}; remove it and declare the page's parent.`);
     return;
   }
+  if (!navigatesFromControl(tag, script)) return;
   const handler = tag.attributes.find((entry) => entry.event && BACK_IDENTIFIER.test(entry.value));
   if (handler) {
     report("nav/back-control", handler.offset, `${handler.raw}="${handler.value.trim()}" is a back handler. ${UP_OWNER}; remove the control and declare the page's parent.`);
@@ -220,48 +247,53 @@ function checkLinkAttribute(tag, entry, report) {
   }
 }
 
-// The value of the first balanced { ... } or [ ... ] starting at or after `start`.
-function balancedFrom(text, start, open = "{", close = "}") {
-  const first = text.indexOf(open, start);
-  if (first < 0) return null;
-  let depth = 0;
-  for (let index = first; index < text.length; index += 1) {
-    if (text[index] === open) depth += 1;
-    else if (text[index] === close && --depth === 0) return { start: first, end: index + 1, text: text.slice(first, index + 1) };
-  }
-  return null;
-}
-
-// The object literal that encloses `offset`, as { start, end, text }, or null.
-function enclosingObject(text, offset) {
-  let depth = 0;
-  for (let index = offset; index >= 0; index -= 1) {
-    if (text[index] === "}") depth += 1;
-    else if (text[index] === "{") {
-      if (depth === 0) return balancedFrom(text, index);
-      depth -= 1;
-    }
-  }
-  return null;
-}
-
 const stringValue = (text, key) => new RegExp(`\\b${key}\\s*:\\s*(["'\\u0060])([^"'\\u0060]*)\\1`, "u").exec(text)?.[2];
 
-// Main-navigation destinations, by surface: every main-navigation placement's suffixes.
+// Main-navigation destinations, by surface: every main-navigation placement's suffixes, and its address when it has
+// one (`to`). A link that names its surface (props.surface) leads to that surface's page wherever it shows, so it is a
+// destination of that surface only; one that names none leads to the page on each surface it shows on. A placement is
+// literal data; one whose suffixes, address or surface are computed (built by a helper, spread or interpolated) can't
+// be read, and is returned as unreadable.
 function readMainNavigation(sources) {
   const destinations = [];
-  for (const source of sources) {
+  const unreadable = [];
+  for (const { file, source } of sources) {
     for (const match of source.matchAll(MAIN_NAV_TARGET)) {
       const placement = enclosingObject(source, match.index)?.text || "";
-      const surfaces = [stringValue(placement, "surface"), ...(/\bsurfaces\s*:\s*\[([^\]]*)\]/u.exec(placement)?.[1] || "")
-        .split(",").map((entry) => entry.trim().replace(/^["'`]|["'`]$/gu, ""))].filter(Boolean);
+      const computed = computedPlacementPart(placement);
+      if (computed) {
+        unreadable.push({ file, source, offset: match.index, computed });
+        continue;
+      }
+      const surface = stringValue(placement, "surface");
+      const surfaces = surface ? [surface] : (/\bsurfaces\s*:\s*\[([^\]]*)\]/u.exec(placement)?.[1] || "")
+        .split(",").map((entry) => entry.trim().replace(/^["'`]|["'`]$/gu, "")).filter(Boolean);
       for (const key of ["scopedSuffix", "unscopedSuffix"]) {
         const suffix = stringValue(placement, key);
         if (suffix !== undefined) destinations.push({ suffix: normalisePath(suffix.split(/[?#]/u)[0]), surfaces });
       }
+      // A link with an address of its own (`to: "/account"`, a package's global route) leads to that path.
+      const to = stringValue(placement, "to");
+      if (to?.startsWith("/")) destinations.push({ to: normalisePath(to.split(/[?#]/u)[0]), surfaces });
     }
   }
-  return destinations;
+  return { destinations, unreadable };
+}
+
+// What makes a placement computed rather than literal data, or "": a spread, props that aren't an object literal, or
+// a link key that isn't a plain string (or a list of strings, for surfaces), such as a variable, a call or an
+// interpolated template.
+function computedPlacementPart(placement) {
+  if (/[{,]\s*\.\.\./u.test(placement)) return "it spreads another object";
+  if (/(?<=[{,]\s*)props\s*:(?!\s*\{)/u.test(placement)) return "its props are computed";
+  for (const key of ["scopedSuffix", "unscopedSuffix", "surface", "to"]) {
+    // The key as a property, `key: value` or shorthand `key`, whose value is not a quoted string without ${}.
+    const property = new RegExp(`(?<=[{,]\\s*)${key}\\s*(?::(?!\\s*(["'\\u0060])[^"'\\u0060$]*\\1)|(?=[,}]))`, "u");
+    if (property.test(placement)) return `its ${key} is computed`;
+  }
+  const surfaces = /(?<=[{,]\s*)surfaces\s*:\s*(\[[^\]]*\])?/u.exec(placement);
+  if (surfaces && !/^\[\s*(?:(["'`])[^"'`$]*\1\s*,?\s*)*\]$/u.test(surfaces[1] || "")) return "its surfaces are computed";
+  return "";
 }
 
 function normalisePath(value) {
@@ -328,20 +360,21 @@ function readPage(file, source) {
     redirect: REDIRECT_KEY.test(meta),
     parent: declarations.find(({ text }) => PARENT_KEY.test(text)),
     surfaceRoot: SURFACE_KEY.test(meta.replace(PARENT_OBJECT, "")),
-    shell: false
+    shell: "none"
   };
 }
 
 // Whether a component draws the shell's top app bar, and with it Up: it, or a component it imports from the app,
-// renders ShellLayout (directly or through the app's wrapper) or shell-web's ShellUpButton in a bar of its own.
-function createShellBarReader(appFiles, read) {
+// renders ShellLayout (directly or through the app's wrapper) or shell-web's ShellUpButton in a bar of its own (or,
+// given SHELL_TITLE_TAG, the bar's page title).
+function createShellBarReader(appFiles, read, tag = SHELL_UP_TAG) {
   const known = new Set(appFiles);
   const verdicts = new Map();
   async function drawsShellBar(file) {
     if (verdicts.has(file)) return verdicts.get(file);
     verdicts.set(file, false);
     const source = await read(file);
-    let verdict = SHELL_LAYOUT_IMPORT.test(source) || SHELL_UP_TAG.test(splitVue(source).template?.text || "");
+    let verdict = SHELL_LAYOUT_IMPORT.test(source) || tag.test(splitVue(source).template?.text || "");
     for (const match of source.matchAll(LOCAL_IMPORT)) {
       if (verdict) break;
       const imported = localComponent(file, match[1], known);
@@ -353,12 +386,142 @@ function createShellBarReader(appFiles, read) {
   return drawsShellBar;
 }
 
-// The app's .vue file an import names: "@/components/Bar.vue" is src/components/Bar.vue; "./Bar" is beside the file.
-function localComponent(file, specifier, known) {
-  const base = specifier.startsWith("@/")
-    ? path.posix.join("src", specifier.slice(2))
-    : path.posix.join(path.posix.dirname(file), specifier);
-  return [base, `${base}.vue`].find((candidate) => candidate.endsWith(".vue") && known.has(candidate)) || null;
+const SHELL_LAYOUT_SPECIFIER = /^(?:@\/components\/ShellLayout|@jskit-ai\/shell-web\/client\/components\/ShellLayout)(?:\.vue)?$/u;
+
+/**
+ * Where a layout renders its pages: "all" under the shell's top app bar (every <RouterView /> inside ShellLayout or
+ * an app component that draws the bar, or a bar drawn beside them: ShellUpButton, or such a component around no
+ * RouterView), "some" when a branch renders them without it (a shop device's sign-in in a v-if beside the
+ * ShellLayout), or "none".
+ * @param {string} file
+ * @param {string} source
+ * @param {(file: string) => Promise<boolean>} drawsShellBar
+ * @param {Set<string>} known The app's files.
+ * @param {RegExp} [barTag] The shell-web piece that marks a bar of the layout's own: Up, or, for the page title,
+ *   ShellPageTitle (with drawsShellBar then reading the title too).
+ */
+async function shellPlacement(file, source, drawsShellBar, known, barTag = SHELL_UP_TAG) {
+  const { template, scripts } = splitVue(source);
+  const text = blankHtmlComments(template?.text || "");
+  if (barTag.test(text)) return "all";
+  const shellTags = new Set();
+  for (const block of scripts) {
+    for (const [, name, specifier] of blankJsComments(block.text).matchAll(DEFAULT_IMPORT)) {
+      const imported = localComponent(file, specifier, known);
+      if (SHELL_LAYOUT_SPECIFIER.test(specifier) || (imported && await drawsShellBar(imported))) shellTags.add(kebab(name));
+    }
+  }
+  const open = [];
+  let inside = 0;
+  let outside = 0;
+  let barBeside = false;
+  for (const [, closing, rawName, , selfClosing] of text.matchAll(TEMPLATE_TAG)) {
+    const name = kebab(rawName);
+    if (closing) {
+      const index = open.findLastIndex((entry) => entry.name === name);
+      if (index < 0) continue;
+      barBeside ||= open.slice(index).some((entry) => entry.shell && !entry.view);
+      open.length = index;
+      continue;
+    }
+    const shell = shellTags.has(name);
+    if (name === "router-view") {
+      const around = open.filter((entry) => entry.shell);
+      for (const entry of around) entry.view = true;
+      if (around.length > 0) inside += 1;
+      else outside += 1;
+    }
+    if (selfClosing || VOID_TAGS.has(name)) barBeside ||= shell;
+    else open.push({ name, shell, view: false });
+  }
+  if (barBeside) return "all";
+  if (inside === 0) return "none";
+  return outside === 0 ? "all" : "some";
+}
+
+/**
+ * The app's .vue files that render under the shell's page title, where an in-page h1 would be a second one: a file
+ * that shows the title (ShellLayout's bar, or ShellPageTitle in a bar of its own), a page a layout always renders
+ * under it, and a component such a file imports. A component no .vue file imports (routed or placed from JavaScript) counts
+ * too, as where it renders can't be read, unless JavaScript hands it to the shell to render outside every layout (the
+ * router's notFoundComponent or fallbackRoute, the app's rootComponent) or it is a package route's page, which the
+ * kernel adds at the top level: that one counts only as App.vue does, which counts only when it shows the title itself.
+ * @param {{ root: string, appFiles: string[] }} options
+ */
+async function readTitledFiles({ root, appFiles }) {
+  const sources = new Map();
+  const read = async (file) => {
+    if (!sources.has(file)) sources.set(file, await readFile(path.join(root, file), "utf8"));
+    return sources.get(file);
+  };
+  const known = new Set(appFiles);
+  const vueFiles = appFiles.filter((file) => file.endsWith(".vue"));
+  const showsTitle = createShellBarReader(appFiles, read, SHELL_TITLE_TAG);
+  const importers = new Map();
+  for (const file of vueFiles) {
+    for (const match of (await read(file)).matchAll(LOCAL_IMPORT)) {
+      const imported = localComponent(file, match[1], known);
+      if (imported) importers.set(imported, [...(importers.get(imported) || []), file]);
+    }
+  }
+  // Whether each component JavaScript imports is handed to the shell only to render outside every layout.
+  const outsideLayouts = new Map();
+  for (const file of appFiles.filter((entry) => /\.(?:[cm]?[jt]s)$/u.test(entry))) {
+    const code = blankJsComments(await read(file));
+    for (const [, name, specifier] of code.matchAll(DEFAULT_IMPORT)) {
+      const imported = localComponent(file, specifier, known);
+      if (!imported) continue;
+      const outside = rendersOutsideLayouts(code, name);
+      outsideLayouts.set(imported, (outsideLayouts.get(imported) ?? true) && outside);
+    }
+  }
+  const packagePages = new Set((await readPackageRoutes(root, known)).map((route) => route.file));
+  const verdicts = new Map();
+  async function titled(file) {
+    if (verdicts.has(file)) return verdicts.get(file);
+    verdicts.set(file, false);
+    let verdict = await showsTitle(file);
+    if (!verdict && isPageFile(file)) {
+      // The layouts that render the page: src/pages/home/settings.vue renders home/settings/*.
+      const segments = pageKey(file).split("/");
+      for (let length = segments.length - 1; length > 0 && !verdict; length -= 1) {
+        const layout = `src/pages/${segments.slice(0, length).join("/")}.vue`;
+        // A layout that renders its pages without the title on one branch (a shop device's sign-in in a bare v-main
+        // beside the ShellLayout) leaves them unjudged, as which branch shows a page is decided at runtime.
+        if (known.has(layout) && ROUTER_VIEW_TAG.test(splitVue(await read(layout)).template?.text || "")) {
+          verdict = await shellPlacement(layout, await read(layout), showsTitle, known, SHELL_TITLE_TAG) === "all";
+        }
+      }
+    } else if (!verdict && path.posix.basename(file) !== "App.vue") {
+      const users = importers.get(file) || [];
+      verdict = users.length === 0;
+      if (verdict && (outsideLayouts.get(file) === true || packagePages.has(file))) {
+        verdict = known.has("src/App.vue") && await showsTitle("src/App.vue");
+      }
+      for (const user of users) {
+        if (verdict) break;
+        verdict = await titled(user);
+      }
+    }
+    verdicts.set(file, verdict);
+    return verdict;
+  }
+  const result = new Set();
+  for (const file of vueFiles) if (await titled(file)) result.add(file);
+  return result;
+}
+
+// A component JavaScript gives the shell to render outside every layout: the router's notFoundComponent or
+// fallbackRoute component, or the app's rootComponent.
+function rendersOutsideLayouts(code, name) {
+  const escaped = name.replaceAll("$", "\\$");
+  const named = String.raw`(?<![\w$.])${escaped}(?![\w$])`;
+  const handed = new RegExp(String.raw`\b(?:notFoundComponent|rootComponent)\s*:\s*${named}|\bcreateFallbackNotFoundRoute\s*\(\s*${named}|\bfallbackRoute\s*:\s*\{[^{}]*\bcomponent\s*:\s*${named}`, "gu");
+  // Every use after the import (whose specifier may spell the name too) is a hand-over, or it may render anywhere.
+  const body = code.replace(new RegExp(String.raw`\bimport\s+${escaped}\s+from\s*["'][^"']+["']`, "gu"), "");
+  const uses = [...body.matchAll(new RegExp(named, "gu"))].length;
+  const handovers = [...body.matchAll(handed)].length;
+  return handovers > 0 && handovers === uses;
 }
 
 /**
@@ -378,29 +541,56 @@ async function checkPageParents({ root, appFiles, pageFiles, report }) {
   const pages = new Map();
   for (const file of appFiles.filter(isPageFile)) pages.set(pageKey(file), readPage(file, await read(file)));
   const drawsShellBar = createShellBarReader(appFiles, read);
+  const known = new Set(appFiles);
   for (const page of pages.values()) {
-    if (page.layout) page.shell = await drawsShellBar(page.file);
+    if (page.layout) page.shell = await shellPlacement(page.file, page.source, drawsShellBar, known);
   }
   const surfaces = readSurfaces(configSource, [...pages.values()].map(({ file }) => routeOf(file)));
   const scripts = appFiles.filter((file) => /\.(?:[cm]?[jt]s|vue)$/u.test(file));
-  const navigation = readMainNavigation(await Promise.all(scripts.map(async (file) => blankJsComments(await read(file)))));
+  const navigation = readMainNavigation(await Promise.all(scripts.map(async (file) => ({ file, source: blankJsComments(await read(file)) }))));
+  for (const { file, source, offset, computed } of navigation.unreadable) {
+    if (!pageFiles.includes(file)) continue;
+    report({ rule: "nav/placement-data", file, ...lineIndex(source)(offset), message: `A main-navigation placement that isn't literal data: ${computed}. Declare each placement literally, with plain string suffixes and surface, so its destination can be read; until then no page is judged for nav/missing-parent.` });
+  }
   const surfacePath = (file, surface) => normalisePath(routePattern(routeOf(file).slice(surface.pagesRoot.length)));
-  const isDestination = (relative, surface) => navigation.some(({ suffix, surfaces: owners }) =>
-    suffix === relative && (owners.length === 0 || owners.includes(surface.id) || owners.includes("*")));
+  const addressOf = (relative, surface) => normalisePath(routePattern(`${surface.pagesRoot}${relative}`));
+  const shownOn = (owners, surface) => owners.length === 0 || owners.includes(surface.id) || owners.includes("*");
+  // A destination by its suffix on the surface, or by its address (`to`).
+  const isDestination = (relative, surface) => navigation.destinations.some(({ suffix, to, surfaces: owners }) =>
+    to === undefined ? suffix === relative && shownOn(owners, surface) : to === addressOf(relative, surface));
+  // A global route's address is a destination when a link's `to` names it, or a suffix leads there on a surface.
+  const isAddress = (address) => navigation.destinations.some(({ suffix, to, surfaces: owners }) =>
+    to === undefined ? surfaces.some((surface) => shownOn(owners, surface) && addressOf(suffix, surface) === address) : to === address);
+  // An App.vue that wraps every page in the shell's bar leaves no page outside it.
+  const appShell = appFiles.includes("src/App.vue") && await drawsShellBar("src/App.vue");
   const judged = [];
   for (const file of pageFiles.filter(isPageFile)) {
     const page = pages.get(pageKey(file));
     const surface = surfaceOf(routeOf(file), surfaces);
     if (!surface || page.redirect) continue;
+    // The record that carries jskit.surface is the surface root, where Up stops, so a parent beside it is never read.
+    if (page.surfaceRoot && page.parent) {
+      const at = lineIndex(page.source)(page.parent.offset + PARENT_KEY.exec(page.parent.text).index);
+      const fix = page.layout ? "move jskit.parent to the page this layout renders" : "remove jskit.surface and keep jskit.parent";
+      report({ rule: "nav/surface-parent", file, ...at, message: `${path.posix.basename(file)} declares jskit.parent beside jskit.surface, so the shell never reads it and the page shows no Up: the record with the surface is the surface root, where Up stops. Declare the surface only on the surface's layout page (ShellLayout around <RouterView />) and the parent on the page it renders; here, ${fix}.` });
+    }
     // The layouts that render this page, nearest first: src/pages/home/settings.vue renders home/settings/*.
     const segments = pageKey(file).split("/");
     const layouts = segments.slice(1).map((_, index) => pages.get(segments.slice(0, segments.length - 1 - index).join("/")))
       .filter((entry) => entry?.layout);
-    // Up lives in the shell's top app bar, so only pages a shell layout renders have one.
-    if (!layouts.some((entry) => entry.shell)) continue;
     const relative = surfacePath(file, surface);
-    const destination = isDestination(relative, surface);
     const position = lineIndex(page.source);
+    // Up lives in the shell's top app bar, so only pages a shell layout renders have one. A page that declares a
+    // parent expects that bar, with its title, Up and page actions; under no shell layout it shows none of them.
+    if (!layouts.some((entry) => entry.shell !== "none")) {
+      if (page.parent && !appShell && !await drawsShellBar(file)) {
+        const at = position(page.parent.offset + PARENT_KEY.exec(page.parent.text).index);
+        const layout = surface.pagesRoot ? `, src/pages/${surface.pagesRoot}.vue` : "";
+        report({ rule: "nav/missing-shell-layout", file, ...at, message: `${relative} of ${surface.id} declares a parent, but no layout that draws the shell's top app bar renders it, so its title, Up and page actions never show. Give the surface its layout${layout}: ShellLayout around <RouterView />, with meta.jskit.surface "${surface.id}".` });
+      }
+      continue;
+    }
+    const destination = isDestination(relative, surface);
     if (destination && page.parent) {
       const at = position(page.parent.offset + PARENT_KEY.exec(page.parent.text).index);
       report({ rule: "nav/top-level-parent", file, ...at, message: `${relative} is a main-navigation destination of ${surface.id}, so it declares no parent: choosing it starts a fresh trail.` });
@@ -415,14 +605,63 @@ async function checkPageParents({ root, appFiles, pageFiles, report }) {
     const inherited = chain.find((entry) => entry.parent);
     const topLevel = destination || relative === "/" || chain.some((entry) => isDestination(surfacePath(entry.file, surface), surface));
     judged.push({ file, route: relative, surface: surface.id, topLevel, parent: page.parent ? "own" : inherited ? "inherited" : null });
-    if (!topLevel && !page.parent && !inherited) {
+    // A layout that also renders its pages without the shell (a shop device's sign-in) leaves which of them show Up
+    // unreadable, so only a page that always renders under the bar needs a parent.
+    const alwaysInShell = layouts.some((entry) => entry.shell === "all");
+    if (!topLevel && !page.parent && !inherited && alwaysInShell && navigation.unreadable.length === 0) {
       const at = position(page.declarations[0]?.offset ?? 0);
       report({ rule: "nav/missing-parent", file, ...at, message: `Inner page ${relative} of ${surface.id} has no parent. Declare it once in the page's route meta (or its layout's, for tabs), so Up works after a direct entry.` });
     }
   }
+  for (const route of await readPackageRoutes(root, known)) {
+    if (!pageFiles.includes(route.file) && !pageFiles.includes(route.manifest)) continue;
+    const verdict = await judgePackageRoute(route, { surfaces, appShell, drawsShellBar, isDestination, isAddress, readable: navigation.unreadable.length === 0, report });
+    if (verdict) judged.push(verdict);
+  }
   return judged;
 }
 
+/**
+ * The page rules for a package's route, which the kernel adds at the top level: under the shell's bar only when its
+ * component (or App.vue) draws it, with the parent its package.json declares in meta.jskit.parent. Findings point at
+ * the route's entry in package.json.
+ */
+async function judgePackageRoute(route, { surfaces, appShell, drawsShellBar, isDestination, isAddress, readable, report }) {
+  const position = lineIndex(route.source);
+  const at = (offset) => ({ file: route.manifest, ...position(offset) });
+  const address = normalisePath(route.path);
+  const name = `${address} (route "${route.id}" of ${route.manifest})`;
+  // A surface route's path starts at its surface's base: /app/manage/:view is /manage/:view of app.
+  let surface = { id: "", pagesRoot: "" };
+  let relative = address;
+  if (route.scope === "surface") {
+    surface = surfaces.find(({ id }) => id === route.surface);
+    if (!surface) return null;
+    const base = normalisePath(routePattern(surface.pagesRoot));
+    if (base !== "/" && address !== base && !address.startsWith(`${base}/`)) return null;
+    relative = normalisePath(address.slice(base === "/" ? 0 : base.length));
+  }
+  const where = surface.id ? ` of ${surface.id}` : "";
+  if (route.surfaceRoot && route.parent) {
+    report({ rule: "nav/surface-parent", ...at(route.parentOffset), message: `${name} declares jskit.parent beside jskit.surface, so the shell never reads it and the page shows no Up: the record with the surface is the surface root, where Up stops. Remove meta.jskit.surface; the route's own "surface" chooses where it is served.` });
+  }
+  if (!appShell && !await drawsShellBar(route.file)) {
+    if (route.parent) {
+      report({ rule: "nav/missing-shell-layout", ...at(route.parentOffset), message: `${name} declares a parent, but its component, ${route.file}, doesn't draw the shell's top app bar, so its title, Up and page actions never show. A package's route renders at the top level, under no layout: render ShellLayout around the page.` });
+    }
+    return null;
+  }
+  const destination = route.scope === "surface" ? isDestination(relative, surface) : isAddress(address);
+  if (destination && route.parent) {
+    report({ rule: "nav/top-level-parent", ...at(route.parentOffset), message: `${name} is a main-navigation destination${where}, so it declares no parent: choosing it starts a fresh trail.` });
+  }
+  const topLevel = destination || relative === "/";
+  if (!topLevel && !route.parent && readable) {
+    report({ rule: "nav/missing-parent", ...at(route.offset), message: `Inner page ${name}${where} has no parent. Declare it in the route's meta, "meta": { "jskit": { "parent": ... } }, so Up works after a direct entry.` });
+  }
+  return { file: route.file, route: relative, surface: surface.id || "global", topLevel, parent: route.parent ? "own" : null };
+}
+
 // src/pages/home/suppliers.vue is home/suppliers and src/pages/home/suppliers/index.vue is home/suppliers/index.
 function pageKey(file) {
   return file.replace(/^src\/pages\//u, "").replace(/\.vue$/u, "");
@@ -441,5 +680,6 @@ export {
   checkPageParents,
   checkScriptBackNames,
   isInAppPath,
-  isPageFile
+  isPageFile,
+  readTitledFiles
 };

package/scripts/package-routes.mjs

@@ -0,0 +1,93 @@
+// The pages an app's own packages give the router, for the navigation rules: each package.json route in
+// jskit.metadata.ui.routes with the component its client entry's routeComponents names.
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_IMPORT, balancedFrom, blankJsComments, enclosingObject, localComponent } from "./material3-source.mjs";
+
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const ROUTE_COMPONENTS = /\brouteComponents\s*=\s*(?:Object\s*\.\s*freeze\s*\(\s*)?(?=\{)/u;
+// One routeComponents entry: `key: () => import("./page.vue")` or `"key": ImportedPage`.
+const ROUTE_COMPONENT = /(?<=[{,]\s*)(?:(["'])([^"']+)\1|([A-Za-z_$][\w$]*))\s*:\s*(?:\(\s*\)\s*=>\s*import\s*\(\s*(["'])([^"']+)\4\s*\)|([A-Za-z_$][\w$]*))(?=\s*[,}])/gu;
+
+// The file a package's "./client" export names, relative to the app: packages/shelves/src/client/index.js.
+function clientEntryOf(manifest, directory) {
+  const target = manifest?.exports?.["./client"];
+  const entry = typeof target === "string" ? target : target?.import || target?.default;
+  return typeof entry === "string" ? path.posix.join(directory, entry) : "";
+}
+
+// The app's .vue file of each routeComponents key in a client entry, from its literal map: an entry another module
+// builds, or one naming a file outside the app, has none.
+function readRouteComponents(entry, code, known) {
+  const components = new Map();
+  const start = ROUTE_COMPONENTS.exec(code);
+  const map = start ? balancedFrom(code, start.index + start[0].length)?.text || "" : "";
+  const imports = new Map([...code.matchAll(DEFAULT_IMPORT)].map(([, name, specifier]) => [name, specifier]));
+  for (const match of map.matchAll(ROUTE_COMPONENT)) {
+    const specifier = match[5] ?? imports.get(match[6]);
+    const file = specifier ? localComponent(entry, specifier, known) : null;
+    if (file) components.set(match[2] ?? match[3], file);
+  }
+  return components;
+}
+
+/**
+ * The pages an app's own packages give the router: each packages/<name>/package.json's jskit.metadata.ui.routes entry
+ * the kernel registers (not autoRegister: false), with the component its client entry's literal routeComponents map
+ * names for componentKey. The kernel adds each at the top level, so no layout renders it: it is under the shell's top
+ * app bar only when its component (or App.vue) draws the bar. Its parent and surface are its meta.jskit, as declared.
+ * @param {string} root
+ * @param {Set<string>} known The app's files; a package whose client entry or component is not among them is skipped.
+ */
+async function readPackageRoutes(root, known) {
+  let directories = [];
+  try {
+    directories = (await readdir(path.join(root, "packages"), { withFileTypes: true })).filter((entry) => entry.isDirectory());
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const pages = [];
+  for (const directory of directories.map((entry) => `packages/${entry.name}`).sort()) {
+    const manifestFile = `${directory}/package.json`;
+    let manifestSource;
+    let manifest;
+    try {
+      manifestSource = await readFile(path.join(root, manifestFile), "utf8");
+      manifest = JSON.parse(manifestSource);
+    } catch (error) {
+      if (error?.code === "ENOENT" || error instanceof SyntaxError) continue;
+      throw error;
+    }
+    const routes = manifest?.jskit?.metadata?.ui?.routes;
+    const entry = clientEntryOf(manifest, directory);
+    if (!Array.isArray(routes) || !known.has(entry)) continue;
+    const components = readRouteComponents(entry, blankJsComments(await readFile(path.join(root, entry), "utf8")), known);
+    for (const route of routes) {
+      const file = isRecord(route) && route.autoRegister !== false ? components.get(String(route.componentKey || "").trim()) : null;
+      if (!file) continue;
+      const id = String(route.id || "").trim();
+      const jskit = isRecord(route.meta?.jskit) ? route.meta.jskit : {};
+      const parent = typeof jskit.parent === "string" ? jskit.parent.trim() : isRecord(jskit.parent) ? jskit.parent : "";
+      // Where package.json declares the route, and its parent, for findings.
+      const declared = new RegExp(String.raw`"id"\s*:\s*${JSON.stringify(id).replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}`, "u").exec(manifestSource);
+      const object = declared ? enclosingObject(manifestSource, declared.index) : null;
+      const parentKey = object ? /"parent"\s*:/u.exec(object.text) : null;
+      pages.push({
+        file,
+        manifest: manifestFile,
+        source: manifestSource,
+        id,
+        path: String(route.path || "").trim(),
+        scope: String(route.scope || "surface").trim().toLowerCase() === "global" ? "global" : "surface",
+        surface: String(route.surface || "").trim().toLowerCase(),
+        parent,
+        surfaceRoot: Boolean(jskit.surface),
+        offset: declared?.index ?? 0,
+        parentOffset: parentKey ? object.start + parentKey.index : declared?.index ?? 0
+      });
+    }
+  }
+  return pages;
+}
+
+export { readPackageRoutes };

package/scripts/test-budget.mjs

@@ -0,0 +1,19 @@
+import os from "node:os";
+import process from "node:process";
+
+// The machine's test budget: how many test files (node --test), Playwright workers or Vitest workers a run may use at
+// once. A test runner that hands out slots exports V64_TEST_CONCURRENCY for each run; anywhere else a run takes half
+// of the machine, so a test suite neither runs one file at a time nor overwhelms the machine (a 2-vCPU VPS stays at 1).
+const BUDGET_VARIABLE = "V64_TEST_CONCURRENCY";
+
+/**
+ * @param {{ env?: Record<string, string | undefined>, parallelism?: number }} [options]
+ * @returns {number} a whole number of at least 1
+ */
+function testConcurrency({ env = process.env, parallelism = os.availableParallelism() } = {}) {
+  const configured = String(env[BUDGET_VARIABLE] ?? "").trim();
+  if (/^[1-9]\d*$/u.test(configured)) return Number(configured);
+  return Math.max(1, Math.floor(parallelism / 2));
+}
+
+export { BUDGET_VARIABLE, testConcurrency };