@astryxdesign/cli 0.4.7 → 0.5.0-canary.009bcb3

package/clients/cli/commands/build-theme.data-tokens.test.mjs

@@ -0,0 +1,144 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Asserts `astryx theme build` emits the `--color-data-*` defaults the
+ * way the `<Theme>` runtime does — once, at `:root`, in `@layer astryx-base`.
+ *
+ * Seeding them into the theme's own `@scope` block instead makes every nested
+ * `<Theme>` re-declare the default and shadow a parent theme's override, which
+ * no other token family does. Layer order is fixed by first declaration, so
+ * the base block also has to sit after `@layer reset` and before
+ * `@layer astryx-theme` for a consumer who imports this stylesheet alone.
+ *
+ * Building requires a compiled @astryxdesign/core, so this suite builds core
+ * once in beforeAll via the shared ensureCoreBuilt() helper.
+ *
+ * The build formats the defaults block itself, from the public
+ * `dataTokenDefaults` export; core formats it for the runtime. This suite is
+ * what keeps those two independent formattings byte-identical.
+ */
+
+import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+// Core's own generator, imported from source rather than from the package: it
+// is deliberately not part of `@astryxdesign/core/theme`'s public surface, and
+// this suite is the guard that the build's independent formatting matches it.
+import {generateDataTokenDefaultsCSS} from '../../../../core/src/theme/generateThemeRules';
+import {dataTokenDefaults as sourceDataTokenDefaults} from '../../../../core/src/theme/domainTokens/dataTokens';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+function writeTheme(dir, name, theme) {
+  fs.mkdirSync(dir, {recursive: true});
+  const file = path.join(dir, `${name}.mjs`);
+  fs.writeFileSync(
+    file,
+    `export default ${JSON.stringify({name, ...theme})};\n`,
+  );
+  return file;
+}
+
+async function buildTheme(tmpDir, name, theme) {
+  const project = path.join(tmpDir, 'project');
+  const themesDir = path.join(project, 'themes');
+  const themeFile = writeTheme(themesDir, name, theme);
+
+  const result = await runCli(
+    ['theme', 'build', path.relative(project, themeFile)],
+    project,
+  );
+  expect(result.code).toBe(0);
+
+  return fs.readFileSync(path.join(themesDir, `${name}.css`), 'utf-8');
+}
+
+beforeAll(() => {
+  ensureCoreBuilt();
+}, 200_000);
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-data-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build data token output', () => {
+  it('emits the defaults once, at :root, in @layer astryx-base', async () => {
+    const css = await buildTheme(tmpDir, 'charts-untouched', {
+      tokens: {'--color-accent': '#0077B6'},
+    });
+
+    const baseStart = css.indexOf('@layer astryx-base');
+    expect(baseStart).toBeGreaterThanOrEqual(0);
+
+    const baseBlock = css.slice(baseStart, css.indexOf('@layer astryx-theme'));
+    expect(baseBlock).toContain(':root {');
+    expect(baseBlock).toContain('--color-data-categorical-blue:');
+    expect(baseBlock).toContain('--color-data-gray-1:');
+    expect(css.match(/--color-data-categorical-blue:/g)).toHaveLength(1);
+    expect(css.match(/@layer astryx-base/g)).toHaveLength(1);
+  });
+
+  it('declares astryx-base after reset and before astryx-theme', async () => {
+    const css = await buildTheme(tmpDir, 'charts-order', {
+      tokens: {'--color-accent': '#0077B6'},
+    });
+
+    const reset = css.indexOf('@layer reset');
+    const base = css.indexOf('@layer astryx-base');
+    const theme = css.indexOf('@layer astryx-theme');
+
+    expect(reset).toBeGreaterThanOrEqual(0);
+    expect(base).toBeGreaterThan(reset);
+    expect(theme).toBeGreaterThan(base);
+  });
+
+  it("puts only the theme's own data token in its scope block", async () => {
+    const css = await buildTheme(tmpDir, 'charts-override', {
+      tokens: {'--color-data-categorical-blue': '#00A3FF'},
+    });
+
+    const themeBlock = css.slice(css.indexOf('@layer astryx-theme'));
+    expect(themeBlock).toContain('--color-data-categorical-blue: #00A3FF;');
+    expect(themeBlock).not.toContain('--color-data-categorical-orange');
+    expect(themeBlock).not.toContain('--color-data-gray-1');
+  });
+
+  it('emits the bytes the runtime generator emits', async () => {
+    const css = await buildTheme(tmpDir, 'charts-parity', {
+      tokens: {'--color-accent': '#0077B6'},
+    });
+
+    // The expectation below comes from core's SOURCE; the stylesheet came from
+    // core's dist. ensureCoreBuilt() only checks that dist exists, never that
+    // it is current, so a dist older than the source would fail the byte
+    // comparison with a colour mismatch that reads as formatter drift. Name
+    // that case first.
+    const {dataTokenDefaults: builtDataTokenDefaults} = await import(
+      '@astryxdesign/core/theme'
+    );
+    expect(
+      builtDataTokenDefaults,
+      'packages/core/dist is stale — run `pnpm -F @astryxdesign/core build`',
+    ).toEqual(sourceDataTokenDefaults);
+
+    // The build formats this block itself, from the public `dataTokenDefaults`
+    // export; the runtime formats it in core. Nothing else holds the two
+    // together, so compare the bytes — a changed indent or separator in either
+    // one fails here.
+    const runtimeBase = generateDataTokenDefaultsCSS();
+    const marker = '@layer astryx-base {\n';
+    const start = css.indexOf(marker);
+    expect(start).toBeGreaterThanOrEqual(0);
+
+    const bodyStart = start + marker.length;
+    expect(css.slice(bodyStart, bodyStart + runtimeBase.length)).toBe(
+      runtimeBase,
+    );
+    expect(css.slice(bodyStart + runtimeBase.length)).toMatch(/^\n\}/);
+  });
+});

