@astryxdesign/cli 0.1.6-canary.aeb5ee6 → 0.1.6-canary.b2a4936

package/docs/integration-authoring.md

@@ -0,0 +1,105 @@
+# Authoring an Astryx Integration
+
+> **Status:** working notes. This should eventually move to the public wiki
+> alongside the rest of the integration-authoring guidance; it lives here for
+> now so it ships and is versioned with the CLI.
+
+An **Integration** is an npm package that contributes components, templates, and/or
+codemods to a consumer's design-system workflow. Consumers install the 3rd party
+package, add a line to their astryx.config file:
+
+```js
+import {createConfig} from '@astryxdesign/cli/config';
+
+export default createConfig({
+  integrations: ['@acme/astryx-widgets'],
+  ...
+});
+```
+
+Then the integration's components and templates will be surfaced alongside Astryx
+components in the Astryx CLI.
+
+```sh
+astryx component AcmeCarousel --props
+astryx component --list --package @acme/astryx-widgets
+```
+
+## The Integration File
+
+In order to register your package as an Astryx Integration, create an
+`astryx.integration.{ts,mjs,js}` file as a sibling to your `package.json`. This file
+tells Astryx where to find your components, templates, codemods, etc.
+
+```js
+// astryx.integration.{ts,mjs,js}
+import {createIntegration} from '@astryxdesign/cli/integration';
+
+export default createIntegration({
+  components: './components',
+  templates: './templates',
+  codemods: './codemods',
+  issuesUrl: 'https://github.com/acme/widgets/issues',
+});
+```
+
+## Components
+
+Your components themselves may be exported from your library as you see fit (consumers
+will still import them from your package) but Astryx CLI will look for a .doc.{ts,mjs,js}
+file with the same stem e.g. `AcmeCarousel.tsx` and `AcmeCarousel.doc.ts`.
+
+```js
+// AcmeCarousel.doc.ts
+import {createComponentDoc} from '@astryxdesign/cli/doc';
+
+export default createComponentDoc({
+  name: 'AcmeCarousel',
+  description: '...',
+  ...
+});
+```
+
+## Templates
+
+Templates are typically not exported from the package directly, but instead accessed
+via the Astryx CLI. Consumers can look through your templates and materialize them
+into their apps.
+
+You define a template with the `createPageTemplate` (for full pages) or `createBlockTemplate`
+(for smaller chunks). e.g. `AcmeLandingPage.tsx`, `AcmeLandingPage.template.ts`
+
+```js
+// AcmeLandingPage.template.ts
+import {createPageTemplate} from '@astryxdesign/cli/template';
+
+export default createPageTemplate({
+  ...
+});
+```
+
+Note that, since the CLI needs access to the template source code, you need to make sure
+that it is included in your published package. This will also allow us to render previews
+of templates in the future by bundling your template into a doc site build.
+
+Typically, this is done via the package.json `exports` key.
+
+```jsonc
+{
+  "exports": {
+    // ...
+    "./templates/*.tsx": "./templates/*.tsx",
+  },
+}
+```
+
+In order to verify that it's working, you can test importing the template component like this:
+
+```ts
+import('@acme/astryx-widgets/templates/AcmeLandingPage.tsx');
+```
+
+Import **with the `.tsx` extension** — an extensionless specifier won't resolve
+under `moduleResolution: bundler`. The extensionful `"./templates/*.tsx"` export
+above is what lets that import type-check without consumers enabling
+`allowImportingTsExtensions`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.6-canary.aeb5ee6",
+  "version": "0.1.6-canary.b2a4936",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -75,10 +75,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.aeb5ee6",
-    "@astryxdesign/core": "0.1.6-canary.aeb5ee6",
-    "@astryxdesign/lab": "0.1.6-canary.aeb5ee6",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.aeb5ee6",
+    "@astryxdesign/charts": "0.1.6-canary.b2a4936",
+    "@astryxdesign/core": "0.1.6-canary.b2a4936",
+    "@astryxdesign/lab": "0.1.6-canary.b2a4936",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.b2a4936",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -96,10 +96,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.aeb5ee6",
-    "@astryxdesign/core": "0.1.6-canary.aeb5ee6",
-    "@astryxdesign/lab": "0.1.6-canary.aeb5ee6",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.aeb5ee6",
+    "@astryxdesign/charts": "0.1.6-canary.b2a4936",
+    "@astryxdesign/core": "0.1.6-canary.b2a4936",
+    "@astryxdesign/lab": "0.1.6-canary.b2a4936",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.b2a4936",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/src/api/integration-block-exports.test.mjs

