@webjsdev/ui 0.3.7 → 0.3.9

package/packages/registry/components/tooltip.ts

@@ -11,14 +11,6 @@
  *   TooltipProvider       → not needed; delay state is per-tooltip (and globally
  *                           shared via `skip-delay-duration` cooldown).
  *
- * Usage:
- *   <ui-tooltip delay-duration="500" skip-delay-duration="300">
- *     <ui-tooltip-trigger>
- *       <button class=${buttonClass({ size: 'icon', variant: 'ghost' })} aria-label="Help">?</button>
- *     </ui-tooltip-trigger>
- *     <ui-tooltip-content side="top">Helpful tip</ui-tooltip-content>
- *   </ui-tooltip>
- *
  * Attributes on <ui-tooltip>:
  *   `open`:                boolean (reflected). Open state.
  *   `delay-duration`:      ms, default 700. Initial hover delay before opening.
@@ -39,9 +31,20 @@
  * Programmatic API on <ui-tooltip>: `.show()` · `.hide()`.
  *
  * Design tokens used: --foreground, --background.
+ *
+ * @example
+ * ```html
+ * <ui-tooltip delay-duration="500" skip-delay-duration="300">
+ *   <ui-tooltip-trigger>
+ *     <button class=${buttonClass({ size: 'icon', variant: 'ghost' })} aria-label="Help">?</button>
+ *   </ui-tooltip-trigger>
+ *   <ui-tooltip-content side="top">Helpful tip</ui-tooltip-content>
+ * </ui-tooltip>
+ * ```
  */
 import { WebComponent, html, prop } from '@webjsdev/core';
-import { ensureId, onBeforeCache } from '../lib/utils.ts';
+import { ensureId } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
 
 // UA `[popover]` defaults paint a bordered, padded panel centered with

package/packages/registry/lib/dom.ts

@@ -0,0 +1,18 @@
+// Client-only DOM helpers. Kept SEPARATE from lib/utils.ts because these
+// reference `document`: any module that references a client global is treated
+// as client-effecting by the elision analyzer, so bundling this with the pure
+// `cn()` would pin every page that imports `cn` to the browser (#819). Import
+// these ONLY from components (which ship anyway), never from a page/layout.
+
+/**
+ * Run `reset` just before the webjs client router snapshots the page into its
+ * back/forward cache (the `webjs:before-cache` event). Transient overlays use
+ * this to close themselves so a restored snapshot is clean. SSR-safe (a no-op
+ * when there is no `document`). Wire it in `connectedCallback` and call the
+ * returned disposer in `disconnectedCallback` so it never leaks across navs.
+ */
+export function onBeforeCache(reset: () => void): () => void {
+  if (typeof document === 'undefined') return () => {};
+  document.addEventListener('webjs:before-cache', reset);
+  return () => document.removeEventListener('webjs:before-cache', reset);
+}

package/packages/registry/lib/utils.ts

@@ -127,95 +127,12 @@ export function ensureId(el: { id: string }, prefix = 'ui'): string {
   return el.id;
 }
 