package/clients/cli/commands/build-theme.mjs

@@ -38,6 +38,7 @@ import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {themeAdd} from '../../../api/theme/add/add.mjs';
 import {themeTemplate} from '../../../api/theme/template/template.mjs';
 import {themeList} from '../../../api/theme/list/list.mjs';
+import {themeTargets} from '../../../api/theme/targets/targets.mjs';
 import {themeBuild, importSpecifier} from '../../../api/theme/build/build.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as themeGroup} from './theme.doc.mjs';
@@ -45,10 +46,12 @@ import {doc as themeBuildCommand} from './theme-build.doc.mjs';
 import {doc as themeListCommand} from './theme-list.doc.mjs';
 import {doc as themeAddCommand} from './theme-add.doc.mjs';
 import {doc as themeTemplateCommand} from './theme-template.doc.mjs';
+import {doc as themeTargetsCommand} from './theme-targets.doc.mjs';
 import {doc as themeBuildFn} from '../../../api/theme/themeBuild.doc.mjs';
 import {doc as themeListFn} from '../../../api/theme/themeList.doc.mjs';
 import {doc as themeAddFn} from '../../../api/theme/themeAdd.doc.mjs';
 import {doc as themeTemplateFn} from '../../../api/theme/themeTemplate.doc.mjs';
+import {doc as themeTargetsFn} from '../../../api/theme/themeTargets.doc.mjs';
 
 /**
  * Path to this CLI's real entry (clients/cli/bin/astryx.mjs), resolved from
@@ -194,6 +197,36 @@ function printThemeList(themes) {
   );
 }
 
+/**
+ * Render the targets as one greppable line each, under an aligned header. A
+ * `records()` block would be five lines per target — over a thousand for the
+ * full surface, which is the view this command exists to make readable.
+ * @param {import('../../../api/theme/theme.type.mjs').ThemeTargetEntry[]} targets
+ * @returns {string}
+ */
+function formatTargetsTable(targets) {
+  const rows = targets.map(t => ({
+    key: t.key,
+    component: t.component,
+    props: t.props.join(', ') || '-',
+    states: t.states.join(', ') || '-',
+  }));
+  const head = {key: 'key', component: 'component', props: 'props', states: 'states'};
+  const width = (/** @type {'key'|'component'|'props'} */ field) =>
+    [head, ...rows].reduce((max, r) => Math.max(max, r[field].length), 0);
+  const w = {key: width('key'), component: width('component'), props: width('props')};
+  const line = (/** @type {typeof head} */ r) =>
+    [
+      r.key.padEnd(w.key),
+      r.component.padEnd(w.component),
+      r.props.padEnd(w.props),
+      r.states,
+    ]
+      .join('  ')
+      .trimEnd();
+  return [line(head), ...rows.map(line)].join('\n');
+}
+
 /**
  * @param {import('commander').Command} program
  */
