@webjsdev/ui 0.3.17 → 0.5.0

package/src/commands/init.js

@@ -5,7 +5,16 @@ import prompts from 'prompts';
 import { writeConfig, CONFIG_FILE } from '../utils/get-config.js';
 import { logger } from '../utils/logger.js';
 import { getRegistryItem, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
-import { ensureTheme } from '../utils/theme.js';
+import { ensureTheme, presetThemeBlock } from '../utils/theme.js';
+import { STYLE_NAMES } from '../registry/style-bake.js';
+import {
+  ICON_LIBRARIES,
+  decodePreset,
+  getIconLibrary,
+  isPresetCode,
+  presetFontUrls,
+  resolvePresetConfig,
+} from '../../packages/registry/themes/preset.js';
 
 const BASE_COLORS = ['neutral', 'stone', 'zinc', 'mauve', 'olive', 'mist', 'taupe'];
 
@@ -50,11 +59,46 @@ export const init = new Command()
   .option('-y, --yes', 'skip confirmation prompts', false)
   .option('--base-color <color>', `base color (${BASE_COLORS.join('|')})`)
   .option('--css <path>', 'path to the project Tailwind CSS file')
-  .option('-o, --overwrite', 'replace an existing alias map and existing helper files', false)
+  .option('-o, --overwrite', 'replace an existing alias map, existing helper files and the theme block', false)
+  .option('--preset <code>', 'apply a design-system preset code from webjs.dev/ui/create (style, colors, font, radius, icons)')
+  .option('--style <name>', `component style (${STYLE_NAMES.join('|')})`)
+  .option('--icons <library>', `icon library (${ICON_LIBRARIES.map((l) => l.name).join('|')})`)
   .option('--registry <url>', 'registry base URL', DEFAULT_REGISTRY_URL)
   .action(async (opts) => {
     const cwd = opts.cwd;
 
+    // A preset is the configurator's whole design system in one code (#1666).
+    // An explicit flag beside it wins over the field it names, so a code can
+    // be reused with one choice changed.
+    /** @type {import('../../packages/registry/themes/preset.js').PresetConfig | null} */
+    let preset = null;
+    if (opts.preset) {
+      const decoded = isPresetCode(opts.preset) ? decodePreset(opts.preset) : null;
+      if (!decoded) {
+        logger.error(`"${opts.preset}" is not a preset code. Copy one from ${logger.cyan('https://webjs.dev/ui/create')}.`);
+        process.exit(1);
+      }
+      const resolved = resolvePresetConfig({
+        ...decoded,
+        ...(opts.style ? { style: opts.style } : null),
+        ...(opts.icons ? { iconLibrary: opts.icons } : null),
+        ...(opts.baseColor ? { baseColor: opts.baseColor } : null),
+      });
+      if (resolved.error) {
+        logger.error(`Preset ${opts.preset}: ${resolved.error}.`);
+        process.exit(1);
+      }
+      preset = resolved.config;
+    }
+    if (opts.style && !STYLE_NAMES.includes(opts.style)) {
+      logger.error(`Unknown style "${opts.style}". Use one of: ${STYLE_NAMES.join(', ')}.`);
+      process.exit(1);
+    }
+    if (opts.icons && !getIconLibrary(opts.icons)) {
+      logger.error(`Unknown icon library "${opts.icons}". Use one of: ${ICON_LIBRARIES.map((l) => l.name).join(', ')}.`);
+      process.exit(1);
+    }
+
     // Re-running `init` on a project that already has one must not RELOCATE it.
     // The alias map decides where cn() lives and what every already-added
     // component imports, and `tailwind.css` decides which stylesheet the app
@@ -97,7 +141,7 @@ export const init = new Command()
 
     /** @type {{ baseColor: string, css: string }} */
     let answers = {
-      baseColor: opts.baseColor || initialBaseColor,
+      baseColor: (preset && preset.baseColor) || opts.baseColor || initialBaseColor,
       css: opts.css || initialCss,
     };
 
@@ -105,7 +149,7 @@ export const init = new Command()
       const r = await prompts(
         [
           {
-            type: opts.baseColor ? null : 'select',
+            type: opts.baseColor || preset ? null : 'select',
             name: 'baseColor',
             message: 'Base color?',
             choices: BASE_COLORS.map((c) => ({ title: c, value: c })),
@@ -127,9 +171,12 @@ export const init = new Command()
     // unrecognised key through here would write a file that `getConfig` (and
     // therefore `add` / `diff` / `info`) throws on. Preserving a project's
     // settings means its VALUES, not arbitrary extra fields.
+    // A style or icon library the command names replaces the stored one,
+    // since naming it is the request; otherwise a re-run keeps what is there.
+    const iconLibrary = (preset && preset.iconLibrary) || opts.icons || (keep && existing.iconLibrary) || 'lucide';
     const config = {
       $schema: 'https://ui.webjs.dev/schema.json',
-      style: (keep && existing.style) || 'default',
+      style: (preset && preset.style) || opts.style || (keep && existing.style) || 'default',
       tailwind: {
         css: answers.css,
         baseColor: answers.baseColor,
@@ -138,7 +185,7 @@ export const init = new Command()
           : true,
       },
       aliases,
-      iconLibrary: (keep && existing.iconLibrary) || 'lucide',
+      iconLibrary,
     };
 
     writeConfig(cwd, config);
@@ -147,17 +194,49 @@ export const init = new Command()
     // Pull lib/utils + the chosen theme from the registry and write them in.
     await writeLibUtils(cwd, aliases.utils, opts.registry, opts.overwrite);
 
+    // The icon library is written only when the command names one, since it
+    // is a large file an app that draws no kit icons does not need.
+    if (preset || opts.icons) await writeIcons(cwd, aliases.utils, iconLibrary, opts.registry, opts.overwrite);
+
+    // A preset's tokens are its own palette over the kit's theme file.
+    let block;
+    if (preset) {
+      try {
+        const neutral = await getRegistryItem('theme-neutral', opts.registry);
+        block = presetThemeBlock(neutral.files[0].content || '', preset);
+      } catch (e) {
+        logger.error(`Could not build the theme for preset ${opts.preset}: ${e.message}`);
+        process.exit(1);
+      }
+    }
+
     // The theme tokens are what the class helpers render against. A silent
     // failure here (the old behaviour) left an unstyled install with a clean
     // exit code, the exact trap for an autonomous agent, so hard-fail (#983).
-    const theme = await ensureTheme(cwd, answers.baseColor, answers.css, opts.registry);
+    // A preset, or --overwrite, replaces an existing block in place (#1666).
+    const theme = await ensureTheme(cwd, answers.baseColor, answers.css, opts.registry, {
+      replace: Boolean(preset || opts.overwrite),
+      block,
+    });
     if (theme.status === 'failed') {
       logger.error(`Could not write theme tokens into ${answers.css}: ${theme.error}`);
       logger.info('The class helpers render against these tokens, so this must succeed.');
       process.exit(1);
     }
     if (theme.status === 'written') logger.success(`Wrote theme into ${answers.css}`);
-    else logger.info(`Theme already present in ${answers.css}: skipping.`);
+    else if (theme.status === 'replaced') logger.success(`Replaced the theme in ${answers.css}`);
+    else if (theme.status === 'legacy') {
+      logger.warn(`The theme block in ${answers.css} predates the end marker, so it was left as it is.`);
+      logger.info(`To replace it, delete the block (from ${logger.cyan('/* @webjsdev/ui theme */')} to the end of its rules) and re-run init.`);
+    } else logger.info(`Theme already present in ${answers.css}: skipping.`);
+
+    if (preset) {
+      const urls = presetFontUrls(preset);
+      if (urls.length) {
+        logger.info('The preset names its fonts in the theme. Load the faces, either self-hosted under public/ or from:');
+        for (const url of urls) logger.info(`  ${url}`);
+      }
+    }
 
     logger.break();
     logger.success('Done.');
@@ -201,8 +280,8 @@ async function writeLibUtils(cwd, utilsAlias, registryUrl, overwrite) {
   }
 
   // The onBeforeCache() DOM helper lives in a SEPARATE module (#819) because
-  // it references `document`, so keeping it out of cn()'s file prevents the
-  // elision analyzer pinning every page that imports cn to the browser.
+  // it references `document`, so keeping it out of cn()'s file keeps cn()
+  // free of browser globals for the pages and layouts that import it.
   // Overlay components import it from `../lib/dom.ts`, so write it as a
   // sibling of the utils file, which lands it at lib/utils/dom.ts next to
   // cn.ts. `add` reads that same adjacency when it rewrites the import.
@@ -224,6 +303,44 @@ async function writeLibUtils(cwd, utilsAlias, registryUrl, overwrite) {
   }
 }
 
+/**
+ * Write the chosen icon library as the utils file's sibling `icons.ts`, the
+ * path a block's icon import is rewritten to (#1666). Naming a library is a
+ * request to switch, so a file that is still one of the five libraries as
+ * shipped is replaced. A file the app has edited is kept unless `--overwrite`
+ * says otherwise, the same rule as the other helpers.
+ */
+async function writeIcons(cwd, utilsAlias, library, registryUrl, overwrite) {
+  const lib = getIconLibrary(library);
+  if (!lib) return;
+  const target = join(dirname(join(cwd, utilsAlias.replace(/^@\//, '') + '.ts')), 'icons.ts');
+  const rel = relative(cwd, target);
+  try {
+    const item = await getRegistryItem(lib.item, registryUrl);
+    const content = item.files && item.files[0] ? item.files[0].content || '' : '';
+    if (!content) throw new Error(`${lib.item} has no content`);
+    if (existsSync(target) && !overwrite) {
+      const current = readFileSync(target, 'utf8');
+      if (current === content) {
+        logger.info(`${rel} is already ${lib.title}: keeping it.`);
+        return;
+      }
+      const pristine = await Promise.all(
+        ICON_LIBRARIES.map((l) => getRegistryItem(l.item, registryUrl).then((it) => it.files[0].content, () => null)),
+      );
+      if (!pristine.includes(current)) {
+        logger.warn(`${rel} has been edited, so it was kept. Re-run with --overwrite to replace it with ${lib.title}.`);
+        return;
+      }
+    }
+    ensureDir(dirname(target));
+    writeFileSync(target, content, 'utf8');
+    logger.success(`Wrote ${rel} (${lib.title})`);
+  } catch (e) {
+    logger.warn(`Could not fetch ${lib.item} from the registry (${e.message}).`);
+  }
+}
+
 function relative(cwd, p) {
   return p.startsWith(cwd) ? p.slice(cwd.length + 1) : p;
 }

package/src/commands/list.js

@@ -1,25 +1,57 @@
 import { Command } from 'commander';
 import { getRegistryIndex, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
+import { uiBlocks, BLOCK_DEFINITION } from '../registry/extract.js';
 import { logger } from '../utils/logger.js';
 
+const TYPES = ['ui', 'block', 'chart', 'all'];
+
+/** The three labelled groups `list` prints, in order. */
+const GROUPS = [
+  ['ui', 'Components'],
+  ['block', `Blocks (${BLOCK_DEFINITION})`],
+  ['chart', 'Charts'],
+];
+
 export const list = new Command()
   .name('list')
   .alias('search')
-  .description('List components available in the registry')
-  .argument('[filter]', 'filter by substring')
+  .description('List the components, blocks and charts in the registry')
+  .argument('[filter]', 'filter by substring of the name')
+  .option('--type <type>', `ui, block, chart or all (${TYPES.join(' | ')})`, 'all')
+  .option('--category <name>', 'only blocks and charts in this category (e.g. login, sidebar, area)')
+  .option('--json', 'print one compact JSON array of { name, type, categories, description }')
   .option('--registry <url>', 'registry base URL', DEFAULT_REGISTRY_URL)
   .action(async (filter, opts) => {
-    const items = await getRegistryIndex(opts.registry);
-    const ui = items.filter((i) => i.type === 'registry:ui');
-    const filtered = filter ? ui.filter((i) => i.name.includes(filter)) : ui;
-    if (!filtered.length) {
+    if (!TYPES.includes(opts.type)) {
+      logger.error(`Unknown --type "${opts.type}". Use one of: ${TYPES.join(', ')}.`);
+      process.exit(1);
+    }
+    const index = await getRegistryIndex(opts.registry);
+    const items = uiBlocks({ type: opts.type, category: opts.category }, index)
+      .filter((i) => !filter || i.name.includes(filter));
+
+    // The JSON form is the whole of stdout, so nothing else is printed.
+    if (opts.json) {
+      console.log(JSON.stringify(items));
+      return;
+    }
+    if (!items.length) {
       logger.info('No matches.');
       return;
     }
-    for (const i of filtered) {
-      const desc = i.description ? logger.dim(': ' + i.description) : '';
-      logger.info(`  ${logger.cyan(i.name)}${desc}`);
+    for (const [type, label] of GROUPS) {
+      const group = items.filter((i) => i.type === type);
+      if (!group.length) continue;
+      logger.info(logger.bold(`${label}:`));
+      for (const i of group) {
+        const desc = i.description ? logger.dim(': ' + i.description) : '';
+        logger.info(`  ${logger.cyan(i.name)}${desc}`);
+      }
+      logger.info('');
     }
-    logger.info('');
-    logger.info(`${filtered.length} component${filtered.length === 1 ? '' : 's'}.`);
+    const count = (type, word) => {
+      const n = items.filter((i) => i.type === type).length;
+      return n ? `${n} ${word}${n === 1 ? '' : 's'}` : null;
+    };
+    logger.info([count('ui', 'component'), count('block', 'block'), count('chart', 'chart')].filter(Boolean).join(', ') + '.');
   });

package/src/commands/view.js

@@ -1,34 +1,62 @@
 import { Command } from 'commander';
 import { getRegistryItem, DEFAULT_REGISTRY_URL, isDefaultRegistry } from '../registry/fetcher.js';
-import { uiComponent, renderComponentText } from '../registry/extract.js';
+import { uiComponent, renderComponentText, itemKind, projectBlock, renderBlockText } from '../registry/extract.js';
 import { logger } from '../utils/logger.js';
+import { getConfig } from '../utils/get-config.js';
+import { bakeForStyle } from '../registry/style-bake.js';
+
+/**
+ * The style to bake with: `--style`, else the project's components.json, else
+ * the default. Outside a project (no components.json) there is no config to
+ * read, which is not an error for `view`.
+ */
+function styleFor(opts) {
+  if (opts.style) return opts.style;
+  try { return getConfig(process.cwd())?.style; } catch { return undefined; }
+}
 
 export const view = new Command()
   .name('view')
   .description("Print a registry item's source (and the paste-ready example) to stdout")
-  .argument('<name>', 'component name')
+  .argument('<name>', 'component, block or chart name')
   .option('--registry <url>', 'registry base URL', DEFAULT_REGISTRY_URL)
   .option('--source', 'print only the raw source, not the projected view')
+  .option('--style <name>', 'the style to bake the source with (default: components.json, else new-york)')
+  .option('--json', 'a block or chart: print the projection as one JSON document')
+  .option('--files-only', 'a block or chart: print the file list and stop before the sources')
   .action(async (name, opts) => {
+    const style = styleFor(opts);
+
+    // A block or chart (D18) prints what it is, how to install it and where
+    // its files land, then the sources, all from the projector the MCP `ui`
+    // tool shares. Resolved first, since a block has no component projection.
+    const item = await getRegistryItem(name, opts.registry);
+    const kind = itemKind(item);
+    if (kind === 'block' || kind === 'chart') {
+      const block = projectBlock(item, { style, source: !opts.filesOnly });
+      console.log(opts.json ? JSON.stringify(block, null, 2) : renderBlockText(block));
+      return;
+    }
     // For a local registry:ui component, lead with the projected view (helper
     // signatures + the paste-ready @example + deps). This is the human /
     // offline path to the example that `add` strips from the copied file, and
     // it shares ONE projector with the MCP `ui` tool (`registry/extract.js`).
     // The projection reads the LOCAL packaged registry, so it only applies to
     // the default registry (a custom --registry gets the raw fetched source).
-    const projected = opts.source || !isDefaultRegistry(opts.registry) ? null : uiComponent(name);
+    const projected = opts.source || !isDefaultRegistry(opts.registry) ? null : uiComponent(name, { style });
     if (projected) {
       console.log(renderComponentText(projected));
       console.log('');
       logger.info(logger.dim('# --- full source ---'));
     }
 
-    const item = await getRegistryItem(name, opts.registry);
     logger.info(logger.dim(`# ${item.name}: ${item.type}`));
     if (item.description) logger.info(logger.dim(`# ${item.description}`));
     for (const f of item.files || []) {
       logger.info('');
       logger.info(logger.dim(`# ${f.path}`));
-      console.log(f.content || '');
+      // Baked, so the printed source is the plain Tailwind `add` would write
+      // (#1666). A custom registry's file with no cn-* name passes unchanged.
+      console.log(bakeForStyle(f.content || '', style));
     }
   });

package/src/lint/rules/no-restyle.js

@@ -11,7 +11,7 @@
  * invented: a helper matching neither authored shape yields no value list.
  *
  * `allow` takes category names and class-group ids. The documented starting
- * configuration is `["layout", "rounded"]`, which is what lets the skill's
+ * configuration is `["layout", "rounded"]`, which is what lets the kit's
  * sanctioned one-off (`cn(buttonClass({ size: 'none' }), 'w-9 h-9
  * rounded-full')`) pass: `w-9 h-9` is layout, and `rounded-full` is the plain
  * radius group granted by name without opening the whole `shape` category.

package/src/registry/extract.js

@@ -19,6 +19,7 @@
  */
 
 import { loadRegistryItem, loadRegistryIndex, isCustomElementSource } from './local.js';
+import { bakeForStyle } from './style-bake.js';
 import { extractExample } from './example.js';
 
 /**
@@ -243,17 +244,23 @@ export function extractDocHeader(src) {
  * Project one registry component into the agent-facing shape. Returns null when
  * the name is not a `registry:ui` component.
  *
+ * The source is BAKED first (#1666): the registry is in base form, and what an
+ * agent copies from this projection must be the plain Tailwind an app gets,
+ * never a `cn-*` name. `style` is the app's `components.json` style, and an
+ * absent one means `new-york`, the kit's default look.
+ *
  * @param {string} name
+ * @param {{ style?: string }} [opts]
  * @returns {{
  *   name: string, tier: 1|2, type: string,
  *   description: string, helpers: string[], example: string,
  *   dependencies: string[], registryDependencies: string[],
  * } | null}
  */
-export function uiComponent(name) {
+export function uiComponent(name, opts = {}) {
   const item = loadRegistryItem(name);
   if (!item || item.type !== 'registry:ui') return null;
-  const src = (item.files || []).map((f) => f.content || '').join('\n');
+  const src = (item.files || []).map((f) => bakeForStyle(f.content || '', opts.style)).join('\n');
   const tier = isCustomElementSource(src) ? 2 : 1;
   return {
     name: item.name,
@@ -267,11 +274,25 @@ export function uiComponent(name) {
   };
 }
 
+/**
+ * A component's files baked for a style, as `webjs ui view` prints them and
+ * `add` writes them (paths are the registry's). The /ui docs' Manual tab
+ * shows these, so the page and the CLI cannot disagree about the source.
+ *
+ * @param {string} name
+ * @param {{ style?: string }} [opts]
+ * @returns {Array<{ path: string, content: string }> | null}
+ */
+export function uiComponentFiles(name, opts = {}) {
+  const item = loadRegistryItem(name);
+  if (!item) return null;
+  return (item.files || []).map((f) => ({ path: f.path, content: bakeForStyle(f.content || '', opts.style) }));
+}
+
 /**
  * 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.
+ * helper signatures, npm deps). The no-args payload for the MCP `ui` tool, so
+ * an agent reaches for a helper instead of expanding Tailwind by hand.
  *
  * @returns {Array<{ name: string, tier: 1|2, helpers: string[], dependencies: string[] }>}
  */
@@ -290,6 +311,174 @@ export function uiInventory() {
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/* -------------------- blocks and charts (#1666, D18) -------------------- */
+
+/**
+ * What a block is, in the one phrasing every agent-facing surface uses. A
+ * block and a chart are both `registry:block` items on the wire (shadcn
+ * parity), told apart by a chart's `chart` category.
+ */
+export const BLOCK_DEFINITION = 'a ready-made view you install and then edit';
+
+/** The category that marks a `registry:block` as a chart. */
+export const CHART_CATEGORY = 'chart';
+
+/**
+ * The agent-facing kind of a registry item: `ui` for a component, `chart` for
+ * a block carrying the `chart` category, `block` for any other block, and
+ * null for everything else (a lib, a theme).
+ *
+ * @param {{ type?: string, categories?: string[] }} item
+ * @returns {'ui' | 'block' | 'chart' | null}
+ */
+export function itemKind(item) {
+  if (!item) return null;
+  if (item.type === 'registry:ui') return 'ui';
+  if (item.type !== 'registry:block') return null;
+  return (item.categories || []).includes(CHART_CATEGORY) ? 'chart' : 'block';
+}
+
+/**
+ * The category a block is grouped under in a compact listing: its LAST, most
+ * specific category (`login` for `['authentication', 'login']`, `area` for
+ * `['chart', 'area']`), so each name appears once. A block with none is
+ * grouped under `other`. Filtering by category still matches every one.
+ *
+ * @param {{ categories?: string[] }} item
+ * @returns {string}
+ */
+export function primaryCategory(item) {
+  const cats = (item.categories || []).filter((c) => c !== CHART_CATEGORY);
+  return cats.length ? cats[cats.length - 1] : 'other';
+}
+
+/**
+ * One compact entry per block or chart (and per component when `type` asks
+ * for them): `{ name, type, categories, description }`, sorted by name. The
+ * shape `webjsui list --json` prints and the MCP `ui` tool's filtered
+ * listing returns.
+ *
+ * @param {{ type?: 'ui' | 'block' | 'chart' | 'all', category?: string }} [opts]
+ *   `type` defaults to `block` plus `chart`; `all` adds the components.
+ * @param {any[]} [index] the registry index, the packaged one by default
+ * @returns {Array<{ name: string, type: 'ui' | 'block' | 'chart', categories: string[], description: string }>}
+ */
+export function uiBlocks(opts = {}, index = loadRegistryIndex()) {
+  const want = opts.type || 'blocks';
+  const keep = (/** @type {string|null} */ kind) =>
+    kind !== null && (
+      want === 'all' ? true
+        : want === 'blocks' ? kind === 'block' || kind === 'chart'
+          : kind === want
+    );
+  return index
+    .map((i) => ({ i, kind: itemKind(i) }))
+    .filter(({ i, kind }) => keep(kind) && (!opts.category || (i.categories || []).includes(opts.category)))
+    .map(({ i, kind }) => ({
+      name: i.name,
+      type: /** @type {'ui' | 'block' | 'chart'} */ (kind),
+      categories: i.categories || [],
+      description: i.description || '',
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * The blocks and charts as NAME LISTS grouped by {@link primaryCategory}, with
+ * no descriptions: `{ blocks: { login: [...] }, charts: { area: [...] } }`.
+ * The no-argument MCP `ui` payload carries this, so it stays cheap however
+ * many blocks the kit ships.
+ *
+ * @param {any[]} [index]
+ * @returns {{ blocks: Record<string, string[]>, charts: Record<string, string[]> }}
+ */
+export function uiBlockIndex(index = loadRegistryIndex()) {
+  /** @type {{ blocks: Record<string, string[]>, charts: Record<string, string[]> }} */
+  const out = { blocks: {}, charts: {} };
+  for (const b of uiBlocks({}, index)) {
+    const group = b.type === 'chart' ? out.charts : out.blocks;
+    (group[primaryCategory(b)] ??= []).push(b.name);
+  }
+  return out;
+}
+
+/** The command that installs a registry item, as every printed hint spells it (invariant 8). */
+export function installCommand(name) {
+  return `npx @webjsdev/ui add ${name}`;
+}
+
+/**
+ * Project one block (or chart) item into the agent-facing shape: what it is,
+ * how to install it, and the files it writes with their targets. Pure over
+ * the item, so `view` can project an item fetched from a custom registry.
+ * Returns null when the item is not a block.
+ *
+ * The sources are left out unless `source` is true, since the cheap path is
+ * to install the block and read the files on disk. When included they are
+ * BAKED (#1666), so no `cn-*` name reaches an agent, but their imports stay
+ * registry-relative: `add` is what rewrites them to the app's aliases.
+ *
+ * @param {any} item a registry item with its files
+ * @param {{ style?: string, source?: boolean }} [opts]
+ */
+export function projectBlock(item, opts = {}) {
+  const kind = itemKind(item);
+  if (kind !== 'block' && kind !== 'chart') return null;
+  return {
+    name: item.name,
+    type: kind,
+    title: item.title || item.name,
+    description: item.description || '',
+    categories: item.categories || [],
+    install: installCommand(item.name),
+    dependencies: item.dependencies || [],
+    registryDependencies: item.registryDependencies || [],
+    ...(item.cssVars ? { cssVars: item.cssVars } : {}),
+    files: (item.files || []).map((f) => ({
+      path: f.path,
+      type: f.type,
+      target: f.target || f.path,
+      ...(opts.source ? { content: bakeForStyle(f.content || '', opts.style) } : {}),
+    })),
+  };
+}
+
+/**
+ * {@link projectBlock} for a block in the packaged registry, by name. Null
+ * when the name is not a block.
+ *
+ * @param {string} name
+ * @param {{ style?: string, source?: boolean }} [opts]
+ */
+export function uiBlock(name, opts = {}) {
+  const item = loadRegistryItem(name);
+  return item ? projectBlock(item, opts) : null;
+}
+
+/**
+ * Render a block projection as human-readable text for `webjsui view`: the
+ * description, categories, dependencies, the install command and the file
+ * list with targets. The sources, when the projection carries them, follow.
+ *
+ * @param {ReturnType<typeof projectBlock>} b
+ * @returns {string}
+ */
+export function renderBlockText(b) {
+  if (!b) return '';
+  const lines = [`# ${b.name}  (${b.type})`];
+  if (b.description) lines.push('', b.description);
+  if (b.categories.length) lines.push('', `categories: ${b.categories.join(', ')}`);
+  if (b.registryDependencies.length) lines.push(`registry deps: ${b.registryDependencies.join(', ')}`);
+  if (b.dependencies.length) lines.push(`npm: ${b.dependencies.join(', ')}`);
+  lines.push('', `Install: ${b.install}`, '', 'Files:');
+  for (const f of b.files) lines.push(`  ${f.target}`);
+  for (const f of b.files) {
+    if (f.content === undefined) continue;
+    lines.push('', `# --- ${f.target} ---`, f.content.replace(/\n$/, ''));
+  }
+  return lines.join('\n');
+}
+
 /**
  * Render a component projection as human-readable text for `webjsui view`.
  * Shares the SAME {@link uiComponent} data the MCP `ui` tool returns, so the

package/src/registry/icons.js

@@ -0,0 +1,31 @@
+/**
+ * The app's icon library in a resolved install tree (#1666).
+ *
+ * Registry items depend on `lib-icons` (the Lucide file). The other four
+ * libraries export the same function names and land at the same path, so an
+ * app whose `components.json` names one of them gets that library's file in
+ * place of Lucide's, and a block's icons draw in the library the app chose.
+ *
+ * @module registry/icons
+ */
+
+import { getRegistryItem } from './fetcher.js';
+import { getIconLibrary } from '../../packages/registry/themes/preset.js';
+
+/**
+ * Replace `lib-icons` in a resolved tree with the item for `iconLibrary`.
+ * A tree without `lib-icons`, Lucide, or an unknown library name is
+ * returned as it is.
+ *
+ * @param {any[]} tree the items `resolveTree` returned
+ * @param {string | undefined} iconLibrary `components.json` `iconLibrary`
+ * @param {string} [registryUrl]
+ * @returns {Promise<any[]>}
+ */
+export async function withIconLibrary(tree, iconLibrary, registryUrl) {
+  const lib = getIconLibrary(iconLibrary || 'lucide');
+  if (!lib || lib.item === 'lib-icons') return tree;
+  if (!tree.some((it) => it.name === 'lib-icons')) return tree;
+  const chosen = await getRegistryItem(lib.item, registryUrl);
+  return tree.map((it) => (it.name === 'lib-icons' ? chosen : it));
+}