@@ -0,0 +1,240 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Proves the minimal `exports` recipe an integration package needs so a
+ * bundler-resolution consumer can `import()` its block templates AND type-check
+ * them under `moduleResolution: bundler`.
+ *
+ * Integration packages in this ecosystem ship TypeScript SOURCE — their block
+ * templates are `.tsx` files with no compiled `.d.ts`. A later feature renders
+ * showcase previews by a REAL dynamic `import()` of a block's `.tsx` source
+ * (e.g. `import('@acme/widgets/templates/Gauge/GaugeShowcase.tsx')`) instead of
+ * eval'ing source text. For that import to resolve, the integration's
+ * `package.json#exports` map must GATE the deep path.
+ *
+ * These tests stand up a throwaway `@acme/widgets` fixture and drive the two
+ * gates that matter with the repo's own toolchain:
+ *   1. `tsc --noEmit` under `moduleResolution: bundler` (the consumer profile
+ *      used by the Next.js example apps — NO `allowImportingTsExtensions`).
+ *   2. `esbuild --bundle` (a real bundler resolving + loading the deep import).
+ *
+ * CANONICAL RECIPE (see integration-authoring.md):
+ *   exports: { "./templates/*.tsx": "./templates/*.tsx" }
+ *   import:  import('@acme/widgets/templates/<Name>/<Name>Showcase.tsx')   // WITH .tsx
+ *
+ * The negative controls lock in WHY the extension is required: a bare
+ * `./templates/*` export with an extensionless import fails to type-check under
+ * bundler resolution (TS cannot infer the `.tsx` extension for a deep
+ * specifier), and an extensionless import fails to bundle.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {createRequire} from 'node:module';
+import {execFileSync} from 'node:child_process';
+
+const require = createRequire(import.meta.url);
+
+/** Resolve the workspace tsc/esbuild binaries; null if unavailable. */
+function resolveBin(spec) {
+  try {
+    return require.resolve(spec);
+  } catch {
+    return null;
+  }
+}
+const TSC_BIN = resolveBin('typescript/bin/tsc');
+const ESBUILD_BIN = resolveBin('esbuild/bin/esbuild');
+
+let tmpDir;
+
+/**
+ * Build an @acme/widgets fixture: a block template (`.template.ts` doc +
+ * same-stem `.tsx` source) under `templates/`, plus an astryx.integration
+ * manifest, plus a caller-supplied `exports` map.
+ * @param {Record<string, string> | undefined} exportsMap
+ */
+function makeWidgets(exportsMap) {
+  const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+  const blockDir = path.join(pkgDir, 'templates', 'Gauge');
+  fs.mkdirSync(blockDir, {recursive: true});
+
+  const pkg = {name: '@acme/widgets', version: '2.0.0', type: 'module'};
+  if (exportsMap) pkg.exports = exportsMap;
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify(pkg, null, 2),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default { templates: './templates' };\n`,
+  );
+  // The template-spec doc (canonical `.template.*` family).
+  fs.writeFileSync(
+    path.join(blockDir, 'GaugeShowcase.template.ts'),
+    `export default { name: 'Gauge showcase', description: 'A gauge.' };\n`,
+  );
+  // The same-stem `.tsx` SOURCE that a preview will dynamically import().
+  // Returns a plain value so the fixture type-checks without React types.
+  fs.writeFileSync(
+    path.join(blockDir, 'GaugeShowcase.tsx'),
+    `const GaugeShowcase = (): string => 'gauge-showcase';\n` +
+      `export default GaugeShowcase;\n`,
+  );
+  return pkgDir;
+}
+
+/** Write a consumer that dynamically imports the given specifier. */
+function writeConsumer(specifier) {
+  fs.writeFileSync(
+    path.join(tmpDir, 'consumer.ts'),
+    `const load = () => import('${specifier}');\nexport default load;\n`,
+  );
+}
+
+/**
+ * The realistic consumer tsconfig: matches the repo's Next.js example apps
+ * (`moduleResolution: bundler`, `noEmit`, and deliberately NO
+ * `allowImportingTsExtensions`).
+ */
+function writeTsconfig() {
+  fs.writeFileSync(
+    path.join(tmpDir, 'tsconfig.json'),
+    JSON.stringify(
+      {
+        compilerOptions: {
+          target: 'ES2022',
+          lib: ['ES2022', 'DOM', 'DOM.Iterable'],
+          module: 'ESNext',
+          moduleResolution: 'bundler',
+          jsx: 'react-jsx',
+          strict: true,
+          skipLibCheck: true,
+          esModuleInterop: true,
+          noEmit: true,
+          isolatedModules: true,
+        },
+        include: ['consumer.ts'],
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+/** @returns {{ok: boolean, out: string}} */
+function runTsc() {
+  try {
+    execFileSync(process.execPath, [TSC_BIN, '--noEmit', '-p', 'tsconfig.json'], {
+      cwd: tmpDir,
+      stdio: 'pipe',
+    });
+    return {ok: true, out: ''};
+  } catch (e) {
+    return {ok: false, out: `${e.stdout ?? ''}${e.stderr ?? ''}`};
+  }
+}
+
+/** @returns {{ok: boolean, out: string}} */
+function runEsbuild() {
+  try {
+    // esbuild's bin is a native executable (not a node script), so invoke it
+    // directly rather than through process.execPath.
+    execFileSync(
+      ESBUILD_BIN,
+      [
+        'consumer.ts',
+        '--bundle',
+        '--format=esm',
+        '--loader:.tsx=tsx',
+        '--outfile=/dev/null',
+        '--log-level=error',
+      ],
+      {cwd: tmpDir, stdio: 'pipe'},
+    );
+    return {ok: true, out: ''};
+  } catch (e) {
+    return {ok: false, out: `${e.stdout ?? ''}${e.stderr ?? ''}`};
+  }
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-block-exports-'));
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer', private: true, type: 'module'}),
+  );
+  writeTsconfig();
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+const CANONICAL = 'import(@acme/widgets/templates/Gauge/GaugeShowcase.tsx)';
+const SPEC = '@acme/widgets/templates/Gauge/GaugeShowcase.tsx';
+
+describe('integration block-template exports recipe', () => {
+  it.runIf(TSC_BIN != null)(
+    `CANONICAL: exports {"./templates/*.tsx"} + ${CANONICAL} type-checks under bundler resolution`,
+    () => {
+      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
+      writeConsumer(SPEC);
+      const {ok, out} = runTsc();
+      expect(out).toBe('');
+      expect(ok).toBe(true);
+    },
+    30_000,
+  );
+
+  it.runIf(ESBUILD_BIN != null)(
+    `CANONICAL: the same import resolves + bundles with a real bundler`,
+    () => {
+      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
+      writeConsumer(SPEC);
+      const {ok, out} = runEsbuild();
+      expect(out).toBe('');
+      expect(ok).toBe(true);
+    },
+    30_000,
+  );
+
+  it.runIf(TSC_BIN != null)(
+    'NEGATIVE: an extensionless import does NOT type-check (TS cannot infer .tsx)',
+    () => {
+      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
+      writeConsumer('@acme/widgets/templates/Gauge/GaugeShowcase');
+      const {ok, out} = runTsc();
+      expect(ok).toBe(false);
+      expect(out).toContain('TS2307');
+    },
+    30_000,
+  );
+
+  it.runIf(TSC_BIN != null)(
+    'NEGATIVE: a bare "./templates/*" export (no .tsx entry) does NOT type-check the .tsx import',
+    () => {
+      // Only a bare mapping — the extensionful subpath is not exported.
+      makeWidgets({'./templates/*': './templates/*'});
+      writeConsumer(SPEC);
+      const {ok, out} = runTsc();
+      expect(ok).toBe(false);
+      // Bare export forces the TS5097 opt-in requirement (allowImportingTsExtensions).
+      expect(out).toContain('TS5097');
+    },
+    30_000,
+  );
+
+  it.runIf(ESBUILD_BIN != null)(
+    'NEGATIVE: an extensionless import does NOT bundle against the .tsx-only export',
+    () => {
+      makeWidgets({'./templates/*.tsx': './templates/*.tsx'});
+      writeConsumer('@acme/widgets/templates/Gauge/GaugeShowcase');
+      const {ok} = runEsbuild();
+      expect(ok).toBe(false);
+    },
+    30_000,
+  );
+});

package/src/api/template-suffix.test.mjs

@@ -0,0 +1,246 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The canonical `.template.{ts,mjs,js}` suffix is discovered identically
+ * to the legacy `.doc.{ts,mjs,js}` suffix.
+ *
+ * Template-spec files are named for what they are: a scaffoldable TEMPLATE that
+ * exports `createBlockTemplate`/`createPageTemplate`. The `.doc.*` suffix was
+ * inherited from the component-doc convention and is still accepted during the
+ * transition. These tests stand up integration templates and external blocks in
+ * both families and assert byte-for-byte-equivalent discovery + scaffolding.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  template,
+  findShowcase,
+  findRelatedBlocks,
+} from './template.mjs';
+
+/** Absolute path to the CLI package so fixtures can import /src/template.mjs. */
+const CLI_PKG = path.resolve(import.meta.dirname, '..', '..');
+
+let tmpDir;
+let originalCwd;
+
+function makeConsumer() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-suffix-'));
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: 'consumer'}),
+  );
+  fs.writeFileSync(
+    path.join(dir, 'astryx.config.mjs'),
+    `export default { integrations: ['@acme/widgets'] };\n`,
+  );
+  return dir;
+}
+
+function installWidgets(consumerDir) {
+  const pkgDir = path.join(consumerDir, 'node_modules', '@acme', 'widgets');
+  fs.mkdirSync(path.join(pkgDir, 'templates'), {recursive: true});
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '2.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default { templates: './templates' };\n`,
+  );
+  return pkgDir;
+}
+
+/**
+ * Write a template-spec file (default-export createPageTemplate/BlockTemplate)
+ * plus its same-stem `.tsx` source under the templates root.
+ * @param {string} pkgDir
+ * @param {string} id
+ * @param {{kind: 'page'|'block', suffix: string}} opts
+ */
+function writeTemplate(pkgDir, id, {kind, suffix}) {
+  const docPath = path.join(pkgDir, 'templates', `${id}${suffix}`);
+  fs.mkdirSync(path.dirname(docPath), {recursive: true});
+  const create =
+    kind === 'page' ? 'createPageTemplate' : 'createBlockTemplate';
+  fs.writeFileSync(
+    docPath,
+    `import {${create}} from '${CLI_PKG}/src/template.mjs';\n` +
+      `export default ${create}({name: '${id} name', description: '${id} desc'});\n`,
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'templates', `${id}.tsx`),
+    `export default function ${id.replace(/[^a-zA-Z0-9]/g, '')}() { return null; }\n`,
+  );
+}
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  tmpDir = makeConsumer();
+  process.chdir(tmpDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('integration templates: .template.* discovered like legacy .doc.*', () => {
+  for (const suffix of ['.template.ts', '.template.mjs', '.doc.mjs']) {
+    it(`discovers + lists a page template authored as ${suffix}`, async () => {
+      const pkgDir = installWidgets(tmpDir);
+      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix});
+
+      const result = await template(undefined, {list: true, cwd: tmpDir});
+      const entry = result.data.find(t => t.id === 'pricing');
+      expect(entry).toBeTruthy();
+      expect(entry.type).toBe('page');
+      expect(entry.package).toBe('@acme/widgets');
+      expect(entry.name).toBe('pricing name');
+      expect(entry.description).toBe('pricing desc');
+    });
+
+    it(`scaffolds a page template authored as ${suffix}`, async () => {
+      const pkgDir = installWidgets(tmpDir);
+      writeTemplate(pkgDir, 'pricing', {kind: 'page', suffix});
+
+      const result = await template('pricing', {
+        targetPath: './dest',
+        cwd: tmpDir,
+      });
+      expect(result.type).toBe('template.copy');
+      expect(result.data.fileName).toBe('page.tsx');
+      expect(fs.existsSync(path.join(tmpDir, 'dest', 'page.tsx'))).toBe(true);
+    });
+
+    it(`scaffolds a nested block template authored as ${suffix}`, async () => {
+      const pkgDir = installWidgets(tmpDir);
+      writeTemplate(pkgDir, 'marketing/hero', {kind: 'block', suffix});
+
+      const result = await template('marketing/hero', {
+        targetPath: './dest',
+        cwd: tmpDir,
+      });
+      expect(result.type).toBe('template.copy');
+      expect(result.data.fileName).toBe('hero.tsx');
+      expect(fs.existsSync(path.join(tmpDir, 'dest', 'hero.tsx'))).toBe(true);
+    });
+  }
+
+  it('treats a .template.ts and a legacy .doc.mjs identically (same shape)', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'gauge', {kind: 'block', suffix: '.template.ts'});
+    writeTemplate(pkgDir, 'chip', {kind: 'block', suffix: '.doc.mjs'});
+
+    const result = await template(undefined, {list: true, cwd: tmpDir});
+    const gauge = result.data.find(t => t.id === 'gauge');
+    const chip = result.data.find(t => t.id === 'chip');
+
+    // Both discovered, both blocks, both from the same package, both ready.
+    for (const entry of [gauge, chip]) {
+      expect(entry).toBeTruthy();
+      expect(entry.type).toBe('block');
+      expect(entry.package).toBe('@acme/widgets');
+    }
+    // Field-by-field parity apart from the (intentionally different) id/name.
+    expect(gauge.type).toBe(chip.type);
+    expect(gauge.package).toBe(chip.package);
+  });
+});
+
+describe('external showcase blocks: .template.* discovered like legacy .doc.*', () => {
+  /**
+   * Create a consumer whose @test/ext package contributes two showcase blocks,
+   * one authored as `Foo.template.ts` and one as legacy `Bar.doc.mjs`.
+   */
+  function makeShowcaseFixture() {
+    // Symlink the real core package (needed by findCoreDir during discovery).
+    const realCoreDir = path.resolve(
+      import.meta.dirname,
+      '..',
+      '..',
+      '..',
+      'core',
+    );
+    const coreDir = path.join(tmpDir, 'packages', 'core');
+    fs.mkdirSync(path.dirname(coreDir), {recursive: true});
+    fs.symlinkSync(realCoreDir, coreDir);
+
+    const extDir = path.join(tmpDir, 'node_modules', '@test', 'ext');
+    const blocksDir = path.join(extDir, 'blocks', 'components');
+
+    // Foo showcase — canonical .template.ts (default-export createBlockTemplate).
+    const fooDir = path.join(blocksDir, 'Foo');
+    fs.mkdirSync(fooDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(fooDir, 'FooShowcase.template.ts'),
+      `import {createBlockTemplate} from '${CLI_PKG}/src/template.mjs';\n` +
+        `export default createBlockTemplate({\n` +
+        `  name: 'Foo — Showcase',\n` +
+        `  description: 'Foo showcase.',\n` +
+        `  isShowcase: true,\n` +
+        `  aspectRatio: 16 / 9,\n` +
+        `  componentsUsed: ['Foo'],\n` +
+        `});\n`,
+    );
+    fs.writeFileSync(
+      path.join(fooDir, 'FooShowcase.tsx'),
+      "'use client';\nexport default function FooShowcase() { return <div>Foo</div>; }",
+    );
+
+    // Bar showcase — legacy .doc.mjs (export const doc).
+    const barDir = path.join(blocksDir, 'Bar');
+    fs.mkdirSync(barDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(barDir, 'BarShowcase.doc.mjs'),
+      `export const doc = {\n` +
+        `  type: 'block',\n` +
+        `  name: 'Bar — Showcase',\n` +
+        `  description: 'Bar showcase.',\n` +
+        `  isReady: true,\n` +
+        `  isShowcase: true,\n` +
+        `  aspectRatio: 4 / 3,\n` +
+        `  componentsUsed: ['Bar', 'Chip'],\n` +
+        `};\n`,
+    );
+    fs.writeFileSync(
+      path.join(barDir, 'BarShowcase.tsx'),
+      "'use client';\nexport default function BarShowcase() { return <div>Bar</div>; }",
+    );
+
+    fs.writeFileSync(
+      path.join(extDir, 'package.json'),
+      JSON.stringify({
+        name: '@test/ext',
+        astryx: {docs: './src', category: 'Common', blocks: './blocks/components'},
+      }),
+    );
+    fs.mkdirSync(path.join(extDir, 'src'), {recursive: true});
+  }
+
+  it('findShowcase resolves a .template.ts external block by directory name', async () => {
+    makeShowcaseFixture();
+    const result = await findShowcase('Foo', tmpDir);
+    expect(result).not.toBeNull();
+    expect(result.name).toBe('Foo — Showcase');
+    expect(result.filePath).toContain('FooShowcase.tsx');
+  });
+
+  it('findShowcase resolves a legacy .doc.mjs external block by componentsUsed', async () => {
+    makeShowcaseFixture();
+    const result = await findShowcase('Bar', tmpDir);
+    expect(result).not.toBeNull();
+    expect(result.name).toBe('Bar — Showcase');
+  });
+
+  it('findRelatedBlocks finds both suffix families', async () => {
+    makeShowcaseFixture();
+    const foo = await findRelatedBlocks('Foo', tmpDir);
+    expect(foo.map(b => b.dirName)).toContain('FooShowcase');
+    const chip = await findRelatedBlocks('Chip', tmpDir);
+    expect(chip.map(b => b.dirName)).toContain('BarShowcase');
+  });
+});

