mlola-ui 1.0.13 → 1.1.0

package/registry/source-manifest.json

@@ -1,71 +1,73 @@
 {
   "packages/components/_internal/anchor.ts": "sha256-/yW3RVjoY6QfTWnUYSeZ9rFkC9W4WGB1qop8Jp/H1r8=",
   "packages/components/_internal/clipboard.ts": "sha256-0y5p88CTXWuOrUYlC5J4XP1VCrOwkx9jYWVHmD2LouQ=",
-  "packages/components/_internal/dialog.ts": "sha256-796y3oNOVWarLvICTdi+d0/2axqSrzLVJiyBeh9X7bU=",
-  "packages/components/_internal/floating.ts": "sha256-+WxgC4CtAlSr2qA1EkoDTgto535XLIPsvtOfdOK6CHk=",
+  "packages/components/_internal/dialog.ts": "sha256-dfOsfaszM/rhBJXvl7vtM4Vdh7SGflY5Capi1YoY6ow=",
+  "packages/components/_internal/dom.ts": "sha256-TJp94MipbXHonH/PC7FFHu5pnAqcoxzLocksWLsTAsc=",
+  "packages/components/_internal/floating.ts": "sha256-8iKD2nqqwTY0grZ+KDnP81CcChrQK4CDvlDvApl0fF4=",
   "packages/components/_internal/match.ts": "sha256-3tUYob6xmD2nLerh634E3R5iPbzMeNBzdDynsDFjj28=",
-  "packages/components/_internal/react.ts": "sha256-SH63/haiB4Q93uFjMIMe5xZbaxENu3VI+GcidV8HELM=",
+  "packages/components/_internal/media.ts": "sha256-ziH0YZtu8y3X7OcDI6lYxpvGJCi9zQXq4dynG8n8U9c=",
+  "packages/components/_internal/react.ts": "sha256-INfds1J2f1MLpN6kBXz0GkfBEMIiRlhv0DXX455qAZo=",
   "packages/components/_internal/scroll.ts": "sha256-/YxhPPJa6Iax4q5eEs8dmpQp634TbvB+421MphEyscQ=",
-  "packages/components/accordion/accordion.tsx": "sha256-0ALaLJd1fvj8Vbx86HLBKm3qUItrtwbrGJTykVfNSMg=",
-  "packages/components/activity-heatmap/activity-heatmap.tsx": "sha256-IAcU8FLAJbgKAS+2X+mt6PMqJBzxr4QVdwsVAl67BH4=",
+  "packages/components/accordion/accordion.tsx": "sha256-NodsdXiIL5VE7C2m3C0IC854lNUOIWgQQmmSKr6v59E=",
+  "packages/components/activity-heatmap/activity-heatmap.tsx": "sha256-nHXmfiLpZOH+PrqE1/fyIjevjyPD2/8hSPZRn/+cYcY=",
   "packages/components/activity-heatmap/calendar.ts": "sha256-NB+AjXY5Xc+KzR8MMTRBgZxdzOeoHhkW0KQOW7WJPuQ=",
-  "packages/components/alert/alert.tsx": "sha256-j680akXvCIh4MTVnUo79acvVrv51XyQ3UBJ5FBAy8Dw=",
-  "packages/components/app-shell/app-shell.tsx": "sha256-XAq82XOTH3ZR+hxTkYFu8P7Ih2aI6ERy/TpXc2VMUwM=",
-  "packages/components/avatar/avatar.tsx": "sha256-EjqC8ytKqRtsTVdK6vncaDfhO/i7ICe+jwaYCg5bjIw=",
+  "packages/components/alert/alert.tsx": "sha256-vQ0pvYOpLmafcglpwub6aHLjDPSP4N8qoTCwjo5aEi8=",
+  "packages/components/app-shell/app-shell.tsx": "sha256-slT7UclIZtl2xu7MALrR/i52BHGOR05eCwFTD1mh9AI=",
+  "packages/components/avatar/avatar.tsx": "sha256-61GyO7vZiTEe05z8si1gXKrzgm7I9kN+OFdgk0H8u4Y=",
   "packages/components/badge/badge.tsx": "sha256-flEH8S2jZ/64n3Y/ROhC9+9rvF7wXaN0xLcMMwqNOVQ=",
   "packages/components/breadcrumb/breadcrumb.tsx": "sha256-mxQpach2kFayT8H1vMt5252LQLxVV+sohdVXDhPuKoU=",
-  "packages/components/button/button.tsx": "sha256-sXVANbGeFSYPHpiWuPvHHqMoPjG0zl0HSsKEdTgl5ME=",
+  "packages/components/button/button.tsx": "sha256-sMEaFncanTcURNkkrEH6MK87wrY/HtJSSzqpY8kxaK8=",
   "packages/components/calendar/calendar.tsx": "sha256-rWiS4YAueZfVoo6j5Fi3uN7A+yApe5U6HMm1woTVjys=",
   "packages/components/calendar/dates.ts": "sha256-mygYkoC70av2ZQ0vkxf885trwW97Wd10I4dptYQe+4A=",
-  "packages/components/card/card.tsx": "sha256-aMKbv5DWYYWq7GZAFR9O1fuYE0H61WCjkvEbRMOd894=",
-  "packages/components/carousel/carousel.tsx": "sha256-Gsw0LhQsOuvdQN/F2KDGVC/gJq53+ifLs19u95RWCoU=",
+  "packages/components/card/card.tsx": "sha256-YNqJWotnswv0UiYGtmJV9KxylKopXC0EZD7hTt8eQ0E=",
+  "packages/components/carousel/carousel.tsx": "sha256-WxvQoG9/u190ka4x6cpZT8ZS6XyhEaAlJZ/JyXG+ACU=",
   "packages/components/checkbox/checkbox.tsx": "sha256-hz4YbGwOxv/aJpJHrLXR4MKSWJGyjzoJEIGvdhyML9M=",
-  "packages/components/color-picker/color-picker.tsx": "sha256-E+QB6MbSxg+3AZX3A7bOkst4arxgpmFL2ZmochoWCl8=",
+  "packages/components/color-picker/color-picker.tsx": "sha256-/UyEbxqknsHheX444Imc3WphyixZbvj8hGL+r+zyG5w=",
   "packages/components/color-picker/color.ts": "sha256-YqSgYjzn7XfPWAHuyzbwOhbg/ScaSfB7V73e9w+OjJs=",
-  "packages/components/combobox/combobox.tsx": "sha256-CvuYc/hJoS7yw6QM9vv1SIkwflx0Kwd95UjchtC+AOs=",
-  "packages/components/command-menu/command-menu.tsx": "sha256-mF1z92yrPY609pjx5Dt1l5EhGHl9EWV8F8Sq0hyJRw4=",
-  "packages/components/context-menu/context-menu.tsx": "sha256-YgYsIzvLGFcJG1XX5zFJwrid5Z1Kn0lyWVzmLKmbMVU=",
+  "packages/components/combobox/combobox.tsx": "sha256-fiK8UpFpI5G1tZGFXiUmjMvCWcL8aW7qy9FUaMmAqhw=",
+  "packages/components/command-menu/command-menu.tsx": "sha256-wZnlj17zVlcfp5I08ziggHtchfdqjlvNl+MyiP+Rdbo=",
+  "packages/components/context-menu/context-menu.tsx": "sha256-OGaKzthZJGaV5T+4sRWYecA64wEEg2KImKnIzMMg1i4=",
   "packages/components/copy-button/copy-button.tsx": "sha256-6fvfifoiDOtW+WxKWon4SGEn3THtERuCX2hqGSZDtVM=",
-  "packages/components/date-picker/date-picker.tsx": "sha256-rsmDweD3RVfKTXR2i+/pnTb/MsrDAZXmHAYBvcUGxig=",
+  "packages/components/date-picker/date-picker.tsx": "sha256-QABmZzPKHc706/Rs+ln3ifDK3T2lXl34rehhuRXW+8o=",
   "packages/components/dropdown-menu/dropdown-menu.tsx": "sha256-xgybCu9HBxIieafu5CjAtY4aCOQoaAj/VUCH6D6vLP8=",
   "packages/components/dropzone/dropzone.tsx": "sha256-tHCCpEWE6839UeLOszTo+R2vAL4Sp9UxuRdLkFLfnq4=",
-  "packages/components/empty-state/empty-state.tsx": "sha256-uCKqYpr9vkozXZHpdl4GFtdX9ijcGOriCHvgyarBqRw=",
-  "packages/components/hover-card/hover-card.tsx": "sha256-AyRbxfqDOYBgGlgjgrtQZm5DipArLEzQn6XnzjPd0ro=",
-  "packages/components/input/input.tsx": "sha256-lbbheo+ydQTzyujTf0W7DD96TogOjifCyqj9c3h3W0g=",
+  "packages/components/empty-state/empty-state.tsx": "sha256-/phk3A6TDaiqo61fCcAc/4Bi85e1yBGAtKXFaGhrjyw=",
+  "packages/components/hover-card/hover-card.tsx": "sha256-Bu5m03mFjiM7x38U1aSrcb9Th8RLYozyjwW/Cu3knlk=",
+  "packages/components/input/input.tsx": "sha256-K0YrpEsEJZTzw64t+Cyg/OGYwlU6LU1/yXTNUxYUIAI=",
   "packages/components/kbd/kbd.tsx": "sha256-e8EO2Gw6JiUyrU0YcEZOaQNMel1pe/EcJrxwwgd1Ggk=",
-  "packages/components/modal/modal.tsx": "sha256-rIytVY+hz8aabJ53UGQ0VADgSlW0sAG920iMQaoak+0=",
-  "packages/components/number-input/number-input.tsx": "sha256-BDOyvCNtMULD/HK7uWHsYbGg79lrRDrVqtGQQrYHpmM=",
+  "packages/components/modal/modal.tsx": "sha256-gqrMncs7lEgUjsWXXEl5FYIUoYAxj93gcVh1pZTuatQ=",
+  "packages/components/number-input/number-input.tsx": "sha256-mo7rVoOQ4p/I0Hhx5w+SwXUtl3sI4VOt3QX9FwdB2q4=",
   "packages/components/number-input/number.ts": "sha256-IrHCQrEhI5ein9ifMFuSViSoxQUBoT3tNmmCu/paGGM=",
-  "packages/components/otp-input/otp-input.tsx": "sha256-QURn8g5HqCQXBTdeENPbVxoPlqs3ZtoAPLRlFjQDxmI=",
+  "packages/components/otp-input/otp-input.tsx": "sha256-0KeyDLCC27/GqOocMWXggJ255PCEpCOCcINAcabksSk=",
   "packages/components/pagination/pagination.tsx": "sha256-FBwk8tq4JcsK2D0dlWEYiDSRx3owgBmGzEIlVRaNBoE=",
   "packages/components/password-input/password-input.tsx": "sha256-oY//vTILhUicJyfAWZrSUTl8WWsf4P2S1Bh0x4OxwLs=",
-  "packages/components/popover/popover.tsx": "sha256-/kTiAuFklU4IuP97XaiCUGdEpKtNyMPLPS359mfzPHw=",
+  "packages/components/popover/popover.tsx": "sha256-NYKKNo0sO3jvR5W4iuIlnTw7B+xyOhMZczAtQG/lmw4=",
   "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-9OjecRNPWn7Bfe+C5IyXaKsW1NJae6X5gco1o0X5XkE=",
+  "packages/components/progress/progress.tsx": "sha256-oDxj1Ccl1pKV4+e6A7aaJL1FThW8qs9r4Gb0hEmExeM=",
   "packages/components/radio-group/radio-group.tsx": "sha256-jhnSEBLkdpe8dv5us/Q1sMsQF4sKGRgDXWGKm2JSFew=",
   "packages/components/rating/rating.tsx": "sha256-zgPOQXzAiRE4qGNPQ8qat3SP1XSI/7567kA5VaT51P0=",
   "packages/components/resizable/resizable.tsx": "sha256-Yxlq88qElhv2Q5DooPdriZkawRS0QWx08nd6ybz5oeY=",
   "packages/components/segmented-control/segmented-control.tsx": "sha256-MCBG5XHFWCwbACctsYKbqe8mvSSR6pf60tyRgdCDKDA=",
-  "packages/components/select/select.tsx": "sha256-m8QmKUGC4386XcklosSntal0XwUAFjKosTBQSF0dduQ=",
-  "packages/components/sheet/sheet.tsx": "sha256-EIn3OeRDmXGHbYf/uihRh8aw3LmzarIFiyC9DUsL1jg=",
+  "packages/components/select/select.tsx": "sha256-WfS//CI0wnqhsQvglElqPK1MOL5vwjSaBnaC1BpWVVc=",
+  "packages/components/sheet/sheet.tsx": "sha256-gmc8rZ87NHfN/bErEWHm6HlaAoeNT/Fw6y2PrW88WFI=",
   "packages/components/skeleton/skeleton.tsx": "sha256-2Fk72NbLr3+CrXH7jGbHNsc3t+vskMqSyySe/UwbGCs=",
-  "packages/components/slider/slider.tsx": "sha256-l+VrBqPYHIIcemiVixxwDxNDB0HEMmYRZekx/H5HroQ=",
+  "packages/components/slider/slider.tsx": "sha256-tqffrl4r0kxrVFqX1ExBHZKzenVFAZcOCQl8khJ/QEU=",
   "packages/components/spinner/spinner.tsx": "sha256-FZQmcGkQ8N0485n9bYsLTpTnolbM729YKjkQrXriz9A=",
   "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-xJlWzCH76Lrgg/HrlnVTHkG5dfCkbzjWXEdTVG5Jk4w=",
-  "packages/components/tabs/tabs.tsx": "sha256-kWAQjE9mshqZL7V3NJTUiurp6M5Nu3vx5O1LsIgdV5Y=",
-  "packages/components/tag-input/tag-input.tsx": "sha256-lc4ofz1/lUnb7B/GlFElVKXLbPwtJFAjE5vWwAY99fA=",
-  "packages/components/textarea/textarea.tsx": "sha256-C9jMYZ63w+m6bgdLvHjvULRuoCe26q5zbgS4+ahWzr8=",
-  "packages/components/time-picker/time-picker.tsx": "sha256-og8Cbf+e8oFYewfagUgjRzLHSIIlAZh+1OpAn9yNq70=",
+  "packages/components/tabs/tabs.tsx": "sha256-Wp0WhVFPwaX3aIGXNJBbSGNWPMT6X/Sbl+kE+zZSyvk=",
+  "packages/components/tag-input/tag-input.tsx": "sha256-LnOwotLuPB06nlkdzckjDVhk03D6c/exJXJs2blZNRQ=",
+  "packages/components/textarea/textarea.tsx": "sha256-zculOGfrK4LVcWne3+jS+7qKcfJPM/25vJdm7AXOJfk=",
+  "packages/components/time-picker/time-picker.tsx": "sha256-HquGogkQB7YGs/1iTSqftSJ310hgXqKdAc+fU1RtQ5Y=",
   "packages/components/time-picker/times.ts": "sha256-V/4uqFZPn9gVnyx8cB9vwp/RocmTYaPmLxjfy8DPQOI=",
   "packages/components/timeline/timeline.tsx": "sha256-nVg7lBcAUAzqEb0YrHagJXSaHE2aWWE9bUbQMWQY6PU=",
   "packages/components/toast/toast.tsx": "sha256-f0DwN0XuV46fSsQf3i9RJcfQbAs2mSz7A8UJoIIICHg=",
   "packages/components/toggle/toggle.tsx": "sha256-8qPHeSliHNdzQS7OLJ47BrvRR75MYyUGJlK4s21XS/U=",
-  "packages/components/tooltip/tooltip.tsx": "sha256-hplqwWF/ZqQQ9oyoErrOA3VjkRCDCbqwt5xgZOdsFcA=",
-  "packages/components/tour/tour.tsx": "sha256-mrAE8aVDBVIibGvQah9Gh3mzIiWDFxB6aObzqFo5xXU=",
-  "packages/components/virtual-list/virtual-list.tsx": "sha256-raGEFn4HlAOIohqZcy0DgptsnUIPS/6bWLYeTe+M9E8=",
+  "packages/components/tooltip/tooltip.tsx": "sha256-OEghEwKydt5SU7XNGuQxmmy+S7YyLKu02pPQeoNZQKw=",
+  "packages/components/tour/tour.tsx": "sha256-b2XJokzSio2N9MFDbAbXn6w2f7diJb1KWedSCycRMmE=",
+  "packages/components/virtual-list/virtual-list.tsx": "sha256-oA8xFCwUgskmM+symA4gZxFqSyBCpeKfyM5zHyJaYaQ=",
   "packages/components/virtual-list/virtual.ts": "sha256-PyDIj3C2Vwb1i4ZssxSlYjgKmZPBIFLZFNq8YCW2Z78="
 }

