@astryxdesign/cli 0.6.5-canary.031021b → 0.6.5-canary.0353bb2

package/README.md

@@ -69,7 +69,7 @@ Results for "button" (20 of 239):
 
 Options:
 
-- `--type <component|hook|doc|template>`: restrict to a single domain
+- `--type <component|hook|doc|template|theme>`: restrict to a single domain (`doc` and `theme` work outside an app too)
 - `--limit <n>`: cap the number of results (default 20)
 - `--verbose`: also print each result's match score and reason
 - `--json`: typed `{ apiVersion, type: 'search', data: { query, matchCount, results } }` envelope — `matchCount` is how many candidates matched in total, `results` the slice `--limit` allowed
@@ -91,7 +91,7 @@ Options:
 | `init`        | Initialize the design system in your project                                                  |
 | `integration` | Author and verify an Astryx integration package                                               |
 | `layout`      | Generate XDS layouts from compressed expressions (XLE/XLO)                                    |
-| `search`      | Search components, hooks, docs, and templates in one ranked list                              |
+| `search`      | Search components, hooks, docs, templates, and themes in one ranked list                      |
 | `swizzle`     | Copy component source for customization                                                       |
 | `template`    | List, show, or scaffold page and block templates                                              |
 | `theme`       | Create and build themes: add a shipped one, compile to CSS, or list what a theme can override |
@@ -303,11 +303,12 @@ Shape:
 ```
 
 The manifest is **derived from Commander metadata** (commands, arguments, options)
-so it can't drift from the real command definitions. The two facts Commander
-doesn't track (`--json` support and emitted response types) are layered on from
-the `JSON_SUPPORTED` allowlist and a small declarative `RESPONSE_TYPES` map in
-`src/lib/manifest.mjs`, guarded by a drift test (`manifest.test.mjs`) so adding a
-command without describing it fails CI.
+so it can't drift from the real command definitions. The facts Commander doesn't
+track come from each command's docs: examples from its CommandDoc, and emitted
+response types from the returns of the FunctionDoc it wraps (plus the few
+envelopes the CLI layer builds itself). `--json` support comes from the
+`JSON_SUPPORTED` allowlist. Drift tests (`manifest.test.mjs`) fail CI when a
+command is added without describing it.
 
 **Backwards-compat:** the bare `astryx --json` envelope keeps `type: "help"` and its
 original shallow fields (`name`, `version`, `commands` as a `string[]` of names,
@@ -450,9 +451,9 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `gap-report.categories`           | The fixed gap category values and human-readable labels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `gap-report.file`                 | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.                                                                                                                                                                                                                                                                                                                                                                 |
 | `template.list`                   | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `template.show`                   | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `template.show`                   | The resolved template's source, exactly as a copy writes it, plus its description, kind, the component names it composes, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media).                                                                                                                                                                                                                                                                                                                                                           |
 | `template.skeleton`               | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `template.copy`                   | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `template.copy`                   | A scaffold receipt: template id, output directory, written file name, file count, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media).                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `template.cdn`                    | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.                                                                                                                                                                                                                                                                                                                                                                    |
 | `hook.list`                       | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `hook.detail`                     | One hook's full authored HookDoc.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -468,18 +469,18 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `upgrade.list`                    | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `upgrade.registry`                | The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items.                                                                                                                                                                                                                                                                                                                                                                                            |
 | `upgrade.status`                  | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `upgrade.run`                     | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `upgrade.run`                     | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                                                                                                                                                                                                                                                                                                    |
 | `manifest`                        | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.                                                                                                                                                                                                                                                                                                                                    |
 | `help`                            | Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). `--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). data.manifest marks the first shape; data.usage marks the second.                                                                                     |
 | `version`                         | The CLI version, for `astryx --version --json`: {version}.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `doctor`                          | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status.                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `integration.add`                 | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `integration.pack-check`          | The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}].                                                                                                                                                                            |
