@astryxdesign/cli 0.1.6 → 0.1.7-canary.0a6de96

package/docs/theme.doc.dense.mjs

@@ -5,17 +5,17 @@
 export const docsDense = {
   description: 'Theme provider, custom themes, light/dark, component overrides',
   sections: [
-    { title: 'Quick Start', content: [null, null, null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
-    { title: 'Themes', content: [null, null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
-    { title: 'Props', content: [null] },
-    { title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },
-    { title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent hex via HCT.' }, null, null] },
-    { title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-press-scale etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `npx astryx component <Name>` for details.' }, null, null, null, null] },
-    { title: 'Custom Variants', content: [{ type: 'prose', text: 'any unknown prop:value in components becomes a new variant. astryx theme build generates TS augmentations. works on any extensible prop axis (variant, status, etc).' }, null, null, null, null] },
-    { title: 'Build for Production', content: [{ type: 'prose', text: 'npx astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },
-    { title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS on first paint. USE /built + theme.css FOR SSR.' }, null, null, null] },
-    { title: 'Light/Dark', content: [{ type: 'prose', text: 'light-dark() in token values via [light, dark] tuples. mode=system follows OS.' }, null, null] },
-    { title: 'Nesting', content: [{ type: 'prose', text: 'wrap sections in separate <Theme> providers' }, null] },
-    { title: 'useTheme', content: [null, { type: 'prose', text: 'read-only. manage state at app level.' }] },
+    { section: 'Quick Start', title: 'Quick Start', content: [null, null, null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
+    { section: 'Available Themes', title: 'Themes', content: [null, null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
+    { section: 'Theme Props', title: 'Props', content: [null] },
+    { section: 'Creating a Custom Theme', title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },
+    { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent hex via HCT.' }, null, null] },
+    { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-press-scale etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `npx astryx component <Name>` for details.' }, null, null, null, null] },
+    { section: 'Custom Variants', title: 'Custom Variants', content: [{ type: 'prose', text: 'any unknown prop:value in components becomes a new variant. astryx theme build generates TS augmentations. works on any extensible prop axis (variant, status, etc).' }, null, null, null, null] },
+    { section: 'Building Themes for Production', title: 'Build for Production', content: [{ type: 'prose', text: 'npx astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },
+    { section: 'Runtime vs Built Themes', title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS on first paint. USE /built + theme.css FOR SSR.' }, null, null, null] },
+    { section: 'Light/Dark Mode', title: 'Light/Dark', content: [{ type: 'prose', text: 'light-dark() in token values via [light, dark] tuples. mode=system follows OS.' }, null, null] },
+    { section: 'Nesting Themes', title: 'Nesting', content: [{ type: 'prose', text: 'wrap sections in separate <Theme> providers' }, null] },
+    { section: 'useTheme Hook', title: 'useTheme', content: [null, { type: 'prose', text: 'read-only. manage state at app level.' }] },
   ],
 };

package/docs/theme.doc.zh.mjs

@@ -5,15 +5,15 @@
 export const docsZh = {
   description: 'Theme 提供者、自定义主题、亮/暗模式和组件样式覆盖。',
   sections: [
-    { title: '快速开始', content: [null, null, null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS（需配合 theme.css）。' }] },
-    { title: '可用主题', content: [null, null, { type: 'prose', text: '已发布主题：neutral（推荐起点）、butter、chocolate、gothic（仅暗色）、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版（运行时注入）。@astryxdesign/theme-{name}/built = 优化版（配合 theme.css）。' }] },
-    { title: 'Theme 属性', content: [null] },
-    { title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导（推荐）或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },
-    { title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置（typography、radius、motion）+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },
-    { title: '生产构建', content: [{ type: 'prose', text: 'npx astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js（__built:true）+ .d.ts。' }, null, null, null, null] },
-    { title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时：useInsertionEffect 在客户端注入样式。构建：静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },
-    { title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'（默认）跟随系统偏好。" }, null, null] },
-    { title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <Theme> 提供者中。' }, null] },
-    { title: 'useTheme 钩子', content: [null, { type: 'prose', text: '这是只读的。要更改主题/模式，在应用层管理状态并传递给 <Theme>。' }] },
+    { section: 'Quick Start', title: '快速开始', content: [null, null, null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS（需配合 theme.css）。' }] },
+    { section: 'Available Themes', title: '可用主题', content: [null, null, { type: 'prose', text: '已发布主题：neutral（推荐起点）、butter、chocolate、gothic（仅暗色）、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版（运行时注入）。@astryxdesign/theme-{name}/built = 优化版（配合 theme.css）。' }] },
+    { section: 'Theme Props', title: 'Theme 属性', content: [null] },
+    { section: 'Creating a Custom Theme', title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导（推荐）或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },
+    { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置（typography、radius、motion）+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },
+    { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'npx astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js（__built:true）+ .d.ts。' }, null, null, null, null] },
+    { section: 'Runtime vs Built Themes', title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时：useInsertionEffect 在客户端注入样式。构建：静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },
+    { section: 'Light/Dark Mode', title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'（默认）跟随系统偏好。" }, null, null] },
+    { section: 'Nesting Themes', title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <Theme> 提供者中。' }, null] },
+    { section: 'useTheme Hook', title: 'useTheme 钩子', content: [null, { type: 'prose', text: '这是只读的。要更改主题/模式，在应用层管理状态并传递给 <Theme>。' }] },
   ],
 };

package/docs/tokens.doc.dense.mjs

@@ -5,12 +5,11 @@
 export const docsDense = {
   description: 'spacing/color/radius/type/shadow token ref',
   sections: [
-    { title: 'Spacing', content: [{ type: 'prose', text: 'defined in tokens.stylex.ts. gap props use space0-space12.' }, null] },
-    { title: 'Size', content: [{ type: 'prose', text: 'control heights for buttons/inputs/selectors.' }, null] },
-    { title: 'Color', content: [{ type: 'prose', text: 'semantic colors, support light-dark() auto switching.' }, null, null, null] },
-    { title: 'Radius', content: [null] },
-    { title: 'Elevation', content: [null] },
-    { title: 'Typography', content: [null, null, null, null] },
-    { title: 'StyleX Usage', content: [null, null] },
+    { section: 'Color Tokens', title: 'Color', content: [{ type: 'prose', text: 'semantic colors, support light-dark() auto switching.' }, null, null, null] },
+    { section: 'Spacing Tokens', title: 'Spacing', content: [{ type: 'prose', text: 'defined in tokens.stylex.ts. gap props use space0-space12.' }, null] },
+    { section: 'Size Tokens', title: 'Size', content: [{ type: 'prose', text: 'control heights for buttons/inputs/selectors.' }, null] },
+    { section: 'Radius Tokens', title: 'Radius', content: [null] },
+    { section: 'Shadow Tokens', title: 'Elevation', content: [null] },
+    { section: 'Usage in StyleX', title: 'StyleX Usage', content: [null, null] },
   ],
 };

package/docs/tokens.doc.zh.mjs

@@ -5,12 +5,11 @@
 export const docsZh = {
   description: '间距、颜色、圆角、排版和阴影设计令牌参考。',
   sections: [
-    { title: '间距令牌', content: [{ type: 'prose', text: '所有设计令牌定义在 packages/core/src/theme/tokens.stylex.ts 中。组件的 gap 属性使用 space0-space12 映射到这些令牌。' }, null] },
-    { title: '尺寸令牌', content: [{ type: 'prose', text: '控制按钮、输入框和选择器的一致高度。' }, null] },
-    { title: '颜色令牌', content: [{ type: 'prose', text: '语义化颜色，支持 light-dark() 自动切换模式。' }, null, null, null] },
-    { title: '圆角令牌', content: [null] },
-    { title: '阴影令牌', content: [null] },
-    { title: '排版令牌', content: [null, null, null, null] },
-    { title: 'StyleX 用法', content: [null, null] },
+    { section: 'Color Tokens', title: '颜色令牌', content: [{ type: 'prose', text: '语义化颜色，支持 light-dark() 自动切换模式。' }, null, null, null] },
+    { section: 'Spacing Tokens', title: '间距令牌', content: [{ type: 'prose', text: '所有设计令牌定义在 packages/core/src/theme/tokens.stylex.ts 中。组件的 gap 属性使用 space0-space12 映射到这些令牌。' }, null] },
+    { section: 'Size Tokens', title: '尺寸令牌', content: [{ type: 'prose', text: '控制按钮、输入框和选择器的一致高度。' }, null] },
+    { section: 'Radius Tokens', title: '圆角令牌', content: [null] },
+    { section: 'Shadow Tokens', title: '阴影令牌', content: [null] },
+    { section: 'Usage in StyleX', title: 'StyleX 用法', content: [null, null] },
   ],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.6",
+  "version": "0.1.7-canary.0a6de96",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -47,6 +47,10 @@
       "types": "./src/types/integration.d.ts",
       "import": "./src/integration.mjs"
     },
+    "./doc": {
+      "types": "./src/types/doc.d.ts",
+      "import": "./src/doc.mjs"
+    },
     "./template": {
       "types": "./src/types/template-api.d.ts",
       "import": "./src/template.mjs"
@@ -75,10 +79,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.1.7-canary.0a6de96",
+    "@astryxdesign/core": "0.1.7-canary.0a6de96",
+    "@astryxdesign/lab": "0.1.7-canary.0a6de96",
+    "@astryxdesign/theme-neutral": "0.1.7-canary.0a6de96",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -96,10 +100,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.1.7-canary.0a6de96",
+    "@astryxdesign/core": "0.1.7-canary.0a6de96",
+    "@astryxdesign/lab": "0.1.7-canary.0a6de96",
+    "@astryxdesign/theme-neutral": "0.1.7-canary.0a6de96",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/src/api/docOverlays.test.mjs

@@ -0,0 +1,133 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guards the --dense / --zh reference-doc overlays against drift (#2182).
+ * @input packages/cli/docs/{topic}.doc.mjs and its .doc.dense.mjs / .doc.zh.mjs overlays.
+ * @output Vitest failures naming any overlay section that does not anchor to a
+ *   real base section, or whose content overrides land on the wrong block type.
+ * @position Regression gate for the docs API. Sits with the loader it guards.
+ *
+ * The overlays used to be applied BY ARRAY POSITION, so an overlay whose
+ * sections were ordered differently from the base grafted every title onto the
+ * wrong body. `docs tokens --dense` printed the entire colour table under a
+ * heading that said "## Spacing", above prose reading "gap props use
+ * space0-space12" — teaching any agent that spacing tokens are named
+ * `--color-*`. CLAUDE.md tells every agent to run that exact command at
+ * bootstrap, which is what made a doc bug into a codegen bug.
+ *
+ * Overlays now anchor to a base section by title, so a reordered or
+ * partial overlay is correct by construction. These tests keep it that way.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {docs} from './docs.mjs';
+
+const DOCS_DIR = path.join(import.meta.dirname, '..', '..', 'docs');
+
+/** Every base reference doc that has at least one overlay. */
+function overlayPairs() {
+  const pairs = [];
+  for (const file of fs.readdirSync(DOCS_DIR)) {
+    const m = file.match(/^(.+)\.doc\.(dense|zh)\.mjs$/);
+    if (!m) continue;
+    const [, topic, variant] = m;
+    pairs.push({
+      topic,
+      variant,
+      basePath: path.join(DOCS_DIR, `${topic}.doc.mjs`),
+      overlayPath: path.join(DOCS_DIR, file),
+    });
+  }
+  return pairs;
+}
+
+async function load(p) {
+  return await import(pathToFileURL(p).href);
+}
+
+describe('reference doc overlays (#2182)', () => {
+  const pairs = overlayPairs();
+
+  it('finds overlays to check', () => {
+    // A rename that stops overlays being discovered must not silently pass.
+    expect(pairs.length).toBeGreaterThan(0);
+  });
+
+  for (const {topic, variant, basePath, overlayPath} of pairs) {
+    it(`${topic} --${variant}: every overlay section anchors to a real base section`, async () => {
+      const base = await load(basePath);
+      const overlayMod = await load(overlayPath);
+      const overlay = overlayMod.docsDense || overlayMod.docsZh;
+
+      const baseTitles = base.docs.sections.map(s => s.title);
+      const unanchored = (overlay.sections || [])
+        .filter(s => s.section == null || !baseTitles.includes(s.section))
+        .map(s => s.section ?? `(no anchor) "${s.title}"`);
+
+      expect(
+        unanchored,
+        `${topic}.doc.${variant}.mjs has section entries that do not name a ` +
+          `base section via \`section:\`. Without an anchor the overlay is ` +
+          `applied by array position, which silently grafts each title onto ` +
+          `the wrong body. Base sections are: ${baseTitles.join(', ')}.`,
+      ).toEqual([]);
+    });
+
+    it(`${topic} --${variant}: no base section is overridden twice`, async () => {
+      const overlayMod = await load(overlayPath);
+      const overlay = overlayMod.docsDense || overlayMod.docsZh;
+      const anchors = (overlay.sections || []).map(s => s.section);
+      const dupes = anchors.filter((a, i) => anchors.indexOf(a) !== i);
+      expect(dupes, `${topic}.doc.${variant}.mjs overrides the same base section twice`).toEqual([]);
+    });
+  }
+});
+
+describe('the reported defect: docs tokens --dense (#2182)', () => {
+  it('does not print the colour table under the Spacing heading', async () => {
+    const result = await docs('tokens', null, {dense: true});
+    const spacing = result.data.sections.find(s => /spacing/i.test(s.title));
+    expect(spacing, 'tokens docs should have a spacing section').toBeTruthy();
+
+    const text = JSON.stringify(spacing);
+    expect(
+      text.includes('--color-'),
+      `The "${spacing.title}" section of \`docs tokens --dense\` contains ` +
+        `colour tokens. An agent reading this learns that spacing tokens are ` +
+        `named --color-*.`,
+    ).toBe(false);
+    expect(text).toContain('--spacing-');
+  });
+
+  it('keeps every base section reachable, even without an overlay entry', async () => {
+    // The tokens overlay compresses only 6 of 13 sections. The other 7 must
+    // still render (in English), not vanish or absorb a neighbour's title.
+    const full = await docs('tokens', null, {});
+    const dense = await docs('tokens', null, {dense: true});
+    expect(dense.data.sections.length).toBe(full.data.sections.length);
+  });
+
+  it('does not lose the Extending a Theme section from docs theme --dense', async () => {
+    const dense = await docs('theme', null, {dense: true});
+    const titles = dense.data.sections.map(s => s.title);
+    expect(titles).toContain('Extending a Theme');
+  });
+
+  it('does not emit a duplicate useTheme heading in docs theme --dense', async () => {
+    const dense = await docs('theme', null, {dense: true});
+    const titles = dense.data.sections.map(s => s.title.toLowerCase());
+    const useTheme = titles.filter(t => t.includes('usetheme'));
+    expect(useTheme.length).toBe(1);
+  });
+
+  it('does not leak English headings into docs theme --zh', async () => {
+    const zh = await docs('theme', null, {zh: true});
+    const titles = zh.data.sections.map(s => s.title);
+    // Every section the overlay translates must appear once, in Chinese only.
+    expect(titles).not.toContain('Light/Dark Mode');
+    expect(titles).toContain('亮/暗模式');
+  });
+});

package/src/api/docs.mjs

@@ -38,11 +38,23 @@ async function loadReferenceDocs(docPath, {lang} = {}) {
   const translation = translationMod.docsZh || translationMod.docsDense;
   if (!translation) return docs;
 
+  // Overlays are keyed to a base section by title (`section`), not by array
+  // position. Position-keying silently grafted each overlay title onto whatever
+  // base section happened to share its index, so an overlay that omitted or
+  // reordered a section corrupted every section after it — `docs tokens --dense`
+  // printed the colour table under a "Spacing" heading (#2182). An overlay may
+  // now cover any subset of sections, in any order; sections it does not name
+  // keep their base content.
+  const bySection = new Map();
+  for (const ts of translation.sections ?? []) {
+    if (ts?.section != null) bySection.set(ts.section, ts);
+  }
+
   return {
     ...docs,
     description: translation.description || docs.description,
-    sections: docs.sections.map((section, si) => {
-      const ts = translation.sections?.[si];
+    sections: docs.sections.map(section => {
+      const ts = bySection.get(section.title);
       if (!ts) return section;
       return {
         ...section,

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,
+  );
+});