mlola-ui 1.0.0

package/registry/source/packages/components/virtual-list/virtual-list.tsx

@@ -0,0 +1,121 @@
+"use client";
+
+import * as React from "react";
+import { cx } from "../_internal/react";
+import { offsetsOf, visibleRange } from "./virtual";
+
+export { offsetsOf, rowAt, visibleRange } from "./virtual";
+
+export interface VirtualListProps {
+  count: number;
+  /** One row. Rows may differ in height; each is measured once rendered. */
+  renderItem: (index: number) => React.ReactNode;
+  /** A guess for rows not yet measured, in pixels. */
+  estimateSize?: number;
+  /** A stable key per row; the index by default. */
+  getKey?: (index: number) => React.Key;
+  /** Height of the scrolling area: a CSS length, or fill the parent by default. */
+  height?: string | number;
+  overscan?: number;
+  /** Called when the reader nears the end, to load more. */
+  onEndReached?: () => void;
+  /** How near, in pixels. */
+  endThreshold?: number;
+  label?: string;
+  className?: string;
+}
+
+/**
+ * A list that renders only the rows on screen, so ten thousand rows scroll
+ * like ten. Rows may have any height; each is measured as it appears, and the
+ * list keeps its place while measurements arrive. Pair `onEndReached` with a
+ * growing `count` for infinite loading.
+ */
+export function VirtualList({ count, renderItem, estimateSize = 44, getKey, height = "100%", overscan = 6, onEndReached, endThreshold = 400, label, className }: VirtualListProps) {
+  const scroller = React.useRef<HTMLDivElement>(null);
+  const sizes = React.useRef(new Map<number, number>());
+  const [version, setVersion] = React.useState(0);
+  const [view, setView] = React.useState({ top: 0, height: 600 });
+  const ended = React.useRef(-1);
+
+  const offsets = React.useMemo(() => offsetsOf(count, (index) => sizes.current.get(index) ?? estimateSize), [count, estimateSize, version]);
+  const { start, end } = visibleRange(offsets, view.top, view.height, overscan);
+
+  React.useLayoutEffect(() => {
+    const element = scroller.current;
+    if (!element) return;
+    const update = () => setView({ top: element.scrollTop, height: element.clientHeight });
+    update();
+    const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(update);
+    observer?.observe(element);
+    return () => observer?.disconnect();
+  }, []);
+
+  // One observer measures every rendered row; a change re-lays the list out.
+  const measurer = React.useMemo(
+    () =>
+      typeof ResizeObserver === "undefined"
+        ? null
+        : new ResizeObserver((entries) => {
+            let changed = false;
+            for (const entry of entries) {
+              const index = Number((entry.target as HTMLElement).dataset.index);
+              const size = Math.round(entry.borderBoxSize?.[0]?.blockSize ?? (entry.target as HTMLElement).offsetHeight);
+              if (sizes.current.get(index) !== size) {
+                sizes.current.set(index, size);
+                changed = true;
+              }
+            }
+            if (changed) setVersion((current) => current + 1);
+          }),
+    [],
+  );
+  React.useEffect(() => () => measurer?.disconnect(), [measurer]);
+
+  React.useEffect(() => {
+    if (!onEndReached || !count) return;
+    const bottom = view.top + view.height;
+    if (offsets[count] - bottom < endThreshold && ended.current !== count) {
+      ended.current = count;
+      onEndReached();
+    }
+  }, [view, offsets, count, onEndReached, endThreshold]);
+
+  const rows: React.ReactNode[] = [];
+  for (let index = start; index <= end; index++) {
+    rows.push(
+      <div
+        key={getKey?.(index) ?? index}
+        className="ml-virtual-list-row"
+        data-index={index}
+        role="listitem"
+        aria-setsize={count}
+        aria-posinset={index + 1}
+        style={{ transform: `translateY(${offsets[index]}px)` }}
+        ref={(element) => {
+          if (!element || !measurer) return;
+          measurer.observe(element);
+          return () => measurer.unobserve(element);
+        }}
+      >
+        {renderItem(index)}
+      </div>,
+    );
+  }
+
+  return (
+    <div
+      ref={scroller}
+      className={cx("ml-virtual-list", className)}
+      style={{ height }}
+      role="list"
+      aria-label={label}
+      tabIndex={0}
+      onScroll={(event) => setView({ top: event.currentTarget.scrollTop, height: event.currentTarget.clientHeight })}
+    >
+      <div className="ml-virtual-list-space" style={{ height: offsets[count] }}>
+        {rows}
+      </div>
+    </div>
+  );
+}