-// ---------------------------------------------------------------------------
-// Custom-element base: SSR-safe. In the browser `Base = HTMLElement`. On
-// the server (Node, during SSR) `HTMLElement` is undefined; we substitute
-// a stub class so that `class Foo extends Base { … }` doesn't throw at
-// module-load time. The stub's methods are never actually called server-side
-// because connectedCallback/lifecycle hooks only run when the element is
-// inserted into a live DOM, which doesn't happen during webjs SSR.
-// ---------------------------------------------------------------------------
-
-const HasHTMLElement = typeof HTMLElement !== 'undefined';
-
-class ServerHTMLElementStub {
-  // Minimal surface so attribute reads/writes inside synchronous code paths
-  // that DO execute during SSR (e.g. attribute reflection) don't throw.
-  _ssrAttrs: Record<string, string> = {};
-  getAttribute(name: string): string | null {
-    return this._ssrAttrs[name] ?? null;
-  }
-  setAttribute(name: string, value: string): void {
-    this._ssrAttrs[name] = String(value);
-  }
-  hasAttribute(name: string): boolean {
-    return name in this._ssrAttrs;
-  }
-  removeAttribute(name: string): void {
-    delete this._ssrAttrs[name];
-  }
-  toggleAttribute(name: string, force?: boolean): boolean {
-    const want = force === undefined ? !this.hasAttribute(name) : force;
-    if (want) this.setAttribute(name, '');
-    else this.removeAttribute(name);
-    return want;
-  }
-  addEventListener(): void {}
-  removeEventListener(): void {}
-  dispatchEvent(): boolean {
-    return true;
-  }
-  // Tree-walk APIs no-op into null: components that call them server-side
-  // simply see "no children / no siblings", which is acceptable for SSR.
-  closest(): null {
-    return null;
-  }
-  querySelector(): null {
-    return null;
-  }
-  querySelectorAll(): never[] {
-    return [];
-  }
-  focus(): void {}
-  blur(): void {}
-  contains(): boolean {
-    return false;
-  }
-  insertBefore<T>(node: T): T {
-    return node;
-  }
-  appendChild<T>(node: T): T {
-    return node;
-  }
-  replaceChildren(): void {}
-  get firstChild(): null {
-    return null;
-  }
-  get classList() {
-    return { add: () => {}, remove: () => {}, toggle: () => false, contains: () => false };
-  }
-  get className(): string {
-    return this._ssrAttrs.class ?? '';
-  }
-  set className(v: string) {
-    this._ssrAttrs.class = v;
-  }
-  get style(): Record<string, string> {
-    return {};
-  }
-}
-
-/** SSR-safe base class: `HTMLElement` in browser, a thin stub in Node. */
-export const Base: typeof HTMLElement = (HasHTMLElement
-  ? HTMLElement
-  : (ServerHTMLElementStub as unknown as typeof HTMLElement)) as typeof HTMLElement;
-
-/** Register a custom element. No-op on server (no `customElements` global). */
-export function defineElement(name: string, cls: CustomElementConstructor): void {
-  if (typeof customElements === 'undefined') return;
-  if (customElements.get(name)) return; // already defined (HMR / double-import)
-  customElements.define(name, cls);
-}
+// NOTE: the old `HTMLElement`-era `Base` / `defineElement` / SSR-stub helpers
+// were removed. The ui registry components extend `WebComponent` from
+// `@webjsdev/core` now, so those helpers were dead code, and referencing
+// `HTMLElement` / `customElements` at module scope marked this util (and any
+// page that imports `cn`) as client-effecting. Everything below is pure or
+// SSR-safe, so importing `cn` no longer pins a page to the browser (#819).
 
 // ---------------------------------------------------------------------------
 // Layout helpers: encode the design-system rhythm (spacing between label /
@@ -266,19 +183,3 @@ export const helpClass = () => 'text-xs text-muted-foreground';
 
 /** Validation error text: replaces hint when the field is invalid. */
 export const errorClass = () => 'text-sm font-medium text-destructive';
-
-/**
- * Run `reset` just before the webjs client router snapshots the page into its
- * back/forward cache (the `webjs:before-cache` event). Transient overlays use
- * this to close themselves so a restored snapshot is clean rather than, say, a
- * hover-card frozen open after Back then Forward (#766). Wire it in
- * `connectedCallback` and call the returned disposer in `disconnectedCallback`
- * so the listener never leaks across soft navigations.
- *
- * SSR-safe: a no-op when there is no `document` (server / no client router).
- */
-export function onBeforeCache(reset: () => void): () => void {
-  if (typeof document === 'undefined') return () => {};
-  document.addEventListener('webjs:before-cache', reset);
-  return () => document.removeEventListener('webjs:before-cache', reset);
-}

