@astryxdesign/cli 0.6.4 → 0.6.5-canary.01972bc

package/api/integration/pack-check.test.mjs

@@ -36,6 +36,8 @@ function writePackage({
   scripts,
 } = {}) {
   const pkg = {name, version};
+  // A theme needs a CLI that reads typed theme descriptors.
+  if (themes) pkg.peerDependencies = {'@astryxdesign/cli': '>=0.6.4'};
   if (files !== undefined) pkg.files = files;
   if (scripts !== undefined) pkg.scripts = scripts;
   fs.writeFileSync(
@@ -94,6 +96,38 @@ describe('integrationPackCheck', () => {
     );
   });
 
+  it('fails a package that ships a theme on a CLI range that cannot read it', async () => {
+    writePackage({files: ['astryx.integration.mjs', 'themes']});
+    const pkgFile = path.join(tmpDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+    delete pkg.peerDependencies;
+    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+
+    const missing = await integrationPackCheck({cwd: tmpDir});
+    expect(missing.data.packable).toBe(false);
+    expect(missing.data.issues).toContainEqual(
+      expect.objectContaining({
+        code: 'themes_need_cli',
+        message: expect.stringContaining('ships a theme'),
+      }),
+    );
+
+    pkg.peerDependencies = {'@astryxdesign/cli': '^0.6.3'};
+    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+    const old = await integrationPackCheck({cwd: tmpDir});
+    expect(old.data.issues).toContainEqual(
+      expect.objectContaining({code: 'themes_need_cli'}),
+    );
+
+    // Published 0.6.4 reads typed theme descriptors.
+    pkg.peerDependencies = {'@astryxdesign/cli': '>=0.6.4'};
+    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+    const current = await integrationPackCheck({cwd: tmpDir});
+    expect(current.data.issues).not.toContainEqual(
+      expect.objectContaining({code: 'themes_need_cli'}),
+    );
+  });
+
   it('fails when a theme entry omits its inferred runtime export', async () => {
     writePackage({files: ['astryx.integration.mjs', 'themes']});
     fs.writeFileSync(
@@ -193,6 +227,39 @@ describe('integrationPackCheck', () => {
     );
   });
 
+  it('resolves public imports in the packed package, not the source', async () => {
+    // The root export's target is left out of `files`: the source package
+    // resolves it, but an app that installs the tarball cannot.
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs'],
+        exports: {'.': './index.mjs'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'index.mjs'),
+      "export {AcmeWidget} from './components/AcmeWidget.tsx';\n",
+    );
+    await integrationAddComponent('AcmeWidget', {cwd: tmpDir});
+    const docFile = path.join(tmpDir, 'components', 'AcmeWidget.doc.mjs');
+    const doc = fs.readFileSync(docFile, 'utf-8');
+    expect(doc).toContain('@acme/widgets/components/AcmeWidget');
+    fs.writeFileSync(
+      docFile,
+      doc.replace('@acme/widgets/components/AcmeWidget', '@acme/widgets'),
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(false);
+    expect(result.data.issues).toContainEqual(
+      expect.objectContaining({code: 'component_export_missing'}),
+    );
+  });
+
   it('fails when packed template source is hidden by package exports', async () => {
     writePackage({
       manifest: "export default {templates: './templates'};\n",
@@ -307,7 +374,10 @@ describe('integrationPackCheck', () => {
     expect(await codes()).toContain('docs_tree_needs_cli');
     peer('^0.6.0 || >=0.7.0');
     expect(await codes()).toContain('docs_tree_needs_cli');
-    peer('>=0.7.0');
+    peer('>=0.6.3');
+    expect(await codes()).toContain('docs_tree_needs_cli');
+    // Published 0.6.4 reads the docs tree.
+    peer('>=0.6.4');
     expect(await codes()).not.toContain('docs_tree_needs_cli');
   }, 120_000);
 
@@ -336,6 +406,41 @@ describe('integrationPackCheck', () => {
     expect(await codes()).not.toContain('docs_tree_needs_cli');
   }, 120_000);
 
+  it('fails a package whose doc section sets id on a CLI range that rejects the field', async () => {
+    writePackage({manifest: "export default {docs: './docs'};\n", themes: false});
+    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+    const topic = (/** @type {string} */ section) =>
+      `export default {type: 'generic', name: 'notes', title: 'Notes', description: 'Notes.', sections: [${section}]};\n`;
+    const file = path.join(tmpDir, 'docs', 'notes.doc.mjs');
+    const codes = async () =>
+      (await integrationPackCheck({cwd: tmpDir})).data.issues.map(
+        (/** @type {{code: string}} */ issue) => issue.code,
+      );
+    fs.writeFileSync(
+      file,
+      topic("{title: 'Take notes', content: [{type: 'prose', text: 'Notes.'}]}"),
+    );
+    expect(await codes()).not.toContain('section_ids_need_cli');
+    // A fresh file name: the module loader caches a path once it is imported.
+    fs.rmSync(file);
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'notes-with-ids.doc.mjs'),
+      topic(
+        "{id: 'take-notes', title: 'Take notes', content: [{type: 'prose', text: 'Notes.'}]}",
+      ),
+    );
+    expect(await codes()).toContain('section_ids_need_cli');
+    const pkgFile = path.join(tmpDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+    pkg.peerDependencies = {'@astryxdesign/cli': '^0.6.3'};
+    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+    expect(await codes()).toContain('section_ids_need_cli');
+    // Published 0.6.4 reads a section id.
+    pkg.peerDependencies = {'@astryxdesign/cli': '>=0.6.4'};
+    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+    expect(await codes()).not.toContain('section_ids_need_cli');
+  }, 120_000);
+
   it('fails a package with a template that sets replaces on a CLI range that rejects the field', async () => {
     writePackage({manifest: "export default {templates: './templates'};\n", themes: false});
     fs.mkdirSync(path.join(tmpDir, 'templates'), {recursive: true});
@@ -363,10 +468,44 @@ describe('integrationPackCheck', () => {
     expect(await codes()).toContain('replaces_needs_cli');
     peer('^0.6.0');
     expect(await codes()).toContain('replaces_needs_cli');
+    // `replaces` still needs 0.7.0.
+    peer('>=0.6.4');
+    expect(await codes()).toContain('replaces_needs_cli');
     peer('>=0.7.0');
     expect(await codes()).not.toContain('replaces_needs_cli');
   }, 120_000);
 
+  it('fails a package with a template that sets keywords on a CLI range that rejects the field', async () => {
+    writePackage({manifest: "export default {templates: './templates'};\n", themes: false});
+    fs.mkdirSync(path.join(tmpDir, 'templates'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'templates', 'acme-health.doc.mjs'),
+      "export default {type: 'page', name: 'acme-health', description: 'Status tiles.', keywords: ['uptime']};\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'templates', 'acme-health.tsx'),
+      'export default function AcmeHealth() { return null; }\n',
+    );
+    const file = path.join(tmpDir, 'package.json');
+    const peer = (/** @type {string | undefined} */ range) => {
+      const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+      if (range == null) delete pkg.peerDependencies;
+      else pkg.peerDependencies = {'@astryxdesign/cli': range};
+      fs.writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+    };
+    const codes = async () =>
+      (await integrationPackCheck({cwd: tmpDir})).data.issues.map(
+        (/** @type {{code: string}} */ issue) => issue.code,
+      );
+
+    peer(undefined);
+    expect(await codes()).toContain('keywords_needs_cli');
+    peer('^0.6.0');
+    expect(await codes()).toContain('keywords_needs_cli');
+    peer('>=0.7.0');
+    expect(await codes()).not.toContain('keywords_needs_cli');
+  }, 120_000);
+
   it('passes when package.json has no files field', async () => {
     writePackage({files: undefined});
     const result = await integrationPackCheck({cwd: tmpDir});

package/api/integration/pack-check.type.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Colocated types for `astryx integration pack --check`.
+ * @file Colocated types for `astryx integration verify`.
  */
 
 /**

package/api/integration/validate-integration.d.mts

@@ -19,8 +19,10 @@ export function validateInstalledIntegration(spec: string, cwd?: string): Promis
 /**
  * Unified entry: validate the LOCAL integration (no `pkg`) or an INSTALLED one
  * (`pkg` given) and return the `integration.validate` envelope. The no-manifest
- * local case is guidance, not an error — it comes back with `name: null` and no
- * issues so the CLI can print a hint and stay exit-0.
+ * local case is guidance, not an error — it comes back with `validated: false`,
+ * `name: null` and no issues so the CLI can print a hint and stay exit-0.
+ * `validated` is what tells a machine consumer that empty `issues` means
+ * "nothing was checked" rather than "checked and healthy".
  *
  * This is the seam that keeps the CLI a thin wrapper: the command handler calls
  * this and only chooses how to render (human vs --json) + the exit code.

package/api/integration/validate-integration.mjs

@@ -427,8 +427,10 @@ export async function validateInstalledIntegration(spec, cwd = process.cwd()) {
 /**
  * Unified entry: validate the LOCAL integration (no `pkg`) or an INSTALLED one
  * (`pkg` given) and return the `integration.validate` envelope. The no-manifest
- * local case is guidance, not an error — it comes back with `name: null` and no
- * issues so the CLI can print a hint and stay exit-0.
+ * local case is guidance, not an error — it comes back with `validated: false`,
+ * `name: null` and no issues so the CLI can print a hint and stay exit-0.
+ * `validated` is what tells a machine consumer that empty `issues` means
+ * "nothing was checked" rather than "checked and healthy".
  *
  * This is the seam that keeps the CLI a thin wrapper: the command handler calls
  * this and only chooses how to render (human vs --json) + the exit code.
@@ -445,6 +447,9 @@ export async function validateIntegration(pkg, options = {}) {
   return {
     type: 'integration.validate',
     data: {
+      // The one bit that separates "checked and clean" from "never checked":
+      // with no manifest there is nothing to validate, and issues stays [].
+      validated: result.found,
       name: result.found ? (result.name ?? null) : null,
       version: result.found ? (result.version ?? null) : null,
       issues: result.issues,

package/api/integration/validate-integration.test.mjs

@@ -625,3 +625,58 @@ describe('integration diagnostics are read-only', () => {
     expect({pkg: snapshot(pkgDir), consumer: snapshot(consumer)}).toEqual(before);
   });
 });
+
+describe('validated separates "checked and clean" from "never checked"', () => {
+  // `doctor integration validate --json` from a directory with no manifest
+  // returned {name: null, version: null, issues: []} and exit 0 — the same
+  // envelope a healthy, fully validated integration produces. Wire that into
+  // CI from the wrong directory and it is green forever.
+  it('is false for every check when no manifest is found', async () => {
+    const dir = path.join(tmpDir, 'plain');
+    fs.mkdirSync(dir, {recursive: true});
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      JSON.stringify({name: 'plain-app', version: '1.0.0'}),
+    );
+
+    const validate = await validateIntegration(undefined, {cwd: dir});
+    expect(validate.data.validated).toBe(false);
+    expect(validate.data.issues).toEqual([]);
+
+    const templates = await integrationTemplateConflicts(undefined, {cwd: dir});
+    const components = await integrationComponentConflicts(undefined, {cwd: dir});
+    const docs = await integrationDocConflicts(undefined, {cwd: dir});
+    expect(templates.data.validated).toBe(false);
+    expect(components.data.validated).toBe(false);
+    expect(docs.data.validated).toBe(false);
+  });
+
+  it('is true for a real integration, whose empty issue list then means healthy', async () => {
+    const dir = path.join(tmpDir, 'integration');
+    writePackage(dir, {manifest: 'export default {};\n'});
+
+    const validate = await validateIntegration(undefined, {cwd: dir});
+    expect(validate.data.validated).toBe(true);
+    expect(validate.data.name).toBe('@acme/widgets');
+
+    const templates = await integrationTemplateConflicts(undefined, {cwd: dir});
+    const components = await integrationComponentConflicts(undefined, {cwd: dir});
+    const docs = await integrationDocConflicts(undefined, {cwd: dir});
+    expect(templates.data.validated).toBe(true);
+    expect(components.data.validated).toBe(true);
+    expect(docs.data.validated).toBe(true);
+  });
+
+  it('is true for an installed package that could not be found — that is a real finding', async () => {
+    const consumer = path.join(tmpDir, 'consumer');
+    fs.mkdirSync(consumer, {recursive: true});
+    fs.writeFileSync(
+      path.join(consumer, 'package.json'),
+      JSON.stringify({name: 'consumer', version: '1.0.0'}),
+    );
+
+    const res = await validateIntegration('@acme/nope', {cwd: consumer});
+    expect(res.data.validated).toBe(true);
+    expect(summarizeIssues(res.data.issues).errors).toBeGreaterThan(0);
+  });
+});

package/api/integration/validate-integration.type.d.mts

@@ -27,10 +27,15 @@ export type ValidateIntegrationOptions = {
 };
 /**
  * `astryx --json doctor integration validate [package]`.
+ *
+ * `validated` is false in exactly one case: no integration manifest was found,
+ * so nothing was checked. An empty `issues` then means "not looked at", not
+ * "healthy" — the two are otherwise byte-identical.
  */
 export type ValidateIntegrationResponse = {
     type: "integration.validate";
     data: {
+        validated: boolean;
         name: string | null;
         version: string | null;
         issues: import("../../foundation/integrations/issue").AstryxIntegrationIssue[];

package/api/integration/validate-integration.type.mjs

@@ -32,9 +32,13 @@
 
 /**
  * `astryx --json doctor integration validate [package]`.
+ *
+ * `validated` is false in exactly one case: no integration manifest was found,
+ * so nothing was checked. An empty `issues` then means "not looked at", not
+ * "healthy" — the two are otherwise byte-identical.
  * @typedef {object} ValidateIntegrationResponse
  * @property {'integration.validate'} type
- * @property {{name: string | null, version: string | null, issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
+ * @property {{validated: boolean, name: string | null, version: string | null, issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
  */
 
 export {};

package/api/integration/validateIntegration.doc.mjs

@@ -46,7 +46,7 @@ export const doc = {
     {
       type: 'integration.validate',
       description:
-        'The result envelope: `data.name` and `data.version` of the validated package (both null only when no local manifest is found; `data.name` is `(local package)` when the local package.json has no readable name), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
+        'The result envelope: `data.validated`, false only when no integration manifest was found — nothing was checked, so the empty `data.issues` means "not looked at", not "healthy"; `data.name` and `data.version` of the validated package (both null when `data.validated` is false; `data.name` is `(local package)` when the local package.json has no readable name), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
     },
   ],
   examples: [

package/api/json/assertResponse.doc.mjs

@@ -49,7 +49,7 @@ export const doc = {
   throws: [
     {
       code: 'Error',
-      when: 'the CLI returned an error envelope (the CLI message is rethrown), or the response `type` is not expectedType',
+      when: 'a plain Error with no code: the CLI returned an error envelope (its message is rethrown; code and suggestions are dropped), or the response `type` is not expectedType',
     },
   ],
   examples: [

package/api/json/isError.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'isError()',
   summary: 'Did the CLI return an error envelope?',
   description:
-    'Tests a parsed response for an `error` key. Branch on this before touching `data`: ' +
+    'Tests a parsed response for an `error` key. Branch on this before touching `data`, ' +
     'and prefer the stable `code` field over matching the human-readable message, which is ' +
     'not a contract. Note this returns a plain boolean, not a TypeScript type predicate, so ' +
     'it does not narrow on its own: cast to the matching *Response type to get typed access.',

package/api/layout/expand/expand.mjs

@@ -18,7 +18,7 @@ import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {assertWithin, isFilePathArg, PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
 import {detectForm} from '../../../foundation/xle/parse.mjs';
 import {expand} from '../../../foundation/xle/expand.mjs';
-import {stripTemplateAssetRefs} from '../../template/template.mjs';
+import {replaceDemoMedia} from '../../template/template.mjs';
 import {analyze, formatIssue} from '../_adapter.mjs';
 
 /** @param {string} name */
@@ -59,28 +59,32 @@ function collectHintNames(doc) {
 /**
  * Build the blockModules map expand() needs: import-mode for app components,
  * splice-mode (reading + asset-stripping the block source) for template blocks.
- * Only blocks actually referenced are read.
+ * Only blocks actually referenced are read. Also returns how many demo media
+ * references the splice-mode sources had replaced.
  *
  * @param {import('../../../foundation/xle/xle-ast').XLEDoc} doc
  * @param {import('../_adapter.mjs').LayoutBlock[]} blocks
- * @returns {Map<string, import('../../../foundation/xle/xle-ast').BlockModule>}
+ * @returns {{modules: Map<string, import('../../../foundation/xle/xle-ast').BlockModule>, demoMediaReplaced: number}}
  */
 function buildBlockModules(doc, blocks) {
   const referenced = collectHintNames(doc);
-  if (referenced.size === 0) return new Map();
+  if (referenced.size === 0) return {modules: new Map(), demoMediaReplaced: 0};
   const byKey = new Map(blocks.map(b => [normKey(b.dirName), b]));
   /** @type {Map<string, import('../../../foundation/xle/xle-ast').BlockModule>} */
   const modules = new Map();
+  let demoMediaReplaced = 0;
   for (const name of referenced) {
     const block = byKey.get(normKey(name));
     if (!block) continue;
     if (block.kind === 'component') {
       modules.set(name, /** @type {import('../../../foundation/xle/xle-ast').BlockModule} */ (/** @type {unknown} */ ({mode: 'import', componentName: block.name, importPath: block.importPath, isDefault: block.isDefault})));
     } else if (block.filePath && fs.existsSync(block.filePath)) {
-      modules.set(name, /** @type {import('../../../foundation/xle/xle-ast').BlockModule} */ ({mode: 'splice', componentName: block.dirName, source: stripTemplateAssetRefs(fs.readFileSync(block.filePath, 'utf-8'))}));
+      const spliced = replaceDemoMedia(fs.readFileSync(block.filePath, 'utf-8'));
+      demoMediaReplaced += spliced.demoMediaReplaced;
+      modules.set(name, /** @type {import('../../../foundation/xle/xle-ast').BlockModule} */ ({mode: 'splice', componentName: block.dirName, source: spliced.source}));
     }
   }
-  return modules;
+  return {modules, demoMediaReplaced};
 }
 
 /**
@@ -115,7 +119,7 @@ export async function layoutExpand(expression, options = {}) {
       ERROR_CODES.ERR_INVALID_ARGUMENT,
     );
   }
-  const blockModules = buildBlockModules(doc, blocks);
+  const {modules: blockModules, demoMediaReplaced} = buildBlockModules(doc, blocks);
   const result = expand(doc, registry, {componentName, blockModules});
 
   let written = null;
@@ -150,6 +154,7 @@ export async function layoutExpand(expression, options = {}) {
       blocksReferenced: [...blockModules.entries()].map(([name, m]) => ({name, mode: m.mode})),
       warnings: warnings.map(formatIssue),
       written,
+      demoMediaReplaced,
     },
   };
 }

package/api/layout/expand/expand.receipt.test.mjs

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The layout.expand receipt discloses demo media replaced in the template
+ * blocks it splices. Blocks are picked by what their source contains, not by
+ * name, so catalog renames do not break the suite.
+ */
+
+import {describe, it, expect, beforeAll} from 'vitest';
+import * as fs from 'node:fs';
+import {layoutExpand} from '../layout.mjs';
+import {discoverTemplates} from '../../template/template.mjs';
+import {buildRegistry} from '../../../foundation/xle/registry.mjs';
+
+const SLOW = 60_000;
+const FIXTURE_REF = /\/template-assets\/[\w.-]+\.\w+/g;
+
+beforeAll(async () => {
+  await buildRegistry();
+}, 120_000);
+
+/** @param {string} name */
+const hintKey = name => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/** @type {Promise<Array<{hint: string, refs: number}>> | undefined} */
+let catalog;
+
+/**
+ * Template blocks a `{hint}` resolves to unambiguously, with the number of demo
+ * media references in each one's source.
+ * @returns {Promise<Array<{hint: string, refs: number}>>}
+ */
+function catalogBlocks() {
+  catalog ??= discoverTemplates().then(found => {
+    const all = /** @type {Array<{dirName: string, type: string, filePath: string}>} */ (
+      found
+    ).filter(t => t.type === 'block' && t.filePath && fs.existsSync(t.filePath));
+    const seen = new Map();
+    for (const t of all) seen.set(hintKey(t.dirName), (seen.get(hintKey(t.dirName)) ?? 0) + 1);
+    return all
+      .filter(t => seen.get(hintKey(t.dirName)) === 1)
+      .map(t => ({
+        hint: hintKey(t.dirName),
+        refs: (fs.readFileSync(t.filePath, 'utf-8').match(FIXTURE_REF) ?? []).length,
+      }));
+  });
+  return catalog;
+}
+
+describe('layout.expand receipt - replaced demo media', () => {
+  it('counts the demo media of a spliced block once, however often it is referenced', async () => {
+    const block = (await catalogBlocks()).find(b => b.refs > 0);
+    if (!block) throw new Error('no template block carries demo media');
+    const res = await layoutExpand(`V > {${block.hint}}*3`);
+    expect(res.type).toBe('layout.expand');
+    expect(res.data.blocksReferenced).toHaveLength(1);
+    expect(res.data.demoMediaReplaced).toBe(block.refs);
+    expect(res.data.code).not.toContain('/template-assets/');
+  }, SLOW);
+
+  it('sums the demo media of every spliced block', async () => {
+    const [a, b] = (await catalogBlocks()).filter(x => x.refs > 0);
+    if (!b) throw new Error('fewer than two template blocks carry demo media');
+    const res = await layoutExpand(`V > {${a.hint}} + {${b.hint}}`);
+    expect(res.data.demoMediaReplaced).toBe(a.refs + b.refs);
+  }, SLOW);
+
+  it('reports 0 when nothing spliced carries demo media', async () => {
+    const plain = (await catalogBlocks()).find(b => b.refs === 0);
+    if (!plain) throw new Error('every template block carries demo media');
+    expect((await layoutExpand(`V > {${plain.hint}}`)).data.demoMediaReplaced).toBe(0);
+    expect((await layoutExpand('V > B"Save"')).data.demoMediaReplaced).toBe(0);
+  }, SLOW);
+});

package/api/layout/layout.type.d.mts

@@ -36,6 +36,7 @@ export type LayoutExpandResponse = {
         blocksReferenced: LayoutBlockReference[];
         warnings: string[];
         written: string | null;
+        demoMediaReplaced: number;
     };
 };
 /**

package/api/layout/layout.type.mjs

@@ -48,6 +48,7 @@
  * @property {LayoutBlockReference[]} data.blocksReferenced
  * @property {string[]} data.warnings
  * @property {string | null} data.written
+ * @property {number} data.demoMediaReplaced Astryx demo media references (images, posters, videos) replaced in the spliced template blocks: images with a neutral placeholder, videos with an empty source. Swap in your own media at those points in the code; no media is installed. 0 when no spliced block carried any.
  */
 
 /**

package/api/layout/layoutExpand.doc.mjs

@@ -70,7 +70,7 @@ export const doc = {
     {
       type: 'layout.expand',
       description:
-        'The expansion: the parsed form, the generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the relative output path, or null when nothing was written).',
+        'The expansion: the parsed form, the generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, written (the relative output path, or null when nothing was written), and demoMediaReplaced (how many Astryx demo media references in the spliced template blocks, such as images, posters and videos, were replaced with placeholders for you to swap for your own media).',
     },
   ],
   throws: [

package/api/search/search.d.mts

@@ -24,6 +24,23 @@ export function sameWord(a: string, b: string): boolean;
  * @returns {string[]}
  */
 export function tokenizeQuery(term: string): string[];
+/**
+ * The first title or heading that holds every word of the query, in order and
+ * side by side, or null.
+ * @param {string} term - Lowercased full query.
+ * @param {string[] | undefined} titles
+ * @returns {string | null}
+ */
+export function headingWithPhrase(term: string, titles: string[] | undefined): string | null;
+/**
+ * The first title or heading of two words or more that the query holds whole,
+ * in order and side by side, or null. A question such as "how do I add dark
+ * mode" names the "Dark mode" section outright, around words no title has.
+ * @param {string} term - Lowercased full query.
+ * @param {string[] | undefined} titles
+ * @returns {string | null}
+ */
+export function titleInQuery(term: string, titles: string[] | undefined): string | null;
 /**
  * @param {string} term - Lowercased full query.
  * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
@@ -49,6 +66,8 @@ export function scoreQuery(term: string, tokens: string[], candidate: Candidate)
  * @param {string} term - Lowercased search term.
  * @param {object} candidate
  * @param {string} candidate.name - Primary identifier (component/hook name, topic, template name).
+ * @param {string} [candidate.domain] - A component, hook, or template name
+ *   also matches typed as words: `command palette` is CommandPalette.
  * @param {string[]} [candidate.keywords] - Authored intent (componentsUsed, category words).
  * @param {string[]} [candidate.weakKeywords] - Derived signal (components a page renders).
  * @param {string} [candidate.description]
@@ -57,8 +76,9 @@ export function scoreQuery(term: string, tokens: string[], candidate: Candidate)
  * @param {{fuzzy?: boolean}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false.
  * @returns {{score: number, reason: string} | null}
  */
-export function scoreCandidate(term: string, { name, keywords, weakKeywords, description, prose, guidance, }: {
+export function scoreCandidate(term: string, { name, domain, keywords, weakKeywords, description, prose, guidance, }: {
     name: string;
+    domain?: string | undefined;
     keywords?: string[] | undefined;
     weakKeywords?: string[] | undefined;
     description?: string | undefined;
@@ -70,6 +90,30 @@ export function scoreCandidate(term: string, { name, keywords, weakKeywords, des
     score: number;
     reason: string;
 } | null;
+/**
+ * The components (name and keywords) a search response was scored against, or
+ * null when that search was narrowed away from components.
+ * @param {object} response
+ * @returns {{name: string, keywords: string[]}[] | null}
+ */
+export function searchedComponents(response: object): {
+    name: string;
+    keywords: string[];
+}[] | null;
+/**
+ * Every component the project can use, Core's and its integrations', with the
+ * keywords its own doc declares: the discovery and doc reads search's own
+ * candidates use, without the import paths and prose a result carries. `build`
+ * reads it to tell a part of a page from a page when its search was narrowed
+ * away from components.
+ * @param {string} coreDir
+ * @param {string} cwd
+ * @returns {Promise<{name: string, keywords: string[]}[]>}
+ */
+export function componentKeywords(coreDir: string, cwd: string): Promise<{
+    name: string;
+    keywords: string[];
+}[]>;
 /**
  * Unified ranked search across components, hooks, docs, and templates.
  *
@@ -122,6 +166,12 @@ export type Candidate = {
     description?: string | undefined;
     prose?: string[] | undefined;
     guidance?: string[] | undefined;
+    /**
+     * - A doc's title and the headings inside it:
+     * the lines a reader scans to pick it. The whole query standing in one of
+     * them, or one of them standing whole in the query, is a top-tier match.
+     */
+    titles?: string[] | undefined;
     _import?: string | undefined;
     _title?: string | undefined;
     /**

package/api/search/search.doc.mjs

@@ -48,7 +48,7 @@ export const doc = {
       name: 'options.cwd',
       type: 'string',
       description:
-        "Directory to resolve @astryxdesign/core from. A docs-only search (`type: 'doc'`) does not need it.",
+        "Directory to resolve @astryxdesign/core from. A docs-only search (`type: 'doc'`) does not need it, and a search with no `type` covers the docs alone when core is missing.",
     },
   ],
   returns: [
@@ -65,7 +65,7 @@ export const doc = {
     },
     {
       code: 'ERR_CORE_NOT_FOUND',
-      when: '@astryxdesign/core cannot be found from the cwd, and the search reads it: every `type` but `doc`',
+      when: '@astryxdesign/core cannot be found from the cwd, and `type` names a domain that reads it: `component`, `hook`, or `template`',
     },
   ],
   examples: [