@astryxdesign/cli 0.1.2-canary.41cdf33 → 0.1.2-canary.4497b08

package/docs/layout.doc.dense.mjs

@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceTranslationDoc} */
+
+export const docsDense = {
+  description:
+    'frame-first app layout: shell choice, region budgets, cards vs rows',
+  sections: [
+    {
+      title: 'Frame First',
+      content: [
+        {
+          type: 'prose',
+          text: 'decide frame before content. content-first (Card-wrapped sections in a scroll column) = prototype look.',
+        },
+        {
+          type: 'list',
+          items: [
+            'pick frame: AppShell (nav apps) | Layout+LayoutPanel+LayoutContent (multi-pane tools) | plain column (docs/forms)',
+            'budget regions in px first: side nav 240-280, rail 64-72, inspector 340-420, facet rail 220-260',
+            'container policy per region: dense data = rows; dashboards/galleries = card grids',
+            'write responsive contract up front',
+          ],
+        },
+        null,
+      ],
+    },
+    {
+      title: 'App Archetypes',
+      content: [
+        {
+          type: 'prose',
+          text: 'container choice tracks archetype, not preference.',
+        },
+        null,
+        {
+          type: 'prose',
+          text: 'start from matching template (astryx template --list), study with --skeleton.',
+        },
+      ],
+    },
+    {
+      title: 'Cards vs Rows',
+      content: [
+        {
+          type: 'prose',
+          text: 'Card = widget container, NOT list-item wrapper. dense/scannable/selectable data = rows: Table (columnar) or List/Item (single-line), edge-to-edge, 32-40px rows, dividers.',
+        },
+        {
+          type: 'list',
+          items: [
+            'Table+plugins: hosts, deployments, monitors, users',
+            'List/Item rows: issues, files, conversations',
+            'Card: KPI tiles, chart panels, gallery entries, settings groups',
+            'EmptyState for zero-match',
+          ],
+        },
+        {
+          type: 'list',
+          items: [
+            'no Card-wrapped list items (card soup)',
+            'no stacked full-width Cards as page structure',
+            'no Cards in Cards',
+            'no decorative Badge — counts/enums only; StatusDot/Token for status',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Panels and Inspectors',
+      content: [
+        {
+          type: 'prose',
+          text: 'master-detail: row select opens fixed-width inspector (LayoutPanel end slot + width budget + resizable/useResizable). overlay content <=1024px, do not compress.',
+        },
+        null,
+      ],
+    },
+    {
+      title: 'Responsive Contract',
+      content: [
+        {
+          type: 'prose',
+          text: 'declare breakpoint behavior as comment at frame root: which regions collapse/overlay/drop at which widths.',
+        },
+        null,
+      ],
+    },
+  ],
+};

package/docs/layout.doc.mjs

@@ -0,0 +1,160 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'layout',
+  title: 'Layout',
+  category: 'guide',
+  description:
+    'Frame-first app layout: choosing a shell, budgeting regions, and when to use cards vs rows.',
+
+  sections: [
+    {
+      title: 'Frame First',
+      content: [
+        {
+          type: 'prose',
+          text: 'Decide the frame before writing any content. Real applications are built top-down: pick the shell, name its regions, give each region an explicit size budget, then fill regions with content. Content-first layout (writing sections and wrapping each one in a Card) produces a padded scroll column that reads as a prototype, not a product.',
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Pick the frame: AppShell (top nav and/or side nav apps), Layout + LayoutPanel + LayoutContent (multi-pane tools like explorers and consoles), or a plain content column (documents, marketing, forms)',
+            'Budget regions in px before filling them: side nav 240–280, icon rail 64–72, detail/inspector panel 340–420, filter/facet rail 220–260',
+            'Decide the container policy per region: dense data renders as rows; widget dashboards and galleries render as card grids (see Cards vs Rows)',
+            'Write the responsive contract up front: which regions collapse, overlay, or drop at which breakpoints (see Responsive Contract)',
+          ],
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'A three-region tool frame',
+          code: `// Frame: nav 256 | content flex | inspector 380 (resizable)
+<AppShell sideNav={<SideNav>{/* nav items */}</SideNav>} contentPadding={0}>
+  <Layout>
+    <LayoutContent>{/* dense list or table, edge-to-edge */}</LayoutContent>
+    <LayoutPanel width={380} resizable={{minSizePx: 320, maxSizePx: 480}} hasDivider>
+      {/* inspector for the selected row */}
+    </LayoutPanel>
+  </Layout>
+</AppShell>`,
+        },
+      ],
+    },
+    {
+      title: 'App Archetypes',
+      content: [
+        {
+          type: 'prose',
+          text: 'Match the frame and container policy to the kind of app you are building. These recipes are distilled from product-scale apps built with the design system; container choice tracks the archetype, not personal preference.',
+        },
+        {
+          type: 'table',
+          headers: ['Archetype', 'Frame', 'Container policy'],
+          rows: [
+            [
+              'Tracker / work tool (issues, tickets, CRM)',
+              'AppShell + SideNav; inspector LayoutPanel on select',
+              'Rows only. Grouped edge-to-edge lists, zero cards',
+            ],
+            [
+              'Console / observability (metrics, logs, deploys)',
+              'AppShell + SideNav or TopNav + TabList',
+              'Card grid for dashboard widgets; Table for everything else',
+            ],
+            [
+              'Messaging / feed',
+              'Column frame: rail + sidebar + stream + panel',
+              'Rows and bubbles. No cards in the stream',
+            ],
+            [
+              'Media library / gallery',
+              'AppShell + TopNav; grid content',
+              'Card grid (ClickableCard) with dense metadata rows in detail views',
+            ],
+            [
+              'Settings / forms',
+              'AppShell + SideNav or settings template',
+              'Sections with FormLayout; Card only to group dangerous or billing actions',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Start from a template that matches the archetype (`npx astryx template --list`), then study its structure with `--skeleton` before customizing.',
+        },
+      ],
+    },
+    {
+      title: 'Cards vs Rows',
+      content: [
+        {
+          type: 'prose',
+          text: 'Card is a widget container, not a list-item wrapper. The fastest way to make an app look like a generic AI prototype is to wrap every record in a Card with a Badge. Dense data — anything the user scans, filters, or selects — belongs in rows: Table for columnar data, List/Item for single-line records, edge-to-edge with dividers and 32–40px row height.',
+        },
+        {
+          type: 'list',
+          style: 'do',
+          items: [
+            'Table (with selection/sorting plugins) for columnar records: hosts, deployments, monitors, users',
+            'List/Item rows for scannable single-line records: issues, files, conversations',
+            'Card for self-contained widgets: KPI tiles, chart panels, gallery entries, settings groups',
+            'EmptyState inside the region when a filter matches nothing',
+          ],
+        },
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            'Wrapping each list item in a Card (card soup)',
+            'Stacking full-width Cards as a substitute for page structure',
+            'Nesting Cards inside Cards',
+            'Using Badge as decoration — reserve it for counts and enumerated states; use StatusDot or Token for status and metadata',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Panels and Inspectors',
+      content: [
+        {
+          type: 'prose',
+          text: 'Master-detail is the backbone of tool UIs: selecting a row opens a fixed-width inspector panel rather than navigating away. Use LayoutPanel in the end slot with an explicit width budget; add resizable (useResizable) for user control, and let the panel overlay the content region below ~1024px instead of compressing it.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Inspector that overlays at narrow widths',
+          code: `<LayoutPanel
+  width={380}
+  hasDivider
+  isScrollable
+  label="Details"
+  resizable={{minSizePx: 320, maxSizePx: 480, autoSaveId: 'inspector'}}>
+  {selected ? <DetailFields item={selected} /> : <EmptyState title="Nothing selected" />}
+</LayoutPanel>`,
+        },
+      ],
+    },
+    {
+      title: 'Responsive Contract',
+      content: [
+        {
+          type: 'prose',
+          text: 'Declare breakpoint behavior as a contract before building, and keep it in a comment at the frame root. A typical contract: full frame above 1024px; inspector panels overlay the content column at 1024px and below; the side nav collapses into MobileNav at 768px and below. Deciding this up front keeps every region change intentional instead of emergent.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Contract comment at the frame root',
+          code: `// Responsive contract:
+//   > 1024px  nav 256 | content | inspector 380
+//   <= 1024px inspector overlays content (position: absolute, end-aligned)
+//   <= 768px  nav collapses into MobileNav drawer; toolbar actions wrap`,
+        },
+      ],
+    },
+  ],
+};

package/docs/principles.doc.dense.mjs

@@ -6,9 +6,9 @@ export const docsDense = {
   description: 'core design principles + rules for the design system',
   sections: [
     { title: 'Philosophy', content: [{ type: 'list', items: ['components over primitives', 'semantic tokens over hardcoded values', 'theme-agnostic code', 'open internals'] }] },
-    { title: 'Rules', content: [{ type: 'list', items: ['use components', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },
+    { title: 'Rules', content: [{ type: 'list', items: ['use components', 'frame-first layout: shell + region budgets before content (astryx docs layout)', 'dense data = rows (Table, List/Item) not Cards; Card = widgets/galleries/settings groups', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },
     { title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout. See astryx docs styling.' }] },
-    { title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useLinkComponent()', 'read docs before inventing props'] }] },
+    { title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useLinkComponent()', 'no Card-wrapped list items — frame first, rows for dense data (astryx docs layout)', 'no decorative Badge — StatusDot/Token for status', 'read docs before inventing props'] }] },
     { title: 'Tokens', content: [{ type: 'prose', text: 'run npx astryx docs tokens for full reference' }] },
   ],
 };

package/docs/principles.doc.mjs

@@ -39,6 +39,8 @@ export const docs = {
           style: 'ordered',
           items: [
             'Use components for everything they cover',
+            'Layout is frame-first: pick the shell and budget regions before writing content (see \`npx astryx docs layout\`)',
+            'Dense data renders as rows (Table, List/Item), edge-to-edge with dividers; Card is for widgets, galleries, and settings groups',
             'StyleX or Tailwind for custom styling; both are first-class (see \`npx astryx docs styling\`)',
             'Semantic tokens, not hardcoded values (see \`npx astryx docs tokens\`)',
             'CSS custom properties for colors, not hex values',
@@ -74,6 +76,8 @@ export const docs = {
             'Hardcoded colors (#fff). Use var(--color-*) or Tailwind semantic classes (text-primary, bg-surface)',
             'Hardcoded spacing (16px). Use spacing tokens or Tailwind spacing utilities',
             'Hardcoded <a> elements. Use useLinkComponent() so consumers can swap in their framework router via LinkProvider',
+            'Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see \`npx astryx docs layout\`)',
+            'Badge as decoration. Reserve Badge for counts and enumerated states; use StatusDot or Token for status',
             'Inventing props. Read component docs first',
           ],
         },

package/docs/principles.doc.zh.mjs

@@ -6,9 +6,9 @@ export const docsZh = {
   description: 'XDS 核心设计原则和规则。',
   sections: [
     { title: '设计哲学', content: [{ type: 'list', items: ['组件优于原始元素 — 优先使用 XDS 组件', '语义化令牌优于硬编码值', '主题无关的代码 — 深色模式自动生效', '开放的内部机制 — 所有基础组件均可导出和组合'] }] },
-    { title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌，不使用硬编码值', '使用 CSS 变量设置颜色，不使用十六进制值', '表单输入为受控组件（value + onChange）', '使用 useLinkComponent() 进行导航'] }] },
+    { title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '布局采用框架优先：先选定外壳并规划区域尺寸，再编写内容（见 astryx docs layout）', '密集数据使用行（Table、List/Item）通栏渲染；Card 用于小部件、画廊和设置分组', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌，不使用硬编码值', '使用 CSS 变量设置颜色，不使用十六进制值', '表单输入为受控组件（value + onChange）', '使用 useLinkComponent() 进行导航'] }] },
     { title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。详见 astryx docs styling。' }] },
-    { title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要自创属性。先阅读组件文档'] }] },
+    { title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要把每个列表项都包在 Card 里 — 先定框架，密集数据用行渲染（见 astryx docs layout）', '不要把 Badge 当装饰 — 状态请使用 StatusDot 或 Token', '不要自创属性。先阅读组件文档'] }] },
     { title: '设计令牌', content: [{ type: 'prose', text: '运行 npx astryx docs tokens 查看完整参考' }] },
   ],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.2-canary.41cdf33",
+  "version": "0.1.2-canary.4497b08",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -75,9 +75,9 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.41cdf33",
-    "@astryxdesign/lab": "0.1.2-canary.41cdf33",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.41cdf33",
+    "@astryxdesign/core": "0.1.2-canary.4497b08",
+    "@astryxdesign/lab": "0.1.2-canary.4497b08",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.4497b08",
     "gpt-tokenizer": "^2.0.0"
   },
   "peerDependenciesMeta": {
@@ -92,9 +92,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.41cdf33",
-    "@astryxdesign/lab": "0.1.2-canary.41cdf33",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.41cdf33",
+    "@astryxdesign/core": "0.1.2-canary.4497b08",
+    "@astryxdesign/lab": "0.1.2-canary.4497b08",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.4497b08",
     "gpt-tokenizer": "^2.0.0"
   },
   "scripts": {

package/src/commands/agent-docs.mjs

@@ -180,6 +180,9 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
   // Rules — the top error-preventers.
   lines.push('RULES:');
   lines.push('- No <div> — components do all layout/spacing. Full page → AppShell; sidebar nav → SideNav.');
+  lines.push('- Frame first: pick the shell (AppShell / Layout+LayoutPanel) and budget regions in px BEFORE writing content (`astryx docs layout`).');
+  lines.push('- Dense data = rows (Table, List/Item) edge-to-edge — never Card-wrapped list items. Card = dashboard widgets, galleries, settings groups only.');
+  lines.push('- Status → StatusDot/Token; Badge only for counts and enumerated states, never decoration.');
   // Styling guidance tailored to the project's configured system — never
   // recommend a path that isn't compiled here (xstyle needs the StyleX compiler;
   // utilities need Tailwind). Tokens are always the source of truth.

package/src/commands/build-theme.import-path.test.mjs

@@ -18,14 +18,10 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import {fileURLToPath} from 'node:url';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
-const REPO_ROOT = path.resolve(__dirname, '../../../..');
-const CORE_THEME_ENTRY = path.join(
-  REPO_ROOT,
-  'packages/core/dist/theme/index.js',
-);
 
 function runCli(args, cwd) {
   try {
@@ -59,13 +55,7 @@ function writeTheme(dir, name) {
 // in-CLI fallback generator). Build core once if it isn't already present so
 // the suite works in any CI job, regardless of job ordering.
 beforeAll(() => {
-  if (!fs.existsSync(CORE_THEME_ENTRY)) {
-    execFileSync('pnpm', ['-F', '@astryxdesign/core', 'build'], {
-      cwd: REPO_ROOT,
-      stdio: 'pipe',
-      timeout: 180_000,
-    });
-  }
+  ensureCoreBuilt();
 }, 200_000);
 
 let tmpDir;

package/src/commands/build-theme.prose.test.mjs

@@ -18,9 +18,9 @@
  *   - paragraphs use the body font, not the heading font.
  *
  * Building `astryx theme build` requires a compiled @astryxdesign/core (there is no in-CLI
- * fallback generator), so this suite builds core once in beforeAll — mirroring
- * scripts/build-css.test.mjs — to stay self-sufficient regardless of CI job
- * ordering.
+ * fallback generator), so this suite builds core once in beforeAll via the
+ * shared ensureCoreBuilt() helper — which serializes concurrent Vitest workers
+ * behind a lock — to stay self-sufficient regardless of CI job ordering.
  */
 
 import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
@@ -29,14 +29,10 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import {fileURLToPath} from 'node:url';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
-const REPO_ROOT = path.resolve(__dirname, '../../../..');
-const CORE_THEME_ENTRY = path.join(
-  REPO_ROOT,
-  'packages/core/dist/theme/index.js',
-);
 
 function runCli(args, cwd) {
   try {
@@ -71,13 +67,7 @@ function writeTheme(dir, name) {
 // `astryx theme build` imports the compiled @astryxdesign/core/theme entry. Build core
 // once if it isn't already present so the suite works in any CI job.
 beforeAll(() => {
-  if (!fs.existsSync(CORE_THEME_ENTRY)) {
-    execFileSync('pnpm', ['-F', '@astryxdesign/core', 'build'], {
-      cwd: REPO_ROOT,
-      stdio: 'pipe',
-      timeout: 180_000,
-    });
-  }
+  ensureCoreBuilt();
 }, 200_000);
 
 let tmpDir;

package/src/commands/build-theme.watch.test.mjs

@@ -9,7 +9,9 @@
  * the watcher keeps running.
  *
  * Building `astryx theme build` requires a compiled @astryxdesign/core, so this
- * suite builds core once in beforeAll (mirrors build-theme.prose.test.mjs).
+ * suite builds core once in beforeAll via the shared ensureCoreBuilt() helper —
+ * which serializes concurrent Vitest workers behind a lock — to stay
+ * self-sufficient regardless of CI job ordering.
  */
 
 import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
@@ -18,14 +20,10 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import {fileURLToPath} from 'node:url';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
-const REPO_ROOT = path.resolve(__dirname, '../../../..');
-const CORE_THEME_ENTRY = path.join(
-  REPO_ROOT,
-  'packages/core/dist/theme/index.js',
-);
 
 function runCli(args, cwd) {
   try {
@@ -56,13 +54,7 @@ async function waitFor(predicate, {timeout = 8000, interval = 50} = {}) {
 }
 
 beforeAll(() => {
-  if (!fs.existsSync(CORE_THEME_ENTRY)) {
-    execFileSync('pnpm', ['-F', '@astryxdesign/core', 'build'], {
-      cwd: REPO_ROOT,
-      stdio: 'pipe',
-      timeout: 180_000,
-    });
-  }
+  ensureCoreBuilt();
 }, 200_000);
 
 let tmpDir;

package/src/commands/ensure-core-built.mjs

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Shared test helper: build @astryxdesign/core once, race-free.
+ *
+ * `astryx theme build` imports the compiled @astryxdesign/core/theme entry
+ * (there is no in-CLI fallback generator), so any test exercising it needs a
+ * built core. The CI `test` job runs `pnpm test` without a prior core build,
+ * and Vitest runs test files in parallel worker forks. When two build-theme
+ * suites each ran `if (!exists) pnpm -F @astryxdesign/core build` in their own
+ * beforeAll, both workers saw dist missing and launched concurrent builds that
+ * collided on the shared packages/core/dist (core's build starts with
+ * `rimraf dist`): one worker wiped dist while the other was mid-write, failing
+ * nondeterministically ("Could not resolve dist/index.js" / "ENOTEMPTY rmdir
+ * dist/hooks").
+ *
+ * This serializes the build behind a filesystem lock so exactly one worker
+ * builds and the rest wait for it to finish before reading dist.
+ */
+
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../..',
+);
+const CORE_THEME_ENTRY = path.join(
+  REPO_ROOT,
+  'packages/core/dist/theme/index.js',
+);
+// A lock directory (mkdir is atomic across processes) guards the build.
+const LOCK_DIR = path.join(os.tmpdir(), 'astryx-core-build.lock');
+
+const BUILD_TIMEOUT_MS = 180_000;
+// A lock older than this is assumed abandoned by a crashed/killed worker.
+const STALE_LOCK_MS = BUILD_TIMEOUT_MS + 20_000;
+const POLL_MS = 250;
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function buildCore() {
+  execFileSync('pnpm', ['-F', '@astryxdesign/core', 'build'], {
+    cwd: REPO_ROOT,
+    stdio: 'pipe',
+    timeout: BUILD_TIMEOUT_MS,
+  });
+}
+
+function lockIsStale() {
+  try {
+    return Date.now() - fs.statSync(LOCK_DIR).mtimeMs > STALE_LOCK_MS;
+  } catch {
+    // Vanished between the exists check and stat — treat as released.
+    return false;
+  }
+}
+
+/** Try to acquire the lock. Returns true if this worker now holds it. */
+function tryAcquire() {
+  try {
+    fs.mkdirSync(LOCK_DIR);
+    return true;
+  } catch (err) {
+    if (err.code !== 'EEXIST') {
+      throw err;
+    }
+    if (lockIsStale()) {
+      fs.rmSync(LOCK_DIR, {recursive: true, force: true});
+      try {
+        fs.mkdirSync(LOCK_DIR);
+        return true;
+      } catch (retryErr) {
+        if (retryErr.code !== 'EEXIST') {
+          throw retryErr;
+        }
+      }
+    }
+    return false;
+  }
+}
+
+/**
+ * Ensure packages/core/dist is built exactly once, even when called
+ * concurrently from parallel Vitest workers. Safe to call from every
+ * build-theme suite's beforeAll.
+ */
+export function ensureCoreBuilt() {
+  if (fs.existsSync(CORE_THEME_ENTRY)) {
+    return;
+  }
+
+  const deadline = Date.now() + STALE_LOCK_MS;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(CORE_THEME_ENTRY)) {
+      return;
+    }
+    if (tryAcquire()) {
+      try {
+        if (!fs.existsSync(CORE_THEME_ENTRY)) {
+          buildCore();
+        }
+      } finally {
+        fs.rmSync(LOCK_DIR, {recursive: true, force: true});
+      }
+      return;
+    }
+    // Another worker is building; wait for it to finish and release the lock.
+    sleepSync(POLL_MS);
+  }
+
+  // Waited past the stale threshold without the artifact appearing — build it
+  // ourselves rather than let the suite fail on a missing entry.
+  buildCore();
+}