package/src/api/template.mjs

@@ -6,6 +6,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import {createJiti} from 'jiti';
 import {loadModuleWithSchema} from '../lib/module-loader.mjs';
 import {TemplateEnvelopeSchema} from '../template.mjs';
 import {CLI_ROOT, discoverExternalPackages} from '../utils/paths.mjs';
@@ -21,9 +22,54 @@ import {Project} from '../lib/project.mjs';
 /** Identity used for core (built-in) templates in package-scoped listings. */
 const CORE_PACKAGE = '@astryxdesign/core';
 
-/** Doc-file basename suffixes for integration templates, in precedence order. */
+/**
+ * Canonical basename suffixes for template-spec files, in precedence order.
+ * A template spec exports a `createBlockTemplate`/`createPageTemplate` result
+ * (a scaffoldable TEMPLATE), so `.template.*` is the descriptive family name.
+ */
+const TEMPLATE_SUFFIXES = ['.template.ts', '.template.mjs', '.template.js'];
+
+/**
+ * Legacy basename suffixes for template-spec files, in precedence order.
+ * `.doc.*` was inherited from the component-doc convention before templates
+ * had their own name; it is still accepted during the transition window.
+ */
 const DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];
 
+/**
+ * The union of canonical + legacy template-spec suffixes, canonical first so
+ * `.template.*` wins over `.doc.*` when both stems exist. All template
+ * discovery matches this union so a `Foo.template.ts` file is treated exactly
+ * like a legacy `Foo.doc.mjs`.
+ */
+const ALL_TEMPLATE_SUFFIXES = [...TEMPLATE_SUFFIXES, ...DOC_SUFFIXES];
+
+/**
+ * The template-spec suffix present on `file`, or null if none matches.
+ * Recognizes both the canonical `.template.*` and legacy `.doc.*` families.
+ * @param {string} file
+ * @returns {string | null}
+ */
+function matchedTemplateSuffix(file) {
+  return ALL_TEMPLATE_SUFFIXES.find(suffix => file.endsWith(suffix)) ?? null;
+}
+
+/**
+ * RegExp matching either template-spec suffix family at end of a basename.
+ * Used where a per-file regex is convenient (e.g. block discovery walks).
+ */
+const TEMPLATE_SUFFIX_RE = /\.(template|doc)\.(ts|mjs|js)$/;
+
+let jitiInstance;
+/** Lazily-created jiti for loading `.ts` template specs (JSX-capable). */
+function getJiti() {
+  if (!jitiInstance) {
+    jitiInstance = createJiti(import.meta.url, {jsx: true});
+  }
+  return jitiInstance;
+}
+
+
 /**
  * Load an integration template doc module and validate it against the template
  * envelope at the load boundary. Default export only — `.ts` via jiti,
@@ -87,12 +133,29 @@ export function stripTemplateAssetRefs(source) {
     source,
   );
 }
+/**
+ * Load a template-spec module and return its metadata object. Supports both
+ * families of suffix:
+ *   - Legacy `.doc.*` core/external specs export `export const doc = {...}`.
+ *   - Specs authored with `createPageTemplate`/`createBlockTemplate` export the
+ *     stamped object as the default export.
+ * Prefers the default export, falling back to the named `doc` export, so a
+ * `Foo.template.ts` (default export) is read identically to a legacy
+ * `Foo.doc.mjs` (`doc` export). `.ts` is loaded via jiti; `.mjs`/`.js` via a
+ * native dynamic import. Returns null if the file does not exist.
+ *
+ * @param {string} docPath absolute path to the spec file
+ * @returns {Promise<Record<string, unknown> | undefined | null>}
+ */
 async function loadDocModule(docPath) {
   if (!fs.existsSync(docPath)) return null;
-  const docModule = await import(`file://${docPath}`);
-  return docModule.doc;
+  const docModule = docPath.endsWith('.ts')
+    ? await getJiti().import(docPath)
+    : await import(`file://${docPath}`);
+  return docModule.default ?? docModule.doc;
 }
 
