@webjsdev/ui 0.3.10 → 0.3.11

package/packages/registry/lib/utils.ts

@@ -52,6 +52,10 @@ const GROUPS: Array<[RegExp, string]> = [
   [/^p-/, 'p'], [/^px-/, 'px'], [/^py-/, 'py'], [/^pt-/, 'pt'], [/^pr-/, 'pr'], [/^pb-/, 'pb'], [/^pl-/, 'pl'],
   [/^m-/, 'm'], [/^mx-/, 'mx'], [/^my-/, 'my'], [/^mt-/, 'mt'], [/^mr-/, 'mr'], [/^mb-/, 'mb'], [/^ml-/, 'ml'],
   [/^w-/, 'w'], [/^h-/, 'h'], [/^size-/, 'size'],
+  // A `bg-[url(…)]` / `bg-[linear-gradient(…)]` background image is classified
+  // by its FUNCTION, since it carries no type hint to classify it by. The
+  // hinted forms are handled centrally, in `hintedGroup`.
+  [/^bg-\[(url\(|linear-gradient|radial-gradient|conic-gradient)/, 'bg-image'],
   [/^bg-(linear|gradient|conic|radial|none)/, 'bg-image'],
   [/^bg-(no-repeat|repeat|repeat-x|repeat-y|repeat-round|repeat-space)$/, 'bg-repeat'],
   [/^bg-(fixed|local|scroll)$/, 'bg-attach'],
@@ -62,17 +66,127 @@ const GROUPS: Array<[RegExp, string]> = [
   [/^text-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl)$/, 'text-size'],
   // Text color: anything else starting with text- that isn't alignment / wrap / overflow.
   [/^text-(?!align-|left$|right$|center$|justify$|start$|end$|wrap$|nowrap$|balance$|pretty$|clip$|ellipsis$|xs$|sm$|base$|lg$|xl$|\d?xl$)/, 'text-color'],
-  [/^border(-[trblxy])?-?\d/, 'border-w'],
+  // Border sub-properties that are neither a width nor a colour. These come
+  // FIRST so the width / colour classifier below never sees them.
+  [/^border-(collapse|separate)$/, 'border-collapse'],
+  [/^border-spacing(-[xy])?-/, 'border-spacing'],
+  [/^border-(solid|dashed|dotted|double|hidden|none)$/, 'border-style'],
+  ...borderGroups(),
   [/^rounded(-[a-z]+)?$/, 'rounded'],
   [/^rounded-/, 'rounded'],
   [/^opacity-/, 'opacity'],
   [/^font-(thin|light|normal|medium|semibold|bold|black|extralight|extrabold)$/, 'font-weight'],
   [/^shadow(-|$)/, 'shadow'],
   [/^z-/, 'z'],
-  [/^flex(-|$)/, 'flex'],
-  [/^grid(-|$)/, 'grid'],
+  // A bare `flex` / `grid` is a DISPLAY value, not a member of the flex / grid
+  // sub-property groups below, so it must never dedupe against them: an element
+  // can be both a flex container and a flex child (`class="flex flex-1"`), and
+  // collapsing the two silently drops `display:flex`. It still belongs to a
+  // group of its own, alongside every other display keyword, so a repeated one
+  // collapses and `cn('hidden', open && 'flex')` resolves to one display.
+  [/^(inline-block|inline-flex|inline-grid|inline-table|inline|block|flex|grid|flow-root|contents|hidden|list-item|table-caption|table-cell|table-column-group|table-column|table-footer-group|table-header-group|table-row-group|table-row|table)$/, 'display'],
+  // Each sub-utility below gets the group of the real CSS property it sets, so
+  // none of them collapses against the display value or against each other.
+  [/^flex-(row|row-reverse|col|col-reverse)$/, 'flex-direction'],
+  [/^flex-(wrap|wrap-reverse|nowrap)$/, 'flex-wrap'],
+  [/^flex-(\d+|auto|initial|none|\[[^\]]*\])$/, 'flex'],
+  [/^grid-cols-/, 'grid-cols'],
+  [/^grid-rows-/, 'grid-rows'],
+  [/^grid-flow-/, 'grid-flow'],
 ];
 
+/**
+ * Border WIDTH and border COLOUR share the `border-` prefix but are different
+ * CSS properties, so they need different groups: `cn('border-2',
+ * 'border-primary')` must keep BOTH, while `cn('border-border',
+ * 'border-accent')` must keep only the later colour (today the winner is
+ * decided by compiled stylesheet order, which silently loses whenever the
+ * override sorts alphabetically earlier).
+ *
+ * Classification, after an optional side / axis segment: a bare or numeric
+ * value is a width (`border`, `border-2`, `border-t-4`), an arbitrary value
+ * that opens with a digit, a dot, or `length:` is a width (`border-[3px]`,
+ * `border-[length:var(--w)]`), and everything else is a colour
+ * (`border-primary`, `border-red-500/50`, `border-[#fff]`). An ambiguous
+ * `border-[var(--x)]` falls to colour, which is the far more common intent.
+ *
+ * Each side is its own group so a per-side utility only overrides its own side,
+ * and the shorthand / axis subsumption is declared in CONFLICTS below, exactly
+ * like padding and margin. The logical inline sides (`border-s-*`,
+ * `border-e-*`) get their own groups but are subsumed only by the all-sides
+ * shorthand, never by `border-x-*`: which physical side they land on depends on
+ * the writing direction, so an axis override there would be a guess.
+ */
+function borderGroups(): Array<[RegExp, string]> {
+  const width = '(\\d+(\\.\\d+)?|\\[(length:|\\d|\\.)[^\\]]*\\])';
+  const out: Array<[RegExp, string]> = [];
+  // Sides before the bare form: `border-t-primary` must match the `t` colour
+  // group, not be swallowed by the side-less `^border-` colour pattern.
+  const sides = ['x', 'y', 't', 'r', 'b', 'l', 's', 'e', ''];
+  for (const side of sides) {
+    const seg = side ? `-${side}` : '';
+    out.push([new RegExp(`^border${seg}(-${width})?$`), `border-w${seg}`]);
+  }
+  for (const side of sides) {
+    const seg = side ? `-${side}` : '';
+    out.push([new RegExp(`^border${seg}-`), `border-color${seg}`]);
+  }
+  return out;
+}
+
+/**
+ * An arbitrary value may carry a Tailwind TYPE HINT: `bg-[image:var(--g)]`,
+ * `text-[length:14px]`, `shadow-[color:red]`. The hint exists precisely because
+ * the utility prefix is ambiguous, so the PREFIX cannot decide the group and
+ * the hint must. Letting a hinted value fall into the prefix's default group
+ * evicts a class that sets an entirely different property (`shadow-[color:red]`
+ * would eat `shadow-lg`).
+ *
+ * Every `<prefix>:<hint>` pair listed here names the group it belongs to; an
+ * empty string means the hint names the prefix's OWN default property, so the
+ * GROUPS table above is already right for it and matching falls through. A pair
+ * that is NOT listed gets a group of its own, so it can only ever collide with
+ * the identical hint under the identical prefix, never with the prefix's
+ * default. That is the safe direction to fail: an extra class renders, a
+ * dropped one does not.
+ *
+ * This is central rather than per-prefix on purpose. Handling only the prefixes
+ * that came to mind is how `shadow-[color:red]` was left evicting `shadow-lg`
+ * while `bg-` and `text-` were correct.
+ *
+ * These reach the matcher at all only because `variantPrefix` splits on the
+ * last colon OUTSIDE brackets; see the comment there.
+ */
+const HINTED_GROUPS: Record<string, string> = {
+  'bg:color': '',
+  'bg:image': 'bg-image',
+  'bg:position': 'bg-position',
+  'bg:size': 'bg-size',
+  'bg:length': 'bg-size',
+  'text:color': '',
+  'text:length': 'text-size',
+};
+
+/**
+ * The group for a hinted arbitrary value, `null` when the normal GROUPS table
+ * should decide it, `undefined` when the token carries no hint at all.
+ */
+function hintedGroup(bare: string): string | null | undefined {
+  const m = /^([a-z][a-z-]*)-\[([a-z][a-z-]*):/.exec(bare);
+  if (!m) return undefined;
+  const prefix = m[1];
+  const hint = m[2];
+  const key = `${prefix}:${hint}`;
+  if (key in HINTED_GROUPS) return HINTED_GROUPS[key] || null;
+  // A border width or colour hint is read by `borderGroups()`'s value parser,
+  // which already classifies `border-[length:2px]` as a width and everything
+  // else after `border-` as a colour. The side list MUST match the one
+  // `borderGroups()` enumerates, logical inline sides included, or the hinted
+  // and plain spellings of one utility land in different groups.
+  if (/^border(-[xytrbles])?$/.test(prefix) && (hint === 'length' || hint === 'color')) return null;
+  return `hint:${key}`;
+}
+
 // Directional shorthand conflicts (the tailwind-merge model). A shorthand
 // utility invalidates the axis / side utilities it SUBSUMES, because Tailwind's
 // cascade makes the shorthand win: `p-0` after `px-4 py-2` drops both, but
@@ -88,6 +202,12 @@ const CONFLICTS: Record<string, string[]> = {
   mx: ['ml', 'mr'],
   my: ['mt', 'mb'],
   size: ['w', 'h'],
+  'border-w': ['border-w-x', 'border-w-y', 'border-w-t', 'border-w-r', 'border-w-b', 'border-w-l', 'border-w-s', 'border-w-e'],
+  'border-w-x': ['border-w-l', 'border-w-r'],
+  'border-w-y': ['border-w-t', 'border-w-b'],
+  'border-color': ['border-color-x', 'border-color-y', 'border-color-t', 'border-color-r', 'border-color-b', 'border-color-l', 'border-color-s', 'border-color-e'],
+  'border-color-x': ['border-color-l', 'border-color-r'],
+  'border-color-y': ['border-color-t', 'border-color-b'],
 };
 
 function dedupeUtilities(input: string): string {
@@ -102,9 +222,15 @@ function dedupeUtilities(input: string): string {
     // only apply WITHIN the same variant (`px-4 hover:p-0` keeps both).
     const prefix = variantPrefix(token);
     const bare = prefix ? token.slice(prefix.length) : token;
-    let gk: string | null = null;
-    for (const [re, g] of GROUPS) {
-      if (re.test(bare)) { gk = g; break; }
+    // A type-hinted arbitrary value is classified by its HINT, which overrides
+    // the prefix-keyed table below (`hintedGroup` returns null when the hint
+    // names the prefix's own default property and the table is already right).
+    const hinted = hintedGroup(bare);
+    let gk: string | null = hinted ?? null;
+    if (hinted === undefined || hinted === null) {
+      for (const [re, g] of GROUPS) {
+        if (re.test(bare)) { gk = g; break; }
+      }
     }
     if (gk) {
       // Remove earlier survivors in this group AND in every group it subsumes.
@@ -121,8 +247,21 @@ function dedupeUtilities(input: string): string {
 }
 
 function variantPrefix(token: string): string {
-  // capture leading variants like `hover:`, `dark:`, `md:`: overrides only conflict within the same variant set
-  const i = token.lastIndexOf(':');
+  // Capture leading variants like `hover:`, `dark:`, `md:`: overrides only
+  // conflict within the same variant set. The split is the last colon OUTSIDE
+  // square brackets, because an arbitrary value can contain one of its own
+  // (`border-[length:2px]`, `bg-[url(https://x/y.png)]`, `text-[color:var(--c)]`).
+  // Splitting on the last colon anywhere hands the group matcher a fragment
+  // like `2px]`, which matches nothing, so the utility silently stops
+  // deduping against its own property.
+  let depth = 0;
+  let i = -1;
+  for (let n = 0; n < token.length; n += 1) {
+    const c = token[n];
+    if (c === '[') depth += 1;
+    else if (c === ']') depth -= 1;
+    else if (c === ':' && depth === 0) i = n;
+  }
   return i === -1 ? '' : token.slice(0, i + 1);
 }
 

package/packages/registry/registry.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://ui.webjs.dev/schema/registry.json",
   "name": "@webjsdev/ui",
-  "homepage": "https://ui.webjs.dev",
+  "homepage": "https://webjs.dev/ui",
   "items": [
     {
       "name": "lib-utils",

package/packages/registry/themes/base-colors.js

@@ -5,7 +5,7 @@
  * preserved; only hue / chroma shift.
  *
  * Pure ESM data module: imported at request time by the website's registry
- * composer (`app/_lib/registry.server.ts`) to synthesize `theme-<color>` items
+ * composer (`website/modules/ui/queries/registry.server.ts`) to synthesize `theme-<color>` items
  * on demand. No build step, no committed output. Numbers match the values
  * shadcn emits in `apps/v4/public/r/themes/*.json`.
  */

package/src/commands/add.js

@@ -74,6 +74,16 @@ async function writeRegistryFile(cwd, config, item, file, opts) {
   const target = resolveTarget(cwd, config, item, file);
   ensureDir(dirname(target));
 
+  // The shared helpers are yours to edit, and since #1129 they live at the
+  // `utils` alias, which is the file `webjs create` generates and the one the
+  // docs tell you to retune. `--yes` means "do not ask me about overwrites",
+  // which is the normal non-interactive invocation, so honouring it here would
+  // replace edited source on every `add`. Only an explicit `--overwrite` may.
+  if (existsSync(target) && !opts.overwrite && helperTarget(config, item, file)) {
+    logger.info(`${relative(cwd, target)} already exists: keeping it.`);
+    return;
+  }
+
   if (existsSync(target) && !opts.overwrite && !opts.yes) {
     const r = await prompts({
       type: 'confirm',
@@ -168,6 +178,17 @@ function replaceImportSpecifier(content, spec, destAbs, target) {
 }
 
 function resolveTarget(cwd, config, item, file) {
+  // The two shared helpers are pinned to `lib/utils.ts` / `lib/dom.ts` by the
+  // registry manifest, but where they actually BELONG is wherever the project's
+  // `utils` alias points, because that is the path `rewriteUtilsImport` writes
+  // into every component's import. Honour the alias for them, ahead of the
+  // manifest target, or `add` writes a second copy at the pinned path that
+  // nothing imports while the components resolve to the aliased one.
+  // The dom helper is the utils file's SIBLING, the same relationship the
+  // rewrite assumes, so the two cannot disagree.
+  const helper = helperTarget(config, item, file);
+  if (helper) return helper;
+
   // explicit `target` wins
   if (file.target) return join(cwd, file.target);
 
@@ -188,6 +209,35 @@ function resolveTarget(cwd, config, item, file) {
   }
 }
 
+/**
+ * Absolute target for the `lib-utils` / `lib-dom` registry items, derived from
+ * the project's configured `utils` alias, or null for anything else.
+ *
+ * Kept as the single place that answers "where do the shared helpers live",
+ * so `add`'s WRITE and {@link rewriteUtilsImport}'s REWRITE read the same
+ * answer. `init` writes the same two paths (see `init.js` `writeLibUtils`).
+ *
+ * @param {{ resolvedPaths?: { utils?: string } }} config parsed components.json
+ * @param {{ name?: string }} [item] the registry item
+ * @param {{ path?: string }} [file] the file within that item
+ * @returns {string | null}
+ */
+function helperTarget(config, item, file) {
+  const utilsAbs = config?.resolvedPaths?.utils;
+  if (!utilsAbs || !item) return null;
+  // Matched per FILE, not per item. `rewriteUtilsImport` always retargets
+  // component imports to `resolvedPaths.utils`, so the ONE file those imports
+  // resolve to has to be written there or it is an orphan. Any other file a
+  // custom registry ships under the same item is not that file, so it keeps
+  // its manifest target: routing them all here would collapse them onto one
+  // path and lose every file but the last.
+  if (!file) return null;
+  const name = basename(file.path || '');
+  if (item.name === 'lib-utils' && name === 'utils.ts') return utilsAbs;
+  if (item.name === 'lib-dom' && name === 'dom.ts') return join(dirname(utilsAbs), 'dom.ts');
+  return null;
+}
+
 function relative(cwd, p) {
   return p.startsWith(cwd) ? p.slice(cwd.length + 1) : p;
 }

package/src/commands/info.js

@@ -2,20 +2,17 @@ import { Command } from 'commander';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { getConfig } from '../utils/get-config.js';
-import { detectProject } from '../utils/detect-project.js';
 import { DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
 import { logger } from '../utils/logger.js';
 
 export const info = new Command()
   .name('info')
-  .description('Print project diagnostics (config, project type, registry)')
+  .description('Print project diagnostics (config, registry)')
   .option('-c, --cwd <cwd>', 'the working directory', process.cwd())
   .action((opts) => {
     const cwd = opts.cwd;
-    const { type } = detectProject(cwd);
     const config = getConfig(cwd);
 
-    logger.info(`${logger.bold('Project')}      ${type}`);
     logger.info(`${logger.bold('cwd')}          ${cwd}`);
     logger.info(`${logger.bold('Registry')}     ${DEFAULT_REGISTRY_URL}`);
     logger.info(`${logger.bold('Config')}       ${config ? 'components.json ✔' : 'components.json ✖ (run `webjsui init`)'}`);

package/src/commands/init.js

@@ -1,8 +1,7 @@
 import { Command } from 'commander';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, 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 { getRegistryItem, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
@@ -10,22 +9,96 @@ import { ensureTheme } from '../utils/theme.js';
 
 const BASE_COLORS = ['neutral', 'stone', 'zinc', 'mauve', 'olive', 'mist', 'taupe'];
 
+/**
+ * The stylesheet `init` defaults to. It is `styles/globals.css`, NOT
+ * `app/globals.css`, because in WebJs `app/` is routing-only, so a
+ * non-routing stylesheet lives outside it.
+ *
+ * Exported so `webjs create` can be checked against it rather than against a
+ * hand-copied literal (`test/scaffolds/scaffold-ui-integration.test.js`).
+ */
+export const DEFAULT_TAILWIND_CSS = 'styles/globals.css';
+
+/**
+ * The alias map `init` writes into `components.json`. These are the paths a
+ * WebJs app uses, and they match byte for byte what `webjs create` scaffolds
+ * (see `packages/cli/lib/create.js`), so `init` on a bare app and a freshly
+ * scaffolded one land on the same layout.
+ *
+ * `utils` is `lib/utils/cn`, not `lib/utils`: `get-config.js` appends `'.ts'`
+ * when resolving the alias, so this resolves to `lib/utils/cn.ts`. Writing
+ * the helper into the `lib/utils/` DIRECTORY is what lets the client-only
+ * `onBeforeCache()` helper sit beside it at `lib/utils/dom.ts` (#819), which
+ * is where `add` rewrites the registry's `'../lib/dom.ts'` import to point.
+ *
+ * Exported for the same drift check as {@link DEFAULT_TAILWIND_CSS}. The two
+ * generators used to disagree here (init said `lib/utils`, the scaffold said
+ * `lib/utils/cn`) with only a comment claiming they matched, so the agreement
+ * is asserted now rather than described.
+ */
+export const DEFAULT_ALIASES = {
+  components: 'components',
+  utils: 'lib/utils/cn',
+  ui: 'components/ui',
+  lib: 'lib',
+};
+
 export const init = new Command()
   .name('init')
-  .description('Initialize @webjsdev/ui in a project: writes components.json, theme CSS, lib/utils')
+  .description('Initialize @webjsdev/ui in a project: writes components.json, theme CSS, lib/utils/cn.ts')
   .option('-c, --cwd <cwd>', 'the working directory', process.cwd())
   .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('--registry <url>', 'registry base URL', DEFAULT_REGISTRY_URL)
   .action(async (opts) => {
     const cwd = opts.cwd;
-    const defaults = defaultsForProject(cwd);
+
+    // 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
+    // actually builds, so adopting the current defaults over an existing
+    // project's values would strand those imports and append the tokens to a
+    // file nothing compiles. Keep what the project declared; `--overwrite`
+    // opts into replacing it.
+    //
+    // Read the RAW json rather than going through `getConfig`: its schema is
+    // `.strict()`, so a config carrying any unknown key (a shadcn-shaped one
+    // with `rsc` / `tsx`, or a hand-added field) throws, and treating that as
+    // "no config" is exactly what would relocate a real project and then
+    // overwrite the file. Only a file we cannot parse AT ALL is a refusal,
+    // because silently replacing unreadable config is the same data loss.
+    const cfgPath = join(cwd, CONFIG_FILE);
+    /** @type {any} */
+    let existing = null;
+    if (existsSync(cfgPath)) {
+      try {
+        existing = JSON.parse(readFileSync(cfgPath, 'utf8'));
+      } catch {
+        if (!opts.overwrite) {
+          logger.error(`${CONFIG_FILE} exists but is not valid JSON, so its settings cannot be preserved.`);
+          logger.info('Fix or delete it, or re-run with --overwrite to replace it.');
+          process.exit(1);
+        }
+      }
+    }
+    const keep = existing && !opts.overwrite;
+    if (keep) {
+      logger.info(`${CONFIG_FILE} already exists: keeping its settings (use --overwrite to reset them).`);
+    }
+    // Layer over the defaults rather than replacing them: the schema gives
+    // several alias keys defaults, so a hand-written map may legitimately omit
+    // one, and reading it raw (above) skips that default-filling. Taking the
+    // map wholesale left `utils` undefined and crashed on the write.
+    const aliases = { ...DEFAULT_ALIASES, ...((keep && existing.aliases) || null) };
+    const initialCss = (keep && existing.tailwind && existing.tailwind.css) || DEFAULT_TAILWIND_CSS;
+    const initialBaseColor = (keep && existing.tailwind && existing.tailwind.baseColor) || 'neutral';
 
     /** @type {{ baseColor: string, css: string }} */
     let answers = {
-      baseColor: opts.baseColor || 'neutral',
-      css: opts.css || defaults.tailwindCss,
+      baseColor: opts.baseColor || initialBaseColor,
+      css: opts.css || initialCss,
     };
 
     if (!opts.yes) {
@@ -36,13 +109,13 @@ export const init = new Command()
             name: 'baseColor',
             message: 'Base color?',
             choices: BASE_COLORS.map((c) => ({ title: c, value: c })),
-            initial: 0,
+            initial: Math.max(0, BASE_COLORS.indexOf(initialBaseColor)),
           },
           {
             type: opts.css ? null : 'text',
             name: 'css',
             message: 'Tailwind CSS file path?',
-            initial: defaults.tailwindCss,
+            initial: initialCss,
           },
         ],
         { onCancel: () => process.exit(1) },
@@ -50,23 +123,29 @@ export const init = new Command()
       answers = { ...answers, ...r };
     }
 
+    // Built from KNOWN keys only. The schema is `.strict()`, so carrying an
+    // 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.
     const config = {
       $schema: 'https://ui.webjs.dev/schema.json',
-      style: 'default',
+      style: (keep && existing.style) || 'default',
       tailwind: {
         css: answers.css,
         baseColor: answers.baseColor,
-        cssVariables: true,
+        cssVariables: keep && existing.tailwind && existing.tailwind.cssVariables !== undefined
+          ? existing.tailwind.cssVariables
+          : true,
       },
-      aliases: defaults.aliases,
-      iconLibrary: 'lucide',
+      aliases,
+      iconLibrary: (keep && existing.iconLibrary) || 'lucide',
     };
 
     writeConfig(cwd, config);
     logger.success(`Wrote ${CONFIG_FILE}`);
 
     // Pull lib/utils + the chosen theme from the registry and write them in.
-    await writeLibUtils(cwd, defaults.aliases.utils, opts.registry);
+    await writeLibUtils(cwd, aliases.utils, opts.registry, opts.overwrite);
 
     // The theme tokens are what the class helpers render against. A silent
     // failure here (the old behaviour) left an unstyled install with a clean
@@ -86,30 +165,53 @@ export const init = new Command()
     logger.info(`Add components with:  ${logger.cyan('npx webjsui add button card dialog')}`);
   });
 
-async function writeLibUtils(cwd, utilsAlias, registryUrl) {
-  // `utils` alias points at e.g. "lib/utils" so we write to lib/utils.ts
+/**
+ * Write the two shared helpers, WITHOUT clobbering a copy the project already
+ * has. The kit is source-copied and you-own-it, so `lib/utils/cn.ts` is a file
+ * users are told to edit ("change one helper to retune the entire app"), and
+ * `webjs create` puts its own copy there. An unguarded write was harmless while
+ * init targeted `lib/utils.ts`, a path nothing else owned, but the moment it
+ * writes where the scaffold and the user's edits live it becomes silent data
+ * loss, and re-running init is the documented fix for an unstyled install. So
+ * an existing file is kept unless `--overwrite` says otherwise. `add` keeps
+ * the same two files on the same terms (its `--yes` skips prompts but does not
+ * license replacing them), and the theme is idempotent, so every path into a
+ * project leaves an edited helper alone.
+ */
+async function writeLibUtils(cwd, utilsAlias, registryUrl, overwrite) {
+  // The `utils` alias omits the extension ("lib/utils/cn"), matching how
+  // get-config.js resolves it, so append '.ts' to get the target path.
   const utilsRel = utilsAlias.replace(/^@\//, '') + '.ts';
   const utilsTarget = join(cwd, utilsRel);
   try {
-    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`);
+    if (existsSync(utilsTarget) && !overwrite) {
+      logger.info(`${utilsRel} already exists: keeping it.`);
+    } else {
+      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 ${utilsRel}`);
+        }
       }
     }
   } catch (e) {
-    logger.warn(`Could not fetch lib-utils from registry (${e.message}). You may need to write lib/utils.ts manually.`);
+    logger.warn(`Could not fetch lib-utils from registry (${e.message}). You may need to write ${utilsRel} manually.`);
   }
 
   // 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).
+  // 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.
   const domTarget = join(dirname(utilsTarget), 'dom.ts');
   try {
+    if (existsSync(domTarget) && !overwrite) {
+      logger.info(`${relative(cwd, domTarget)} already exists: keeping it.`);
+      return;
+    }
     const item = await getRegistryItem('lib-dom', registryUrl);
     if (!item.files) return;
     for (const f of item.files) {
@@ -118,7 +220,7 @@ async function writeLibUtils(cwd, utilsAlias, registryUrl) {
       logger.success(`Wrote ${relative(cwd, domTarget)}`);
     }
   } catch (e) {
-    logger.warn(`Could not fetch lib-dom from registry (${e.message}). You may need to write lib/dom.ts manually.`);
+    logger.warn(`Could not fetch lib-dom from registry (${e.message}). You may need to write ${relative(cwd, domTarget)} manually.`);
   }
 }
 

package/src/registry/fetcher.js

@@ -4,8 +4,16 @@ import { loadRegistryItem, loadRegistryIndex } from './local.js';
 /**
  * The canonical hosted registry. Local-first resolution applies ONLY for this
  * exact URL: it is the one registry whose sources ship inside the package.
+ *
+ * This moved from `https://ui.webjs.dev/registry` when the gallery merged into
+ * the marketing site (#1099). The OLD URL still works and must keep working
+ * forever, because every already-published version of this package carries it
+ * and cannot be corrected: `ui.webjs.dev` now permanently redirects here, and
+ * `fetch` follows redirects by default (verified against the real published
+ * 0.3.1 and 0.3.8 tarballs before the move). Pointing new releases straight at
+ * the destination just saves them the hop.
  */
-export const HOSTED_REGISTRY_URL = 'https://ui.webjs.dev/registry';
+export const HOSTED_REGISTRY_URL = 'https://webjs.dev/ui/registry';
 
 /**
  * Default registry URL. A `REGISTRY_URL` env var points at a CUSTOM registry,

package/src/registry/local.js

@@ -9,7 +9,7 @@
  * 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
+ * (`website/modules/ui/queries/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

package/src/utils/index.js

@@ -1,3 +1,2 @@
 export { getConfig, writeConfig, CONFIG_FILE } from './get-config.js';
-export { detectProject, defaultsForProject } from './detect-project.js';
 export { logger } from './logger.js';

package/src/utils/detect-project.js

@@ -1,63 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-/**
- * Detect the host project type so we can pick sensible defaults for paths.
- *
- * @param {string} cwd
- * @returns {{ type: 'webjs' | 'next' | 'vite' | 'astro' | 'plain', meta: any }}
- */
-export function detectProject(cwd = process.cwd()) {
-  const pkgPath = join(cwd, 'package.json');
-  if (!existsSync(pkgPath)) return { type: 'plain', meta: {} };
-
-  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
-
-  if (deps['@webjsdev/server'] || deps['@webjsdev/cli'] || existsSync(join(cwd, 'app', 'layout.ts')) || existsSync(join(cwd, 'app', 'layout.js'))) {
-    return { type: 'webjs', meta: { pkg } };
-  }
-  if (deps['next']) return { type: 'next', meta: { pkg } };
-  if (deps['vite'] || deps['@vitejs/plugin-react'] || deps['@vitejs/plugin-vue']) return { type: 'vite', meta: { pkg } };
-  if (deps['astro']) return { type: 'astro', meta: { pkg } };
-
-  return { type: 'plain', meta: { pkg } };
-}
-
-/**
- * Pick default `aliases` + `tailwind.css` path based on the detected project.
- *
- * @param {string} cwd
- */
-export function defaultsForProject(cwd = process.cwd()) {
-  const { type } = detectProject(cwd);
-  switch (type) {
-    case 'webjs':
-      return {
-        // 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':
-      return {
-        tailwindCss: 'app/globals.css',
-        aliases: { components: '@/components', utils: '@/lib/utils', ui: '@/components/ui', lib: '@/lib' },
-      };
-    case 'vite':
-      return {
-        tailwindCss: 'src/index.css',
-        aliases: { components: 'src/components', utils: 'src/lib/utils', ui: 'src/components/ui', lib: 'src/lib' },
-      };
-    case 'astro':
-      return {
-        tailwindCss: 'src/styles/globals.css',
-        aliases: { components: 'src/components', utils: 'src/lib/utils', ui: 'src/components/ui', lib: 'src/lib' },
-      };
-    default:
-      return {
-        tailwindCss: 'styles/globals.css',
-        aliases: { components: 'components', utils: 'lib/utils', ui: 'components/ui', lib: 'lib' },
-      };
-  }
-}