package/src/cli.js

@@ -14,6 +14,7 @@ import { loadCatalogNames, loadRegistry, resolveItems } from "./registry.js";
 import { clearCredentials, fetchProItems, GUIDE_FILENAME, hostFrom, readCredentials, saveCredentials, verifyToken, writeProGuide, writeProStyles } from "./pro.js";
 import { serveMcp } from "./mcp.js";
 import { pullTheme } from "./theme-pull.js";
+import { buildTheme } from "./theme-build.js";
 
 const HELP = `Mlola UI — source-copy components with Theme
 
@@ -28,6 +29,7 @@ Usage:
   mlola-ui list [--kind component|block|template|asset] [--json]
   mlola-ui doctor
   mlola-ui theme pull <theme-id | url> [--host <url>] [--overwrite]
+  mlola-ui theme build [--file mlola.theme.json]
 
 Examples:
   npx mlola-ui init                   (also tells your coding agents about Mlola)
@@ -37,6 +39,7 @@ Examples:
   npx mlola-ui add asset empty-inbox orb
   npx mlola-ui list --kind block
   npx mlola-ui theme pull https://ui.mlola.com/t/th-4k2x9qf7wz3m
+  npx mlola-ui theme build            (renders your mlola.theme.json, offline)
   npx mlola-ui mcp                    (an MCP server for Claude Code, Cursor, Codex…)
 `;
 