@@ -225,6 +258,18 @@ export function registerTheme(program) {
     },
   });
 
+  // Theming questions are asked at `theme`, but per-component overrides live
+  // under `component`. Without this pointer the group reads as a build-tool
+  // menu, and the component targets are unreachable from the noun the user
+  // started at.
+  theme.addHelpText(
+    'after',
+    `\nComponent style overrides:\n` +
+      `  ${getCliInvocation()} theme targets            Every themeable class, with its props and states\n` +
+      `  ${getCliInvocation()} component <Name>         One component's theming table\n` +
+      `  ${getCliInvocation()} docs theme               How component overrides work\n`,
+  );
+
   defineCommand(theme, themeBuildCommand, {
     fn: themeBuildFn,
     action: async (
@@ -502,4 +547,44 @@ export function registerTheme(program) {
       );
     },
   });
+
+  defineCommand(theme, themeTargetsCommand, {
+    fn: themeTargetsFn,
+    action: async (/** @type {string | undefined} */ filter) => {
+      const json = program.opts().json || false;
+
+      /** @type {import('../../../api/theme/theme.type.mjs').ThemeTargetsResponse} */
+      let result;
+      try {
+        result = await themeTargets(filter, {cwd: process.cwd()});
+      } catch (e) {
+        const err =
+          /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {
+          suggestions: err.suggestions || [],
+          code: err.code,
+        });
+        return;
+      }
+
+      if (json) return jsonOut(result);
+
+      const run = getCliInvocation();
+      const {targets, componentCount} = result.data;
+      emit(
+        section(
+          'Theming targets',
+          `${targets.length} across ${componentCount} component${componentCount === 1 ? '' : 's'}`,
+        ),
+        text(formatTargetsTable(targets)),
+        text(
+          [
+            `Each key goes under \`components\` in defineTheme; it paints \`.astryx-<key>\`.`,
+            `Props take a value (\`variant:secondary\`); states are written bare (\`checked\`).`,
+            `One component in full: ${run} component <Name>`,
+          ].join('\n'),
+        ),
+      );
+    },
+  });
 }

package/clients/cli/commands/build-theme.variants.test.mjs