package/registry/source/packages/components/virtual-list/virtual.ts

@@ -0,0 +1,33 @@
+/**
+ * Windowing arithmetic: which rows of a long list are on screen, given each
+ * row's height (measured, or estimated until measured).
+ */
+
+/** Running offsets: offsets[i] is where row i starts; offsets[count] is the total height. */
+export function offsetsOf(count: number, sizeOf: (index: number) => number): number[] {
+  const offsets = new Array<number>(count + 1);
+  offsets[0] = 0;
+  for (let index = 0; index < count; index++) offsets[index + 1] = offsets[index] + sizeOf(index);
+  return offsets;
+}
+
+/** The first row whose bottom is below `y` (binary search). */
+export function rowAt(offsets: number[], y: number): number {
+  let low = 0;
+  let high = offsets.length - 2;
+  while (low < high) {
+    const middle = (low + high) >> 1;
+    if (offsets[middle + 1] <= y) low = middle + 1;
+    else high = middle;
+  }
+  return Math.max(0, low);
+}
+
+/** Rows to render for a viewport, with `overscan` extra rows on each side. */
+export function visibleRange(offsets: number[], scrollTop: number, viewport: number, overscan = 4) {
+  const count = offsets.length - 1;
+  if (count <= 0) return { start: 0, end: -1 };
+  const first = rowAt(offsets, scrollTop);
+  const last = rowAt(offsets, scrollTop + viewport);
+  return { start: Math.max(0, first - overscan), end: Math.min(count - 1, last + overscan) };
+}

package/registry/source-manifest.json