@@ -301,7 +304,11 @@ export async function run(argv, options = {}) {
 
     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>`);
+      if (subcommand === "build") {
+        await buildTheme(cwd, { file: optionValue(args, "--file") ?? undefined, output });
+        return 0;
+      }
+      if (subcommand !== "pull") throw new Error(`Unknown theme command "${subcommand ?? ""}". Try: mlola-ui theme build, or 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"),

package/src/config.js

@@ -35,7 +35,9 @@ export const DEFAULT_CONFIG = {
 };
 
 const REQUIRED_ALIASES = ["components", "blocks", "templates", "lib", "styles"];
-const THEMES = new Set(["graphite", "atelier", "machined", "aerogel", "nordic"]);
+export const THEMES = new Set(["graphite", "atelier", "machined", "aerogel", "nordic"]);
+/** A project theme's id, as mlola.theme.json and data-theme spell it. */
+const THEME_ID = /^[a-z][a-z0-9-]{0,47}$/;
 
 export function configPath(cwd) {
   return path.join(cwd, CONFIG_FILENAME);
@@ -45,7 +47,9 @@ 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(", ")}`);
+  if (typeof config.theme !== "string" || !(THEMES.has(config.theme) || THEME_ID.test(config.theme))) {
+    errors.push(`theme must be one of ${[...THEMES].join(", ")}, or your own theme's id from mlola.theme.json (lowercase letters, digits and dashes)`);
+  }
   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`);

package/src/doctor.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { interpolateTarget, loadConfig, targetRoot } from "./config.js";
+import { THEMES, interpolateTarget, loadConfig, targetRoot } from "./config.js";
 import { createTransformContext, expectedFile } from "./installer.js";
 import { loadRegistry, readJson, sha256, sourcePath } from "./registry.js";
 
@@ -110,6 +110,16 @@ export function runDoctor(cwd) {
     }
   }
 
+  // A project theme is rendered into the stylesheet, by `theme build` or `theme pull`.
+  if (!THEMES.has(config.theme)) {
+    const themeCss = path.join(cwd, targetRoot(config, "styles"), "mlola", "theme.css");
+    if (fs.existsSync(themeCss) && fs.readFileSync(themeCss, "utf8").includes(`[data-theme="${config.theme}"]`)) {
+      findings.push(finding("pass", `the project theme "${config.theme}" is rendered in ${path.relative(cwd, themeCss)}`));
+    } else {
+      findings.push(finding("warn", `the theme "${config.theme}" is not rendered yet; run mlola-ui theme build`));
+    }
+  }
+
   if (projectContains(cwd, /\bdata-theme\s*=/)) {
     findings.push(finding("pass", "data-theme is present in application source"));
   } else if (projectContains(cwd, /\bdata-skin\s*=/)) {

package/src/mcp.js

@@ -23,17 +23,13 @@ const PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05
 const INSTRUCTIONS = `This project's UI is Mlola UI: native CSS classes (ml-*), data-* attributes for state and variant, and --ml-* tokens. There is no Tailwind.
 Before writing UI: call get_design_rules once, then search_components for what you need and get_component for how to use it. Read tokens with get_tokens instead of writing colors, sizes, shadows or durations. After writing markup, run check_markup on it and fix what it reports.`;
 
+const REMOTE_INSTRUCTIONS = `Mlola UI is a component system on native CSS classes (ml-*), data-* attributes for state and variant, and --ml-* tokens. There is no Tailwind.
+Before writing UI: call get_design_rules once, then search_components for what you need and get_component for how to use it. Read tokens with get_tokens. After writing markup, run check_markup and fix what it reports. This server cannot write files: get_install_command gives the commands to run in the project, and Mlola Pro items need a license token (npx mlola-ui login).`;
+
 const text = (value) => ({ content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }] });
 
-function tools({ cwd, run }) {
-  const capture = async (argv) => {
-    const lines = [];
-    const output = { log: (...parts) => lines.push(parts.join(" ")), error: (...parts) => lines.push(parts.join(" ")) };
-    // stdout is this server's protocol channel: a package manager started by
-    // init or add writes to stderr and reads nothing.
-    const code = await run(argv, { cwd, output, installStdio: ["ignore", 2, 2] });
-    return { code, output: lines.join("\n") };
-  };
+/** Tools that only read the registry: the local and the remote server share them. */
+function readTools({ cwd }) {
   return [
     {
       name: "get_design_rules",
@@ -100,6 +96,20 @@ function tools({ cwd, run }) {
         return text(issues.length ? issues : "No issues: every Mlola class exists and every data-* value is one its element reacts to.");
       },
     },
+  ];
+}
+
+function tools({ cwd, run }) {
+  const capture = async (argv) => {
+    const lines = [];
+    const output = { log: (...parts) => lines.push(parts.join(" ")), error: (...parts) => lines.push(parts.join(" ")) };
+    // stdout is this server's protocol channel: a package manager started by
+    // init or add writes to stderr and reads nothing.
+    const code = await run(argv, { cwd, output, installStdio: ["ignore", 2, 2] });
+    return { code, output: lines.join("\n") };
+  };
+  return [
+    ...readTools({ cwd }),
     {
       name: "add_components",
       title: "Install Mlola components",
@@ -169,26 +179,27 @@ function prompt(name, args) {
   };
 }
 
-export async function serveMcp({ cwd, run, version, input = process.stdin, output = process.stdout }) {
-  const available = tools({ cwd, run });
-  const send = (message) => output.write(`${JSON.stringify(message)}\n`);
-  const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
-  const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
-
-  async function handle(message) {
+/**
+ * The protocol, apart from any transport: takes one JSON-RPC message and
+ * resolves to the reply, or to null for a notification. The stdio server
+ * here and the site's HTTP endpoint both answer through it.
+ */
+export function createMcpHandler({ tools: available, listResources, readResource: read, version, instructions }) {
+  const reply = (id, result) => ({ jsonrpc: "2.0", id, result });
+  const fail = (id, code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
+  return async function handle(message) {
     const { id, method, params } = message ?? {};
     const isRequest = id !== undefined && id !== null;
     try {
       switch (method) {
         case "initialize": {
           const requested = params?.protocolVersion;
-          reply(id, {
+          return reply(id, {
             protocolVersion: PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSIONS[0],
             capabilities: { tools: { listChanged: false }, resources: { listChanged: false }, prompts: { listChanged: false } },
             serverInfo: { name: "mlola-ui", title: "Mlola UI", version },
-            instructions: INSTRUCTIONS,
+            instructions,
           });
-          return;
         }
         case "ping":
           return reply(id, {});
@@ -205,23 +216,76 @@ export async function serveMcp({ cwd, run, version, input = process.stdin, outpu
           }
         }
         case "resources/list":
-          return reply(id, { resources: resources(cwd) });
+          return reply(id, { resources: listResources() });
         case "resources/templates/list":
           return reply(id, { resourceTemplates: [] });
         case "resources/read":
-          return reply(id, { contents: [{ uri: params?.uri, mimeType: "text/markdown", text: readResource(params?.uri, cwd) }] });
+          return reply(id, { contents: [{ uri: params?.uri, mimeType: "text/markdown", text: read(params?.uri) }] });
         case "prompts/list":
           return reply(id, { prompts: PROMPTS });
         case "prompts/get":
           return reply(id, prompt(params?.name, params?.arguments));
         default:
-          if (method?.startsWith("notifications/")) return;
-          if (isRequest) fail(id, -32601, `Method not found: ${method}`);
+          if (method?.startsWith("notifications/")) return null;
+          return isRequest ? fail(id, -32601, `Method not found: ${method}`) : null;
       }
     } catch (error) {
-      if (isRequest) fail(id, error.code ?? -32603, error.message);
+      return isRequest ? fail(id, error.code ?? -32603, error.message) : null;
     }
-  }
+  };
+}
+
+/**
+ * The server ui.mlola.com/mcp runs: the read-only tools, and install
+ * commands instead of installs, since a remote server cannot write to the
+ * project. Mlola Pro items are described; their source needs a license and
+ * arrives through `npx mlola-ui add`.
+ */
+export function remoteMcpHandler({ version }) {
+  const cwd = process.cwd();
+  const install = {
+    name: "get_install_command",
+    title: "How to install Mlola components",
+    description: "The commands to run in the project to set Mlola up and add components, blocks, pages or templates, including the license step for Mlola Pro items.",
+    inputSchema: { type: "object", properties: { names: { type: "array", items: { type: "string" }, minItems: 1 } }, required: ["names"], additionalProperties: false },
+    annotations: { readOnlyHint: true },
+    handler: ({ names }) => {
+      const found = names.map((name) => searchItems({ query: name }).find((item) => item.name === name));
+      const unknown = names.filter((_, index) => !found[index]);
+      if (unknown.length) return { ...text(`No Mlola item is called ${unknown.join(", ")}. Find names with search_components.`), isError: true };
+      const pro = found.filter((item) => item.tier === "pro").map((item) => item.name);
+      return text([
+        "Run in the project:",
+        "",
+        "npx mlola-ui init   # once: config, stylesheet, the engine, and agent instructions",
+        ...(pro.length ? [`npx mlola-ui login <token>   # ${pro.join(", ")} ${pro.length === 1 ? "is" : "are"} Mlola Pro: create a token at https://ui.mlola.com/account`] : []),
+        `npx mlola-ui add ${names.join(" ")}`,
+        "",
+        'Then import styles/mlola/index.css once and set data-theme="graphite" (or atelier, machined, aerogel, nordic) on the root element.',
+      ].join("\n"));
+    },
+  };
+  return createMcpHandler({
+    tools: [...readTools({ cwd }), install],
+    listResources: () => [{ uri: "mlola://guide", name: "Mlola UI design guide", description: "Classes, attributes, tokens and rules, generated from the stylesheet.", mimeType: "text/markdown" }],
+    readResource: (uri) => {
+      if (uri === "mlola://guide") return designGuide() ?? "";
+      throw Object.assign(new Error(`Unknown resource ${uri}`), { code: -32002 });
+    },
+    version,
+    instructions: REMOTE_INSTRUCTIONS,
+  });
+}
+
+export async function serveMcp({ cwd, run, version, input = process.stdin, output = process.stdout }) {
+  const handle = createMcpHandler({
+    tools: tools({ cwd, run }),
+    listResources: () => resources(cwd),
+    readResource: (uri) => readResource(uri, cwd),
+    version,
+    instructions: INSTRUCTIONS,
+  });
+  const send = (message) => output.write(`${JSON.stringify(message)}\n`);
 
   const lines = readline.createInterface({ input, crlfDelay: Infinity });
   const pending = new Set();
@@ -235,7 +299,11 @@ export async function serveMcp({ cwd, run, version, input = process.stdin, outpu
       continue;
     }
     for (const entry of Array.isArray(message) ? message : [message]) {
-      const task = handle(entry).finally(() => pending.delete(task));
+      const task = handle(entry)
+        .then((response) => {
+          if (response) send(response);
+        })
+        .finally(() => pending.delete(task));
       pending.add(task);
     }
   }

package/src/theme-build.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { DEFAULT_CONFIG, loadConfig, targetRoot } from "./config.js";
+import { ensureImport } from "./theme-pull.js";
+
+/**
+ * `mlola-ui theme build`: render the project's own theme, offline.
+ *
+ * Reads mlola.theme.json (written by hand or pulled from the Studio) and
+ * renders it with the engine installed in the project, the same function
+ * that renders every canonical theme, so its palette is solved for contrast
+ * the same way. Writes <styles>/mlola/theme.css, imported from index.css,
+ * which is where `theme pull` puts a Studio theme.
+ */
+
+export const THEME_FILENAME = "mlola.theme.json";
+
+/** The engine's theme renderer, from the project's own node_modules. */
+async function projectEngine(cwd, engine) {
+  const require = createRequire(path.join(cwd, "package.json"));
+  let resolved;
+  try {
+    resolved = require.resolve(`${engine}/theme`);
+  } catch {
+    throw new Error(`Building a theme needs ${engine} 1.1 or later in this project. Install it: npm install ${engine}@latest`);
+  }
+  return import(pathToFileURL(resolved).href);
+}
+
+export async function buildTheme(cwd, { file = THEME_FILENAME, output = console, loadEngine = projectEngine } = {}) {
+  const themeFile = path.resolve(cwd, file);
+  if (!fs.existsSync(themeFile)) {
+    throw new Error(`No ${file} in ${cwd}. Write one (https://ui.mlola.com/docs/theming#custom) or pull one from the Studio: mlola-ui theme pull <theme-id>`);
+  }
+  let spec;
+  try {
+    spec = JSON.parse(fs.readFileSync(themeFile, "utf8"));
+  } catch (error) {
+    throw new Error(`${file} is not valid JSON: ${error.message}`);
+  }
+
+  const config = fs.existsSync(path.join(cwd, "mlola.config.json")) ? loadConfig(cwd) : DEFAULT_CONFIG;
+  const engine = await loadEngine(cwd, config.engine?.engine ?? "@mlola-ui/engine");
+  const { id } = engine.defineTheme(spec);
+  const css = engine.renderThemeCss(spec);
+
+  const stylesDirectory = path.join(cwd, targetRoot(config, "styles"), "mlola");
+  fs.mkdirSync(stylesDirectory, { recursive: true });
+  fs.writeFileSync(path.join(stylesDirectory, "theme.css"), css);
+  const imported = ensureImport(path.join(stylesDirectory, "index.css"), '@import "./theme.css";');
+
+  const stylesRelative = path.relative(cwd, stylesDirectory);
+  output.log(`✓ Built ${path.join(stylesRelative, "theme.css")} from ${path.relative(cwd, themeFile)}`);
+  if (imported) output.log(`✓ Imported it from ${path.join(stylesRelative, "index.css")}`);
+  if (config.theme !== id) output.log(`Set "theme": "${id}" in mlola.config.json, and data-theme="${id}" on <html> or any container.`);
+  else output.log(`Set data-theme="${id}" on <html> or any container.`);
+  return { id };
+}

package/src/theme-pull.js

@@ -45,7 +45,7 @@ async function fetchText(url, fetcher) {
   return response.text();
 }
 
-function ensureImport(indexFile, line) {
+export function ensureImport(indexFile, line) {
   const current = fs.existsSync(indexFile) ? fs.readFileSync(indexFile, "utf8") : "";
   if (current.includes(line)) return false;
   fs.mkdirSync(path.dirname(indexFile), { recursive: true });