+
 export {discoverAll as discoverTemplates};
 
 export function listTemplates() {
@@ -122,6 +185,20 @@ function findDocFiles(dir, pattern) {
   return results;
 }
 
+/**
+ * Resolve the template-spec file for a core page directory: the first existing
+ * `template.<suffix>` in canonical-then-legacy precedence, or null.
+ * @param {string} dirPath
+ * @returns {string | null}
+ */
+function findPageDocFile(dirPath) {
+  for (const suffix of ALL_TEMPLATE_SUFFIXES) {
+    const candidate = path.join(dirPath, `template${suffix}`);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
 async function discoverPages() {
   if (!fs.existsSync(PAGES_DIR)) return [];
   const dirs = fs
@@ -131,7 +208,9 @@ async function discoverPages() {
   const templates = [];
   for (const dir of dirs) {
     const dirPath = path.join(PAGES_DIR, dir.name);
-    const doc = await loadDocModule(path.join(dirPath, 'template.doc.mjs'));
+    const docPath =
+      findPageDocFile(dirPath) ?? path.join(dirPath, 'template.doc.mjs');
+    const doc = await loadDocModule(docPath);
     templates.push({
       type: 'page',
       dirName: dir.name,
@@ -141,17 +220,18 @@ async function discoverPages() {
       isReady: doc?.isReady ?? true,
       scaffold: doc?.scaffold ?? false,
       filePath: path.join(dirPath, 'page.tsx'),
-      docPath: path.join(dirPath, 'template.doc.mjs'),
+      docPath,
     });
   }
   return templates;
 }
 
 async function discoverBlocks() {
-  const docFiles = findDocFiles(BLOCKS_DIR, /\.doc\.mjs$/);
+  const docFiles = findDocFiles(BLOCKS_DIR, TEMPLATE_SUFFIX_RE);
   const blocks = [];
   for (const docPath of docFiles) {
-    const basename = path.basename(docPath, '.doc.mjs');
+    const suffix = matchedTemplateSuffix(docPath);
+    const basename = path.basename(docPath, suffix);
     const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
     if (!fs.existsSync(tsxPath)) continue;
     const doc = await loadDocModule(docPath);
@@ -173,6 +253,7 @@ async function discoverBlocks() {
   return blocks;
 }
 
+
 /**
  * Discover blocks from external packages that declare `astryx.blocks` in
  * their package.json. Same shape as discoverBlocks() output.
@@ -185,9 +266,10 @@ async function discoverExternalBlocks(cwd = process.cwd()) {
 
   for (const ext of externals) {
     if (!ext.blocksDir || !fs.existsSync(ext.blocksDir)) continue;
-    const docFiles = findDocFiles(ext.blocksDir, /\.doc\.mjs$/);
+    const docFiles = findDocFiles(ext.blocksDir, TEMPLATE_SUFFIX_RE);
     for (const docPath of docFiles) {
-      const basename = path.basename(docPath, '.doc.mjs');
+      const suffix = matchedTemplateSuffix(docPath);
+      const basename = path.basename(docPath, suffix);
       const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
       if (!fs.existsSync(tsxPath)) continue;
       const doc = await loadDocModule(docPath);
@@ -258,8 +340,9 @@ async function discoverAllWithErrors(cwd = process.cwd()) {
 export {discoverAllWithErrors};
 
 /**
- * Recursively collect integration template doc files under `root`.
- * Returns absolute paths to files ending in one of DOC_SUFFIXES.
+ * Recursively collect integration template-spec files under `root`.
+ * Returns absolute paths to files ending in one of ALL_TEMPLATE_SUFFIXES
+ * (canonical `.template.*` or legacy `.doc.*`).
  *
  * @param {string} root
  * @returns {string[]}
@@ -272,7 +355,7 @@ function findIntegrationDocFiles(root) {
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) {
         walk(full);
-      } else if (DOC_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {
+      } else if (ALL_TEMPLATE_SUFFIXES.some(suffix => entry.name.endsWith(suffix))) {
         results.push(full);
       }
     }
@@ -281,24 +364,17 @@ function findIntegrationDocFiles(root) {
   return results;
 }
 
-/**
- * The doc-file suffix present on `file`, or null if none matches.
- * @param {string} file
- */
-function matchedDocSuffix(file) {
-  return DOC_SUFFIXES.find(suffix => file.endsWith(suffix)) ?? null;
-}
-
 /**
  * Discover templates contributed by configured integrations.
  *
  * For each integration with a resolved `templates` root, every
- * `<id>.doc.{ts,mjs,js}` file is a template whose id is its path relative to
- * the templates root with the `.doc.*` suffix stripped (kebab-case, may be
- * nested). The doc's `type` (page|block) decides scaffolding — there is no
- * `/pages` vs `/blocks` requirement. A same-stem sibling source file
- * (`<id>.tsx`) is required; a doc missing its source, or missing `type`, is
- * an integration error and that template is skipped (recorded in `errors`).
+ * `<id>.template.{ts,mjs,js}` (or legacy `<id>.doc.{ts,mjs,js}`) file is a
+ * template whose id is its path relative to the templates root with the
+ * matched suffix stripped (kebab-case, may be nested). The doc's `type`
+ * (page|block) decides scaffolding — there is no `/pages` vs `/blocks`
+ * requirement. A same-stem sibling source file (`<id>.tsx`) is required; a doc
+ * missing its source, or missing `type`, is an integration error and that
+ * template is skipped (recorded in `errors`).
  *
  * @param {string} [cwd]
  * @returns {Promise<{templates: object[], errors: {package: string, template?: string, message: string}[]}>}
@@ -344,7 +420,7 @@ export async function discoverIntegrationTemplatesForOne(integration) {
   if (!root || !fs.existsSync(root)) return {templates, errors};
 
   for (const docPath of findIntegrationDocFiles(root)) {
-    const suffix = matchedDocSuffix(docPath);
+    const suffix = matchedTemplateSuffix(docPath);
     const id = path
       .relative(root, docPath)
       .slice(0, -suffix.length)

package/templates/blocks/components/ChatComposerInput/ChatComposerInputControlledInput.tsx

@@ -10,7 +10,7 @@ import {Text} from '@astryxdesign/core/Text';
 export default function ChatComposerInputControlledInput() {
   const [value, setValue] = useState('');
   return (
-    <Stack direction="vertical" gap={3} style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" gap={3} style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => setValue('')}
         value={value}

package/templates/blocks/components/ChatComposerInput/ChatComposerInputDisabled.tsx

@@ -7,7 +7,7 @@ import {Stack} from '@astryxdesign/core/Layout';
 
 export default function ChatComposerInputDisabled() {
   return (
-    <Stack direction="vertical" style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => {}}
         isDisabled

package/templates/blocks/components/ChatComposerInput/ChatComposerInputMentionTrigger.tsx

@@ -43,7 +43,7 @@ export default function ChatComposerInputMentionTrigger() {
   };
 
   return (
-    <Stack direction="vertical" gap={3} style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" gap={3} style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => setValue('')}
         input={

package/templates/blocks/components/ChatComposerInput/ChatComposerInputMultipleTriggers.tsx

@@ -54,7 +54,7 @@ export default function ChatComposerInputMultipleTriggers() {
   };
 
   return (
-    <Stack direction="vertical" gap={3} style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" gap={3} style={{width: 450, maxWidth: '100%'}}>
       <Text type="supporting" color="secondary">
         Type @ for mentions (blue) or / for commands (yellow)
       </Text>

package/templates/blocks/components/ChatComposerInput/ChatComposerInputShowcase.tsx

@@ -7,7 +7,7 @@ import {Stack} from '@astryxdesign/core/Layout';
 
 export default function ChatComposerInputShowcase() {
   return (
-    <Stack direction="vertical" style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => {}}
         input={

package/templates/blocks/components/ChatComposerInput/ChatComposerInputSlashCommands.tsx

@@ -40,7 +40,7 @@ export default function ChatComposerInputSlashCommands() {
   };
 
   return (
-    <Stack direction="vertical" style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => {}}
         input={