@@ -164,6 +164,7 @@ describe('theme build custom-variant augmentations', () => {
           },
           breadcrumbs: { 'variant:customBreadcrumbs': { color: 'currentColor' } },
           button: { 'variant:customButton': { backgroundColor: 'transparent' } },
+          card: { 'variant:customCard': { backgroundColor: 'transparent' } },
           dialog: { 'variant:customDialog': { backgroundColor: 'transparent' } },
           divider: { 'variant:customDivider': { borderColor: 'currentColor' } },
           'field-status': { 'variant:customFieldStatus': { color: 'currentColor' } },
@@ -204,6 +205,7 @@ describe('theme build custom-variant augmentations', () => {
         `import {Banner} from '@astryxdesign/core/Banner';\n` +
         `import {Breadcrumbs} from '@astryxdesign/core/Breadcrumbs';\n` +
         `import {Button} from '@astryxdesign/core/Button';\n` +
+        `import {Card} from '@astryxdesign/core/Card';\n` +
         `import {Dialog} from '@astryxdesign/core/Dialog';\n` +
         `import {Divider} from '@astryxdesign/core/Divider';\n` +
         `import {FieldStatus} from '@astryxdesign/core/FieldStatus';\n` +
@@ -222,6 +224,7 @@ describe('theme build custom-variant augmentations', () => {
         `      <Banner title="Banner" status="customBannerStatus" container="customBannerContainer" />\n` +
         `      <Breadcrumbs variant="customBreadcrumbs">Crumbs</Breadcrumbs>\n` +
         `      <Button label="Button" variant="customButton" />\n` +
+        `      <Card variant="customCard">Card</Card>\n` +
         `      <Dialog isOpen onOpenChange={() => {}} variant="customDialog">Body</Dialog>\n` +
         `      <Divider variant="customDivider" />\n` +
         `      <FieldStatus type="success" message="Ok" variant="customFieldStatus" />\n` +

package/clients/cli/commands/dialog-adaptive-template.test.mjs

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {component} from '../../../api/component/component.mjs';
+
+const CWD = {cwd: '.'};
+
+// Resolves built-in block templates by walking the source tree.
+const SCAN_TIMEOUT = 30_000;
+
+describe(
+  'Dialog adaptive presentation template',
+  () => {
+    it('is listed as a Dialog example block', async () => {
+      const result = await component('Dialog', {
+        ...CWD,
+        blocks: true,
+      });
+      const exampleNames = result.data.examples.map(b => b.name);
+      expect(exampleNames).toContain('DialogAdaptivePresentation');
+    });
+  },
+  SCAN_TIMEOUT,
+);

package/clients/cli/commands/theme-targets.behavior.test.mjs

@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CLI behavior for `astryx theme targets`.
+ *
+ * The API leaf is covered by api/theme/targets/targets.test.mjs; what is only
+ * reachable here is the terminal binding — the table a human reads, the JSON
+ * envelope a lint script reads, and the route into component overrides from
+ * `theme --help`, which is where the question gets asked.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+describe('astryx theme targets', () => {
+  it('prints one greppable line per target, with props and states', async () => {
+    const {status, stdout} = await runCli(['theme', 'targets', 'Switch']);
+
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^switch\s+Switch\s+size\s+checked, disabled$/m);
+    expect(stdout).toMatch(/^switch-thumb\s+Switch\s+size\s+checked$/m);
+    expect(stdout).toMatch(/4 across 1 component/);
+  });
+
+  it('lists the whole surface when unfiltered', async () => {
+    const {status, stdout} = await runCli(['theme', 'targets']);
+
+    expect(status).toBe(0);
+    const rows = stdout.split('\n').filter(l => /^[a-z][a-z0-9-]*\s{2,}/.test(l));
+    expect(rows.length).toBeGreaterThan(100);
+    expect(stdout).toMatch(/^button\s/m);
+    expect(stdout).toMatch(/^switch-thumb\s/m);
+  }, 30_000);
+
+  it('returns a theme.targets envelope under --json', async () => {
+    const {status, stdout} = await runCli(['--json', 'theme', 'targets', 'Switch']);
+
+    expect(status).toBe(0);
+    const payload = JSON.parse(stdout);
+    expect(payload.type).toBe('theme.targets');
+    expect(payload.data.targets).toContainEqual({
+      key: 'switch-thumb',
+      className: 'astryx-switch-thumb',
+      component: 'Switch',
+      props: ['size'],
+      states: ['checked'],
+    });
+  });
+
+  it('fails a filter that matches nothing', async () => {
+    const {status, stderr} = await runCli(['theme', 'targets', 'nosuchthing']);
+
+    expect(status).toBe(1);
+    expect(stderr).toMatch(/No theming target matches "nosuchthing"/);
+  });
+
+  it('routes a theming question from `theme --help` to component overrides', async () => {
+    const {stdout} = await runCli(['theme', '--help']);
+
+    expect(stdout).toMatch(/Component style overrides:/);
+    expect(stdout).toMatch(/theme targets/);
+    expect(stdout).toMatch(/component <Name>/);
+  });
+});

package/clients/cli/commands/theme-targets.doc.mjs

@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx theme targets`. The terminal binding of the
+ * `themeTargets()` function (referenced via `fn`); its args map to that
+ * function's params so a converter can build Commander config + --help from one
+ * source of truth.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'theme targets',
+  displayName: 'astryx theme targets',
+  namespace: 'cli',
+  summary: 'List the component theming targets a theme can override',
+  description:
+    'Prints every `defineTheme` components key across the system: the stable class it paints, ' +
+    'the component that declares it, and the props and states that are legal override keys ' +
+    'under it. This is the whole themeable surface in one command: what auditing a theme, or ' +
+    'answering "which key paints this pixel?", used to need one `astryx component <Name>` per ' +
+    'component to assemble. Pass a component name to scope it; pass any substring to search ' +
+    'keys. `--json` for a list a repo can lint its own theme against.',
+  fn: 'themeTargets',
+  args: [{name: 'filter', param: 'filter', required: false}],
+  examples: [
+    {label: 'The whole themeable surface', cli: 'astryx theme targets'},
+    {label: "One component's targets", cli: 'astryx theme targets Switch'},
+    {label: 'Search keys', cli: 'astryx theme targets thumb'},
+    {label: 'For a lint or an audit script', cli: 'astryx --json theme targets'},
+  ],
+  exitCodes: [
+    {code: 0, when: 'success'},
+    {code: 1, when: 'a filter matches no target, or core cannot be resolved'},
+  ],
+  related: ['component', 'theme build', 'theme template'],
+};

package/clients/cli/commands/theme-template.doc.mjs

@@ -16,9 +16,9 @@ export const doc = {
   namespace: 'cli',
   summary: 'Write the annotated theme template into your project',
   description:
-    'Writes theme.template.ts: the annotated reference for the whole theme surface — every ' +
+    'Writes theme.template.ts: the annotated reference for the whole theme surface, covering every ' +
     'defineTheme field, the token families, the component override syntax, and how a theme is ' +
-    'consumed — naming the CLI command that prints the authoritative reference for each. Read ' +
+    'consumed, naming the CLI command that prints the authoritative reference for each. Read ' +
     'it, copy what you need into your own theme file, delete it. Use `theme add <slug>` instead ' +
     'to start from a theme we ship. Leaves an existing file untouched unless --overwrite.',
   fn: 'themeTemplate',

package/clients/cli/commands/theme.doc.mjs

@@ -17,11 +17,13 @@ export const doc = {
   description:
     'The theme command group. Running astryx theme with no subcommand prints the ' +
     'subcommand list; the work happens in the subcommands: compile a theme (build), ' +
-    'scaffold one into your project (add), start a custom one from the annotated template (template), or list the bundled themes (list).',
-  subcommands: ['build', 'add', 'list', 'template'],
+    'scaffold one into your project (add), start a custom one from the annotated template (template), ' +
+    'list the bundled themes (list), or list the component theming targets a theme can override (targets).',
+  subcommands: ['build', 'add', 'list', 'template', 'targets'],
   examples: [
     {label: 'List bundled themes', cli: 'astryx theme list'},
     {label: 'Scaffold a theme', cli: 'astryx theme add matcha'},
+    {label: 'See what a theme can override', cli: 'astryx theme targets'},
   ],
   exitCodes: [
     {code: 0, when: 'success (help shown, or a subcommand succeeded)'},

package/clients/cli/index.mjs

@@ -70,6 +70,7 @@ export const JSON_SUPPORTED = new Set([
   'theme list',
   'theme add',
   'theme template',
+  'theme targets',
   'upgrade',
   'manifest',
   'doctor',

package/clients/cli/lib/component-format.mjs

@@ -13,8 +13,8 @@ import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
  *
  * Override keys are the component's stable class name with the `astryx-`
  * namespace prefix stripped — `generateThemeRules` re-adds the prefix when it
- * builds the `.astryx-*` selector. So `astryx-base-table` → key `base-table`
- * (→ `.astryx-base-table`), and `astryx-button` → key `button`.
+ * builds the `.astryx-*` selector. So `astryx-table-cell` → key `table-cell`
+ * (→ `.astryx-table-cell`), and `astryx-button` → key `button`.
  *
  * Keep the `astryx-` literal in sync with packages/core/src/naming.ts
  * (NAMESPACE / classPrefix), the same way build-theme.mjs mirrors it.

package/clients/cli/lib/manifest.mjs

@@ -77,6 +77,7 @@ export const RESPONSE_TYPES = {
   'theme list': ['theme.list'],
   'theme add': ['theme.list', 'theme.add'],
   'theme template': ['theme.template'],
+  'theme targets': ['theme.targets'],
   upgrade: ['upgrade.list', 'upgrade.status', 'upgrade.run'],
   manifest: ['manifest'],
   doctor: ['doctor'],
@@ -116,6 +117,7 @@ const EXAMPLES = {
     'astryx theme add matcha ./src/themes/matcha',
   ],
   'theme template': ['astryx theme template', 'astryx theme template --json'],
+  'theme targets': ['astryx theme targets Switch', 'astryx --json theme targets'],
   upgrade: ['astryx upgrade --json'],
   manifest: ['astryx manifest --json', 'astryx --json'],
   doctor: ['astryx doctor', 'astryx doctor --json'],

package/foundation/discovery/component-discovery.mjs

@@ -6,6 +6,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import {existsCaseExact} from '../fs/paths.mjs';
 
 const SKIP_DIRS = new Set(['hooks', 'utils', '__tests__', 'node_modules']);
 
@@ -243,27 +244,27 @@ export function findComponentReadme(coreDir, name) {
 
   // Direct match: src/{name}/{Name}.doc.mjs or src/{name}/Astryx{Name}.doc.mjs
   const direct = path.join(srcDir, name, exactDoc);
-  if (fs.existsSync(direct)) return direct;
+  if (existsCaseExact(direct, srcDir)) return direct;
   const directXds = path.join(srcDir, name, xdsDoc);
-  if (fs.existsSync(directXds)) return directXds;
+  if (existsCaseExact(directXds, srcDir)) return directXds;
 
   // Nested match: src/*/{name}/{Name}.doc.mjs or src/*/{name}/Astryx{Name}.doc.mjs
   const entries = fs.readdirSync(srcDir, {withFileTypes: true});
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const nested = path.join(srcDir, entry.name, name, exactDoc);
-    if (fs.existsSync(nested)) return nested;
+    if (existsCaseExact(nested, srcDir)) return nested;
     const nestedXds = path.join(srcDir, entry.name, name, xdsDoc);
-    if (fs.existsSync(nestedXds)) return nestedXds;
+    if (existsCaseExact(nestedXds, srcDir)) return nestedXds;
   }
 
   // Per-component doc in a parent directory: src/*/{Name}.doc.mjs or src/*/Astryx{Name}.doc.mjs
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const perComp = path.join(srcDir, entry.name, exactDoc);
-    if (fs.existsSync(perComp)) return perComp;
+    if (existsCaseExact(perComp, srcDir)) return perComp;
     const perCompXds = path.join(srcDir, entry.name, xdsDoc);
-    if (fs.existsSync(perCompXds)) return perCompXds;
+    if (existsCaseExact(perCompXds, srcDir)) return perCompXds;
   }
 
   // Sub-component fallback: find the source file, then walk up
@@ -321,7 +322,7 @@ export function findComponentSource(coreDir, name) {
     // Check for an exact match (prefixed or bare) first
     for (const candidate of candidateFiles) {
       const exact = path.join(dirPath, candidate);
-      if (fs.existsSync(exact)) return exact;
+      if (existsCaseExact(exact, dirPath)) return exact;
     }
 
     // Recurse into subdirectories
@@ -336,7 +337,7 @@ export function findComponentSource(coreDir, name) {
 
   // Search in the component's directory
   const directDir = path.join(srcDir, name);
-  if (fs.existsSync(directDir)) {
+  if (existsCaseExact(directDir, srcDir)) {
     const found = searchDir(directDir);
     if (found) return found;
   }
@@ -346,7 +347,7 @@ export function findComponentSource(coreDir, name) {
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const nestedDir = path.join(srcDir, entry.name, name);
-    if (fs.existsSync(nestedDir)) {
+    if (existsCaseExact(nestedDir, srcDir)) {
       const found = searchDir(nestedDir);
       if (found) return found;
     }

package/foundation/discovery/hook-discovery.mjs

@@ -6,6 +6,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import {existsCaseExact} from '../fs/paths.mjs';
 import {levenshteinDistance} from '../text/string-utils.mjs';
 
 const SKIP_DIRS = new Set(['utils', '__tests__', 'node_modules']);
@@ -157,7 +158,7 @@ export function findHookDoc(coreDir, name) {
   // 1. Check src/hooks/{name}.doc.mjs first
   for (const candidate of uniqueCandidates) {
     const direct = path.join(hooksDir, `${candidate}.doc.mjs`);
-    if (fs.existsSync(direct)) return direct;
+    if (existsCaseExact(direct, hooksDir)) return direct;
   }
 
   // 2. Case-insensitive search in hooks directory