@@ -0,0 +1,67 @@
+{
+  "packages/components/_internal/anchor.ts": "sha256-Jo9N3iIaWnS1CJzYhgTv7vnW+8MLyzL8X4GRNjeEp+g=",
+  "packages/components/_internal/dialog.ts": "sha256-Q7DPI2BipgFjPd3T8g2GGicrVal0cp0eMKXWFqcj64k=",
+  "packages/components/_internal/floating.ts": "sha256-+WxgC4CtAlSr2qA1EkoDTgto535XLIPsvtOfdOK6CHk=",
+  "packages/components/_internal/match.ts": "sha256-nKBpKWeow5ubAHUhOW8yOjlrKs0lqYdjbaYYfE8VoII=",
+  "packages/components/_internal/react.ts": "sha256-SH63/haiB4Q93uFjMIMe5xZbaxENu3VI+GcidV8HELM=",
+  "packages/components/_internal/scroll.ts": "sha256-/YxhPPJa6Iax4q5eEs8dmpQp634TbvB+421MphEyscQ=",
+  "packages/components/accordion/accordion.tsx": "sha256-0ALaLJd1fvj8Vbx86HLBKm3qUItrtwbrGJTykVfNSMg=",
+  "packages/components/activity-heatmap/activity-heatmap.tsx": "sha256-fMGDlXKpOfIOy0hmbpR8hKrbbN3fC386tXK27A21ZwM=",
+  "packages/components/activity-heatmap/calendar.ts": "sha256-NB+AjXY5Xc+KzR8MMTRBgZxdzOeoHhkW0KQOW7WJPuQ=",
+  "packages/components/alert/alert.tsx": "sha256-kg//PTcUW7j7AEnhfO/pZFddm++RIo8yKur46OeoeNo=",
+  "packages/components/app-shell/app-shell.tsx": "sha256-XAq82XOTH3ZR+hxTkYFu8P7Ih2aI6ERy/TpXc2VMUwM=",
+  "packages/components/avatar/avatar.tsx": "sha256-hvZUGhatN95ZyX6p6NBhTRf6h1/rrJ+bJrqBMtIspq0=",
+  "packages/components/badge/badge.tsx": "sha256-+mgudoxlPn+mjpQycUfQmv8sC/e/K5FXfXm2+wnH7bI=",
+  "packages/components/breadcrumb/breadcrumb.tsx": "sha256-SiIpg0oAieyoZbMlBwwQDZhR/KVIFLFCLCQJ6vwv7Fs=",
+  "packages/components/button/button.tsx": "sha256-khqYxcV3hlZ+Q+cYNTRXEpAfIijDFSvkuDJXMPtlk7g=",
+  "packages/components/calendar/calendar.tsx": "sha256-uE22LI4jpU8ErR/oBmAkeKiu+Rp0bz3IXZVCurycpwc=",
+  "packages/components/calendar/dates.ts": "sha256-mygYkoC70av2ZQ0vkxf885trwW97Wd10I4dptYQe+4A=",
+  "packages/components/card/card.tsx": "sha256-aMKbv5DWYYWq7GZAFR9O1fuYE0H61WCjkvEbRMOd894=",
+  "packages/components/carousel/carousel.tsx": "sha256-LAPKz9DG9vEBv/8jKjqgH7XiSEERkWWLr4n/Kve1omQ=",
+  "packages/components/checkbox/checkbox.tsx": "sha256-yBfPogs6Q2lEoEbgErLTextGzc11BXn+0UX1RPABtBY=",
+  "packages/components/color-picker/color-picker.tsx": "sha256-UziuULSI7dIGLfu4jjWIz6Cbh2/HiaY2KYXlfQ+6iQg=",
+  "packages/components/color-picker/color.ts": "sha256-3IO6DaelZ6TVn2aw+6o6pZCQGAQdeNRkN7sPypUzddE=",
+  "packages/components/combobox/combobox.tsx": "sha256-CnuJP01m0ZPMB4MGjoKbJCBQ7inI6bPf5aMDrq4m1qI=",
+  "packages/components/command-menu/command-menu.tsx": "sha256-mF1z92yrPY609pjx5Dt1l5EhGHl9EWV8F8Sq0hyJRw4=",
+  "packages/components/context-menu/context-menu.tsx": "sha256-YgYsIzvLGFcJG1XX5zFJwrid5Z1Kn0lyWVzmLKmbMVU=",
+  "packages/components/date-picker/date-picker.tsx": "sha256-pX7snZCO3SxVftkCvI/f5b82bNHPconUa50BJnjYNWc=",
+  "packages/components/dropdown-menu/dropdown-menu.tsx": "sha256-xgybCu9HBxIieafu5CjAtY4aCOQoaAj/VUCH6D6vLP8=",
+  "packages/components/dropzone/dropzone.tsx": "sha256-jMVEnTki4Suhx7pOWfLX9MO1Q3nLz0xqDJ/2EPHdpYg=",
+  "packages/components/empty-state/empty-state.tsx": "sha256-AWwOuZgm71hossjCGYygtvzGcDy6JOPryF+U1UrsLhM=",
+  "packages/components/hover-card/hover-card.tsx": "sha256-HZyB9SUDcRPG8MvRX1sHqHA2rNcO63yVevH9hiGqVAA=",
+  "packages/components/input/input.tsx": "sha256-lbbheo+ydQTzyujTf0W7DD96TogOjifCyqj9c3h3W0g=",
+  "packages/components/kbd/kbd.tsx": "sha256-wrPqzn1e82zJYoKzO7u94Bgq4+nPc0DXLc8GJ/4/3nY=",
+  "packages/components/modal/modal.tsx": "sha256-vybxgBGYCrMYvJRnO1wDAc2VFQylu+mQIf5OZIcabX4=",
+  "packages/components/number-input/number-input.tsx": "sha256-D+8jH2YaW4lCv/F02qvkc9Huhxvz0y1idzgOBwsjiN8=",
+  "packages/components/number-input/number.ts": "sha256-IrHCQrEhI5ein9ifMFuSViSoxQUBoT3tNmmCu/paGGM=",
+  "packages/components/otp-input/otp-input.tsx": "sha256-MWDyTP99wVAQSYJsF78ol1Kv9LKOj1lybmp2zOomVqo=",
+  "packages/components/pagination/pagination.tsx": "sha256-FBwk8tq4JcsK2D0dlWEYiDSRx3owgBmGzEIlVRaNBoE=",
+  "packages/components/popover/popover.tsx": "sha256-/kTiAuFklU4IuP97XaiCUGdEpKtNyMPLPS359mfzPHw=",
+  "packages/components/priority-icon/labels.ts": "sha256-zhmJIb7/gS16wU+xCJ7hkReBi9q5RI3SMwdjkJvvvKU=",
+  "packages/components/priority-icon/priority-icon.tsx": "sha256-3D6hFRpht3YuWouLhakE2DFdldavmJx0B/povEDwrtQ=",
+  "packages/components/progress/progress.tsx": "sha256-3SOA1JX54msiq/pF2UolesQqQZm0zSVyZQi6W38lOOA=",
+  "packages/components/radio-group/radio-group.tsx": "sha256-jhnSEBLkdpe8dv5us/Q1sMsQF4sKGRgDXWGKm2JSFew=",
+  "packages/components/rating/rating.tsx": "sha256-zgPOQXzAiRE4qGNPQ8qat3SP1XSI/7567kA5VaT51P0=",
+  "packages/components/resizable/resizable.tsx": "sha256-40sK2UyIR9Ek72KAu5nvbr44tKEY6JhC5Ftb++Wf6cI=",
+  "packages/components/segmented-control/segmented-control.tsx": "sha256-sExMN2WHtzxcaCu7xN/1jaP+sRVwJ2OAW1WkKGhNYnU=",
+  "packages/components/select/select.tsx": "sha256-MWHL/mlAO2ob4H3EmYSBZcC1qqy+M3cF1Z4s0R+frrc=",
+  "packages/components/sheet/sheet.tsx": "sha256-EIn3OeRDmXGHbYf/uihRh8aw3LmzarIFiyC9DUsL1jg=",
+  "packages/components/skeleton/skeleton.tsx": "sha256-2Fk72NbLr3+CrXH7jGbHNsc3t+vskMqSyySe/UwbGCs=",
+  "packages/components/slider/slider.tsx": "sha256-l+VrBqPYHIIcemiVixxwDxNDB0HEMmYRZekx/H5HroQ=",
+  "packages/components/status-icon/labels.ts": "sha256-EE8q+geQBbJUs7I3RmaHZnPwn7Vjk2GjCfxvI4ruXKM=",
+  "packages/components/status-icon/status-icon.tsx": "sha256-TtrTeoePyfH1VhKuWC0v12FuwfgND1CHnH5x8fyf4AM=",
+  "packages/components/stepper/stepper.tsx": "sha256-uI/dRmkbijlixHiGUceWcpaDzpEixrzQ1UTmoPbGZAY=",
+  "packages/components/table/table.tsx": "sha256-ed1Qn2sIpxRvGdPDAb5ih5AcXr5PmHTHdlrJLYDYRp8=",
+  "packages/components/tabs/tabs.tsx": "sha256-kWAQjE9mshqZL7V3NJTUiurp6M5Nu3vx5O1LsIgdV5Y=",
+  "packages/components/tag-input/tag-input.tsx": "sha256-+R1f2XljDYInsfuggKkpqz5m9TqEa0g3QYKMX2TE6h0=",
+  "packages/components/textarea/textarea.tsx": "sha256-jeyvAlzFr25eWZ/Inkxo1UEOHXlCPB/QHeId124SfR8=",
+  "packages/components/time-picker/time-picker.tsx": "sha256-OyIfJN6xVv6TwUYtRirkemJe5VMcu2HXxjaJj8fvu9I=",
+  "packages/components/time-picker/times.ts": "sha256-V/4uqFZPn9gVnyx8cB9vwp/RocmTYaPmLxjfy8DPQOI=",
+  "packages/components/timeline/timeline.tsx": "sha256-FDZx+ihL5tbIY/sEl0444uj27JWHE5xl0vl8IqRUUPY=",
+  "packages/components/toast/toast.tsx": "sha256-RrqUAAfKavEkZaLjywJHc0iTNHC1DHlIGVX97kftDkg=",
+  "packages/components/toggle/toggle.tsx": "sha256-zwTbHMSs3n0eg5XIpREDnySYLXHaLly1Ew4FWlzvgJY=",
+  "packages/components/tooltip/tooltip.tsx": "sha256-NbaOUmlUbBlUIdovchrWwH2QqzuvXB97DjnJnrHf4Gc=",
+  "packages/components/tour/tour.tsx": "sha256-1aSh7hMVt/DM/kH3WGJzJMGNsNqYEOmnwAZwc8dwRv8=",
+  "packages/components/virtual-list/virtual-list.tsx": "sha256-raGEFn4HlAOIohqZcy0DgptsnUIPS/6bWLYeTe+M9E8=",
+  "packages/components/virtual-list/virtual.ts": "sha256-PyDIj3C2Vwb1i4ZssxSlYjgKmZPBIFLZFNq8YCW2Z78="
+}