-| `integration.validate`            | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `integration.template-conflicts`  | The integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `integration.component-conflicts` | The integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `integration.doc-conflicts`       | The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `layout.expand`                   | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).                                                                                                                                                                                                                                                                                                                                                                                  |
+| `integration.validate`            | The validation result: validated (false when no integration manifest was found, so nothing was checked and the empty issues list proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                                                                                                                                                                                                                                                                           |
+| `integration.template-conflicts`  | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.                                                                                                                                                                                                                                                                                                                         |
+| `integration.component-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                                                                                                                    |
+| `integration.doc-conflicts`       | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                                                                                                            |
+| `layout.expand`                   | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, written (the output path, or null when nothing was written), and demoMediaReplaced (count of demo media placeholders).                                                                                                                                                                                                                                                                                                                            |
 | `layout.check`                    | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).                                                                                                                                                                                                                                                                                                                                                                                              |
 | `layout.grammar`                  | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 

package/api/build/_adapter.d.mts

@@ -7,8 +7,15 @@
  * @property {string} name The template's own id, as search reports it.
  * @property {string} command `astryx template <id> --type page`, the command that selects exactly this template: an integration replacement is selected by the Core id it replaces, and `--type page` keeps a block with the same id from making it ambiguous. Search prints template commands the same way.
  * @property {string} displayName Human-facing name.
- * @property {string} description What the page is: its layout and the ideas it serves.
+ * @property {string} description What the page is and how it is laid out.
  * @property {string} category The template's own `Family - Variant` label; empty when it declares none.
+ * @property {string[]} keywords The ideas the page serves, as its own descriptor names them; empty when it declares none.
+ */
+/**
+ * A component the project can use, as the ranker reads it.
+ * @typedef {object} ComponentWords
+ * @property {string} name The component's name, e.g. `DateRangeInput`.
+ * @property {string[]} keywords The keywords its own doc declares.
  */
 /**
  * Every ready page template the project can scaffold, in discovery order. This
@@ -23,6 +30,30 @@
  * @returns {Promise<PageTemplate[]>}
  */
 export function loadPageTemplates(cwd: string): Promise<PageTemplate[]>;
+/**
+ * The components the project can use, Core's and its integrations', each with
+ * the keywords its own doc declares: what the ranker reads to tell a part of a
+ * page from a page. Search's own discovery, so both agree on what exists; empty
+ * when Core cannot be found.
+ *
+ * @param {string} cwd
+ * @returns {Promise<ComponentWords[]>}
+ */
+export function loadComponents(cwd: string): Promise<ComponentWords[]>;
+/**
+ * The matcher weights checked in beside the kit (`kit/weights.json`), read
+ * once; null when the file is absent or unreadable.
+ * @returns {import('./kit/weights.mjs').WeightsFile | null}
+ */
+export function loadWeights(): import("./kit/weights.mjs").WeightsFile | null;
+/**
+ * Whether a parsed weights file has the shape the kit reads: every row has a
+ * weight per candidate, every bias a number per candidate, and three blend
+ * numbers per member (the tables plus the ranker) and one for the shell.
+ * @param {any} file
+ * @returns {file is import('./kit/weights.mjs').WeightsFile}
+ */
+export function isWeightsFile(file: any): file is import("./kit/weights.mjs").WeightsFile;
 /**
  * A page template the kit can recommend starting from.
  */
@@ -40,11 +71,28 @@ export type PageTemplate = {
      */
     displayName: string;
     /**
-     * What the page is: its layout and the ideas it serves.
+     * What the page is and how it is laid out.
      */
     description: string;
     /**
      * The template's own `Family - Variant` label; empty when it declares none.
      */
     category: string;
+    /**
+     * The ideas the page serves, as its own descriptor names them; empty when it declares none.
+     */
+    keywords: string[];
+};
+/**
+ * A component the project can use, as the ranker reads it.
+ */
+export type ComponentWords = {
+    /**
+     * The component's name, e.g. `DateRangeInput`.
+     */
+    name: string;
+    /**
+     * The keywords its own doc declares.
+     */
+    keywords: string[];
 };

package/api/build/_adapter.mjs

@@ -2,20 +2,25 @@
 
 /**
  * @file The build subject's environment access: the page templates a project
- * can scaffold.
+ * can scaffold, the components it can use, and the checked-in matcher weights.
  *
- * @input Template discovery for `cwd` — the CLI's own templates plus any that
- *   the project's configured integrations contribute.
+ * @input Template and component discovery for `cwd` — the CLI's own templates
+ *   and Core's components, plus any that the project's configured integrations
+ *   contribute.
  * @output Ready page templates as `{name, displayName, description, category,
- *   command}`, where `command` is the `astryx template` command that selects
- *   exactly that template.
- * @position Beside build.mjs (api/build/). The kit leaf reads templates only
- *   through here, because a subject's `_adapter.mjs` is its only environment
- *   access. Search keeps its own discovery; this adds none of its own, it
- *   reuses the template subject's.
+ *   keywords, command}`, where `command` is the `astryx template` command that
+ *   selects exactly that template; components as `{name, keywords}`.
+ * @position Beside build.mjs (api/build/). The kit leaf reads templates and
+ *   components only through here, because a subject's `_adapter.mjs` is its
+ *   only environment access. This adds no discovery of its own: templates come
+ *   from the template subject's, components from search's.
  */
 
+import fs from 'node:fs';
+
 import {discoverTemplates} from '../template/template.mjs';
+import {componentKeywords} from '../search/search.mjs';
+import {findCoreDir} from '../../foundation/fs/paths.mjs';
 
 /**
  * A page template the kit can recommend starting from.
@@ -23,8 +28,16 @@ import {discoverTemplates} from '../template/template.mjs';
  * @property {string} name The template's own id, as search reports it.
  * @property {string} command `astryx template <id> --type page`, the command that selects exactly this template: an integration replacement is selected by the Core id it replaces, and `--type page` keeps a block with the same id from making it ambiguous. Search prints template commands the same way.
  * @property {string} displayName Human-facing name.
- * @property {string} description What the page is: its layout and the ideas it serves.
+ * @property {string} description What the page is and how it is laid out.
  * @property {string} category The template's own `Family - Variant` label; empty when it declares none.
+ * @property {string[]} keywords The ideas the page serves, as its own descriptor names them; empty when it declares none.
+ */
+
+/**
+ * A component the project can use, as the ranker reads it.
+ * @typedef {object} ComponentWords
+ * @property {string} name The component's name, e.g. `DateRangeInput`.
+ * @property {string[]} keywords The keywords its own doc declares.
  */
 
 /**
@@ -53,8 +66,83 @@ export async function loadPageTemplates(cwd) {
       displayName: t.displayName || t.name,
       description: t.description || '',
       category: t.category || '',
+      keywords: t.keywords ?? [],
       // The id `template()` resolves back to this entry: an active replacement
       // owns the Core id it names, so that id selects it, not its own.
       command: `astryx template ${t.replaces ?? t.dirName} --type page`,
     }));
 }
+
+/**
+ * The components the project can use, Core's and its integrations', each with
+ * the keywords its own doc declares: what the ranker reads to tell a part of a
+ * page from a page. Search's own discovery, so both agree on what exists; empty
+ * when Core cannot be found.
+ *
+ * @param {string} cwd
+ * @returns {Promise<ComponentWords[]>}
+ */
+export async function loadComponents(cwd) {
+  const coreDir = findCoreDir(cwd);
+  if (!coreDir) return [];
+  try {
+    return await componentKeywords(coreDir, cwd);
+  } catch {
+    return [];
+  }
+}
+
+/** @type {import('./kit/weights.mjs').WeightsFile | null | undefined} */
+let weights;
+
+/**
+ * The matcher weights checked in beside the kit (`kit/weights.json`), read
+ * once; null when the file is absent or unreadable.
+ * @returns {import('./kit/weights.mjs').WeightsFile | null}
+ */
+export function loadWeights() {
+  if (weights === undefined) {
+    try {
+      const file = JSON.parse(
+        fs.readFileSync(new URL('./kit/weights.json', import.meta.url), 'utf8'),
+      );
+      weights = isWeightsFile(file) ? file : null;
+    } catch {
+      weights = null;
+    }
+  }
+  return weights ?? null;
+}
+
+/**
+ * Whether a parsed weights file has the shape the kit reads: every row has a
+ * weight per candidate, every bias a number per candidate, and three blend
+ * numbers per member (the tables plus the ranker) and one for the shell.
+ * @param {any} file
+ * @returns {file is import('./kit/weights.mjs').WeightsFile}
+ */
+export function isWeightsFile(file) {
+  const n = Array.isArray(file?.candidates) ? file.candidates.length : 0;
+  return (
+    n > 0 &&
+    Array.isArray(file.tables) &&
+    file.tables.length > 0 &&
+    file.tables.every(
+      (/** @type {any} */ t) =>
+        Array.isArray(t?.words) &&
+        Array.isArray(t.rows) &&
+        t.rows.length === t.words.length &&
+        t.rows.every(
+          (/** @type {any} */ r) => typeof r === 'string' && r.length === n,
+        ) &&
+        Array.isArray(t.bias) &&
+        t.bias.length === n &&
+        t.bias.every((/** @type {any} */ b) => Number.isFinite(b)) &&
+        Number.isFinite(t.clip) &&
+        Number.isFinite(t.step),
+    ) &&
+    Array.isArray(file.blend) &&
+    file.blend.length === 3 * (file.tables.length + 1) + 1 &&
+    file.blend.every((/** @type {any} */ x) => Number.isFinite(x))
+  );
+}

package/api/build/build.doc.mjs

@@ -19,8 +19,8 @@ export const doc = {
     'The "build a page" entry point. Called with no query it returns the ' +
     'how-to-build-a-page playbook as data: the workflow steps with their ' +
     'commands, the on-system rules, and related lookups. Called with a query it names the page template to ' +
-    'START from (always one: the page template a ranker built for long descriptions puts first, else the app ' +
-    'shell) and the next two templates, ' +
+    'START from (always one: the page template a ranker built for long descriptions puts first; for a part ' +
+    'of a page, the page it names; else the app shell) and the next two templates, ' +
     'and the unified search grouped around it: the other close page templates, drop-in blocks, and ' +
     'idea-specific components/hooks, plus the always-on frame + foundation. A template carries the page ' +
     'frame and spacing, so the kit never recommends composing a page from components.',

package/api/build/build.test.mjs

@@ -8,7 +8,7 @@ import {describe, it, expect, vi} from 'vitest';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {build} from './build.mjs';
-import {search} from '../search/search.mjs';
+import {search, searchedComponents} from '../search/search.mjs';
 
 // api/build/ -> up 3 = packages/cli, up 4 = repo root (has packages/core).
 const REPO = path.resolve(
@@ -152,6 +152,16 @@ describe('build API', () => {
   });
 });
 
+describe('build kit — reuses the components its search gathered', () => {
+  it('keeps them beside the search response, out of its JSON', async () => {
+    const all = await search('date picker', {cwd: REPO});
+    expect(searchedComponents(all)?.map(c => c.name)).toContain('DateRangeInput');
+    expect(JSON.stringify(all)).not.toContain('"keywords"');
+    const pagesOnly = await search('date picker', {cwd: REPO, type: 'template'});
+    expect(searchedComponents(pagesOnly)).toBeNull();
+  }, 60_000);
+});
+
 describe('build kit — coverage gates the pages group', () => {
   it('does not call a one-word coincidence a direct match', async () => {
     // A page's keywords include every component its source renders, so any
@@ -259,7 +269,7 @@ describe('build kit — a thin kit says what to try next', () => {
     // A skeleton is a 35-line excerpt: a reader who studies it and composes
     // the rest loses the spacing the template exists to carry. A loose match
     // is still the best start there is, so `start` scaffolds it.
-    const r = await build('executive summary', {cwd: REPO});
+    const r = await build('weekly business review with targets', {cwd: REPO});
     expect(r.type).toBe('build.kit');
     if (r.type !== 'build.kit') return;
     expect(r.data.directMatch).toBe(false);
@@ -357,9 +367,35 @@ describe('build kit — every page starts from a template', () => {
     const placed = await build('an empty state for a settings page', {cwd: REPO});
     if (placed.type !== 'build.kit') throw new Error(placed.type);
     expect(placed.data.start).toMatchObject({name: 'settings', basis: 'closest'});
+    expect(placed.data.start?.reason).toMatch(/part of a page, so it starts from the page it names/);
     const loose = await build('a date range picker', {cwd: REPO});
     if (loose.type !== 'build.kit') throw new Error(loose.type);
     expect(loose.data.start).toMatchObject({name: 'shell-top-nav', basis: 'fallback'});
+    expect(loose.data.start?.reason).toMatch(/part of a page and names no page, so it starts from the app shell/);
+  });
+
+  it('starts a change to an existing page from the app shell', async () => {
+    // The page is the builder's to keep; no template scaffolds it.
+    const r = await build('add a sort toggle to the existing reports dashboard', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error(r.type);
+    expect(r.data.start).toMatchObject({name: 'shell-top-nav', basis: 'fallback'});
+    expect(r.data.start?.reason).toMatch(/changes a page you already have, so keep it/);
+    expect(r.data.start?.reason).not.toMatch(/too little of the idea fits/);
+    // A direct match the response reports is still named.
+    if (r.data.directMatch) expect(r.data.start?.reason).toContain(`\`${r.data.pages[0].name}\``);
+  });
+
+  it('does not call a new page that mentions something existing a change', async () => {
+    for (const idea of [
+      'a new dashboard inspired by the existing one',
+      'a new dashboard based on the existing dashboard',
+      'clone the existing dashboard as a new page',
+    ]) {
+      const r = await build(idea, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error(r.type);
+      expect(r.data.start?.name).toBe('dashboard');
+      expect(r.data.start?.reason).not.toMatch(/already have/);
+    }
   });
 
   it('names a direct match the ranker outweighed in the reason', async () => {
@@ -441,6 +477,79 @@ describe('build kit — every page starts from a template', () => {
     expect(r.data.pages.map(p => p.name)).not.toContain('side-gallery');
   });
 
+  it('names a direct match the start does not use, and calls the start direct only when it is', async () => {
+    for (const idea of ['a login form', 'a docs site for our API', 'contact form']) {
+      const r = await build(idea, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error(r.type);
+      expect(r.data.directMatch).toBe(true);
+      const match = r.data.pages[0].name;
+      if (r.data.start?.name === match) {
+        expect(r.data.start?.basis).toBe('direct');
+      } else {
+        expect(['closest', 'fallback']).toContain(r.data.start?.basis);
+        expect(r.data.start?.reason).toContain(`\`${match}\``);
+      }
+    }
+  });
+
+  it('keeps a template search matched directly rather than the app shell', async () => {
+    for (const [idea, name] of [
+      ['a login screen', 'login'],
+      ['a checkout wizard', 'checkout-wizard'],
+    ]) {
+      const r = await build(idea, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error(r.type);
+      expect(r.data.directMatch).toBe(true);
+      expect(r.data.start?.name).toBe(name);
+    }
+  });
+
+  it('lets the weights choose another template over a direct match', async () => {
+    const r = await build('a login form', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error(r.type);
+    expect(r.data.directMatch).toBe(true);
+    const match = r.data.pages[0].name;
+    expect(r.data.start?.name).not.toBe('shell-top-nav');
+    expect(r.data.start?.name).not.toBe(match);
+    expect(r.data.start?.reason).toContain(`\`${match}\``);
+  });
+
+  it('starts a part that names no page from the app shell', async () => {
+    for (const idea of ['a kanban card', 'a date range picker']) {
+      const r = await build(idea, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error(r.type);
+      expect(r.data.start).toMatchObject({name: 'shell-top-nav', basis: 'fallback'});
+      expect(r.data.start?.reason).toMatch(/part of a page/);
+    }
+  });
+
+  it('does not keep a loose match over the app shell', async () => {
+    // Search matches no template directly, so the ranker's closest page does
+    // not override the shell the weights choose.
+    const r = await build('quarterly business review', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error(r.type);
+    expect(r.data.directMatch).toBe(false);
+    expect(r.data.start).toMatchObject({name: 'shell-top-nav', basis: 'fallback'});
+    expect(r.data.start?.reason).toMatch(/closest/);
+  });
+
+  it('starts a new page with no matching template from the app shell', async () => {
+    const r = await build('a new page', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error(r.type);
+    expect(r.data.start?.name).toBe('shell-top-nav');
+  });
+
+  it('starts a page the words describe from its template', async () => {
+    for (const [idea, name] of [
+      ['a weekly report of sales by region', 'dashboard-scorecard'],
+      ['a pricing page with three plans and a comparison table', 'table-page'],
+    ]) {
+      const r = await build(idea, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error(r.type);
+      expect(r.data.start?.name).toBe(name);
+    }
+  });
+
   it('starts a component in a container from a template with that frame', async () => {
     // "in a modal": the modal is the frame, so the dialog template leads
     // instead of the app shell.