@webjsdev/ui 0.3.8 → 0.3.9

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,11 +87,38 @@ 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)}`);
 }
 
+/**
+ * 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

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.');
@@ -79,7 +91,7 @@ async function writeLibUtils(cwd, utilsAlias, registryUrl) {
   const utilsRel = utilsAlias.replace(/^@\//, '') + '.ts';
   const utilsTarget = join(cwd, utilsRel);
   try {
-    const item = await fetchRegistryItem('lib-utils', registryUrl);
+    const item = await getRegistryItem('lib-utils', registryUrl);
     if (item.files) {
       for (const f of item.files) {
         ensureDir(dirname(utilsTarget));
@@ -98,7 +110,7 @@ async function writeLibUtils(cwd, utilsAlias, registryUrl) {
   // 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('lib-dom', registryUrl);
+    const item = await getRegistryItem('lib-dom', registryUrl);
     if (!item.files) return;
     for (const f of item.files) {
       ensureDir(dirname(domTarget));
@@ -114,26 +126,6 @@ function relative(cwd, p) {
   return p.startsWith(cwd) ? p.slice(cwd.length + 1) : p;
 }
 
-async function writeTheme(cwd, baseColor, cssPath, registryUrl) {
-  try {
-    const item = await fetchRegistryItem(`theme-${baseColor}`, 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;
-    }
-    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.`);
-  }
-}
-
 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 || []) {

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.
  *