package/src/cli.js

@@ -0,0 +1,262 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+  DEFAULT_CONFIG,
+  loadConfig,
+  targetRoot,
+  writeDefaultConfig,
+} from "./config.js";
+import { runDoctor } from "./doctor.js";
+import { collectEngineDependencies, installItems } from "./installer.js";
+import { loadCatalogNames, loadRegistry, resolveItems } from "./registry.js";
+import { clearCredentials, fetchProItems, GUIDE_FILENAME, hostFrom, readCredentials, saveCredentials, verifyToken, writeProGuide, writeProStyles } from "./pro.js";
+import { pullTheme } from "./theme-pull.js";
+
+const HELP = `Mlola UI — source-copy components with Theme
+
+Usage:
+  mlola-ui init [--force]
+  mlola-ui add <name...> [--overwrite] [--install|--yes]
+  mlola-ui login <token> [--host <url>]
+  mlola-ui logout
+  mlola-ui list [--kind component|block|template] [--json]
+  mlola-ui doctor
+  mlola-ui theme pull <theme-id | url> [--host <url>] [--overwrite]
+
+Examples:
+  npx mlola-ui init
+  npx mlola-ui add button card
+  npx mlola-ui login mlp_…          (Mlola Pro: a token from /account)
+  npx mlola-ui add conversation bot
+  npx mlola-ui list --kind block
+  npx mlola-ui theme pull https://ui.mlola.com/t/th-4k2x9qf7wz3m
+`;
+
+function hasFlag(args, ...names) {
+  return args.some((argument) => names.includes(argument));
+}
+
+function optionValue(args, name) {
+  const index = args.indexOf(name);
+  return index === -1 ? undefined : args[index + 1];
+}
+
+function writeStyles(cwd, config, force) {
+  const relative = path.join(targetRoot(config, "styles"), "mlola", "index.css");
+  const filename = path.join(cwd, relative);
+  if (fs.existsSync(filename) && !force) return { relative, created: false };
+  fs.mkdirSync(path.dirname(filename), { recursive: true });
+  fs.writeFileSync(
+    filename,
+    `/* Generated by mlola-ui init. Import this file once in your app. */\n@import "${config.engine.engine ?? "@mlola-ui/engine"}";\n`,
+  );
+  return { relative, created: true };
+}
+
+function packageManager(cwd) {
+  if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) return ["pnpm", ["add"]];
+  if (fs.existsSync(path.join(cwd, "yarn.lock"))) return ["yarn", ["add"]];
+  if (fs.existsSync(path.join(cwd, "bun.lockb")) || fs.existsSync(path.join(cwd, "bun.lock"))) {
+    return ["bun", ["add"]];
+  }
+  return ["npm", ["install"]];
+}
+
+function installEngines(cwd, dependencies, output) {
+  if (!dependencies.size) return 0;
+  const [command, baseArgs] = packageManager(cwd);
+  const packages = [...dependencies].map(([name, range]) => `${name}@${range}`);
+  output.log(`Installing ${packages.join(", ")}...`);
+  const result = spawnSync(command, [...baseArgs, ...packages], { cwd, stdio: "inherit" });
+  if (result.error) {
+    output.error(`Unable to run ${command}: ${result.error.message}`);
+    return 1;
+  }
+  return result.status ?? 1;
+}
+
+export async function run(argv, options = {}) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const output = options.output ?? console;
+  const env = options.env ?? process.env;
+  const fetcher = options.fetch ?? fetch;
+  const [command = "help", ...args] = argv;
+
+  try {
+    if (command === "help" || command === "--help" || command === "-h") {
+      output.log(HELP);
+      return 0;
+    }
+
+    if (command === "init") {
+      const force = hasFlag(args, "--force");
+      const configResult = writeDefaultConfig(cwd, { force });
+      const config = configResult.created ? DEFAULT_CONFIG : loadConfig(cwd);
+      const stylesResult = writeStyles(cwd, config, force);
+      output.log(
+        configResult.created
+          ? `✓ Created ${path.relative(cwd, configResult.filename)}`
+          : `• Kept existing ${path.relative(cwd, configResult.filename)}`,
+      );
+      output.log(
+        stylesResult.created
+          ? `✓ Created ${stylesResult.relative}`
+          : `• Kept existing ${stylesResult.relative}`,
+      );
+      output.log(
+        `Set data-theme="${config.theme}" on your document root and import ${stylesResult.relative}.`,
+      );
+      output.log(
+        `Install the engines you use, starting with: npm install ${config.engine.engine ?? "@mlola-ui/engine"} ${config.engine.motion}`,
+      );
+      return 0;
+    }
+
+    if (command === "list") {
+      const registry = loadRegistry();
+      const kind = optionValue(args, "--kind");
+      if (kind && !["component", "block", "template"].includes(kind)) {
+        throw new Error(`--kind must be component, block, or template (received "${kind}")`);
+      }
+      const items = kind
+        ? registry.items.filter((item) => item.type === {
+            component: "registry:ui",
+            block: "registry:block",
+            template: "registry:page",
+          }[kind])
+        : registry.items;
+      if (hasFlag(args, "--json")) {
+        output.log(JSON.stringify(items, null, 2));
+      } else {
+        for (const group of ["registry:ui", "registry:block", "registry:page"]) {
+          const grouped = items.filter((item) => item.type === group);
+          if (!grouped.length) continue;
+          const label = {
+            "registry:ui": "Components",
+            "registry:block": "Blocks",
+            "registry:page": "Templates",
+          }[group];
+          output.log(`${label} (${grouped.length})`);
+          for (const item of grouped) output.log(`  ${item.name.padEnd(18)} ${item.description}`);
+        }
+      }
+      return 0;
+    }
+
+    if (command === "login") {
+      const token = args.find((argument) => !argument.startsWith("-") && argument !== optionValue(args, "--host"));
+      const host = hostFrom(env, optionValue(args, "--host"));
+      if (!token) throw new Error(`Usage: mlola-ui login <token>. Create a token at ${host}/account.`);
+      const { licence } = await verifyToken(host, token, fetcher);
+      const filename = saveCredentials(env, token, host === hostFrom(env) ? undefined : host);
+      output.log(`✓ Logged in to Mlola Pro (${licence.plan} licence). Token saved to ${filename}.`);
+      return 0;
+    }
+
+    if (command === "logout") {
+      output.log(clearCredentials(env) ? "✓ Logged out of Mlola Pro." : "• Not logged in.");
+      return 0;
+    }
+
+    if (command === "add") {
+      const names = args.filter((argument) => !argument.startsWith("-"));
+      if (!names.length) throw new Error("Usage: mlola-ui add <name...>");
+      const overwrite = hasFlag(args, "--overwrite");
+      const bundled = loadRegistry();
+      const config = loadConfig(cwd);
+      const catalogNames = loadCatalogNames();
+      const proNames = names.filter((name) => catalogNames.has(name));
+
+      // Pro items come from the service with their Pro dependencies; free ones from the bundle.
+      let registry = bundled;
+      let styles = [];
+      let guide = null;
+      if (proNames.length) {
+        const credentials = readCredentials(env);
+        const host = hostFrom(env, credentials?.host);
+        if (!credentials) {
+          throw new Error(
+            `${proNames.map((name) => `"${name}"`).join(", ")} ${proNames.length === 1 ? "is" : "are"} part of Mlola Pro. ` +
+              `With a licence, create a token at ${host}/account and run "npx mlola-ui login <token>". See ${host}/pricing to get Pro.`,
+          );
+        }
+        const delivered = await fetchProItems(host, credentials.token, proNames, fetcher);
+        const known = new Set(bundled.items.map((item) => item.name));
+        registry = { ...bundled, items: [...bundled.items, ...delivered.items.filter((item) => !known.has(item.name))] };
+        styles = delivered.styles;
+        guide = delivered.guide;
+      }
+
+      const items = resolveItems(registry, names, catalogNames);
+      const result = installItems(cwd, registry, items, config, { overwrite });
+      const styleResult = writeProStyles(cwd, config, styles, { overwrite });
+      result.written.push(...styleResult.written);
+      result.unchanged.push(...styleResult.unchanged);
+      result.conflicts.push(...styleResult.conflicts);
+      const guideResult = writeProGuide(cwd, guide, { overwrite });
+      if (guideResult.status === "written") result.written.push(GUIDE_FILENAME);
+      if (guideResult.status === "unchanged") result.unchanged.push(GUIDE_FILENAME);
+      if (guideResult.status === "conflict") result.conflicts.push(GUIDE_FILENAME);
+      for (const filename of result.written) output.log(`✓ Added ${filename}`);
+      if (result.unchanged.length) {
+        output.log(`• ${result.unchanged.length} file(s) already match the registry`);
+      }
+      if (result.conflicts.length) {
+        output.error(
+          `✗ Refused to replace ${result.conflicts.length} modified file(s):\n  ${result.conflicts.join(
+            "\n  ",
+          )}\nRun again with --overwrite to replace them.`,
+        );
+        return 1;
+      }
+
+      if (styleResult.index) output.log(`Pro styles are gathered in ${styleResult.index}; import it once, after the engine stylesheet.`);
+      if (guideResult.status === "written") output.log(`Coding agents: point your AGENTS.md at ${GUIDE_FILENAME}, which lists every Pro class and attribute.`);
+
+      const engines = collectEngineDependencies(items);
+      if (engines.size && hasFlag(args, "--install", "--yes")) {
+        return installEngines(cwd, engines, output);
+      }
+      if (engines.size) {
+        output.log(
+          `Engine dependencies: ${[...engines]
+            .map(([name, range]) => `${name}@${range}`)
+            .join(" ")}`,
+        );
+      }
+      return 0;
+    }
+
+    if (command === "theme") {
+      const [subcommand, reference] = args;
+      if (subcommand !== "pull") throw new Error(`Unknown theme command "${subcommand ?? ""}". Try: mlola-ui theme pull <theme-id | url>`);
+      await pullTheme(cwd, reference, {
+        host: optionValue(args, "--host") ?? (process.env.MLOLA_STUDIO_URL || undefined),
+        overwrite: hasFlag(args, "--overwrite"),
+        fetcher,
+        output,
+      });
+      return 0;
+    }
+
+    if (command === "doctor") {
+      const findings = runDoctor(cwd);
+      for (const item of findings) {
+        const symbol = item.level === "pass" ? "✓" : item.level === "warn" ? "!" : "✗";
+        const writer = item.level === "error" ? output.error : output.log;
+        writer.call(output, `${symbol} ${item.message}`);
+      }
+      const errors = findings.filter((item) => item.level === "error").length;
+      const warnings = findings.filter((item) => item.level === "warn").length;
+      output.log(`Doctor completed with ${errors} error(s) and ${warnings} warning(s).`);
+      return errors ? 1 : 0;
+    }
+
+    output.error(`Unknown command "${command}".\n\n${HELP}`);
+    return 1;
+  } catch (error) {
+    output.error(`✗ ${error.message}`);
+    return 1;
+  }
+}