package/packages/registry/registry.json

@@ -15,6 +15,18 @@
         }
       ]
     },
+    {
+      "name": "lib-dom",
+      "type": "registry:lib",
+      "description": "onBeforeCache() client-router cache hook",
+      "files": [
+        {
+          "path": "lib/dom.ts",
+          "type": "registry:lib",
+          "target": "lib/dom.ts"
+        }
+      ]
+    },
     {
       "name": "theme-neutral",
       "type": "registry:theme",
@@ -59,7 +71,8 @@
       "type": "registry:ui",
       "registryDependencies": [
         "button",
-        "dialog"
+        "dialog",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"
@@ -189,7 +202,8 @@
       "type": "registry:ui",
       "registryDependencies": [
         "lib-utils",
-        "button"
+        "button",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"
@@ -205,7 +219,8 @@
       "name": "dropdown-menu",
       "type": "registry:ui",
       "registryDependencies": [
-        "popover"
+        "popover",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"
@@ -221,7 +236,8 @@
       "name": "hover-card",
       "type": "registry:ui",
       "registryDependencies": [
-        "popover"
+        "popover",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"
@@ -381,6 +397,9 @@
     {
       "name": "sonner",
       "type": "registry:ui",
+      "registryDependencies": [
+        "lib-dom"
+      ],
       "dependencies": [
         "@webjsdev/core"
       ],
@@ -476,7 +495,8 @@
       "name": "tooltip",
       "type": "registry:ui",
       "registryDependencies": [
-        "popover"
+        "popover",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"

package/src/commands/add.js

@@ -7,6 +7,9 @@ import { getConfig } from '../utils/get-config.js';
 import { logger } from '../utils/logger.js';
 import { resolveTree, collectNpmDeps } from '../registry/resolver.js';
 import { DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
+import { isCustomElementSource } from '../registry/local.js';
+import { stripExample } from '../registry/example.js';
+import { ensureTheme } from '../utils/theme.js';
 
 export const add = new Command()
   .name('add')
@@ -35,6 +38,20 @@ export const add = new Command()
     const tree = await resolveTree(components, opts.registry);
     logger.info(`Installing ${logger.bold(components.join(', '))}…`);
 
+    // Self-heal missing theme tokens (#983): the helpers render against CSS
+    // design tokens; if the app never ran (or lost) the theme block, plant it
+    // so a copied component is not unstyled. Idempotent when already present.
+    // Skip if the config predates / lacks the tailwind fields (never crash add).
+    const tw = config.tailwind || {};
+    if (tw.css && tw.baseColor) {
+      const theme = await ensureTheme(cwd, tw.baseColor, tw.css, opts.registry);
+      if (theme.status === 'written') {
+        logger.success(`Planted missing theme tokens into ${tw.css}`);
+      } else if (theme.status === 'failed') {
+        logger.warn(`Could not verify theme tokens in ${tw.css}: ${theme.error}`);
+      }
+    }
+
     for (const item of tree) {
       for (const file of item.files || []) {
         await writeRegistryFile(cwd, config, item, file, opts);
@@ -70,37 +87,84 @@ async function writeRegistryFile(cwd, config, item, file, opts) {
     }
   }
 
-  const content = rewriteUtilsImport(file.content || '', target, config);
+  const content = transformForProject(file.content || '', target, config, item);
   writeFileSync(target, content, 'utf8');
   logger.success(`Wrote ${relative(cwd, target)}`);
 }
 
 /**
- * Rewrite the registry-relative `'../lib/utils.ts'` import to the path
- * that resolves correctly from the file's target location to the user's
- * cn() helper.
+ * The single transform that turns a registry file's raw content into what
+ * lands in the user's project. `add` writes this; `diff` compares against it,
+ * so the two cannot disagree (#983). Two steps:
+ *
+ *  1. Retarget the registry-relative `../lib/utils.ts` / `../lib/dom.ts` imports
+ *     to the project's resolved helper paths (see {@link rewriteUtilsImport}).
+ *  2. For a Tier-1 helper component (a `registry:ui` file that is NOT a custom
+ *     element), strip the worked `@example` and leave a one-line pointer, so the
+ *     copied file keeps only the helpers + a lean header. Tier-2 custom-element
+ *     files are left whole (the element IS the component), and lib/theme files
+ *     have no example so the strip is a no-op.
+ *
+ * @param {string} content raw registry file content
+ * @param {string} target absolute path where the file will be written
+ * @param {{ resolvedPaths: { utils: string } }} config parsed components.json
+ * @param {{ name: string, type?: string }} [item] the registry item
+ * @returns {string}
+ */
+export function transformForProject(content, target, config, item) {
+  let out = rewriteUtilsImport(content, target, config);
+  if (item && item.type === 'registry:ui' && !isCustomElementSource(content)) {
+    out = stripExample(out, item.name);
+  }
+  return out;
+}
+
+/**
+ * Rewrite the registry-relative `'../lib/utils.ts'` and `'../lib/dom.ts'`
+ * imports to the paths that resolve correctly from the file's target
+ * location to the user's cn() helper and onBeforeCache() DOM helper.
  *
  * The registry source assumes its own layout (`<registry>/components/<x>.ts`
- * imports `'../lib/utils.ts'`). When that file lands in the user's
- * components/ui/<x>.ts, the literal `'../lib/utils.ts'` resolves to
- * `components/lib/utils.ts`, which doesn't exist. We compute the actual
- * relative path from the target directory to `config.resolvedPaths.utils`
- * (an absolute path the user has already configured via components.json's
- * aliases.utils) and substitute it in.
+ * imports `'../lib/utils.ts'` / `'../lib/dom.ts'`). When that file lands in
+ * the user's components/ui/<x>.ts, the literal `'../lib/utils.ts'` resolves
+ * to `components/lib/utils.ts`, which doesn't exist. We compute the actual
+ * relative path from the target directory to the user's configured helper
+ * (`config.resolvedPaths.utils`, from components.json's aliases.utils) and
+ * substitute it in. The DOM helper is written as a SIBLING of the utils
+ * file (the scaffold puts it at `lib/utils/dom.ts`, next to `cn.ts`), so its
+ * absolute target is `dom.ts` in the utils file's directory. sonner imports
+ * ONLY the DOM helper, so both specifiers are handled independently and
+ * neither presence gates the other.
  *
  * @param {string} content raw file content from the registry
  * @param {string} target absolute path where the file will be written
  * @param {{ resolvedPaths: { utils: string } }} config parsed components.json
  */
 export function rewriteUtilsImport(content, target, config) {
-  if (!content.includes('../lib/utils.ts')) return content;
   const utilsAbs = config?.resolvedPaths?.utils;
   if (!utilsAbs) return content;
-  let rel = relPath(dirname(target), utilsAbs).split(/[\\/]/).join('/');
+  let out = replaceImportSpecifier(content, '../lib/utils.ts', utilsAbs, target);
+  const domAbs = join(dirname(utilsAbs), 'dom.ts');
+  out = replaceImportSpecifier(out, '../lib/dom.ts', domAbs, target);
+  return out;
+}
+
+/**
+ * Replace a single registry-relative import specifier with the relative path
+ * from `target`'s directory to `destAbs`. No-op when `spec` is absent.
+ *
+ * @param {string} content
+ * @param {string} spec the registry-relative specifier to replace
+ * @param {string} destAbs absolute path of the destination file
+ * @param {string} target absolute path where the importing file is written
+ */
+function replaceImportSpecifier(content, spec, destAbs, target) {
+  if (!content.includes(spec)) return content;
+  let rel = relPath(dirname(target), destAbs).split(/[\\/]/).join('/');
   if (!rel.startsWith('.')) rel = './' + rel;
   return content
-    .replaceAll("'../lib/utils.ts'", `'${rel}'`)
-    .replaceAll('"../lib/utils.ts"', `"${rel}"`);
+    .replaceAll(`'${spec}'`, `'${rel}'`)
+    .replaceAll(`"${spec}"`, `"${rel}"`);
 }
 
 function resolveTarget(cwd, config, item, file) {

package/src/commands/diff.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { getConfig } from '../utils/get-config.js';
 import { fetchRegistryItem, fetchRegistryIndex, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
+import { transformForProject } from './add.js';
 import { logger } from '../utils/logger.js';
 
 export const diff = new Command()
@@ -18,16 +19,32 @@ export const diff = new Command()
       process.exit(1);
     }
 
-    const items = name ? [await fetchRegistryItem(name, opts.registry)] : (await fetchRegistryIndex(opts.registry)).filter((i) => i.type === 'registry:ui');
+    // diff compares local files against the LIVE upstream, so it stays on the
+    // network path (NOT local-first): local-first would compare the package
+    // against itself. Resolve the names to compare, then fetch each item's full
+    // content (the index is metadata-only).
+    let names;
+    if (name) {
+      names = [name];
+    } else {
+      const index = await fetchRegistryIndex(opts.registry);
+      names = index.filter((i) => i.type === 'registry:ui').map((i) => i.name);
+    }
+
     const uiDir = config.resolvedPaths.ui;
     let changed = 0;
 
-    for (const item of items) {
+    for (const n of names) {
+      const item = await fetchRegistryItem(n, opts.registry);
       for (const file of item.files || []) {
         const target = join(uiDir, basename(file.path));
         if (!existsSync(target)) continue;
         const local = readFileSync(target, 'utf8');
-        if (local !== (file.content || '')) {
+        // Compare against what `add` WOULD write (import-rewrite + example
+        // strip), not the raw registry content: otherwise a pristine install
+        // reports every import-rewritten component as differing (#983).
+        const expected = transformForProject(file.content || '', target, config, item);
+        if (local !== expected) {
           logger.info(`${logger.bold(item.name)}: ${basename(file.path)} differs from registry`);
           changed++;
         }

package/src/commands/init.js

@@ -1,11 +1,12 @@
 import { Command } from 'commander';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import prompts from 'prompts';
 import { defaultsForProject } from '../utils/detect-project.js';
 import { writeConfig, CONFIG_FILE } from '../utils/get-config.js';
 import { logger } from '../utils/logger.js';
-import { fetchRegistryItem, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
+import { getRegistryItem, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
+import { ensureTheme } from '../utils/theme.js';
 
 const BASE_COLORS = ['neutral', 'stone', 'zinc', 'mauve', 'olive', 'mist', 'taupe'];
 
@@ -66,7 +67,18 @@ export const init = new Command()
 
     // Pull lib/utils + the chosen theme from the registry and write them in.
     await writeLibUtils(cwd, defaults.aliases.utils, opts.registry);
-    await writeTheme(cwd, answers.baseColor, answers.css, opts.registry);
+
+    // 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);
+    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.`);
 
     logger.break();
     logger.success('Done.');
@@ -75,41 +87,45 @@ export const init = new Command()
   });
 
 async function writeLibUtils(cwd, utilsAlias, registryUrl) {
+  // `utils` alias points at e.g. "lib/utils" so we write to lib/utils.ts
+  const utilsRel = utilsAlias.replace(/^@\//, '') + '.ts';
+  const utilsTarget = join(cwd, utilsRel);
   try {
-    const item = await fetchRegistryItem('lib-utils', registryUrl);
-    if (!item.files) return;
-    for (const f of item.files) {
-      // `utils` alias points at e.g. "lib/utils" → we write to lib/utils.ts
-      const target = join(cwd, utilsAlias.replace(/^@\//, '') + '.ts');
-      ensureDir(dirname(target));
-      writeFileSync(target, f.content || '', 'utf8');
-      logger.success(`Wrote ${utilsAlias}.ts`);
+    const item = await getRegistryItem('lib-utils', registryUrl);
+    if (item.files) {
+      for (const f of item.files) {
+        ensureDir(dirname(utilsTarget));
+        writeFileSync(utilsTarget, f.content || '', 'utf8');
+        logger.success(`Wrote ${utilsAlias}.ts`);
+      }
     }
   } catch (e) {
     logger.warn(`Could not fetch lib-utils from registry (${e.message}). You may need to write lib/utils.ts manually.`);
   }
-}
 
-async function writeTheme(cwd, baseColor, cssPath, registryUrl) {
+  // 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.
+  // Overlay components import it from `../lib/dom.ts`, so write it as a
+  // sibling of the utils file (e.g. lib/utils/dom.ts next to cn.ts).
+  const domTarget = join(dirname(utilsTarget), 'dom.ts');
   try {
-    const item = await fetchRegistryItem(`theme-${baseColor}`, registryUrl);
+    const item = await getRegistryItem('lib-dom', registryUrl);
     if (!item.files) return;
-    const target = join(cwd, cssPath);
-    ensureDir(dirname(target));
-    const existing = existsSync(target) ? readFileSync(target, 'utf8') : '';
-    const themeBlock = item.files[0]?.content || '';
-    // Idempotent: only append if our marker isn't already present.
-    if (existing.includes('/* @webjsdev/ui theme */')) {
-      logger.info(`Theme already present in ${cssPath}: skipping.`);
-      return;
+    for (const f of item.files) {
+      ensureDir(dirname(domTarget));
+      writeFileSync(domTarget, f.content || '', 'utf8');
+      logger.success(`Wrote ${relative(cwd, domTarget)}`);
     }
-    writeFileSync(target, existing + (existing && !existing.endsWith('\n') ? '\n' : '') + themeBlock, 'utf8');
-    logger.success(`Wrote theme into ${cssPath}`);
   } catch (e) {
-    logger.warn(`Could not fetch theme-${baseColor} (${e.message}). Skipping theme install.`);
+    logger.warn(`Could not fetch lib-dom from registry (${e.message}). You may need to write lib/dom.ts manually.`);
   }
 }
 
+function relative(cwd, p) {
+  return p.startsWith(cwd) ? p.slice(cwd.length + 1) : p;
+}
+
 function ensureDir(d) {
   if (!existsSync(d)) mkdirSync(d, { recursive: true });
 }

package/src/commands/list.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { fetchRegistryIndex, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
+import { getRegistryIndex, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
 import { logger } from '../utils/logger.js';
 
 export const list = new Command()
@@ -9,7 +9,7 @@ export const list = new Command()
   .argument('[filter]', 'filter by substring')
   .option('--registry <url>', 'registry base URL', DEFAULT_REGISTRY_URL)
   .action(async (filter, opts) => {
-    const items = await fetchRegistryIndex(opts.registry);
+    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) {

package/src/commands/view.js

@@ -1,14 +1,29 @@
 import { Command } from 'commander';
-import { fetchRegistryItem, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
+import { getRegistryItem, DEFAULT_REGISTRY_URL, isDefaultRegistry } from '../registry/fetcher.js';
+import { uiComponent, renderComponentText } from '../registry/extract.js';
 import { logger } from '../utils/logger.js';
 
 export const view = new Command()
   .name('view')
-  .description("Print a registry item's source to stdout")
+  .description("Print a registry item's source (and the paste-ready example) to stdout")
   .argument('<name>', 'component name')
   .option('--registry <url>', 'registry base URL', DEFAULT_REGISTRY_URL)
+  .option('--source', 'print only the raw source, not the projected view')
   .action(async (name, opts) => {
-    const item = await fetchRegistryItem(name, opts.registry);
+    // 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);
+    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 || []) {