@webjsdev/ui 0.3.7 → 0.3.9

package/src/registry/example.js

@@ -0,0 +1,120 @@
+/**
+ * The registry component `@example` block: extract it, strip it (#983).
+ *
+ * A Tier-1 component file is a handful of class-helper functions plus a module
+ * JSDoc whose `@example` block carries the ACCESSIBLE STRUCTURE an author
+ * composes (the `<details name>` exclusive-open wiring, the `group-open`
+ * chevron, the `aria-*` attributes). That worked example is BUILD-TIME
+ * guidance, consumed once while composing, so it should NOT persist in the
+ * copied project file as dead boilerplate. This module is the single source of
+ * truth for that block:
+ *
+ * - {@link extractExample} pulls the paste-ready snippet out (for `webjsui view`
+ *   and the MCP `ui` tool, which serve it on demand without copying it in).
+ * - {@link stripExample} removes it from the file `add` writes and leaves a
+ *   one-line pointer, so the copied file keeps only the helpers + a lean header.
+ *
+ * Both key on the SAME `@example` delimiter in the module JSDoc, so the snippet
+ * has exactly one home (the JSDoc) and cannot drift from a parallel field.
+ * Hand-rolled (no JSDoc/markdown parser dependency: `@webjsdev/ui` ships no
+ * third-party runtime deps).
+ *
+ * @module registry/example
+ */
+
+/**
+ * Locate the first block comment (`/** ... *\/`), i.e. the module JSDoc.
+ *
+ * @param {string} src
+ * @returns {{ start: number, end: number, text: string } | null}
+ */
+function firstBlockComment(src) {
+  const start = src.indexOf('/**');
+  if (start === -1) return null;
+  const end = src.indexOf('*/', start + 3);
+  if (end === -1) return null;
+  return { start, end: end + 2, text: src.slice(start, end + 2) };
+}
+
+/**
+ * True when the module JSDoc carries an `@example` block.
+ *
+ * @param {string} src
+ * @returns {boolean}
+ */
+export function hasExample(src) {
+  const block = firstBlockComment(src);
+  return !!block && /^\s*\*\s*@example\b/m.test(block.text);
+}
+
+/**
+ * Extract the paste-ready example snippet from the module JSDoc. Returns the
+ * fenced code (unwrapped) when the `@example` body is a ```` ```lang ```` block,
+ * else the de-indented text. Empty string when there is no `@example`.
+ *
+ * @param {string} src
+ * @returns {string}
+ */
+export function extractExample(src) {
+  const block = firstBlockComment(src);
+  if (!block) return '';
+  const lines = block.text.split('\n');
+  const exIdx = lines.findIndex((l) => /^\s*\*\s*@example\b/.test(l));
+  if (exIdx === -1) return '';
+  // Everything after the @example line, up to the closing */ OR the next JSDoc
+  // tag (so a trailing @see / @module after the example is not captured).
+  const bodyLines = [];
+  for (let i = exIdx + 1; i < lines.length; i++) {
+    if (/^\s*\*\/\s*$/.test(lines[i])) break; // closing */
+    if (/^\s*\*\s*@\w+/.test(lines[i])) break; // next tag ends the example body
+    // Strip the leading ` * ` JSDoc gutter, preserving inner indentation.
+    bodyLines.push(lines[i].replace(/^\s*\*\s?/, ''));
+  }
+  let body = bodyLines.join('\n').replace(/\s+$/, '');
+  // Unwrap a fenced code block if the example is wrapped in one.
+  const fence = body.match(/^\s*```[A-Za-z0-9]*\n([\s\S]*?)\n```\s*$/);
+  if (fence) body = fence[1];
+  return body.replace(/^\n+/, '').replace(/\s+$/, '');
+}
+
+/**
+ * The one-line pointer left in place of a stripped example. Uses the EXPLICIT
+ * `npx @webjsdev/ui view` form (not the bare `webjsui` bin name, which npx would
+ * resolve to an unrelated `webjsui` package when it is not a direct dep, e.g. in
+ * a scaffolded app where `@webjsdev/ui` is only transitive). Works in a WebJs
+ * app and a standalone project alike.
+ */
+export function pointerLine(name) {
+  return `Full usage example: npx @webjsdev/ui view ${name}  (or the MCP tool: ui ${name})`;
+}
+
+/**
+ * Remove the `@example` block from the module JSDoc and leave a one-line
+ * pointer to `webjsui view` / the MCP `ui` tool. No-op when there is no
+ * `@example`. This runs at `add` write-time so the copied project file keeps
+ * only the helpers + a lean header, not the worked example.
+ *
+ * @param {string} src
+ * @param {string} name  the component name, for the pointer
+ * @returns {string}
+ */
+export function stripExample(src, name) {
+  const block = firstBlockComment(src);
+  if (!block) return src;
+  const lines = block.text.split('\n');
+  const exIdx = lines.findIndex((l) => /^\s*\*\s*@example\b/.test(l));
+  if (exIdx === -1) return src;
+  const head = lines.slice(0, exIdx);
+  // Preserve any JSDoc tags that follow the @example block (so a trailing
+  // @see / @module survives the strip). The example body ends at the next tag
+  // line or the closing */.
+  const tail = [];
+  for (let i = exIdx + 1; i < lines.length; i++) {
+    if (/^\s*\*\/\s*$/.test(lines[i])) break;
+    if (/^\s*\*\s*@\w+/.test(lines[i])) { tail.push(...lines.slice(i, lines.length - 1)); break; }
+  }
+  // Drop trailing blank JSDoc gutter lines (` *`) so we don't double the gap.
+  while (head.length && /^\s*\*\s*$/.test(head[head.length - 1])) head.pop();
+  const rebuilt = [...head, ' *', ` * ${pointerLine(name)}`, ...tail, ' */'].join('\n');
+  return src.slice(0, block.start) + rebuilt + src.slice(block.end);
+}

