@jskit-ai/jskit-catalog 0.2.31 → 0.2.33

package/scripts/material3-source.mjs

@@ -2,6 +2,8 @@
 // so these read Vue, JavaScript and CSS just far enough for the Material 3 rules: blocks, tags with attributes,
 // declarations, and comments blanked to spaces so every offset still maps to its original line and column.
 
+import path from "node:path";
+
 const HEX_DIGITS = "[0-9a-fA-F]";
 // #rgb, #rgba, #rrggbb and #rrggbbaa, not followed by another word character.
 const HEX_COLOUR = `#(?:${HEX_DIGITS}{8}|${HEX_DIGITS}{6}|${HEX_DIGITS}{3,4})(?![\\w-])`;
@@ -121,6 +123,10 @@ function splitVue(source) {
 
 const ATTRIBUTE = /([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/gu;
 const TAG = /<([A-Za-z][\w.-]*)((?:\s+[^\s"'<>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))?)*)\s*(\/?)>/gu;
+// An opening or closing tag in a template, with its attributes; HTML void elements never close.
+const TEMPLATE_TAG = /<(\/?)([A-Za-z][\w.-]*)((?:\s+[^\s"'<>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))?)*)\s*(\/?)>/gu;
+const VOID_TAGS = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "source", "track", "wbr"]);
+const CONDITIONAL = /(?:^|\s)v-(if|else-if|else)(?=[\s=]|$)/u;
 
 function kebab(name) {
   return name.replace(/([a-z0-9])([A-Z])/gu, "$1-$2").toLowerCase();
@@ -172,6 +178,39 @@ function readTags(template) {
   return tags;
 }
 
+// The v-if chains each element of a template (comments already blanked) renders under, by its offset: a list of
+// [chain, branch] pairs, outermost first. A v-if starts a chain among its siblings, each v-else-if or v-else right
+// after it is the chain's next branch, so two elements on different branches of one chain never render together.
+function readConditionalBranches(template) {
+  const branches = new Map();
+  const open = [{ name: "", path: [], chain: null }];
+  let chains = 0;
+  for (const match of template.text.matchAll(TEMPLATE_TAG)) {
+    const [, closing, rawName, attributes, selfClosing] = match;
+    const name = kebab(rawName);
+    if (closing) {
+      const index = open.findLastIndex((entry) => entry.name === name);
+      if (index > 0) open.length = index;
+      continue;
+    }
+    const parent = open.at(-1);
+    const directive = CONDITIONAL.exec(attributes)?.[1];
+    if (directive === "if") parent.chain = { id: (chains += 1), branch: 0 };
+    else if (directive && parent.chain) parent.chain.branch += 1;
+    else parent.chain = null;
+    const path = parent.chain ? [...parent.path, [parent.chain.id, parent.chain.branch]] : parent.path;
+    if (directive === "else") parent.chain = null;
+    branches.set(template.offset + match.index, path);
+    if (!selfClosing && !VOID_TAGS.has(name)) open.push({ name, path, chain: null });
+  }
+  return branches;
+}
+
+// Whether two elements sit on different branches of one v-if chain, so at most one of them renders.
+function exclusiveBranches(left, right) {
+  return left.some(([chain, branch]) => right.some(([other, otherBranch]) => other === chain && otherBranch !== branch));
+}
+
 // CSS declarations with the selectors that enclose them, for flat CSS, nested SCSS and at-rule blocks.
 function readDeclarations(css, offset) {
   const declarations = [];
@@ -207,13 +246,57 @@ function readInlineDeclarations(text, offset) {
   return readDeclarations(`x{${text}}`, offset - 2);
 }
 
+// A default import: `import Name from "specifier"`, its name and specifier.
+const DEFAULT_IMPORT = /\bimport\s+([A-Za-z_$][\w$]*)\s+from\s*["']([^"']+)["']/gu;
+
+// 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;
+}
+
+// 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;
+}
+
 export {
+  DEFAULT_IMPORT,
+  TEMPLATE_TAG,
+  VOID_TAGS,
   HEX_COLOUR,
+  balancedFrom,
   blankCssComments,
   blankHtmlComments,
   blankJsComments,
+  enclosingObject,
+  exclusiveBranches,
   kebab,
   lineIndex,
+  localComponent,
+  readConditionalBranches,
   readDeclarations,
   readExceptions,
   readInlineDeclarations,

package/scripts/material3.mjs

@@ -15,7 +15,9 @@ import {
   blankCssComments,
   blankHtmlComments,
   blankJsComments,
+  exclusiveBranches,
   lineIndex,
+  readConditionalBranches,
   readDeclarations,
   readExceptions,
   readInlineDeclarations,
@@ -51,6 +53,11 @@ const SKIPPED_DIRECTORIES = new Set([
   "fixtures", "server", "migrations"
 ]);
 const SKIPPED_FILE = /\.(?:test|spec)\.[cm]?[jt]s$|\.d\.ts$/u;
+// In JSKIT's own repository, packages/ holds the framework, which implements the navigation, Up and reloads the rules
+// send an app to (ShellUpButton, reloadAppPage(), leaveApp(), the system Back button). A whole-app run reads only the
+// app code a JSKIT package carries, its patterns and templates; an app's own packages are read in full.
+const FRAMEWORK_SCOPE = "@jskit-ai/";
+const FRAMEWORK_APP_CODE = new Set(["patterns", "templates"]);
 // The generated colour scheme is the one home of hex values.
 const THEME_DIRECTORY = "theme";
 // Colours that are content, not UI, keep one value in both schemes, so they are not theme colours (which are toned per
@@ -61,6 +68,12 @@ const WHOLE_APP_ROOTS = Object.freeze(["src", "packages"]);
 
 const hexPattern = () => new RegExp(HEX_COLOUR, "gu");
 const exactHex = new RegExp(`^${HEX_COLOUR}$`, "u");
+// A colour written as channels, as a hand-made shadow is: rgba(0, 0, 0, 0.15), rgb(0 0 0 / 20%), hsl(...). One that
+// reads a theme role, rgba(var(--v-theme-shadow), 0.2), is not.
+const CHANNEL_COLOUR = String.raw`\b(?:rgba?|hsla?)\(\s*[\d.][^()]*\)`;
+const channelColour = () => new RegExp(CHANNEL_COLOUR, "giu");
+const exactChannelColour = new RegExp(`^${CHANNEL_COLOUR}$`, "iu");
+const CHANNEL_FIX = "Use rgb(var(--v-theme-<role>)), with an alpha for a shadow or scrim: rgba(var(--v-theme-shadow), 0.2).";
 const quotedHex = () => new RegExp(`(["'\`])(${HEX_COLOUR})\\1`, "gu");
 const MDI_STRING = /\bmdi-[a-z][a-z0-9-]*/gu;
 const MDI_IMPORT = /(?:from\s*|import\s*|require\(\s*)["'](@mdi\/(?:js|font)[^"']*)["']/gu;
@@ -83,7 +96,18 @@ function isSourceFile(relativePath) {
   return !relativePath.split("/").slice(0, -1).some(isSkippedDirectory);
 }
 
-async function walk(projectRoot, directory, files) {
+async function isFrameworkPackage(projectRoot, directory) {
+  if (!/^packages\/[^/]+$/u.test(directory)) return false;
+  try {
+    const manifest = JSON.parse(await readFile(path.join(projectRoot, directory, "package.json"), "utf8"));
+    return String(manifest?.name || "").startsWith(FRAMEWORK_SCOPE);
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function walk(projectRoot, directory, files, wholeApp = false) {
   let entries;
   try {
     entries = await readdir(path.join(projectRoot, directory), { withFileTypes: true });
@@ -91,10 +115,12 @@ async function walk(projectRoot, directory, files) {
     if (error?.code === "ENOENT") return;
     throw error;
   }
+  const framework = wholeApp && await isFrameworkPackage(projectRoot, directory);
   for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
     const relative = directory ? `${directory}/${entry.name}` : entry.name;
+    if (framework && !(entry.isDirectory() && FRAMEWORK_APP_CODE.has(entry.name))) continue;
     if (entry.isDirectory()) {
-      if (!isSkippedDirectory(entry.name)) await walk(projectRoot, relative, files);
+      if (!isSkippedDirectory(entry.name)) await walk(projectRoot, relative, files, wholeApp);
     } else if (entry.isFile() && isSourceFile(relative)) {
       files.add(relative);
     }
@@ -120,7 +146,7 @@ async function collectFiles(projectRoot, paths) {
       if (paths.length > 0) missing.push(target);
       continue;
     }
-    if (info.isDirectory()) await walk(projectRoot, relative === "" ? "" : relative, files);
+    if (info.isDirectory()) await walk(projectRoot, relative === "" ? "" : relative, files, paths.length === 0);
     else if (isSourceFile(relative)) files.add(relative);
   }
   return { files: [...files].sort(), missing };
@@ -164,6 +190,9 @@ function checkCode(code, offset, { report, themed }) {
     for (const match of code.matchAll(quotedHex())) {
       report("m3/raw-hex", offset + match.index, `Raw colour ${match[2]}. Use a theme colour role. ${CONTENT_COLOUR}`);
     }
+    for (const match of code.matchAll(channelColour())) {
+      report("m3/raw-hex", offset + match.index, `Raw colour ${match[0]}. ${CHANNEL_FIX} ${CONTENT_COLOUR}`);
+    }
   }
   checkNavigationCode(code, offset, report);
 }
@@ -198,6 +227,9 @@ function checkDeclaration(declaration, context) {
     for (const match of declaration.value.matchAll(hexPattern())) {
       report("m3/raw-hex", declaration.valueOffset + match.index, `Raw colour ${match[0]}. Use rgb(var(--v-theme-<role>)). ${CONTENT_COLOUR}`);
     }
+    for (const match of declaration.value.matchAll(channelColour())) {
+      report("m3/raw-hex", declaration.valueOffset + match.index, `Raw colour ${match[0]}. ${CHANNEL_FIX} ${CONTENT_COLOUR}`);
+    }
   }
   const buttonRule = declaration.selectors.some((selector) => /\.v-btn\b/u.test(selector));
   if (buttonRule && ["height", "min-height", "--v-btn-height"].includes(declaration.property)) {
@@ -215,7 +247,9 @@ function checkTemplate(template, context) {
   for (const match of template.text.matchAll(MDI_STRING)) {
     report("m3/mdi-icon", template.offset + match.index, `MDI icon "${match[0]}". Use a Material Symbols alias such as "$add" from the app's Vuetify icon aliases.`);
   }
-  let headings = 0;
+  // The branches each h1 renders under: h1s on different branches of one v-if chain never show together.
+  const branches = readConditionalBranches(template);
+  const headings = [];
   for (const tag of tags) {
     for (const entry of tag.attributes) {
       checkAttribute(tag, entry, context);
@@ -224,9 +258,10 @@ function checkTemplate(template, context) {
     if (tag.name === "v-btn") checkButtonSize(tag, report);
     checkBackControl(tag, report, context.script);
     if (tag.name === "h1") {
-      headings += 1;
-      if (headings > 1) report("m3/duplicate-h1", tag.offset, "A second h1 in one template. A page has one title, carried by the top app bar.");
+      const branch = branches.get(tag.offset) || [];
+      if (headings.some((other) => !exclusiveBranches(other, branch))) report("m3/duplicate-h1", tag.offset, "A second h1 in one template. A page has one title, carried by the top app bar.");
       else if (context.titled) report("m3/duplicate-h1", tag.offset, "An in-page h1 under the top app bar, which carries the page title; use a title role (text-title-large) for a section title.");
+      headings.push(branch);
     }
   }
 }
@@ -239,7 +274,7 @@ function checkAttribute(tag, entry, context) {
     for (const declaration of readInlineDeclarations(entry.value, entry.valueOffset)) {
       checkDeclaration({ ...declaration, selectors: tag.name === "v-btn" ? [".v-btn"] : [] }, context);
     }
-  } else if (!themed && exactHex.test(entry.value.trim())) {
+  } else if (!themed && (exactHex.test(entry.value.trim()) || exactChannelColour.test(entry.value.trim()))) {
     report("m3/raw-hex", entry.valueOffset, `Raw colour ${entry.value.trim()}. Use a theme colour role such as color="primary". ${CONTENT_COLOUR}`);
   }
   checkLinkAttribute(tag, entry, context.report);

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`
@@ -15,7 +28,8 @@ const RULES = Object.freeze({
   "nav/missing-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/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;
@@ -104,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.
@@ -174,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) {
@@ -200,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.`);
@@ -223,37 +247,13 @@ 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. 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 or
-// surface are computed (built by a helper, spread or interpolated) can't be read, and is returned as unreadable.
+// 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 = [];
   const unreadable = [];
@@ -272,6 +272,9 @@ function readMainNavigation(sources) {
         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, unreadable };
@@ -357,7 +360,7 @@ 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"
   };
 }
 
@@ -383,11 +386,66 @@ function createShellBarReader(appFiles, read, tag = SHELL_UP_TAG) {
   return drawsShellBar;
 }
 
+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 showing it renders,
- * 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; App.vue counts only when it shows the title itself.
+ * 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 }) {
@@ -406,6 +464,18 @@ async function readTitledFiles({ root, appFiles }) {
       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);
@@ -416,13 +486,18 @@ async function readTitledFiles({ root, appFiles }) {
       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 showsTitle(layout);
+          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);
@@ -436,12 +511,17 @@ async function readTitledFiles({ root, appFiles }) {
   return result;
 }
 
-// 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;
+// 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;
 }
 
 /**
@@ -461,8 +541,9 @@ 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));
@@ -472,8 +553,14 @@ async function checkPageParents({ root, appFiles, pageFiles, report }) {
     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.destinations.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 = [];
@@ -481,6 +568,12 @@ async function checkPageParents({ root, appFiles, pageFiles, report }) {
     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("/")))
@@ -489,7 +582,7 @@ async function checkPageParents({ root, appFiles, pageFiles, report }) {
     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)) {
+    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` : "";
@@ -512,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 && navigation.unreadable.length === 0) {
+    // 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, "");