package/src/config.js

@@ -0,0 +1,114 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const CONFIG_FILENAME = "mlola.config.json";
+
+export const DEFAULT_CONFIG = {
+  $schema: "https://ui.mlola.com/schema/mlola.config.json",
+  version: 1,
+  theme: "graphite",
+  aliases: {
+    components: "@/components/ui",
+    blocks: "@/components/blocks",
+    pages: "@/app/pages",
+    templates: "@/app/templates",
+    lib: "@/lib/mlola",
+    styles: "@/styles",
+  },
+  targets: {
+    components: "components/ui",
+    blocks: "components/blocks",
+    pages: "app/pages",
+    templates: "app/templates",
+    lib: "lib/mlola",
+    styles: "styles",
+  },
+  engine: {
+    engine: "@mlola-ui/engine",
+    tokens: "@mlola-ui/tokens",
+    motion: "@mlola-ui/motion",
+    scene: "@mlola-ui/scene",
+    icons: "@mlola-ui/icons",
+    behavior: "@mlola-ui/behavior",
+  },
+};
+
+const REQUIRED_ALIASES = ["components", "blocks", "templates", "lib", "styles"];
+const THEMES = new Set(["graphite", "atelier", "machined", "aerogel", "nordic"]);
+
+export function configPath(cwd) {
+  return path.join(cwd, CONFIG_FILENAME);
+}
+
+export function validateConfig(config) {
+  const errors = [];
+  if (!config || typeof config !== "object") return ["configuration must be an object"];
+  if (config.version !== 1) errors.push(`version must be 1 (received ${config.version})`);
+  if (!THEMES.has(config.theme)) errors.push(`theme must be one of ${[...THEMES].join(", ")}`);
+  for (const key of REQUIRED_ALIASES) {
+    if (typeof config.aliases?.[key] !== "string" || !config.aliases[key]) {
+      errors.push(`aliases.${key} must be a non-empty string`);
+    }
+  }
+  if (!config.engine || typeof config.engine !== "object") {
+    errors.push("engine mappings are required");
+  }
+  return errors;
+}
+
+export function loadConfig(cwd) {
+  const filename = configPath(cwd);
+  if (!fs.existsSync(filename)) {
+    throw new Error(`No ${CONFIG_FILENAME} found. Run "npx mlola-ui init" first.`);
+  }
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(filename, "utf8"));
+  } catch (error) {
+    throw new Error(`Cannot parse ${CONFIG_FILENAME}: ${error.message}`);
+  }
+  const errors = validateConfig(config);
+  if (errors.length) {
+    throw new Error(`Invalid ${CONFIG_FILENAME}:\n  - ${errors.join("\n  - ")}`);
+  }
+  return config;
+}
+
+function safeRelative(value, label) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${label} must be a non-empty path.`);
+  }
+  let relative = value.trim().replaceAll("\\", "/");
+  if (relative.startsWith("@/") || relative.startsWith("~/")) relative = relative.slice(2);
+  relative = relative.replace(/^\.?\//, "");
+  if (path.isAbsolute(relative) || relative.split("/").includes("..")) {
+    throw new Error(`${label} must stay inside the project: ${value}`);
+  }
+  return relative;
+}
+
+export function targetRoot(config, key) {
+  const configured = config.targets?.[key] ?? config.aliases?.[key] ?? DEFAULT_CONFIG.targets[key];
+  return safeRelative(configured, `target ${key}`);
+}
+
+export function interpolateTarget(template, config, mode = "filesystem") {
+  const match = /^\{\{aliases\.([a-z]+)\}\}\/(.+)$/.exec(template);
+  if (!match) throw new Error(`Invalid registry target template: ${template}`);
+  const [, key, remainder] = match;
+  const base =
+    mode === "import"
+      ? config.aliases?.[key] ?? DEFAULT_CONFIG.aliases[key]
+      : targetRoot(config, key);
+  if (!base) throw new Error(`No configured alias for "${key}".`);
+  return `${base.replace(/\/$/, "")}/${remainder}`;
+}
+
+export function writeDefaultConfig(cwd, { force = false } = {}) {
+  const filename = configPath(cwd);
+  if (fs.existsSync(filename) && !force) {
+    return { filename, created: false };
+  }
+  fs.writeFileSync(filename, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`);
+  return { filename, created: true };
+}