package/src/registry/extract.js

@@ -0,0 +1,151 @@
+/**
+ * The shared ui-kit projector (#983).
+ *
+ * ONE leaf that turns the packaged registry into an agent-facing view of the
+ * kit, consumed by BOTH `webjsui view` (the CLI / offline path) and the MCP
+ * `ui` tool (the in-context agent path). Following the #979 shared-projector
+ * pattern (one module backs both the CLI and the MCP surface, guarded by a
+ * drift test), so the two cannot disagree. It lives in `@webjsdev/ui` (exported
+ * as `@webjsdev/ui/registry/extract`), NOT in `@webjsdev/mcp`, because the
+ * registry is THIS package's source of truth and mcp has no path to it.
+ *
+ * It reads the LOCAL packaged registry (via `local.js`): the kit inventory and
+ * per-component helper signatures + the paste-ready `@example` + the JSDoc
+ * header (description + a11y obligations) + npm deps. Pure over the on-disk
+ * registry; no network, no app scope (this is about the KIT, unlike the MCP
+ * `list_components` which is about the app).
+ *
+ * @module registry/extract
+ */
+
+import { loadRegistryItem, loadRegistryIndex, isCustomElementSource } from './local.js';
+import { extractExample, stripExample } from './example.js';
+
+// Re-export the lean-copy primitives so the scaffold generator (via
+// `packages/cli/lib/lean-copy.js`) has one import surface for the shared
+// example-strip. (The CLI's own `add` imports them directly from local.js /
+// example.js.)
+export { isCustomElementSource, stripExample };
+
+/**
+ * Extract the exported class-helper signatures from a Tier-1 source, e.g.
+ * `accordionTriggerClass(opts: { disabled?: boolean } = {})`. Best-effort
+ * lexical scan (no TS parser dependency); the parameter list is captured up to
+ * its closing paren, the return-type annotation dropped.
+ *
+ * @param {string} src
+ * @returns {string[]}
+ */
+export function extractHelperSignatures(src) {
+  /** @type {string[]} */
+  const out = [];
+  // Two authored forms, both class-helper functions:
+  //   export const NAME = (params): T => ...      (arrow; the `=>` gates out
+  //                                                 non-function consts)
+  //   export function NAME(params): T { ... }
+  // `export type` / `export interface` never match (no arrow, no `function`).
+  const re =
+    /export\s+(?:const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(\([^)]*\))\s*(?::[^=]+?)?=>|function\s+([A-Za-z_$][\w$]*)\s*(\([^)]*\)))/g;
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    if (m[1]) out.push(`${m[1]}${m[2]}`);
+    else if (m[3]) out.push(`${m[3]}${m[4]}`);
+  }
+  return out;
+}
+
+/**
+ * The JSDoc header text (description + a11y obligations + token notes), with the
+ * `@example` block and the `@module`/`@param`-style tags dropped. This is the
+ * "lean header" the copied file keeps; serving it lets an agent read the
+ * obligations without the worked example.
+ *
+ * @param {string} src
+ * @returns {string}
+ */
+export function extractDocHeader(src) {
+  const start = src.indexOf('/**');
+  if (start === -1) return '';
+  const end = src.indexOf('*/', start + 3);
+  if (end === -1) return '';
+  const lines = src.slice(start + 3, end).split('\n');
+  /** @type {string[]} */
+  const out = [];
+  for (const raw of lines) {
+    const line = raw.replace(/^\s*\*\s?/, '');
+    if (/^\s*@\w+/.test(line)) break; // stop at the first tag (@example, @module, ...)
+    out.push(line);
+  }
+  return out.join('\n').trim();
+}
+
+/**
+ * Project one registry component into the agent-facing shape. Returns null when
+ * the name is not a `registry:ui` component.
+ *
+ * @param {string} name
+ * @returns {{
+ *   name: string, tier: 1|2, type: string,
+ *   description: string, helpers: string[], example: string,
+ *   dependencies: string[], registryDependencies: string[],
+ * } | null}
+ */
+export function uiComponent(name) {
+  const item = loadRegistryItem(name);
+  if (!item || item.type !== 'registry:ui') return null;
+  const src = (item.files || []).map((f) => f.content || '').join('\n');
+  const tier = isCustomElementSource(src) ? 2 : 1;
+  return {
+    name: item.name,
+    tier,
+    type: item.type,
+    description: extractDocHeader(src),
+    helpers: tier === 1 ? extractHelperSignatures(src) : [],
+    example: extractExample(src),
+    dependencies: item.dependencies || [],
+    registryDependencies: item.registryDependencies || [],
+  };
+}
+
+/**
+ * The kit inventory: one compact entry per `registry:ui` component (name, tier,
+ * helper signatures, npm deps). The no-args payload for the MCP `ui` tool and
+ * the `references/ui-kit.md` skill surface, so an agent reaches for a helper
+ * instead of expanding Tailwind by hand.
+ *
+ * @returns {Array<{ name: string, tier: 1|2, helpers: string[], dependencies: string[] }>}
+ */
+export function uiInventory() {
+  return loadRegistryIndex()
+    .filter((i) => i.type === 'registry:ui')
+    .map((i) => {
+      const c = uiComponent(i.name);
+      return {
+        name: i.name,
+        tier: c ? c.tier : 1,
+        helpers: c ? c.helpers : [],
+        dependencies: c ? c.dependencies : [],
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Render a component projection as human-readable text for `webjsui view`.
+ * Shares the SAME {@link uiComponent} data the MCP `ui` tool returns, so the
+ * two never drift.
+ *
+ * @param {ReturnType<typeof uiComponent>} c
+ * @returns {string}
+ */
+export function renderComponentText(c) {
+  if (!c) return '';
+  const lines = [];
+  lines.push(`# ${c.name}  (Tier ${c.tier})`);
+  if (c.description) lines.push('', c.description);
+  if (c.helpers.length) lines.push('', 'Helpers:', ...c.helpers.map((h) => `  ${h}`));
+  if (c.dependencies.length) lines.push('', `npm: ${c.dependencies.join(', ')}`);
+  if (c.registryDependencies.length) lines.push(`registry deps: ${c.registryDependencies.join(', ')}`);
+  if (c.example) lines.push('', 'Example:', '', c.example);
+  return lines.join('\n');
+}

package/src/registry/fetcher.js

@@ -1,12 +1,70 @@
 import { registryItemSchema, registryIndexSchema } from './schema.js';
+import { loadRegistryItem, loadRegistryIndex } from './local.js';
 
 /**
- * Default registry URL. Override via REGISTRY_URL env var, or per-call.
+ * The canonical hosted registry. Local-first resolution applies ONLY for this
+ * exact URL: it is the one registry whose sources ship inside the package.
  */
-export const DEFAULT_REGISTRY_URL = process.env.REGISTRY_URL || 'https://ui.webjs.dev/registry';
+export const HOSTED_REGISTRY_URL = 'https://ui.webjs.dev/registry';
+
+/**
+ * Default registry URL. A `REGISTRY_URL` env var points at a CUSTOM registry,
+ * which (like an explicit `--registry`) forces the NETWORK path, since its
+ * sources are not the packaged ones.
+ */
+export const DEFAULT_REGISTRY_URL = process.env.REGISTRY_URL || HOSTED_REGISTRY_URL;
 
 const cache = new Map();
 
+/**
+ * True when the effective registry is the hosted one whose sources ship in the
+ * package, i.e. local-first resolution applies. A custom registry (via
+ * `--registry <url>` OR a `REGISTRY_URL` env override) is NOT default and forces
+ * the network path, so a self-hosted registry is never silently shadowed by the
+ * packaged sources.
+ *
+ * @param {string} [url]
+ */
+export function isDefaultRegistry(url) {
+  const effective = url || DEFAULT_REGISTRY_URL;
+  return effective === HOSTED_REGISTRY_URL;
+}
+
+/**
+ * Resolve one registry item LOCAL-FIRST (#983): read the packaged registry
+ * sources unless the caller pointed at a custom `--registry` URL, in which case
+ * fetch over the network. This is the resolver `add` / `init` / `view` / `list`
+ * use, so a scaffolded app installs components with no network dependency.
+ *
+ * NOTE: `webjsui diff` deliberately does NOT use this (it compares local files
+ * against the LIVE upstream, so it calls {@link fetchRegistryItem} directly).
+ *
+ * @param {string} name
+ * @param {string} [registryUrl]
+ */
+export async function getRegistryItem(name, registryUrl) {
+  if (isDefaultRegistry(registryUrl)) {
+    const item = loadRegistryItem(name);
+    if (!item) {
+      throw new Error(
+        `Unknown registry item "${name}". Run \`webjsui list\` to see the available components.`,
+      );
+    }
+    return item;
+  }
+  return fetchRegistryItem(name, registryUrl);
+}
+
+/**
+ * Resolve the flat registry index LOCAL-FIRST (#983). See {@link getRegistryItem}.
+ *
+ * @param {string} [registryUrl]
+ */
+export async function getRegistryIndex(registryUrl) {
+  if (isDefaultRegistry(registryUrl)) return loadRegistryIndex();
+  return fetchRegistryIndex(registryUrl);
+}
+
 /**
  * Fetch a registry item by name.
  *

package/src/registry/local.js

@@ -0,0 +1,207 @@
+/**
+ * Local registry composer (#983).
+ *
+ * The registry SOURCES ship inside this npm package (`packages/ui/package.json`
+ * `files` includes `packages/registry`), so `webjsui add` / `list` / `view` and
+ * the MCP `ui` tool can resolve a component with NO network round-trip. This
+ * module reads those on-disk sources and composes the same shadcn-compatible
+ * item shape the hosted registry serves, so a local read and a network fetch
+ * are interchangeable for every consumer.
+ *
+ * It is the plain-JS twin of the ui-website composer
+ * (`packages/ui/packages/website/app/_lib/registry.server.ts`): both read
+ * `packages/registry/registry.json` + the `components/*.ts` sources and
+ * synthesize the 6 non-neutral base-colour themes from `themes/base-colors.js`.
+ * Keeping the CLI on this module (rather than always hitting the network) is
+ * what makes an autonomous agent's `add` deterministic and offline-safe.
+ *
+ * Resolution is relative to THIS module (`import.meta.url`), i.e. the installed
+ * `@webjsdev/ui` package, NOT `process.cwd()`: `webjsui` runs inside a user's
+ * project but the registry lives in the installed package.
+ *
+ * @module registry/local
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  BASE_COLORS,
+  BASE_TITLES,
+  BASE_DESCRIPTIONS,
+  BASE_OVERRIDES,
+  mergeThemeCss,
+} from '../../packages/registry/themes/base-colors.js';
+
+/** Absolute path to the packaged registry root (`packages/ui/packages/registry`). */
+export const REGISTRY_ROOT = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  'packages',
+  'registry',
+);
+const MANIFEST_PATH = join(REGISTRY_ROOT, 'registry.json');
+const NEUTRAL_CSS_PATH = join(REGISTRY_ROOT, 'themes', 'index.css');
+const SCHEMA = 'https://ui.webjs.dev/schema/registry-item.json';
+
+let manifestCache = null;
+let neutralCssCache = null;
+const itemCache = new Map();
+let indexCache = null;
+
+function readManifest() {
+  if (manifestCache) return manifestCache;
+  manifestCache = JSON.parse(readFileSync(MANIFEST_PATH, 'utf8'));
+  return manifestCache;
+}
+
+function readNeutralCss() {
+  if (neutralCssCache) return neutralCssCache;
+  neutralCssCache = readFileSync(NEUTRAL_CSS_PATH, 'utf8');
+  return neutralCssCache;
+}
+
+/**
+ * Return the item with each declared file's on-disk content inlined. A file
+ * whose source is missing degrades to empty content rather than throwing.
+ *
+ * @param {any} item
+ * @returns {any}
+ */
+function inlineFiles(item) {
+  return {
+    $schema: SCHEMA,
+    ...item,
+    files: (item.files || []).map((f) => {
+      const abs = resolve(REGISTRY_ROOT, f.path);
+      if (!existsSync(abs)) return { ...f, content: '' };
+      return { ...f, content: readFileSync(abs, 'utf8') };
+    }),
+  };
+}
+
+/**
+ * Synthesize a `theme-<color>` item by merging the colour's overrides into the
+ * canonical neutral CSS, matching the manifest's `theme-neutral` shape so
+ * `webjsui init --base-color <color>` handles all 7 colours via one path.
+ *
+ * @param {string} color
+ * @returns {any|null}
+ */
+function synthesizeColorTheme(color) {
+  if (!BASE_COLORS.includes(color)) return null;
+  const overrides = BASE_OVERRIDES[color];
+  const content = mergeThemeCss(readNeutralCss(), overrides);
+  return {
+    $schema: SCHEMA,
+    name: `theme-${color}`,
+    type: 'registry:theme',
+    title: BASE_TITLES[color],
+    description: BASE_DESCRIPTIONS[color],
+    files: [
+      {
+        path: 'themes/index.css',
+        type: 'registry:file',
+        target: 'app/globals.css',
+        content,
+      },
+    ],
+  };
+}
+
+/**
+ * Load one registry item by name with its file content inlined. Returns null
+ * when the name is neither a manifest item nor a synthesizable colour theme.
+ *
+ * @param {string} name
+ * @returns {any|null}
+ */
+export function loadRegistryItem(name) {
+  if (itemCache.has(name)) return itemCache.get(name);
+
+  const manifestItem = readManifest().items.find((it) => it.name === name);
+  if (manifestItem) {
+    const composed = inlineFiles(manifestItem);
+    itemCache.set(name, composed);
+    return composed;
+  }
+
+  if (name.startsWith('theme-')) {
+    const color = name.slice('theme-'.length);
+    const synth = synthesizeColorTheme(color);
+    if (synth) {
+      itemCache.set(name, synth);
+      return synth;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Load the flat registry index (metadata only, no inlined content), including
+ * the synthesized non-neutral colour themes.
+ *
+ * @returns {any[]}
+ */
+export function loadRegistryIndex() {
+  if (indexCache) return indexCache;
+  const fromManifest = readManifest().items.map((item) => ({
+    name: item.name,
+    type: item.type,
+    description: item.description,
+    dependencies: item.dependencies,
+    registryDependencies: item.registryDependencies,
+  }));
+  const manifestNames = new Set(fromManifest.map((it) => it.name));
+  const synthesized = BASE_COLORS.filter(
+    (color) => !manifestNames.has(`theme-${color}`),
+  ).map((color) => ({
+    name: `theme-${color}`,
+    type: 'registry:theme',
+    description: BASE_DESCRIPTIONS[color],
+  }));
+  indexCache = [...fromManifest, ...synthesized];
+  return indexCache;
+}
+
+/**
+ * Strip `/* *​/` block comments and `//` line comments so a token check keys on
+ * CODE, not prose. Rough (does not honour a `//` inside a string), but a
+ * component's JSDoc is the realistic false-positive source, and the leading
+ * module JSDoc is exactly what this removes.
+ *
+ * @param {string} src
+ * @returns {string}
+ */
+function stripComments(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+}
+
+/**
+ * True when a component source defines/registers a custom element (Tier-2). A
+ * Tier-1 helper file exports only class-string functions and matches none of
+ * these. Used to gate the example-strip (Tier-2 files are left whole) and to
+ * label the kit inventory. Comments are stripped first so a JSDoc that merely
+ * MENTIONS `.register(` or `WebComponent` does not misclassify a Tier-1 helper.
+ *
+ * @param {string} src
+ * @returns {boolean}
+ */
+export function isCustomElementSource(src) {
+  const code = stripComments(src);
+  return (
+    /\bextends\s+WebComponent\b/.test(code) ||
+    /\bcustomElements\.define\b/.test(code) ||
+    /\.register\(/.test(code)
+  );
+}
+
+/** Reset the in-memory caches. Test-only. */
+export function _resetCache() {
+  manifestCache = null;
+  neutralCssCache = null;
+  indexCache = null;
+  itemCache.clear();
+}

package/src/registry/resolver.js

@@ -1,4 +1,4 @@
-import { fetchRegistryItem } from './fetcher.js';
+import { getRegistryItem } from './fetcher.js';
 
 /**
  * Walk `registryDependencies` transitively. Returns a flat array of items in
@@ -16,7 +16,7 @@ export async function resolveTree(names, baseUrl) {
   async function visit(name) {
     if (seen.has(name)) return;
     seen.set(name, true);
-    const item = await fetchRegistryItem(name, baseUrl);
+    const item = await getRegistryItem(name, baseUrl);
     for (const dep of item.registryDependencies || []) await visit(dep);
     ordered.push(item);
   }

package/src/utils/detect-project.js

@@ -34,7 +34,9 @@ export function defaultsForProject(cwd = process.cwd()) {
   switch (type) {
     case 'webjs':
       return {
-        tailwindCss: 'app/globals.css',
+        // styles/globals.css, NOT app/globals.css: in webjs, app/ is routing-only,
+        // so a non-routing stylesheet lives outside it.
+        tailwindCss: 'styles/globals.css',
         aliases: { components: 'components', utils: 'lib/utils', ui: 'components/ui', lib: 'lib' },
       };
     case 'next':

package/src/utils/theme.js

@@ -0,0 +1,68 @@
+/**
+ * Theme-token install, shared by `init` and `add` (#983).
+ *
+ * The class helpers render against CSS design tokens (`--background`,
+ * `--foreground`, `--destructive`, ...) that the app must define. `init` plants
+ * them; `add` self-heals if they are missing (an app that copied a component
+ * without the tokens paints unstyled). Both go through {@link ensureTheme} so
+ * the contract is one place: a token block is written exactly once, keyed by
+ * the {@link THEME_MARKER}, and a genuine failure to write is reported (never
+ * swallowed) so `init` can exit non-zero instead of leaving a clean exit code
+ * on an unstyled install.
+ *
+ * @module utils/theme
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getRegistryItem } from '../registry/fetcher.js';
+
+/** Idempotency marker at the top of the theme block. */
+export const THEME_MARKER = '/* @webjsdev/ui theme */';
+
+function ensureDir(d) {
+  if (!existsSync(d)) mkdirSync(d, { recursive: true });
+}
+
+/**
+ * Ensure the theme tokens exist in the project's Tailwind CSS file. Idempotent:
+ * if the marker is already present it is a no-op. Returns a status so the caller
+ * decides how to react (`init` fails hard on `'failed'`; `add` warns).
+ *
+ * @param {string} cwd
+ * @param {string} baseColor  one of the base-colour names (`neutral`, ...)
+ * @param {string} cssPath    project-relative path to the Tailwind CSS file
+ * @param {string} [registryUrl]
+ * @returns {Promise<{ status: 'written'|'present'|'failed', cssPath: string, error?: string }>}
+ */
+export async function ensureTheme(cwd, baseColor, cssPath, registryUrl) {
+  if (!cssPath || !baseColor) {
+    return { status: 'failed', cssPath: cssPath || '', error: 'missing tailwind.css / tailwind.baseColor in components.json' };
+  }
+  const target = join(cwd, cssPath);
+  const existing = existsSync(target) ? readFileSync(target, 'utf8') : '';
+  if (existing.includes(THEME_MARKER)) {
+    return { status: 'present', cssPath };
+  }
+  let item;
+  try {
+    item = await getRegistryItem(`theme-${baseColor}`, registryUrl);
+  } catch (e) {
+    return { status: 'failed', cssPath, error: e && e.message ? e.message : String(e) };
+  }
+  const themeBlock = item && item.files && item.files[0] ? item.files[0].content || '' : '';
+  if (!themeBlock) {
+    return { status: 'failed', cssPath, error: `theme-${baseColor} has no content` };
+  }
+  try {
+    ensureDir(dirname(target));
+    writeFileSync(
+      target,
+      existing + (existing && !existing.endsWith('\n') ? '\n' : '') + themeBlock,
+      'utf8',
+    );
+  } catch (e) {
+    return { status: 'failed', cssPath, error: e && e.message ? e.message : String(e) };
+  }
+  return { status: 'written', cssPath };
+}